A Discord music bot built with TypeScript, discord.js v14 and discord-player v7.1.x, featuring TikTok live chat integration for cross-platform music control, real-time web overlay for streaming, and advanced logging system.
|
Music Player
|
TikTok Integration
|
|
Web Overlay
|
Configuration
|
Required: Node.js 18+, Discord Bot Token
Optional: TikTok username for live integration, YouTube cookies for bypass bot detection
# Clone repository
git clone https://github.com/Kiznaiverr/kunang-kunang.git
cd kunang-kunang
# Install dependencies
npm install
# Build the project (TypeScript to JavaScript)
npm run build
# Start the bot
npm start
# For development (auto-restart on changes)
npm run devCreate .env file in root directory:
# Discord Configuration
DISCORD_BOT_TOKEN=your_discord_bot_token_here
DISCORD_CHANNEL_ID=your_channel_id_here
DISCORD_GUILD_ID=your_server_id_here
DISCORD_VOICE_CHANNEL_ID=your_voice_channel_id_here
COMMAND_COOLDOWN=5000
# TikTok API Key (Optional - Recommended to avoid rate limiting)
TIKTOK_SIGN_API_KEY=your_tiktok_api_key_here
# Logging Configuration (Optional)
LOG_LEVEL=info # debug, info, success, warn, error, command, replyGetting TikTok Sign API Key (Optional - Recommended and its free)
Note: TikTok Sign API key is optional but highly recommended to avoid rate limiting issues.
-
Go to EulerStream website
- Visit https://www.eulerstream.com/pricing
- Sign up for a free account
-
Get your free API key
- After registration, you'll receive an API key
- This key allows higher connection limits and prevents rate limiting
-
Add to .env file
TIKTOK_SIGN_API_KEY=your_api_key_here
Benefits of using API key:
- Higher connection limits
- No rate limiting issues
- More reliable TikTok bridge connections
- Better performance for frequent reconnections
Getting YouTube Cookies (for age-restricted content)
-
Install browser extension
- Install Get cookies.txt LOCALLY for your browser
-
Go to YouTube and login
- Visit youtube.com
- Log in to your account (use a new/throwaway account)
-
Export cookies
- Click the extension icon
- Change export format to Netscape (cookies.txt)
- Save the file as
cookies/youtube.txtin the project root
The file will be read automatically by the yt-dlp extractor on startup.
Music Commands
| Command | Aliases | Description |
|---|---|---|
!play <song> |
- | Play a song or add to queue |
!skip |
- | Skip current track |
!pause |
- | Pause current track |
!resume |
- | Resume paused track |
!stop |
- | Stop music and clear queue |
!queue |
!q |
Show current queue |
!nowplaying |
!np, !current |
Show currently playing track |
!volume <1-100> |
!vol |
Set playback volume |
TikTok Bridge Commands
| Command | Aliases | Description |
|---|---|---|
!tiktok |
!tt, !bridge |
Show TikTok bridge status |
!tiktok stats |
- | Show detailed statistics |
!tiktok disconnect |
- | Disconnect TikTok bridge |
!tiktok reconnect |
- | Reconnect TikTok bridge |
Kunang-Kunang features a comprehensive logging system for monitoring and debugging bot operations.
| Level | Description | Use Case |
|---|---|---|
debug |
Detailed debugging information | Development and troubleshooting |
info |
General information | Normal operation monitoring |
success |
Successful operations | Confirming important actions |
warn |
Warning messages | Potential issues |
error |
Error messages | Failures and exceptions |
command |
Command executions | User command tracking |
reply |
Bot responses | Response monitoring |
Set the LOG_LEVEL environment variable to control verbosity:
LOG_LEVEL=debug # Show all log levels
LOG_LEVEL=info # Show info, success, warn, error, command, reply
LOG_LEVEL=warn # Show only warnings and errorsThe bot logs activities across multiple components:
- Bot Initialization: Startup sequence and component loading
- Command Processing: User commands and TikTok bridge commands
- Music Operations: Playback, queue management, and streaming
- Extractor Activities: Music source detection and processing (YouTube via yt-dlp)
- Web Overlay: Server operations and API requests
- TikTok Integration: Bridge connections and message processing
- Error Handling: Failures and recovery attempts
[15.26.56] [INFO] Logged in as BotName#0000
[15.26.57] [COMMAND] play - username
[15.26.58] [DEBUG] YouTubeExtractor: Processing YouTube URL...
[15.26.59] [SUCCESS] Connected to @tiktokuser
[15.27.00] [DEBUG] OverlayServer: NowPlaying API called - preset: 2
[15.27.01] [WARN] Queue is empty
[15.27.02] [ERROR] Failed to connect to TikTok
- Connect to TikTok Live: Bot connects to specified TikTok user's live stream
- Monitor Chat: Listens for commands in TikTok live chat
- Execute Commands: Processes commands and controls Discord music bot
- Cross-platform Control: TikTok viewers can control Discord music
Important: Without an API key, you may encounter rate limiting errors like:
Connection failed: [Rate Limited] (rate_limit_room_id_day) Too many connections started, try again later.
To avoid this, get a free API key from EulerStream and add it to your .env file as TIKTOK_SIGN_API_KEY.
Any Discord music command can be used in TikTok live chat but cant displayed in TikTok live chat
- Auto-reconnection with failure handling
- Statistics tracking (commands processed, uptime)
- Manual control via Discord commands
- Real-time monitoring and status display
- Error handling and logging
Kunang-Kunang includes a built-in web overlay system for streamers, displaying real-time music information that can be captured in OBS using browser source.
- Real-time Updates: Live display of currently playing track
- 4 Visual Presets: Different styles to match your stream aesthetic
- Transparent Design: Seamless integration with streaming software
- Queue Preview: Shows next tracks in queue
- Fixed Size: 400x80px optimized for streaming layouts
| Preset | Style | Theme | Best For |
|---|---|---|---|
| 1 | Vinyl | Classic dark with circular album art | Retro/music streams |
| 2 | Crystal Glass | Modern transparent glassmorphism | Professional/clean streams |
| 3 | Minimal Line | Geometric with green accents | Gaming/tech streams |
| 4 | Neon Pulse | Cyberpunk with cyan/magenta glow | Tech/coding streams |
Custom Overlay
You can customize the overlay by creating your own design using the API endpoint at /api/nowplaying, which provides real-time music data:
{
"title": "Song Title",
"author": "Artist Name",
"thumbnail": "image_url",
"duration": "3:45",
"progress": 45000,
"volume": 100,
"isPlaying": true,
"queue": [
{ "title": "Next Song 1", "author": "Artist 1" },
{ "title": "Next Song 2", "author": "Artist 2" }
]
}-
Add Browser Source in OBS:
- URL:
http://localhost:3000 - Width:
400 - Height:
80 - Check "Shutdown source when not visible"
- URL:
-
Configure preset in Configuration section below
-
Refresh browser source and start playing music!
Bot Settings (src/config.ts)
export default {
// Bot behavior
bot: {
prefix: "!", // Command prefix
activity: {
name: "Kunang-Kunang Music", // Bot activity text
type: 2, // Activity type (LISTENING)
},
},
// Music player settings
player: {
maxQueueSize: 100, // Maximum songs in queue
selfDeaf: true, // Bot deafens itself in voice channels
volume: 100, // Default volume (0-100)
quality: "high", // Audio quality: low, medium, high
// Leave options for voice channel
leaveOptions: {
leaveOnEnd: true, // Leave after queue finishes
leaveOnEndCooldown: 300000, // 5 minutes
leaveOnEmpty: true, // Leave when voice channel is empty
leaveOnEmptyCooldown: 300000, // 5 minutes
leaveOnStop: true, // Leave when player is stopped
leaveOnStopCooldown: 300000, // 5 minutes
},
},
// TikTok integration settings
tiktok: {
username: "", // TikTok username for live integration
maxReconnectAttempts: 3, // Max reconnection attempts
reconnectDelay: 5000, // Delay between reconnection attempts (ms)
enabled: false, // Enable/disable TikTok integration
},
// Web overlay settings
overlay: {
enabled: true, // Enable/disable overlay server
port: 3000, // Server port for overlay
pollingInterval: 1000, // Update frequency in ms
maxQueueDisplay: 3, // Number of queue items to display
preset: 2, // Visual preset: 1, 2, 3, or 4
},
};src/
├── commands/
│ ├── play.ts
│ ├── queue.ts
│ ├── nowplaying.ts
│ ├── skip.ts
│ ├── pause.ts
│ ├── resume.ts
│ ├── stop.ts
│ ├── volume.ts
│ ├── shuffle.ts
│ ├── leave.ts
│ ├── help.ts
│ └── tiktok-stats.ts
├── events/
│ ├── discord/
│ │ ├── index.ts
│ │ ├── clientEvents.ts
│ │ ├── playerEvents.ts
│ │ └── errorEvents.ts
│ └── discordEvents.ts
├── extractors/
│ ├── index.ts
│ └── GoogleVideoExtractor.ts
├── utils/
│ ├── logging.ts
│ ├── helpers.ts
│ ├── copy-overlay.ts
│ └── TikTokBridge.ts
├── web/
│ ├── server.ts
│ └── overlay/
│ ├── index.html
│ ├── css/
│ │ ├── preset1.css
│ │ ├── preset2.css
│ │ ├── preset3.css
│ │ └── preset4.css
│ └── js/
│ └── overlay.js
├── types/
│ ├── bot.ts
│ ├── command.ts
│ ├── discord.ts
│ └── tiktok.ts
├── config.ts
└── index.ts
- Create command file in
src/commands/ - Follow existing command structure:
import { Message } from "discord.js";
import { Command } from "../types/command.js";
const commandName: Command = {
name: "commandname",
aliases: ["alias1", "alias2"],
description: "Command description",
execute: async (message: Message, args: string[], bot: any): Promise<any> => {
// Command logic here
},
};
export default commandName;- Create extractor in
src/extractors/ - Add export to
src/extractors/index.ts:
import { YourExtractor } from "./YourExtractor.js";
export {
// ... existing exports
YourExtractor,
};- Register in
src/index.ts:
import { YourExtractor } from "./extractors/index.js";
await this.player.extractors.register(YourExtractor, {});Add event handlers in src/events/discordEvents.ts:
bot.player.events.on("eventName", (queue, data) => {
// Handle event
});- Advanced logging system with 7 configurable verbosity levels
- Comprehensive debug logging across all components
- Sending message when a command is triggered from TikTok
- Add other music platforms (YouTube, Spotify)
- Enhanced error handling and recovery
- Make TikTok chat assistant
- Add playlist support for all platforms
- Create web dashboard for bot management
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please open an issue or submit a pull request.
For support and questions:
- Create an issue on GitHub
- Check existing documentation
- I also speak Indonesian, so don't hesitate to make an issue or ask questions in Indonesian.
Kunang-Kunang bot music - adioss