Bass Bot

Bass is a feature-rich discord music bot.
With features like the button-controlled player message, easy interop with spotify links,
built-in lyrics search and many more features, it offers the best listening experience.

Features

• Multi-source playback — YouTube, Spotify, SoundCloud, and more via Lavalink
• Load Playlists — Support for YouTube and Spotify playlists and albums
• Interactive player message — Button controls for play/pause, skip, previous, stop, and loop
• Queue management — View, shuffle, move, remove tracks, and save/load queues across sessions
• Search — Search for tracks directly from Discord with /search
• Loop modes — Loop the current track or the entire queue
• History — Restore your previous queue with /history and /loadqueue
• Web dashboard — Monitor active players, guilds, and activity from a browser
• Lyrics — Look up lyrics for the current song with /lyrics
• Channel binding — Restrict bot commands to specific channels with /bindchannel

Key Commands

Command	Description
/play	Play a song by URL or search query
/search	Search and pick from results
/queue	View the current queue
/shuffle	Shuffle the queue
/lyrics	Show lyrics for the current track
/loop	Toggle loop (track / queue / off)
/history	View previous queues
/loadqueue	Restore a saved queue
/seek	Jump to a position in the track
/volume	Adjust playback volume
/w2g	Create a Watch2Gether room

Self-Host Quick Start (Docker)

The easiest way to run BassBot is with Docker Compose.

1. Download the files

mkdir bassbot && cd bassbot
mkdir bot web

# Docker Compose file
curl -O https://raw.githubusercontent.com/tomfln/bassbot/main/config/compose.yml

# Environment template (rename to .env)
curl -o .env https://raw.githubusercontent.com/tomfln/bassbot/main/config/.env.example

# Lavalink config (into the data directory)
mkdir -p bassbot-data
curl -o bassbot-data/application.yml https://raw.githubusercontent.com/tomfln/bassbot/main/config/application.yml

2. Fill in the .env file

Open .env and set all required values. Docker Compose will warn you about any missing variables.

Variable	Required	Description
DISCORD_BOT_TOKEN	Yes	Bot token (Developer Portal → Bot)
DISCORD_APP_ID	Yes	Application ID (General Information)
DISCORD_OAUTH_CLIENT_SECRET	Yes	OAuth client secret (OAuth2 page)
JWT_SECRET	Yes	Shared secret for bot ↔ web auth. Generate: openssl rand -hex 32
BETTER_AUTH_SECRET	Yes	Web auth encryption secret. Generate: openssl rand -hex 32
WEB_BASE_URL	Yes	Public URL of the dashboard (e.g. http://localhost:3000)
LAVALINK_HOST	No	Lavalink address (default: lavalink:2333)
LAVALINK_PASSWORD	No	Lavalink password (default: youshallnotpass)
W2G_KEY	No	Watch2Gether API key
ADMIN_USERS	No	Comma-separated Discord usernames auto-promoted to admin
API_PORT	No	Bot REST API port (default: 3001)
WEB_PORT	No	Web dashboard port (default: 3000)
API_URL	No	Bot API URL from the browser — only set when bot is on a different domain
BOT_DATA_PATH	No	Bot data bind-mount path (default: ./bot)
WEB_DATA_PATH	No	Web data bind-mount path (default: ./web)
LAVALINK_CONFIG	No	Path to Lavalink application.yml (default: ./application.yml)

Named volumes: If you prefer Docker named volumes instead of bind mounts, see the commented-out sections in compose.yml.

3. (Optional) Configure Spotify

To enable Spotify link support, edit bassbot-data/application.yml, enable the spotify source and set your Spotify API credentials under plugins.lavasrc.spotify:

lavasrc:
  # ...
  sources:
    spotify: true
  # ...
  spotify:
    clientId: "your_spotify_client_id"
    clientSecret: "your_spotify_client_secret"

You can create these at the Spotify Developer Dashboard.

4. Start

docker compose up -d

The bot will start, connect to Lavalink, and be ready to use. Invite it to your server, join a voice channel, and run /play.

---

YouTube OAuth Setup

YouTube requires OAuth authentication for reliable playback. Without it, you may encounter errors or age-restricted content blocks.

Warning: Use a burner Google account, not your main one. OAuth tokens give access to the account's YouTube data.

First-time setup (getting a refresh token)

1. In lavalink/application.yml, make sure OAuth is enabled without a refresh token:

   plugins:
     youtube:
       oauth:
         enabled: true

2. Start the stack:

   docker compose up -d

3. Watch the Lavalink logs:

   docker logs -f lavalink

4. Lavalink will print a message like:

   To give youtube-source access to your account, go to https://www.google.com/device and enter code XXXX-XXXX
   

5. Open the URL in your browser, sign in with a burner Google account, and enter the code.

6. Once authorized, Lavalink logs will show:

   Token retrieved successfully. Store your refresh token as this can be reused. (1//0xxxx...)
   

7. Copy the refresh token and add it to lavalink/application.yml:

   plugins:
     youtube:
       oauth:
         enabled: true
         refreshToken: "1//0xxxx..."
         skipInitialization: true

8. Restart Lavalink to apply:

   docker compose restart lavalink

From now on, Lavalink will use the refresh token automatically — no manual login needed.

---

Web Dashboard Setup

The web dashboard lets users control music playback from a browser. It uses Discord OAuth for authentication.

1. Create a Discord OAuth Application

1. Go to the Discord Developer Portal
2. Select your bot application (or create a new one)
3. Go to OAuth2 → General
4. Copy the Client ID and Client Secret
5. Add a redirect URL: http://localhost:3000/rest/auth/callback/discord (or your production domain)

2. Set the env vars

Make sure these variables are set in your .env:

DISCORD_APP_ID=your_client_id
DISCORD_OAUTH_CLIENT_SECRET=your_client_secret
JWT_SECRET=your-random-secret-here
BETTER_AUTH_SECRET=your-random-secret-here
WEB_BASE_URL=http://localhost:3000

3. Admin Access

Set ADMIN_USERS=yourdiscordusername in .env to auto-promote yourself on login. Once you're an admin, you can promote other users from the Admin → Users page.

---

Local Development

1. Clone the repository
2. Run bun install
3. Copy .env.example to .env and fill in the values
4. Run bun dev to start the bot and dashboard in dev mode

Technologies

• TypeScript — Fully typed codebase with custom type-safe command framework
• Bun — Fast JS runtime, no build step needed
• Lavalink + Shoukaku — Reliable audio playback with Spotify support
• Discord.js — Discord API interaction
• Drizzle ORM + SQLite — Lightweight embedded database for persistence
• Next.js — Dashboard for monitoring the bot

License

This project is licensed under the MIT license. See the LICENSE file for more information.

Contributing

Contributions are welcome! Please open an issue or a pull request.