Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
B

BeatDock

> 编程语言
Open source

Free, open-source, self-hosted Discord music bot with slash commands and Docker deployment. Features YouTube playback, queue management, and multilingual sup

198 stars0 likes3 views
WebsiteGitHub

About

Free, open-source, self-hosted Discord music bot with slash commands and Docker deployment. Features YouTube playback, queue management, and multilingual sup

BeatDock

A Discord music bot powered by Lavalink. Simple to deploy, easy to use.

Table of Contents

  • Features
  • Quick Start
  • Commands
  • Configuration
  • Managing the Bot
  • Troubleshooting
  • Built With
  • Contributing
  • Links
  • License

Features

  • Play music from YouTube, SoundCloud, Bandcamp, Twitch, and Vimeo
  • Optional Spotify support (search and resolve via YouTube)
  • Autoplay mode for continuous music playback
  • Queue management with shuffle, loop, and play-next
  • Interactive search with track selection
  • Deploy-time language selection (English, Spanish, Turkish, Italian, Brazilian Portuguese)
  • Role-based access control
  • Runs entirely in Docker, no host dependencies
  • Works without a self-hosted Lavalink server (automatic public server fallback)

Quick Start

Prerequisites

  • A Discord bot token from the Developer Portal
  • Docker installed

When creating your bot, enable all 3 Privileged Gateway Intents (Presence, Server Members, Message Content).

Option A: Deploy with Docker (recommended)

Uses the pre-built GHCR image, no cloning needed.

1. Create a project directory:

bash
mkdir beatdock && cd beatdock

2. Create .env:

env
TOKEN=your_discord_bot_token

3. Create docker-compose.yml:

…

4. Create application.yml:

…

5. Add the poToken refresher script:

Download scripts/pot-refresher.sh into a scripts/ folder next to your docker-compose.yml. It mints a fresh YouTube poToken and hot-pushes it to Lavalink (see YouTube poToken auto-refresh).

6. Deploy:

bash
docker compose up -d

YouTube poToken auto-refresh

Playing arbitrary (non-music) videos and autoplay/RD-mix recommendations requires YouTube's WEB client, which needs a short-lived poToken. BeatDock keeps this fully automated and credential-free — no Google account, no API key, no manual pasting:

  • bgutil-provider mints a {poToken, visitorData} pair on your server's own IP.
  • pot-refresher pushes it to Lavalink's POST /youtube hot-swap route (no restart) and re-pushes every POT_REFRESH_INTERVAL seconds (default 1800), covering both token expiry and Lavalink restarts.

Music keeps working through the MUSIC/ANDROID_VR clients even if the refresher is temporarily down. Age-restricted videos may still be unavailable.

Note: this only applies to the self-hosted stack. If BeatDock connects to public Lavalink nodes (no LAVALINK_HOST set), tokens are managed by each node's operator, so the bgutil-provider and pot-refresher services are not used and non-music playback depends on the node.

Option B: Deploy from Source

bash
git clone https://github.com/albertgmz/BeatDock.git
cd BeatDock

Create .env with your credentials (see .env.example for all options):

env
TOKEN=your_discord_bot_token
bash
docker compose up -d

No Self-Hosted Lavalink Required

BeatDock can run without a self-hosted Lavalink server. If LAVALINK_HOST, LAVALINK_PORT, and LAVALINK_PASSWORD are not set, the bot automatically fetches free public Lavalink v4 servers and connects to one. User search queries and track requests are sent to the selected public node. Set PUBLIC_NODE_HOST_ALLOWLIST if you only trust specific public Lavalink hosts.

On public nodes the YouTube poToken auto-refresh does not apply: each node manages its own tokens, so whether non-music videos and autoplay mixes play depends on that node's setup.

To use public servers, simply comment out the Lavalink variables in your .env:

env
# LAVALINK_HOST=lavalink
# LAVALINK_PORT=2333
# LAVALINK_PASSWORD=youshallnotpass

Commands

Command Description
/play [next] Play a song (optionally add to front of queue)
/search Search and select tracks
/pause Pause/resume
/skip Skip track
/back Previous track
/stop Stop and disconnect
/queue Show queue
/shuffle Shuffle queue
/autoplay Toggle autoplay mode
/loop Toggle loop mode
/clear Clear queue
/volume Set volume
/lyrics Show lyrics for the current song
/filter Apply audio effects and EQ presets
/nowplaying Current track info
/invite Get bot invite link
/about Bot info

Configuration

All configuration is done through the .env file. Only TOKEN is required.

Variable Default Description
TOKEN - Discord bot token (required)
SPOTIFY_ENABLED false Enable Spotify search support
SPOTIFY_CLIENT_ID - Spotify app client ID
SPOTIFY_CLIENT_SECRET - Spotify app client secret
DEFAULT_LANGUAGE en Global bot language for this deployment (en, es, tr, it, pt-BR)
DEFAULT_VOLUME 80 Default playback volume (0-100)
AUTOPLAY_DEFAULT false Enable autoplay by default when music starts
ALLOWED_ROLES - Comma-separated role IDs to restrict access
DEFAULT_SEARCH_PLATFORM ytmsearch Default search platform for user queries
LAVALINK_PASSWORD youshallnotpass Lavalink server password
PUBLIC_NODE_HOST_ALLOWLIST - Optional comma-separated host or *.domain allowlist for public Lavalink fallback
QUEUE_EMPTY_DESTROY_MS 30000 Disconnect after queue empties (ms)
EMPTY_CHANNEL_DESTROY_MS 60000 Disconnect from empty channel (ms)

Managing the Bot

bash
docker compose logs -f                              # View logs
docker compose restart                              # Restart
docker compose down                                 # Stop
docker compose pull && docker compose up -d --force-recreate   # Update

--force-recreate is required, not optional: application.yml is bind-mounted as a single file, and Docker binds single files by inode. docker compose restart reuses the container, and a plain docker compose up -d only recreates services whose image or compose config changed - so neither picks up an edited application.yml, and Lavalink keeps serving the old one indefinitely.

On Portainer, use Pull and redeploy with Re-pull image and redeploy enabled; that is the only stack action that recreates every container and remounts the bind against the freshly cloned repository. If you use GitOps auto-updates, enable Force redeployment too, otherwise config-only changes will never reach the container.

Troubleshooting

All YouTube tracks fail to play

YouTube periodically blocks the clients Lavalink uses. Check which clients loaded and whether they are being blocked:

bash
docker compose logs lavalink | grep -i "YouTube source initialised with clients"
docker compose logs lavalink | grep -iE "AllClientsFailedException|Sign in to confirm|requires login"

If the client list does not match application.yml, the container is still running an old config - recreate it (see Managing the Bot):

bash
docker compose up -d --force-recreate lavalink

Note that MUSIC initialises under the name WEB_REMIX; that is expected, not drift.

To keep the bot usable while waiting on an upstream fix, switch the default source to SoundCloud in .env and restart the bot:

env
DEFAULT_SEARCH_PLATFORM=scsearch
bash
docker compose restart bot

Autoplay is YouTube-only and stays idle while SoundCloud is the default source.

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. Check with:

bash
getconf PAGE_SIZE

If the result is not 4096, add kernel=kernel8.img under the [all] section in /boot/firmware/config.txt, then reboot and restart the containers. See #109 for details.

Built With

  • discord.js - Discord API client
  • Lavalink - Audio player server
  • lavalink-client - Lavalink client library
  • Docker - Containerized deployment
  • Node.js 22+ - Runtime

Contributing

Contributions are welcome. Bug fixes, new features, translations, docs - all good. Check the guide below to get started.

See CONTRIBUTING.md for setup instructions and guidelines.

Links

  • Website
  • Issues
  • Changelog

License

Apache-2.0

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

JavaScriptdiscorddiscord-botdiscord-jslavalink

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言