133 lines
No EOL
5.2 KiB
Markdown
133 lines
No EOL
5.2 KiB
Markdown
# Discord Jukebox Bot - Architecture
|
|
|
|
This document describes the architecture and design principles of the Discord Jukebox Bot application.
|
|
|
|
## Overview
|
|
|
|
Discord Jukebox Bot is a Go application that connects to a Discord server and a Subsonic-compatible music server to provide a jukebox experience in Discord voice channels. The bot fetches random tracks from the configured Subsonic server and streams them to a Discord voice channel.
|
|
|
|
## Project Structure
|
|
|
|
The project follows a clean, modular structure:
|
|
|
|
```
|
|
discord-jukebox-bot/
|
|
├── cmd/ # Command-line applications
|
|
│ └── bot/ # Main bot application
|
|
│ └── main.go # Entry point
|
|
├── pkg/ # Library packages
|
|
│ ├── config/ # Configuration management
|
|
│ ├── commands/ # Command registration and processing
|
|
│ ├── discord/ # Discord integration
|
|
│ └── subsonic/ # Subsonic API client
|
|
├── README.md # Project documentation
|
|
└── ARCHITECTURE.md # This architecture document
|
|
```
|
|
|
|
## Component Design
|
|
|
|
### Configuration (pkg/config)
|
|
|
|
The configuration package handles loading and validating environment variables. It uses the `JUKEBOX_` prefix for all environment variables to avoid conflicts with other applications.
|
|
|
|
Key responsibilities:
|
|
- Loading configuration from environment variables and .env files
|
|
- Providing default values for optional settings
|
|
- Validating required configuration
|
|
- Cleaning and normalizing input values (like Guild IDs)
|
|
|
|
### Subsonic Client (pkg/subsonic)
|
|
|
|
The Subsonic client package provides a client for interacting with Subsonic-compatible music servers.
|
|
|
|
Key responsibilities:
|
|
- Authenticating with the Subsonic server
|
|
- Fetching random songs with detailed metadata
|
|
- Generating streaming URLs for audio content
|
|
- Handling various API response formats (JSON/XML)
|
|
|
|
### Discord Bot (pkg/discord)
|
|
|
|
The Discord bot package manages the connection to Discord and provides voice channel functionality.
|
|
|
|
Key responsibilities:
|
|
- Connecting to Discord
|
|
- Managing voice channel connections
|
|
- Registering and handling slash commands
|
|
- Real-time audio encoding and streaming to voice channels
|
|
- Processing audio data from Subsonic to Discord-compatible Opus format
|
|
|
|
### Commands (pkg/commands)
|
|
|
|
The commands package sets up and registers all the bot commands, providing a clean interface for adding new commands.
|
|
|
|
Key responsibilities:
|
|
- Registering command handlers
|
|
- Providing a centralized setup function for all components
|
|
|
|
## Data Flow
|
|
|
|
1. The application starts in `cmd/bot/main.go`, which:
|
|
- Loads configuration
|
|
- Sets up the Discord bot and command handlers
|
|
- Starts the bot and waits for termination signals
|
|
|
|
2. When a user invokes the `/jukebox play` command:
|
|
- The bot joins the user's voice channel
|
|
- Fetches random songs from the Subsonic server
|
|
- Retrieves audio streams from Subsonic
|
|
- Transcodes the audio to Opus format in real-time
|
|
- Streams the encoded audio to the Discord voice channel
|
|
|
|
3. The jukebox player manages the playlist and playback:
|
|
- Maintains a queue of songs
|
|
- Fetches more songs when the queue is low
|
|
- Handles play, stop, and skip commands
|
|
- Manages audio encoding and streaming processes
|
|
- Controls volume and timing of audio playback
|
|
|
|
## Extension Points
|
|
|
|
The application is designed for easy extension:
|
|
|
|
1. **Adding New Commands**:
|
|
- Define new command handlers in `pkg/commands/setup.go`
|
|
- Register them with the `RegisterCustomCommand` function
|
|
|
|
2. **Supporting More Subsonic Features**:
|
|
- Extend the Subsonic client in `pkg/subsonic/client.go`
|
|
- Add new API methods as needed
|
|
|
|
3. **Adding New Jukebox Features**:
|
|
- Extend the `JukeboxPlayer` in `pkg/discord/jukebox.go`
|
|
- Add new command handlers for the features
|
|
|
|
## Concurrency Model
|
|
|
|
The application uses Go's concurrency primitives to handle multiple tasks:
|
|
|
|
- Mutexes protect shared state (playlist, playing status)
|
|
- Channels coordinate between the main goroutine and audio playback goroutines
|
|
- Dedicated goroutines handle audio encoding and streaming
|
|
- Precise timing controls for audio frame delivery
|
|
- The main goroutine handles signals for graceful shutdown
|
|
|
|
## Error Handling
|
|
|
|
Error handling follows Go's idiomatic approach:
|
|
- Functions return errors rather than using exceptions
|
|
- Errors are propagated up the call stack
|
|
- Critical errors are logged and cause application termination
|
|
- Non-critical errors (like playback issues) are logged and the application continues
|
|
|
|
## Future Improvements
|
|
|
|
Potential areas for future enhancement:
|
|
|
|
1. **Enhanced Audio Processing**: Add support for more audio formats and quality settings
|
|
2. **Extended Commands**: Add playlist management, search functionality, and more playback controls
|
|
3. **Persistent State**: Save state between restarts (current playlist, volume settings)
|
|
4. **Multiple Guild Support**: Support running in multiple Discord servers simultaneously
|
|
5. **Metrics and Monitoring**: Add telemetry for monitoring bot health and usage
|
|
6. **Voice Effects**: Add audio effects like equalizer, normalization, and bass boost
|
|
7. **Advanced Subsonic Features**: Support album art, playlists, and other Subsonic-specific features |