Discord Music Bot

BEATDOCK

Modern Discord Music Bot with High-Quality Audio
Slash Commands • Multi-Language • Docker Ready • Interactive Search

Quick Start View on GitHub
High-Quality Audio
Interactive Search
Multi-Language
Docker Ready

POWERFUL FEATURES

Everything you need for the perfect music experience

High-Quality Audio

Powered by Lavalink for crystal-clear music playback with minimal latency and robust connection management

Interactive Search

Advanced search with pagination, multi-selection, and visual navigation for discovering new music

Modern Slash Commands

Discord.js v14 slash commands with auto-completion and parameter validation for ease of use

Multi-Language Support

Built-in support for English, Spanish, and Turkish with easy extensibility for additional languages

Visual Player Controller

Rich embeds with interactive buttons for complete playback control and queue management

One-Command Deployment

Deploy instantly with Docker Compose using official pre-built images - no complex setup required

Role-Based Permissions

Flexible permission system with admin override and role-based access control for server management

Optional Spotify Integration

Smart track resolution with ISRC matching for accurate Spotify track discovery and playback

Stateless Design

No database required - perfect for containerized deployments with automatic queue state management

COMPLETE COMMAND SET

12 comprehensive slash commands for total music control

/play Essential

Play music from URL or search query

Parameters: <query> - Song URL or search terms
Example: /play Rick Astley Never Gonna Give You Up
/pause Control

Toggle pause/resume playback

Example: /pause
/skip Playback

Skip to the next track in queue

Example: /skip
/back Playback

Play the previous track from history

Example: /back
/stop Control

Stop playback and disconnect from voice channel

Example: /stop
/volume Control

Adjust playback volume

Parameters: <level> - Volume level (1-100)
Example: /volume 75
/search Interactive

Interactive search with pagination and multi-selection

Parameters: <query> - Search terms (max 200 characters)
Example: /search ambient music
/queue Info

Display current queue with pagination

Example: /queue
/clear Queue

Clear the entire queue

Example: /clear
/shuffle Queue

Shuffle the current queue randomly

Example: /shuffle
/loop Queue

Cycle through loop modes (off → track → queue)

Example: /loop
/nowplaying Info

Show detailed information about the current track

Example: /nowplaying

🎛️ Advanced Features

Interactive Search

Browse search results with navigation buttons, select multiple tracks, and add them to the queue with visual feedback.

Visual Player Controller

Automatic player interface with interactive buttons for all playback controls and real-time status updates.

Loop Modes

Off - No looping | Track - Loop current track | Queue - Loop entire queue

Permission System

All commands respect role-based permissions with admin override functionality.

CRITICAL REQUIREMENTS

Essential setup before deployment

🔒 Discord Privileged Gateway Intents Required

BeatDock requires ALL THREE Discord Privileged Gateway Intents to function properly:

Presence Intent
User presence information
Server Members Intent
Server member data access
Message Content Intent
Message content access
How to enable:
  1. Go to Discord Developer Portal
  2. Select your bot application → "Bot" → "Privileged Gateway Intents"
  3. Enable all three toggles → "Save Changes"
The bot will not start without these intents enabled.

📋 System Requirements

Node.js ≥22.16.0
npm ≥11.4.2
Docker (for deployment)
Discord Bot Token

QUICK SETUP

Deploy BeatDock in just 4 simple steps

1

Clone Repository

Download the BeatDock source code to your server

git clone https://github.com/lazaroagomez/BeatDock.git
cd BeatDock
2

Configure Environment

Create .env file with your Discord bot credentials

# Copy the example file
cp .env.example .env

# Edit with your credentials
# Discord Bot Configuration (Required)
TOKEN=your_discord_bot_token_here
CLIENT_ID=your_discord_client_id_here

# Lavalink Configuration
LAVALINK_HOST=lavalink
LAVALINK_PORT=2333
LAVALINK_PASSWORD=youshallnotpass

# Optional: Spotify Integration
SPOTIFY_ENABLED=false
SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here

# Optional: Additional Settings
DEFAULT_LANGUAGE=en
DEFAULT_VOLUME=80
ALLOWED_ROLES=
Get your Discord credentials from the Discord Developer Portal
3

Deploy Commands

Register slash commands with Discord

docker compose run --rm bot npm run deploy
This step must be completed before starting the bot to register commands with Discord
4

Start BeatDock

Launch the bot and Lavalink server with Docker Compose

# Start all services
docker compose up -d

# View logs (optional)
docker compose logs -f
BeatDock is now running! The bot will automatically connect to your Discord server.

🐳 Docker Management

Stop Services
docker compose down
Restart Services
docker compose restart
View Logs
docker compose logs -f
Update Bot
docker compose pull && docker compose up -d

CONFIGURATION REFERENCE

Complete .env file template

GNU nano 6.2
.env
Modified
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 
# =============================================================================
# BEATDOCK CONFIGURATION FILE
# =============================================================================

# Discord Bot Configuration (Required)
TOKEN=your_discord_bot_token_here
CLIENT_ID=123456789012345678

# Lavalink Configuration (Required for Docker setup)
LAVALINK_HOST=lavalink
LAVALINK_PORT=2333
LAVALINK_PASSWORD=youshallnotpass

# Optional: Spotify Integration
SPOTIFY_ENABLED=false
SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here

# Optional: Bot Behavior Settings
DEFAULT_LANGUAGE=en
QUEUE_EMPTY_DESTROY_MS=30000
EMPTY_CHANNEL_DESTROY_MS=60000
DEFAULT_VOLUME=80
ALLOWED_ROLES=

# Optional: Advanced Lavalink Reconnection Settings
LAVALINK_MAX_RECONNECT_ATTEMPTS=10
LAVALINK_BASE_DELAY_MS=1000
LAVALINK_MAX_DELAY_MS=30000
LAVALINK_HEALTH_CHECK_INTERVAL_MS=30000
LAVALINK_RESET_ATTEMPTS_AFTER_MINUTES=5

# =============================================================================
# END OF CONFIGURATION
# =============================================================================

Configuration Guide

Required Variables
  • TOKEN - Discord bot token from Developer Portal
  • CLIENT_ID - Discord application/client ID
Permission System
  • Empty ALLOWED_ROLES: Everyone can use the bot
  • Admin Override: Administrators always have access
  • Role-Based: Only specified roles can use the bot
Language Options
  • en - English (default)
  • es - Spanish
  • tr - Turkish
Spotify Integration
  • Get credentials from Spotify Dashboard
  • Enable ISRC matching for accurate track resolution
  • Optional feature - bot works without it