BeatDock Discord Music Bot

To play non-music videos or use autoplay/recommendations, YouTube's WEB client requires a short-lived poToken. BeatDock automates this process without requiring Google credentials:

1. bgutil-provider: A service that mints a {poToken, visitorData} pair using your server's own IP address.
2. pot-refresher: A service that pushes this token to Lavalink's POST /youtube hot-swap route on a loop. It re-pushes every POT_REFRESH_INTERVAL seconds (default 1800).

This allows for seamless token updates without restarting Lavalink. If the refresher is down, music playback (via MUSIC/ANDROID_VR clients) will continue to work, though age-restricted videos may become unavailable.

If you do not want to manage a Lavalink server, BeatDock can automatically connect to free public Lavalink v4 servers.

To use this mode, ensure the following environment variables are not set in your .env file:

• LAVALINK_HOST
• LAVALINK_PORT
• LAVALINK_PASSWORD

Note: When using public nodes, the automated YouTube poToken refresh mechanism (via bgutil-provider and pot-refresher) does not apply. Token management is handled by the public node operators. You can restrict which public hosts are used by setting the PUBLIC_NODE_HOST_ALLOWLIST variable.

# To use public servers, comment out these lines in your .env:
# LAVALINK_HOST=lavalink
# LAVALINK_PORT=2333
# LAVALINK_PASSWORD=youshallnotpass

Use standard Docker Compose commands to manage the bot lifecycle.

Important for Configuration Updates: If you modify application.yml, you must use the --force-recreate flag when bringing the containers up. Because application.yml is bind-mounted as a single file, Docker will not automatically detect changes to the file content unless the container is forced to recreate.

Portainer Users: Use Pull and redeploy with Re-pull image and redeploy enabled to ensure all containers are recreated and bind mounts are refreshed.

BeatDock is deployed using a multi-container Docker Compose setup consisting of the bot, lavalink, bgutil-provider, and pot-refresher services.

To run the stack, ensure you have a .env file in the same directory to provide necessary credentials and a scripts/pot-refresher.sh file for the token refresh mechanism. The lavalink service requires an application.yml file mounted from your host to /opt/Lavalink/application.yml.

docker compose up -d

Raspberry Pi 5 running Debian 13 may use a 16KB memory page size, which is incompatible with Lavalink's DAVE encryption library. Lavalink requires a 4096 page size.

1. Check page size: Run getconf PAGE_SIZE. If the output is not 4096, you must change the kernel configuration.
2. Apply fix: Add kernel=kernel8.img under the [all] section in /boot/firmware/config.txt.
3. Restart: Reboot the device and then restart your containers.

The bot service uses a file-based heartbeat mechanism to determine health. You can customize the path where the heartbeat file is located using the HEALTHCHECK_HEARTBEAT_PATH environment variable. The service considers itself healthy if the file's modification time is less than 120,000ms (2 minutes) old.

# Custom path for the heartbeat file (default: /tmp/beatdock-alive)
HEALTHCHECK_HEARTBEAT_PATH=/tmp/custom-heartbeat

The pot-refresher service automates the process of minting YouTube poToken and visitorData via the bgutil-provider and pushing them to Lavalink's POST /youtube hot-swap route. This prevents issues with non-music videos and autoplay/RD mixes.

You can control the frequency of these refreshes using the POT_REFRESH_INTERVAL environment variable.

# Password for the Lavalink instance
LAVALINK_PASSWORD=youshallnotpass

# Interval in seconds between poToken refreshes (default: 1800)
POT_REFRESH_INTERVAL=1800

The following slash commands are available for controlling the music bot:

The LanguageManager class handles multi-language support by loading JSON locale files from a locales directory. It supports a fallback mechanism to English (en) if a requested locale or key is missing.

Translations can include placeholders in the format {index} (e.g., {0}, {1}), which are replaced by arguments passed to the get method.

const LanguageManager = require('./LanguageManager');
const lm = new LanguageManager();

// Basic translation
const text = lm.get('en', 'welcome_message');

// Translation with placeholders
// If 'greet' in en.json is "Hello, {0}!"
const greeting = lm.get('en', 'greet', 'Alice'); // Returns "Hello, Alice!"

// Fallback to English if locale is missing
const fallbackText = lm.get('non-existent-locale', 'some_key');