191 lines
No EOL
6.2 KiB
Markdown
191 lines
No EOL
6.2 KiB
Markdown
# 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](https://discord.com/developers/applications)
|
|
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](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](ARCHITECTURE.md) - Documentation of the project architecture
|
|
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Solutions to common problems
|
|
|
|
## Acknowledgements
|
|
|
|
- [discordgo](https://github.com/bwmarrin/discordgo) - Go package for Discord API
|
|
- [The Subsonic API](http://www.subsonic.org/pages/api.jsp) - The API this bot uses to fetch music
|
|
- [jonas747/dca](https://github.com/jonas747/dca) - Audio encoding for Discord
|
|
- [layeh/gopus](https://github.com/layeh/gopus) - Opus codec binding for Go |