A feature-rich Discord music bot with a web control panel — stream from YouTube with real-time queue management through both Discord slash commands and a browser interface.

• Play music from YouTube (search or direct URLs)
• Playlist support
• Queue management (add, remove, reorder, shuffle)
• Playback controls (play, pause, skip, stop)
• Loop controls
• Web UI with Discord OAuth authentication
• Real-time updates via Socket.io

src/
  config/              # Environment config
  core/                # musicManager, player, queue (central state)
  integrations/        # Spotify & YouTube integrations
  persistence/         # SQLite db.js + schema.sql
  services/            # playback, resolver, trackResolver, resolutionManager
  shared/              # formatTime, queueHelpers
  transports/
    discord/           # Discord.js client, voice, commands
    http/              # Express REST API (middleware, routes)
    realtime/          # Socket.io server
  utils/               # logger
  index.js             # Entry point

• Node.js 22+
• A Discord application with bot token
• FFmpeg (for audio processing)
• yt-dlp (for YouTube streaming)

# Linux/macOS (recommended)
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
chmod a+rx /usr/local/bin/yt-dlp

# Or via pip
pip install yt-dlp

# Verify installation
yt-dlp --version

YT_DLP_PATH is auto-detected (local ./bin/yt-dlp, Docker /app/bin/yt-dlp, or system yt-dlp). Set it manually only for custom paths.

npm install

Copy .env.sample to .env and fill in your credentials:

cp .env.sample .env

Required variables:

• DISCORD_TOKEN - Your bot token from Discord Developer Portal
• APP_ID - Your application ID
• GUILD_ID - Your Discord server ID (restricts web UI to this server's members)
• DISCORD_CLIENT_SECRET - OAuth client secret (for web UI)
• JWT_SECRET - Random string for JWT signing
• OAUTH_REDIRECT_URI - OAuth callback URL (Discord redirects here after login)
• WEB_URL - Frontend URL; used for CORS and as the destination the server redirects back to after the OAuth flow completes

Optional variables:

• TRUST_PROXY - Reverse-proxy hop count. Leave unset for direct local runs; set to 1 when running behind a single reverse proxy / Docker so the rate limiter sees the real client IP. It is a hop count, not a boolean — do not set it to true.
• LOG_LEVEL - error | warn | info | debug (default info).
• YT_DLP_MAX_CONCURRENCY (default 4), YT_DLP_MAX_QUEUE (default 50), YT_DLP_STREAM_TIMEOUT_MS (default 15000) - yt-dlp resource limits.

npm run register

npm start
# or for development with auto-reload:
npm run dev

The bot includes a web control panel accessible at http://localhost:5173 (or your configured WEB_URL).

Features:

• Discord OAuth login
• Real-time queue display
• Playback controls
• Search and add songs
• Drag-and-drop queue reordering

• GET /api/health - Health check
• GET /api/auth/discord - Start OAuth flow
• GET /api/auth/me - Get current user
• POST /api/auth/logout - End session
• GET /api/queue - Get queue
• POST /api/queue - Add track
• DELETE /api/queue/:position - Remove track
• PATCH /api/queue/reorder - Reorder tracks
• POST /api/queue/shuffle - Shuffle queue
• GET /api/queue/search - Search YouTube
• GET /api/queue/history - Get play history
• GET /api/player - Get player state
• POST /api/player/:action - Control playback

# Start with auto-reload
npm run dev

# Register commands globally
npm run register

For local UI development without configuring Discord OAuth redirect URLs, set:

• developerMode=true

When enabled, the API bypasses login and treats you as an authenticated Developer user.

YouTube frequently changes their systems. Keep yt-dlp updated to avoid streaming issues:

# Manual update
yt-dlp -U

# Or delete bin/yt-dlp and run npm run setup to re-download
rm bin/yt-dlp && npm run setup

For age-restricted content or rate limiting issues, export your YouTube cookies:

1. Use a browser extension to export cookies to a file
2. Set YT_DLP_COOKIES=/path/to/cookies.txt in your .env

MIT