Discord Jukebox Bot

A Discord bot written in Go that plays random music from a Subsonic-compatible server. The bot acts as a jukebox, streaming randomly selected songs directly to a Discord voice channel using real-time audio encoding.

Features

• Connect to any Subsonic-compatible server (Subsonic, Navidrome, Airsonic, etc.)
• Play random music in a Discord voice channel with real-time audio streaming
• Automatic audio format conversion for Discord compatibility
• Simple slash commands for controlling the jukebox
• Web interface for viewing current playback status and song history
• Configurable through environment variables

Requirements

• Go 1.24 or later
• A Discord bot token
• A Subsonic-compatible server

Installation

From Source

1. Clone the repository:

   git clone https://github.com/yourusername/discord-jukebox-bot.git
   cd discord-jukebox-bot
   

2. Build the application:

   go build -o jukebox-bot ./cmd/bot
   

3. Set up environment variables (see Configuration section)

4. Create a .env file in the project root (or set environment variables)

5. Run the bot:

   ./jukebox-bot        # Normal mode
   ./jukebox-bot -debug # Debug mode with verbose logging
   

Discord Bot Setup

1. Go to the Discord Developer Portal
2. Create a new application
3. Navigate to the "Bot" tab and click "Add Bot"
4. Under the "Privileged Gateway Intents" section, enable:
   • Server Members Intent
   • Message Content Intent
   • Voice States
5. Copy the bot token (this will be used in your environment variables)
6. Go to the "OAuth2" -> "URL Generator" tab
7. Select the following scopes:
   • bot
   • applications.commands
8. Select the following bot permissions:
   • Connect
   • Speak
   • Send Messages
   • Use Slash Commands
9. Copy the generated URL and open it in your browser to add the bot to your server

Configuration

Configure the bot using environment variables with the JUKEBOX_ prefix. You can set them in two ways:

1. Using a .env file (recommended):

   • Create a .env file in the project root directory (same location as the executable)
   • Use the provided .env.example as a template
   • The bot will automatically load variables from this file when it starts

2. Setting system environment variables:

   • Set the variables in your shell or operating system

Required Environment Variables

• JUKEBOX_DISCORD_TOKEN: Your Discord bot token
• JUKEBOX_DISCORD_GUILD_ID: The ID of your Discord server
• JUKEBOX_SUBSONIC_SERVER: URL of your Subsonic server (e.g., https://demo.subsonic.org)
• JUKEBOX_SUBSONIC_USERNAME: Your Subsonic username
• JUKEBOX_SUBSONIC_PASSWORD: Your Subsonic password

Optional Environment Variables

• JUKEBOX_DISCORD_CHANNEL_ID: Specific voice channel ID (bot will join user's channel if not specified)
• JUKEBOX_SUBSONIC_VERSION: Subsonic API version (default: 1.16.1)
• JUKEBOX_AUDIO_VOLUME: Volume level from 0.0 to 1.0 for audio playback (default: 0.5)
• JUKEBOX_TIMEOUT_SEC: HTTP request timeout in seconds (default: 30)
• JUKEBOX_WEB_ENABLED: Enable the web interface (default: true)
• JUKEBOX_WEB_ADDR: Address and port for the web server (default: :8080)

Sample .env File

# Required settings
JUKEBOX_DISCORD_TOKEN=your_discord_bot_token_here
JUKEBOX_DISCORD_GUILD_ID=your_discord_guild_id_here
JUKEBOX_SUBSONIC_SERVER=https://your-subsonic-server.com
JUKEBOX_SUBSONIC_USERNAME=your_subsonic_username
JUKEBOX_SUBSONIC_PASSWORD=your_subsonic_password

# Optional settings
# JUKEBOX_DISCORD_CHANNEL_ID=specific_voice_channel_id
# JUKEBOX_SUBSONIC_VERSION=1.16.1
# JUKEBOX_AUDIO_VOLUME=0.5
# JUKEBOX_TIMEOUT_SEC=30
# JUKEBOX_WEB_ENABLED=true
# JUKEBOX_WEB_ADDR=:8080

Troubleshooting

If you encounter issues with the bot:

1. First, run the bot in debug mode to get more detailed logs:

   ./jukebox-bot -debug
   

2. Check the TROUBLESHOOTING.md guide for common problems and solutions.

3. If you're having audio issues, the detailed logs in debug mode will show:

   • If songs are being fetched correctly from your Subsonic server
   • The exact URL being used to stream audio
   • Audio encoding and streaming progress

Usage

Debug Mode

If you're experiencing issues with the bot or want to see more detailed logs:

# Run with debug mode enabled
./jukebox-bot -debug

# Using make
make run-debug

Debug mode provides:

• Detailed logging of Subsonic API requests and responses
• Audio encoding and streaming progress information
• Configuration validation and detailed error messages

Commands

The bot provides the following slash commands:

• /jukebox play - Starts playing random music from your Subsonic library
• /jukebox stop - Stops playing music and leaves the voice channel
• /jukebox skip - Skips the current song and plays the next one
• /jukebox info - Displays information about the currently playing song

Web Interface

The bot includes a web interface that displays the current playback status. By default, it runs on port 8080 and can be accessed at:

http://your-server-ip:8080

The web interface features:

• Real-time updates when songs change or playback stops
• Current song information (artist, album, title, etc.)
• History of the last 20 played songs
• Responsive design that works on mobile and desktop
• No additional setup required - it works out of the box

You can configure the web interface using these environment variables:

• JUKEBOX_WEB_ENABLED: Set to false to disable the web interface
• JUKEBOX_WEB_ADDR: Change the address and port (e.g., :8000 for port 8000)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Developer Resources

• ARCHITECTURE.md - Documentation of the project architecture
• TROUBLESHOOTING.md - Solutions to common problems

Acknowledgements

• discordgo - Go package for Discord API
• The Subsonic API - The API this bot uses to fetch music
• jonas747/dca - Audio encoding for Discord
• layeh/gopus - Opus codec binding for Go