Features Commands Setup Config Help GitHub
DISCORD MUSIC BOT

BEATDOCK

Drop the beat. Control the vibe.
High-quality audio powered by Lavalink.

17 Commands
4 Languages
∞ Vibes
Quick Start View Source
Discord.js v14 Lavalink Docker Node.js 22+
SCROLL
// CAPABILITIES

Power Features

Everything you need for the ultimate music experience

High-Quality Audio

Crystal-clear playback powered by Lavalink with minimal latency and robust connection management.

Interactive Search

Browse results with navigation buttons, select multiple tracks, and build your perfect queue.

Slash Commands

Modern Discord.js v14 slash commands with auto-completion and parameter validation.

Multi-Language

Built-in support for English, Spanish, Turkish, and Italian with easy extensibility.

Visual Controller

Rich embeds with interactive buttons for complete playback control.

Docker Ready

Deploy instantly with Docker Compose using official pre-built images.

Role Permissions

Flexible permission system with admin override and role-based access control.

Spotify Integration

Smart track resolution with ISRC matching for accurate Spotify playback.

Stateless Design

No database required - perfect for containerized deployments.

Zero Config Lavalink

No self-hosted Lavalink needed. Automatically connects to free public servers with automatic failover.

Autoplay Mode

Continuous music playback that automatically finds and plays related tracks when your queue ends.

// ARSENAL

Commands

17 powerful slash commands at your fingertips

Playback Control

/play Essential

Play music from URL or search query

Usage: /play Rick Astley Never Gonna Give You Up
/pause Control

Toggle pause/resume playback

/skip Playback

Skip to the next track in queue

/back Playback

Play the previous track from history

/stop Stop

Stop playback and disconnect

/volume Control

Adjust playback volume (1-100)

Usage: /volume 75
/filter Interactive

Apply audio effects and EQ presets

Effects EQ Presets Toggle

Search & Discovery

/search Interactive

Interactive search with pagination and multi-selection

Usage: /search ambient music
Pagination Multi-select Quick add
/lyrics Info

Show lyrics for the currently playing song

Queue Management

/queue Info

Display current queue with pagination

/clear Clear

Clear the entire queue

/shuffle Shuffle

Shuffle the current queue randomly

/autoplay Toggle

Toggle autoplay for continuous related tracks

/loop Toggle

Cycle: off → track → queue

/nowplaying Info

Show current track details

Information

/invite Info

Get a link to invite BeatDock to your server

/about Info

Display bot info, stats, version, and system details

Version Uptime Latency
// INSTALLATION

Quick Setup

Get BeatDock running in 4 simple steps

Required: Discord Gateway Intents

Enable these in Discord Developer Portal → Bot → Privileged Gateway Intents:

Presence Intent Server Members Intent Message Content Intent
01

Clone Repository

Terminal
$ git clone https://github.com/lazaroagomez/BeatDock.git
$ cd BeatDock
02

Configure Environment

.env
# Required
TOKEN=your_discord_bot_token
 
# Lavalink — optional, leave empty for free public servers
# LAVALINK_HOST=lavalink
# LAVALINK_PORT=2333
# LAVALINK_PASSWORD=youshallnotpass
03

Launch BeatDock

Terminal
$ docker compose up -d
BeatDock is now running!

Docker Quick Reference

Stop docker compose down
Restart docker compose restart
Logs docker compose logs -f
Update docker compose pull && docker compose up -d
// TROUBLESHOOTING

Common Issues

Solutions for known platform-specific problems

Audio not working on Raspberry Pi

Raspberry Pi 5 (Debian 13) may use a 16KB memory page size, which is incompatible with Lavalink's DAVE encryption library (libdave.jvm.so), compiled for 4KB pages.

1. Check your page size:

Terminal
$ getconf PAGE_SIZE

If the result is not 4096:

2. Fix by switching to a 4KB kernel:

Terminal
# Add kernel=kernel8.img under [all] in boot config
$ sudo nano /boot/firmware/config.txt
$ sudo reboot
 
# Then restart BeatDock
$ docker compose down && docker compose up -d
See issue #109 for the full discussion and details. Thanks to @Kru3mel for reporting this fix.
// CONFIGURATION

Environment Variables

Complete configuration reference

Required

TOKEN Discord bot token from Developer Portal

Lavalink Optional — leave empty to use free public servers

LAVALINK_HOST lavalink Lavalink server hostname
LAVALINK_PORT 2333 Lavalink server port
LAVALINK_PASSWORD youshallnotpass Lavalink server password

Spotify (Optional)

SPOTIFY_ENABLED false Enable Spotify integration
SPOTIFY_CLIENT_ID Spotify application client ID
SPOTIFY_CLIENT_SECRET Spotify application client secret

Bot Behavior

DEFAULT_LANGUAGE en Default language (en/es/tr/it)
DEFAULT_VOLUME 80 Default playback volume (0-100)
ALLOWED_ROLES empty Comma-separated role IDs (empty = everyone)
AUTOPLAY_DEFAULT false Enable autoplay by default when music starts
QUEUE_EMPTY_DESTROY_MS 30000 Leave after queue empty (ms)
EMPTY_CHANNEL_DESTROY_MS 60000 Leave empty channel after (ms)
DEFAULT_SEARCH_PLATFORM ytmsearch Default search platform (ytsearch, ytmsearch, etc.)
Permission System: Empty ALLOWED_ROLES = everyone can use the bot. Administrators always have access regardless of role settings.