### Install Dependencies and Run Locally

Source: https://github.com/lazaroagomez/beatdock/wiki/Installation

Install project dependencies using npm, start Lavalink via Docker, and then deploy commands and start the bot locally.

```bash
npm install

# Start Lavalink via Docker (or run it locally with Java)
docker compose up -d lavalink

# Update .env: LAVALINK_HOST=localhost

npm run deploy
npm start
```

--------------------------------

### Clone Repository and Setup Environment

Source: https://github.com/lazaroagomez/beatdock/wiki/Installation

Clone the BeatDock repository, navigate into the directory, and copy the example environment file to create your own configuration file.

```bash
git clone https://github.com/lazaroagomez/BeatDock.git
cd BeatDock
cp .env.example .env
```

--------------------------------

### Install Docker on Ubuntu/Debian

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Installs Docker, adds the user to the docker group, and enables Docker to start on boot.

```bash
sudo apt update

curl -fsSL https://get.docker.com | sh

sudo usermod -aG docker $USER

sudo systemctl enable docker
sudo systemctl start docker
```

--------------------------------

### Install Docker on Arch Linux

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Installs Docker and Docker Compose, enables Docker to start on boot, and adds the user to the docker group.

```bash
sudo pacman -S docker docker-compose
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER
```

--------------------------------

### Install Docker on Fedora

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Installs Docker and Docker Compose plugin, enables Docker to start on boot, and adds the user to the docker group.

```bash
sudo dnf install docker docker-compose-plugin
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER
```

--------------------------------

### Enable and Start Systemd Service

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Reloads systemd, enables the BeatDock service to start on boot, and starts the service immediately.

```bash
sudo systemctl daemon-reload
sudo systemctl enable beatdock
sudo systemctl start beatdock
```

--------------------------------

### Install Docker in WSL

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Installs Docker Engine, adds the user to the docker group, and starts the Docker service within the WSL environment.

```bash
# Update packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Start Docker
sudo service docker start
```

--------------------------------

### BeatDock Command Examples

Source: https://github.com/lazaroagomez/beatdock/wiki/Usage

A collection of example commands for playing music, searching, adjusting volume, and managing the loop mode in BeatDock.

```bash
/play never gonna give you up
```

```bash
/play https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

```bash
/search lofi beats
```

```bash
/volume 50
```

```bash
/loop
```

--------------------------------

### Troubleshoot Docker Not Starting

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Command to manually start the Docker service if it fails to start automatically.

```bash
sudo service docker start
```

--------------------------------

### Install and Configure WSL 2

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Install the Windows Subsystem for Linux and set WSL 2 as the default version if it wasn't enabled during Docker Desktop installation.

```powershell
wsl --install
wsl --set-default-version 2
```

--------------------------------

### Install Node.js and Dependencies for Running Without Docker

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Installs Node.js version 22+ and then installs project dependencies using npm.

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

npm install
```

--------------------------------

### Clone Project and Set Up Environment

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Clone the BeatDock repository and copy the example environment file to create your own configuration. Remember to edit the .env file with your specific Discord credentials.

```bash
git clone https://github.com/lazaroagomez/BeatDock.git
cd BeatDock
copy .env.example .env
```

```env
TOKEN=your_discord_bot_token
CLIENT_ID=your_discord_application_id
```

--------------------------------

### Deploy and Start BeatDock

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Use Docker Compose to register slash commands for the bot and then start the application services in detached mode.

```bash
# Register slash commands
docker compose run --rm bot npm run deploy

# Start the bot
docker compose up -d
```

--------------------------------

### Configure and Start BeatDock Without Docker

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Starts Lavalink using Docker (if preferred), updates the .env file to point to localhost for Lavalink, deploys commands, and starts the bot.

```bash
# Run Lavalink separately (requires Java 17+)
# Or use Docker for Lavalink only
docker compose up -d lavalink

# Update .env: LAVALINK_HOST=localhost

# Deploy and start
npm run deploy
npm start
```

--------------------------------

### Install Docker on Raspberry Pi

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Installs Docker using the official convenience script and adds the current user to the docker group. Log out and back in after execution.

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
sudo systemctl enable docker
```

--------------------------------

### Deploy and Start BeatDock

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Deploys and starts BeatDock using Docker Compose. Docker will automatically pull the correct ARM64 images for your architecture.

```bash
docker compose run --rm bot npm run deploy
docker compose up -d
```

--------------------------------

### Install WSL 2

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Installs WSL 2 with Ubuntu by default. Restart your computer when prompted.

```powershell
wsl --install
```

--------------------------------

### Auto-start Docker on WSL Boot

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Configures the system to automatically start the Docker service when WSL boots up, preventing manual starts.

```bash
# Auto-start Docker
if ! pgrep -x "dockerd" > /dev/null;
    sudo service docker start
fi
```

--------------------------------

### Deploy and Start BeatDock Bot

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Registers slash commands and starts the BeatDock bot in detached mode using Docker Compose.

```bash
docker compose run --rm bot npm run deploy

docker compose up -d
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Check if Docker and Docker Compose are installed and accessible in your environment.

```powershell
docker --version
docker compose version
```

--------------------------------

### Deploy BeatDock with Docker

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

Execute this command to build and start the BeatDock bot and its Lavalink dependency in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Enable BeatDock Systemd Service

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Reloads the systemd manager configuration and enables the BeatDock service to start automatically on system boot.

```bash
sudo systemctl daemon-reload
sudo systemctl enable beatdock
```

--------------------------------

### Clone BeatDock and Configure Environment

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Clones the BeatDock repository, navigates into the directory, and copies the example environment file. Configure the .env file with your Discord bot token and client ID.

```bash
git clone https://github.com/lazaroagomez/BeatDock.git
cd BeatDock
cp .env.example .env
nano .env
```

--------------------------------

### Deploy Bot with Docker

Source: https://github.com/lazaroagomez/beatdock/wiki/Installation

Use Docker Compose to deploy slash commands and start the bot in detached mode. Verify the deployment by checking the logs and the running processes.

```bash
docker compose run --rm bot npm run deploy
docker compose up -d
```

```bash
docker compose logs -f
docker compose ps
```

--------------------------------

### Check WSL Status

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Verify if WSL 2 is installed and running on your system.

```powershell
wsl --status
```

--------------------------------

### Set WSL 2 as Default

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Configures WSL 2 as the default version for new installations.

```powershell
wsl --set-default-version 2
```

--------------------------------

### Get Docker and System Environment Information

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Retrieve version information for Docker and Docker Compose, along with system details, to help diagnose environment-specific issues.

```bash
docker --version
docker compose version
uname -a
```

--------------------------------

### Configure Passwordless Sudo for Docker Service

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Allows the Docker service to be started without a password prompt by adding an entry to the sudoers file.

```bash
%docker ALL=(ALL) NOPASSWD: /usr/sbin/service docker start
```

--------------------------------

### Systemd Service Configuration for BeatDock

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Defines a systemd service to manage the BeatDock Docker Compose application, ensuring it starts on boot.

```ini
[Unit]
Description=BeatDock Discord Music Bot
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/path/to/BeatDock
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=yourusername

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Create BeatDock Systemd Service

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Defines a systemd service file to manage the BeatDock Docker Compose application, enabling it to start automatically on boot.

```ini
[Unit]
Description=BeatDock Discord Music Bot
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/pi/BeatDock
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=pi

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Docker Compose Management Commands

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Essential Docker Compose commands for managing the BeatDock application stack, including starting, logging, restarting, updating, and stopping services. Also includes instructions for building the Docker image locally and running the application without Docker.

```bash
# Start the full stack (bot + Lavalink)
docker compose up -d

# Follow live logs from both containers
docker compose logs -f

# Follow only bot logs
docker compose logs -f bot

# Restart both services
docker compose restart

# Pull latest images and redeploy
docker compose pull && docker compose up -d

# Stop and remove containers (data is stateless, no volumes to worry about)
docker compose down

# Build from source instead of GHCR image
docker build -t beatdock:local .
# Then change image: to beatdock:local in docker-compose.yml

# Run from source without Docker
npm install
node src/index.js
```

--------------------------------

### Basic Docker Compose Management Commands

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

These commands are used to manage the BeatDock and Lavalink services deployed via Docker Compose. They cover starting, viewing logs, updating, and stopping the services.

```bash
# Start
docker compose up -d

# View logs
docker compose logs -f

# Update to latest image
docker compose pull && docker compose up -d

# Stop
docker compose down
```

--------------------------------

### Manage BeatDock Bot with Docker Compose

Source: https://github.com/lazaroagomez/beatdock/blob/main/docs/index.html

Use these Docker Compose commands to view logs, restart, stop, or update the BeatDock bot. Ensure Docker is installed and the compose file is present.

```bash
docker compose logs -f          # View logs
```

```bash
docker compose restart          # Restart
```

```bash
docker compose down             # Stop
```

```bash
docker compose pull && \
  docker compose up -d          # Update to latest
```

--------------------------------

### Create Project Directory

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

Use this command to create a new directory for your BeatDock project and navigate into it.

```bash
mkdir beatdock && cd beatdock
```

--------------------------------

### Discord Bot Bootstrap (`src/index.js`)

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Initializes a Discord client with necessary intents, sets up i18n, resolves Lavalink nodes, registers event handlers, loads commands, and handles graceful shutdown. Ensure environment variables like TOKEN, LAVALINK_HOST, LAVALINK_PORT, and LAVALINK_PASSWORD are set.

```javascript
// src/index.js (simplified illustration)
require('dotenv').config();
const { Client, GatewayIntentBits } = require('discord.js');
const { LavalinkManager } = require('lavalink-client');

async function bootstrap() {
    // 1. Create Discord client with required intents
    const client = new Client({
        intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
    });

    // 2. Attach i18n helper: client.t('SONG_ADDED', 'Never Gonna Give You Up')
    client.languageManager = new LanguageManager();
    client.defaultLanguage = process.env.DEFAULT_LANGUAGE || 'en';
    client.t = (key, ...args) => client.languageManager.get(client.defaultLanguage, key, ...args);

    // 3. Resolve Lavalink node (local or public)
    //    - If LAVALINK_HOST + LAVALINK_PORT + LAVALINK_PASSWORD are all set → use local node
    //    - Otherwise → fetch public v4 nodes from lavalink-list API with auto-rotation
    await setupLavalink(client);  // attaches client.lavalink (LavalinkManager)

    // 4. Register Lavalink event handlers (trackStart, trackEnd, queueEnd, trackError, trackStuck)
    registerLavalinkEvents(client);

    // 5. Load slash commands from src/commands/*.js into client.commands Map
    loadCommands(client);

    // 6. Register Discord gateway events from src/events/*.js
    registerEvents(client);

    // 7. Graceful shutdown on SIGINT / SIGTERM
    setupShutdown(client);  // destroys players, nodes, search sessions

    // 8. Login
    await client.login(process.env.TOKEN);
}

bootstrap().catch(err => { console.error(err); process.exit(1); });

```

--------------------------------

### Clone and Deploy BeatDock with Docker

Source: https://github.com/lazaroagomez/beatdock/wiki/Home

Clone the repository, configure your environment variables, and deploy the bot using Docker Compose. This command also deploys slash commands.

```bash
git clone https://github.com/lazaroagomez/BeatDock.git && cd BeatDock
cp .env.example .env  # Edit with your Discord token and client ID
docker compose run --rm bot npm run deploy && docker compose up -d
```

--------------------------------

### Environment Configuration for BeatDock

Source: https://github.com/lazaroagomez/beatdock/blob/main/docs/index.html

Configure BeatDock by setting environment variables in a .env file. Essential variables include the Discord bot token. Optional variables control Spotify integration, default playback settings, language, access control, Lavalink connection, and timeouts.

```dotenv
# Required
TOKEN=your_discord_bot_token

# Spotify (optional)
SPOTIFY_ENABLED=false
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=

# Playback
DEFAULT_VOLUME=80
AUTOPLAY_DEFAULT=false
DEFAULT_SEARCH_PLATFORM=ytmsearch

# Language: en, es, tr, it
DEFAULT_LANGUAGE=en

# Access control (optional)
# ALLOWED_ROLES=role_id_1,role_id_2

# Lavalink (leave commented for public server fallback)
# LAVALINK_HOST=lavalink
# LAVALINK_PORT=2333
# LAVALINK_PASSWORD=youshallnotpass

# Timeouts
QUEUE_EMPTY_DESTROY_MS=30000
EMPTY_CHANNEL_DESTROY_MS=60000
```

--------------------------------

### Enable Spotify Integration in BeatDock

Source: https://github.com/lazaroagomez/beatdock/wiki/Usage

Configure Spotify integration in the .env file by setting SPOTIFY_ENABLED to true and providing your Spotify client ID and secret. This allows BeatDock to resolve Spotify links to YouTube tracks.

```env
SPOTIFY_ENABLED=true
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
```

--------------------------------

### Limit Container Memory Usage

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Configure resource limits for a Docker service within your `docker-compose.yml` file. This example sets a memory limit of 512MB for the bot service.

```yaml
services:
  bot:
    deploy:
      resources:
        limits:
          memory: 512M
```

--------------------------------

### Environment Variables for BeatDock Configuration

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

This file configures essential settings for BeatDock, including the Discord bot token and optional Spotify support. It also allows customization of language, volume, autoplay, access roles, search platforms, and Lavalink reconnection parameters.

```bash
# .env — minimum required configuration
TOKEN=your_discord_bot_token_here

# Optional Spotify support
# SPOTIFY_ENABLED=true
# SPOTIFY_CLIENT_ID=your_spotify_client_id
# SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Optional: use public Lavalink nodes instead of self-hosted (comment out all three to enable)
# LAVALINK_HOST=lavalink
# LAVALINK_PORT=2333
# LAVALINK_PASSWORD=youshallnotpass

# Other optional settings
DEFAULT_LANGUAGE=en           # en | es | tr | it | pt-BR
DEFAULT_VOLUME=80             # 0-100
AUTOPLAY_DEFAULT=false
ALLOWED_ROLES=                # comma-separated role IDs; empty = everyone
DEFAULT_SEARCH_PLATFORM=ytmsearch  # ytmsearch | ytsearch | scsearch | ...
QUEUE_EMPTY_DESTROY_MS=30000
EMPTY_CHANNEL_DESTROY_MS=60000
LOG_LEVEL=info                # debug | info | warn | error

# Lavalink reconnection tuning
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
```

--------------------------------

### Deploy BeatDock with Docker

Source: https://github.com/lazaroagomez/beatdock/blob/main/docs/index.html

Deploy BeatDock using Docker Compose. Ensure your .env and docker-compose.yml files are in the directory before running the command.

```bash
mkdir beatdock && cd beatdock

# Add your .env and docker-compose.yml, then:
docker compose up -d
```

--------------------------------

### Configure .env File

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Sets the Discord bot token and application client ID in the .env file.

```env
TOKEN=your_discord_bot_token
CLIENT_ID=your_discord_application_id
```

--------------------------------

### Lavalink Server Configuration (`application.yml`)

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Configure Lavalink server settings, including port, address, thread counts, enabled plugins like YouTube and Lavasrc, Spotify integration details, and Lavalink specific options such as password, enabled sources, buffer durations, and filters.

```yaml
server:
  port: 2333
  address: 0.0.0.0
  undertow:
    threads:
      io: 4
      worker: 8

plugins:
  youtube:
    enabled: true
    allowSearch: true
    allowDirectVideoIds: true
    allowDirectPlaylistIds: true
    clients:
      - MUSIC
      - WEB
      - ANDROID_VR
  lavasrc:                          # Spotify + cross-source resolution
    providers:
      - "ytsearch:""%ISRC%""
      - "ytmsearch:%QUERY%"
      - "ytsearch:%QUERY%"
      - "scsearch:%QUERY%"
      - "spsearch:%QUERY%"
    sources:
      spotify: ${SPOTIFY_ENABLED:false}
      youtube: false
    spotify:
      clientId: "${SPOTIFY_CLIENT_ID:}"
      clientSecret: "${SPOTIFY_CLIENT_SECRET:}"
      countryCode: "US"
      playlistLoadLimit: 3
      albumLoadLimit: 3

lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:1.16.0"
      snapshot: false
    - dependency: "com.github.topi314.lavasrc:lavasrc-plugin:4.8.1"
      repository: "https://maven.lavalink.dev/releases"
      snapshot: false
  server:
    password: "${LAVALINK_PASSWORD:youshallnotpass}"
    sources:
      youtube: false        # handled by youtube-plugin above
      soundcloud: true
      bandcamp: true
      twitch: true
      vimeo: true
      http: true
      local: false
    bufferDurationMs: 200
    frameBufferDurationMs: 1000
    filters:
      volume: true
      equalizer: true
      karaoke: true
      timescale: true
      tremolo: true
      vibrato: true
      rotation: true
      lowpass: true

logging:
  level:
    root: INFO
    lavalink: INFO

```

--------------------------------

### Verify 64-bit OS Architecture

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Check if the operating system is running in 64-bit mode. This is a prerequisite for ARM64 compatibility.

```bash
uname -m
# Should output: aarch64
```

--------------------------------

### Execute Play Command Logic

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Handles user input for song/playlist queries and playback options. Requires the user to be in a voice channel and Lavalink to be available. It creates or retrieves a Lavalink player, searches for the query, adds the result to the queue, and replies with confirmation.

```javascript
async execute(interaction) {
    const { client, guild, member, options } = interaction;
    const query   = options.getString('query');   // e.g. "lofi hip hop" or a YouTube URL
    const playNext = options.getBoolean('next') || false;
    const voiceChannel = member.voice.channel;

    // Guard: user must be in a voice channel
    if (!voiceChannel) {
        return interaction.reply({ content: client.t('NOT_IN_VOICE'), flags: MessageFlags.Ephemeral });
    }

    // Guard: Lavalink must be connected
    if (!isLavalinkAvailable(client)) {
        return interaction.reply({ content: client.t('LAVALINK_UNAVAILABLE'), flags: MessageFlags.Ephemeral });
    }

    await interaction.deferReply();

    // Get or create Lavalink player for this guild
    let player = client.lavalink.getPlayer(guild.id) || client.lavalink.createPlayer({
        guildId:        guild.id,
        voiceChannelId: voiceChannel.id,
        textChannelId:  interaction.channel.id,
        selfDeaf:       true,
        volume:         getValidVolume(process.env.DEFAULT_VOLUME, 80),
    });

    if (!player.connected) player.connect();

    // Search (defaults to DEFAULT_SEARCH_PLATFORM — ytmsearch)
    const res = await player.search({ query }, interaction.user);
    // res.loadType: "track" | "playlist" | "search" | "empty"
    // res.tracks: Track[]

    if (!res?.tracks.length) {
        return interaction.editReply({ content: client.t('NO_RESULTS') });
    }

    // Add single track or full playlist
    player.queue.add(
        res.loadType === 'playlist' ? res.tracks : res.tracks[0],
        playNext ? 0 : undefined   // position 0 = next up; undefined = end of queue
    );

    if (!player.playing) player.play();

    // Reply and render/update the player embed with control buttons
    const replyKey = res.loadType === 'playlist'
        ? (playNext ? 'PLAYLIST_ADDED_NEXT' : 'PLAYLIST_ADDED')
        : (playNext ? 'SONG_ADDED_NEXT'     : 'SONG_ADDED');
    await interaction.editReply({ content: client.t(replyKey, res.tracks[0].info?.title) });

    // Send persistent player embed (or update existing one)
    await client.playerController.sendPlayer(interaction.channel, player);
    // → Renders embed with track title, artist, duration, artwork thumbnail,
    //   volume footer, and two button rows:
    //   Row 1: ⏮️ Back | ⏸️/▶️ Play/Pause | ⏭️ Skip | ⏹️ Stop
    //   Row 2: 🔀 Shuffle | ➡️/🔂/🔁 Loop | 📜 Queue | 🗑️ Clear
}
```

--------------------------------

### Clone BeatDock Repository

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

Use this command to clone the BeatDock repository from GitHub if you plan to deploy from source.

```bash
git clone https://github.com/lazaroagomez/BeatDock.git
cd BeatDock
```

--------------------------------

### View All Docker Compose Logs

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Follow all logs from all services defined in your `docker-compose.yml` file in real-time. Use `--tail` to view a specific number of recent lines.

```bash
docker compose logs -f
```

```bash
docker compose logs -f bot
```

```bash
docker compose logs -f lavalink
```

```bash
docker compose logs --tail 100
```

--------------------------------

### Configure WSL Memory and Swap

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Sets the maximum memory and swap space allocated to WSL 2 by creating or editing the .wslconfig file.

```ini
[wsl2]
memory=4GB
swap=2GB
```

--------------------------------

### Verify BeatDock Deployment

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Checks the status of running Docker containers for BeatDock and follows the logs.

```bash
docker compose ps
docker compose logs -f
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/lazaroagomez/beatdock/wiki/Installation

Edit the .env file to include your Discord bot token, application ID, and Lavalink connection details. Optional settings for Spotify integration and bot behavior can also be configured.

```env
# Required
TOKEN=your_discord_bot_token
CLIENT_ID=your_discord_application_id

# Lavalink (defaults work with Docker Compose)
LAVALINK_HOST=lavalink
LAVALINK_PORT=2333
LAVALINK_PASSWORD=youshallnotpass
```

```env
# Spotify Integration
SPOTIFY_ENABLED=false
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Bot Behavior
DEFAULT_LANGUAGE=en              # en, es, or tr
DEFAULT_VOLUME=80                # 0-100
QUEUE_EMPTY_DESTROY_MS=30000     # Leave after queue empty (ms)
EMPTY_CHANNEL_DESTROY_MS=60000   # Leave after channel empty (ms)

# Permissions (comma-separated role IDs, empty = everyone)
ALLOWED_ROLES=

# Lavalink Reconnection
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
```

--------------------------------

### Lavalink Application Configuration

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

This application.yml file configures the Lavalink server, including ports, enabled sources (SoundCloud, Bandcamp, Twitch, Vimeo, HTTP), YouTube search settings, and buffer durations. It also specifies the Lavalink plugin for YouTube.

```yaml
server:
  port: 2333
  address: 0.0.0.0

plugins:
  youtube:
    enabled: true
    allowSearch: true
    allowDirectVideoIds: true
    allowDirectPlaylistIds: true
    clients:
      - MUSIC
      - WEB
      - ANDROID_VR

lavalink:
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:1.16.0"
      snapshot: false
  server:
    password: "${LAVALINK_PASSWORD:youshallnotpass}"
    sources:
      youtube: false
      soundcloud: true
      bandcamp: true
      twitch: true
      vimeo: true
      http: true
      local: false
    bufferDurationMs: 200
    frameBufferDurationMs: 1000
    youtubePlaylistLoadLimit: 3
    playerUpdateInterval: 2
    trackStuckThresholdMs: 5000
    useSeekGhosting: true
    youtubeSearchEnabled: true

logging:
  level:
    root: INFO
    lavalink: INFO
```

--------------------------------

### Configure Discord Bot Token

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

Create a .env file to store your Discord bot token. This file is used by Docker to inject environment variables.

```env
TOKEN=your_discord_bot_token
```

--------------------------------

### Apply Audio Effects and EQ Presets

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

This command allows users to apply various audio effects and EQ presets to the currently playing track in real time. Effects are toggled, while EQ presets are set and can be cleared. Active filters are indicated in the embed.

```javascript
// Invoked as: /filter
// src/commands/filter.js  →  src/interactions/filterNavigation.js

// Page 1 — Audio Effects:
// Bass Boost 🔊 | Nightcore 🌙 | Vaporwave 🌊 | 8D Audio 🎧 | Karaoke 🎤
// Tremolo 〰️   | Vibrato 🎵   | Low Pass 🌀  | Reset All 🔄

// Page 2 — EQ Presets:
// Bass Boost Low 🔉 | Bass Boost High 🔊 | Rock 🎸 | Pop 🎶 | Electronic 🎹
// Gaming 🎮        | Classic 🎻         | Full Sound 🔈 | Better Music ✨

// applyFilter(player, key) — toggling behavior:
await fm.toggleNightcore();           // pitch + speed up (timescale)
await fm.toggleVaporwave();           // pitch + speed down
await fm.toggleRotation(0.2);         // 8D — stereo panning at 0.2Hz
await fm.toggleKaraoke();             // remove center-channel vocals
await fm.toggleTremolo();             // volume oscillation
await fm.toggleVibrato();             // pitch oscillation
await fm.toggleLowPass();             // cut high frequencies

// EQ presets use lavalink-client's built-in EQList constants:
await fm.setEQ(EQList.BassboostMedium);  // Bassboost (medium)
await fm.setEQ(EQList.Rock);
await fm.setEQ(EQList.Pop);
await fm.clearEQ();                     // toggle off same preset

// Active filters are shown in the embed description and marked with ✓ in dropdown options
// Reply (followUp): "✅ Applied: Nightcore" or "❌ Removed: Nightcore"
// All filters cleared: "🔄 All filters have been reset."

```

--------------------------------

### Docker Compose Configuration for BeatDock and Lavalink

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

This configuration sets up two services: 'bot' for BeatDock and 'lavalink' for the audio server. It defines networks, dependencies, and environment variables for both. Ensure the Lavalink healthcheck is configured correctly for your environment.

```yaml
services:
  bot:
    container_name: beatdock
    image: ghcr.io/lazaroagomez/beatdock:latest
    depends_on:
      lavalink:
        condition: service_healthy
    networks:
      - beatdock-network
    env_file: .env           # only TOKEN= is required

  lavalink:
    container_name: beatdock-lavalink
    image: ghcr.io/lavalink-devs/lavalink:4
    networks:
      - beatdock-network
    volumes:
      - ./application.yml:/opt/Lavalink/application.yml
    environment:
      - LAVALINK_PASSWORD=${LAVALINK_PASSWORD:-youshallnotpass}
      - SPOTIFY_ENABLED=${SPOTIFY_ENABLED:-false}
      - SPOTIFY_CLIENT_ID=${SPOTIFY_CLIENT_ID:-}
      - SPOTIFY_CLIENT_SECRET=${SPOTIFY_CLIENT_SECRET:-}
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/localhost/2333'"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

networks:
  beatdock-network:
    name: beatdock_network
```

--------------------------------

### Check Running Containers

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Verify that the BeatDock and Lavalink containers are running and healthy using Docker Compose.

```powershell
docker compose ps
```

--------------------------------

### Verify BeatDock Deployment

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Checks the running Docker containers and their logs. Also verifies the architecture of the deployed BeatDock container.

```bash
docker compose ps
docker compose logs -f
```

```bash
docker inspect beatdock --format '{{.Architecture}}'
# Should output: arm64
```

--------------------------------

### Manage BeatDock with Docker Compose

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Provides commands for stopping, restarting, updating, and viewing logs for the BeatDock application using Docker Compose.

```bash
# Stop
docker compose down

# Restart
docker compose restart

# Update
docker compose pull && docker compose up -d

# Logs
docker compose logs -f
```

--------------------------------

### /loop

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Cycles through loop modes: off, track, and queue. Autoplay and loop are mutually exclusive.

```APIDOC
## /loop

### Description
Cycles through loop modes: off → track → queue.

### Method
POST (assumed, as it modifies player state)

### Endpoint
`/loop`

### Parameters
None

### Request Example
```json
{
  "command": "loop"
}
```

### Response
- **ephemeral message** (string) - "🔂 Track loop enabled"
- **ephemeral message** (string) - "🔁 Queue loop enabled"
- **ephemeral message** (string) - "➡️ Loop disabled"

### Notes
- Blocked if autoplay is active.
- Player embed footer updates after 100ms.
- Loop icon in button row: ➡️ (off) | 🔂 (track) | 🔁 (queue)
```

--------------------------------

### /back

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Plays the previous track from the player's history. It removes the track from history and can re-add the current track to the front of the queue.

```APIDOC
## /back

### Description
Plays the previous track from player.queue.previous history.

### Method
POST (assumed, as it modifies player state)

### Endpoint
`/back`

### Parameters
None

### Request Example
```json
{
  "command": "back"
}
```

### Response
- **ephemeral message** (string) - "Playing previous song: [Track Name]"
- **ephemeral message** (string) - "There are no previous songs in the history."
```

--------------------------------

### Deploy Slash Commands and Capture Output

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Redeploy slash commands and capture all output, including errors. This is useful for debugging deployment issues.

```bash
docker compose run --rm bot npm run deploy 2>&1
```

--------------------------------

### Troubleshoot Permission Denied

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Adds the current user to the 'docker' group to resolve permission issues when running Docker commands.

```bash
sudo usermod -aG docker $USER
# Log out and back in
```

--------------------------------

### Inspect Docker Network

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Examine the Docker network configuration for the 'beatdock_network'. This helps in diagnosing network connectivity issues between containers.

```bash
docker network ls
```

```bash
docker network inspect beatdock_network
```

--------------------------------

### View Application Logs

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Monitor the real-time logs of the running Docker containers to troubleshoot issues or observe application activity.

```powershell
docker compose logs -f
```

--------------------------------

### Configure Swap Space on Raspberry Pi

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-ARM

Enables swap space by modifying the dphys-swapfile configuration. This is recommended for devices with limited RAM (e.g., 2GB).

```bash
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=1024
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
```

--------------------------------

### Comment out Lavalink variables in .env

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

To use public Lavalink servers, comment out the Lavalink host, port, and password variables in your .env file.

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

--------------------------------

### Access WSL Files from Windows

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-WSL

Shows the network path to access files within the WSL environment from Windows File Explorer.

```text
\\wsl$\Ubuntu\home\yourusername\BeatDock
```

--------------------------------

### Paginated Queue Viewer with Track Jump

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Displays the upcoming queue in a paginated embed with navigation buttons and a dropdown for instant track jumping. Requires a player with a queue.

```javascript
// Invoked as: /queue
// src/commands/queue.js

async execute(interaction) {
    const player = await requirePlayer(interaction, { requireQueue: true });
    if (!player) return; // replies "Nothing playing" or "Queue empty" automatically

    const queueResponse = createPaginatedQueueResponse(client, player, 1 /* page */);
    return interaction.reply(queueResponse);
}

// createPaginatedQueueResponse (src/utils/PlayerActions.js)
// Returns a full Discord message object ready for interaction.reply() or interaction.update():
// {
//   embeds: [EmbedBuilder],   // "Queue • 14 tracks" with numbered list
//   components: [
//     ActionRow,              // ⏮️ First | ◀️ Prev | ▶️ Next | ⏭️ Last  (only when >1 page)
//     ActionRow,              // StringSelectMenu  "Jump to track..."
//   ],
//   flags: MessageFlags.Ephemeral
// }

// Selecting a track from the dropdown fires customId "queue:select"
// → handleQueueInteraction(interaction, 'jump', [trackIndex, pageNumber])
// → jumpToTrack(player, trackIndex)
//     Splices all tracks before the target, then calls player.skip()
//     so the target becomes the next track to play immediately.

// Example interaction flow:
// User: /queue
// Bot:  Embed showing tracks 1-9 with navigation row + select menu
// User: Selects "3. Bohemian Rhapsody — Queen" from dropdown
// Bot:  "▶️ Jumped to Bohemian Rhapsody and removed all previous tracks from the queue."
```

--------------------------------

### Update Bot with Docker

Source: https://github.com/lazaroagomez/beatdock/wiki/Installation

Pull the latest Docker image and restart the containers to update the bot. For source updates, pull the latest code, redeploy commands, and restart the containers.

```bash
docker compose pull
docker compose up -d
```

```bash
git pull
docker compose run --rm bot npm run deploy
docker compose up -d
```

--------------------------------

### Docker Compose Configuration for BeatDock and Lavalink

Source: https://github.com/lazaroagomez/beatdock/blob/main/README.md

This docker-compose.yml file defines the services for the BeatDock bot and its Lavalink dependency. It specifies container names, images, network configurations, and environment variables, including optional Spotify integration.

```yaml
services:
  bot:
    container_name: beatdock
    image: ghcr.io/lazaroagomez/beatdock:latest
    depends_on:
      lavalink:
        condition: service_healthy
    networks:
      - beatdock-network
    env_file: .env

  lavalink:
    container_name: beatdock-lavalink
    image: ghcr.io/lavalink-devs/lavalink:4
    ports:
      - "2333:2333"
    networks:
      - beatdock-network
    volumes:
      - ./application.yml:/opt/Lavalink/application.yml
    environment:
      - LAVALINK_PASSWORD=${LAVALINK_PASSWORD:-youshallnotpass}
      - SPOTIFY_ENABLED=${SPOTIFY_ENABLED:-false}
      - SPOTIFY_CLIENT_ID=${SPOTIFY_CLIENT_ID:-}
      - SPOTIFY_CLIENT_SECRET=${SPOTIFY_CLIENT_SECRET:-}
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/localhost/2333'"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

networks:
  beatdock-network:
    name: beatdock_network
```

--------------------------------

### Update BeatDock to Latest Image

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

Pull the latest Docker image and redeploy the application to ensure you are running the most recent version.

```bash
docker compose pull
docker compose up -d
```

--------------------------------

### /skip

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Skips to the next track in the queue. If autoplay is enabled and the queue is empty, it triggers an autoplay fetch. It can also force-skip with autoplay active.

```APIDOC
## /skip

### Description
Skips to the next track. If autoplay is on and queue is empty, triggers autoplay fetch.

### Method
POST (assumed, as it modifies player state)

### Endpoint
`/skip`

### Parameters
None explicitly documented for basic usage.

### Request Example
```json
{
  "command": "skip"
}
```

### Response
- **ephemeral message** (string) - "Skipped the current song."

### Notes
- `player.skip()`: normal skip
- `player.skip(0, false)`: force-skip with autoplay active (no track end callback)
```

--------------------------------

### Manage BeatDock with Docker Compose

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Linux

Common Docker Compose commands for managing the BeatDock application, including stopping, restarting, updating, and viewing logs.

```bash
# Stop
docker compose down

# Restart
docker compose restart

# Update
docker compose pull && docker compose up -d

# Logs
docker compose logs -f

# Bot logs only
docker compose logs -f bot
```

--------------------------------

### /volume

Source: https://context7.com/lazaroagomez/beatdock/llms.txt

Sets the playback volume to a specified level between 1 and 100.

```APIDOC
## /volume

### Description
Sets the playback volume to a specified level.

### Method
POST (assumed, as it modifies player state)

### Endpoint
`/volume`

### Parameters
#### Query Parameters
- **level** (integer) - Required - The desired volume level (1-100).

### Request Example
```json
{
  "command": "volume",
  "level": 75
}
```

### Response
- **ephemeral message** (string) - "🔊 Volume set to [level]%"

### Notes
- Player embed footer updates after 100ms to reflect the new volume.
```

--------------------------------

### Generate Docker Logs

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Use this command to capture all Docker logs for debugging purposes. Save the output to a file for easier analysis.

```bash
docker compose logs > logs.txt
```

--------------------------------

### Recreate Docker Containers and Network

Source: https://github.com/lazaroagomez/beatdock/wiki/Troubleshooting

Stop all running containers, remove the network, and then restart the services. This can resolve persistent Docker-related issues.

```bash
docker compose down
```

```bash
docker compose up -d
```

```bash
docker network rm beatdock_network
```

--------------------------------

### Check Docker Network

Source: https://github.com/lazaroagomez/beatdock/wiki/Running-on-Docker-Desktop-Windows

List available Docker networks to help diagnose network-related issues between containers.

```powershell
docker network ls
```