A feature-rich Discord music bot with multi-platform support, rich embed UI, and utility commands — built with discord.js v14 and DisTube v5.
Supports YouTube, Spotify, Apple Music, SoundCloud, and 700+ other sites via yt-dlp.
- Play songs via URL or search query from YouTube, Spotify, Apple Music, SoundCloud, and 700+ more sites
- Full queue management — play, skip, stop, view queue, remove by position
- Loop modes — repeat off, repeat current song, repeat entire queue
- Shuffle upcoming songs in the queue
- YouTube playlist & radio/mix support (auto-capped at 25 tracks for infinite mixes)
- Spotify track, album, and playlist resolution (no API key needed)
- Apple Music track and album resolution via iTunes API with page-scraping fallback
- Scored best-match search — picks the most accurate YouTube result for Spotify/Apple Music tracks
- Progressive playlist loading — first song plays immediately while the rest load in the background
- Full song names, thumbnails, durations, requester info, and platform icons in all embeds
- Dual interface: slash commands (
/play,/skip, …) and prefix commands (^play,^skip, …) - Same-VC guard — all music commands require the user to be in the same voice channel as the bot
- Permission check — bot verifies it has
ConnectandSpeakpermission before joining a channel - Resume after forced disconnect — if the bot is kicked, it saves the full queue snapshot and sends a Resume button valid for 5 minutes; clicking it rejoins, restores the queue, and seeks back to the exact position
- Auto-pause when server-muted, auto-resume when unmuted
- Notified when moved to a different voice channel by an admin
- Auto-leave after 5 minutes idle (queue finished) or 3 minutes alone in a voice channel
- Skip button on every Now Playing embed
- Paginated queue view
- Consistent branded embeds with semantic colors (music pink, success green, error red, warning yellow)
- Centralized theme system (
utils/theme.js) — shared color palette, emoji icon kit, embed builders - Source-aware styling — YouTube red, Spotify green, Apple Music red, SoundCloud orange
- Graceful error handling with rich error embeds
- Minecraft server status lookup with player count bar (via mcstatus.io API)
- Bot info card with live stats (server count, uptime) and creator portfolio link
- A Discord bot application with a bot token
- Node.js v22+
- Python 3 (required by yt-dlp — usually pre-installed on Linux/macOS)
FFmpeg and yt-dlp are bundled via npm and require no manual install.
YouTube requires authentication to stream audio. Place a cookies.txt file (Netscape format) in the project root before starting the bot.
Export from your browser:
# If yt-dlp is installed locally (close the browser first on Windows):
yt-dlp --cookies-from-browser chrome --cookies cookies.txt "https://www.youtube.com"
yt-dlp --cookies-from-browser firefox --cookies cookies.txt "https://www.youtube.com"Or use the "Get cookies.txt LOCALLY" browser extension — visit youtube.com while signed in, click the extension, and export.
Then copy the file to the server if needed:
scp cookies.txt user@server:/path/to/Project-DekBot_v2/cookies.txtNote:
cookies.txtis gitignored and should never be committed. Re-export it when your session expires (typically every few months).
-
Clone and install
git clone https://github.com/hoanghero125/Project-DekBot_v2.git cd Project-DekBot_v2 npm install -
Configure environment
Create a
.envfile in the project root:BOT_TOKEN=your_bot_token_here CLIENT_ID=your_client_id_here GUILD_ID=your_guild_id_here PREFIX=^
GUILD_IDregisters slash commands instantly to that server (good for development). Remove it to register global commands instead (takes up to an hour to propagate). -
Register slash commands
npm run deploy
-
Start the bot
npm start
pm2 is the recommended way to run the bot persistently on a server:
npm install -g pm2
pm2 start main.js --name dekbot
pm2 save # persist across reboots
pm2 startup # generate the OS startup script| Command | Aliases | Description |
|---|---|---|
/play <query> |
^play, ^p |
Play a song or add it to the queue. Accepts URLs or search terms. |
/skip |
^skip, ^s |
Skip the current song |
/stop |
^stop |
Stop playback and clear the queue |
/queue |
^queue, ^q |
Show the current music queue |
/loop <mode> |
^loop, ^repeat |
Set repeat mode: off, song, or queue. No arg cycles through modes. |
/shuffle |
^shuffle |
Shuffle the upcoming songs in the queue |
/remove <position> |
^remove, ^rm |
Remove a song from the queue by its position number |
/help |
^help |
List all commands |
/mcsv <ip> [port] |
^mcsv |
Check a Minecraft server's status |
/info |
^info |
Show bot info, stats, and creator portfolio |
The bot uses a custom MusicPlugin (plugins/music-plugin.js) that routes URLs to the right handler:
| Source | Method |
|---|---|
| YouTube URLs & text searches | Direct yt-dlp resolution |
| YouTube playlists & mixes | yt-dlp with flat-playlist; radio mixes capped at 25 tracks |
| Spotify tracks | spotify-url-info → metadata → scored YouTube search |
| Spotify albums & playlists | Each track resolved individually via scored YouTube search |
| Apple Music tracks | iTunes API lookup → scored YouTube search |
| Apple Music albums | iTunes API lookup → per-track scored YouTube search |
| Apple Music (fallback) | Page scraping for og:title → YouTube search |
| All other URLs | yt-dlp (supports SoundCloud, Bandcamp, and 700+ sites) |
Scored search scrapes YouTube search results and picks the candidate that best matches the known artist + track name, avoiding mismatches on cover versions or lyric videos.
No Spotify API credentials are needed — spotify-url-info extracts metadata without authentication.
Project-DekBot_v2/
├── commands/
│ ├── help.js # /help — categorized command list
│ ├── info.js # /info — bot info & creator portfolio
│ ├── loop.js # /loop — repeat mode (off / song / queue)
│ ├── mcserver.js # /mcsv — Minecraft server status
│ ├── play.js # /play — music playback
│ ├── queue.js # /queue — queue display with pagination
│ ├── remove.js # /remove — remove a song by position
│ ├── shuffle.js # /shuffle — shuffle the queue
│ ├── skip.js # /skip — skip current song
│ └── stop.js # /stop — stop & clear queue
├── plugins/
│ ├── music-plugin.js # Custom DisTube plugin (YouTube, Spotify, Apple Music)
│ └── utils-bridge.js # Bridge for theme utilities in plugin context
├── utils/
│ └── theme.js # Centralized UI theme (colors, icons, embed builders)
├── deploy-commands.js # Slash command registration script
├── main.js # Bot entry point & DisTube event handlers
├── Dockerfile
├── docker-compose.yml
├── package.json
├── LICENSE
└── README.md
| Package | Purpose |
|---|---|
discord.js v14 |
Discord API client |
distube v5 |
Music framework |
@distube/yt-dlp |
YouTube & 700+ site extraction |
spotify-url-info |
Spotify metadata (no API key) |
mcstatus.io API |
Minecraft server pings (via fetch) |
@discordjs/voice + opusscript |
Voice connection & audio encoding |
ffmpeg-static |
Bundled FFmpeg binary |