kasperhonore/discord-music repository overview

⁠Discord Music Bot

A feature-rich Discord music bot with a built-in web control panel. Stream audio from YouTube and manage the queue in real time — from Discord slash commands or a browser. yt-dlp and ffmpeg are bundled in the image, so the only external dependency is a Discord application.

⁠Features

• 🎵 Play from YouTube (search terms or direct URLs) with playlist support
• 📋 Queue management — add, remove, reorder, shuffle, clear
• ⏯️ Playback controls — play, pause, skip, stop, loop (track/queue)
• 🖥️ Web control panel with Discord OAuth login and real-time updates (Socket.io)
• 💾 Persistent play history via SQLite
• 🔒 Web access restricted to members of your Discord server

⁠What's inside

• Node.js 22 runtime, ffmpeg, and yt-dlp (downloaded at build time)
• Express API + Socket.io + the pre-built web UI, all served on one port (3000)
• SQLite database stored at /app/data (mount a volume to persist it)

⁠Quick start

The container is configured entirely through environment variables. Create a .env file (see the variables below), then:

docker run -d \
  --name discord-music-bot \
  -p 3000:3000 \
  -v discord-music-bot-data:/app/data \
  --env-file .env \
  --restart unless-stopped \
  kasperhonore/discord-music:latest

⁠Register slash commands (one-off, first run only)

Discord slash commands must be registered once before they appear in your server:

docker run --rm --env-file .env kasperhonore/discord-music:latest npm run register

⁠docker-compose

services:
  music-bot:
    image: kasperhonore/discord-music:latest
    container_name: discord-music-bot
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - discord-music-bot-data:/app/data
      # - ./cookies.txt:/app/cookies.txt:ro   # optional, for age-restricted videos
    env_file:
      - .env
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:3000/api/health']
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  discord-music-bot-data:

Then register commands once with: docker compose run --rm music-bot npm run register.

⁠Configuration

⁠Required

⁠Common optional

yt-dlp and ffmpeg paths are auto-detected inside the image — no configuration needed.

⁠Ports & volumes

• Port 3000 — REST API, web control panel, and Socket.io
• Volume /app/data — SQLite database (mount to persist across restarts)
• Health check — GET /api/health

⁠Slash commands

/play · /pause · /resume · /skip · /stop · /queue · /nowplaying · /remove · /shuffle · /clear · /loop · /join · /leave · /webui

⁠Notes

• Keep an eye on streaming errors — YouTube changes often. Rebuilding the image pulls the latest yt-dlp; for age-restricted content, supply a cookies file via YT_DLP_COOKIES.
• Full setup, development instructions, and API reference live in the GitHub repository⁠.

⁠License

MIT