396 lines
14 KiB
Markdown
396 lines
14 KiB
Markdown
|
|
# Mumble Music Bot Design Document
|
|
|
|
## Project Overview
|
|
A Dart-based music bot that connects to Mumble servers, processes chat commands, downloads audio from URLs (primarily YouTube), and streams audio back to the server with queue management and admin dashboard functionality.
|
|
|
|
## Technology Stack
|
|
- **Language**: Dart
|
|
- **Mumble Protocol**: dumble (Dart Mumble library)
|
|
- **Audio Processing**: FFmpeg via process execution
|
|
- **YouTube Download**: yt-dlp via process execution
|
|
- **Web Framework**: shelf for admin dashboard
|
|
- **Storage**: SQLite for metadata, filesystem for audio cache
|
|
- **Authentication**: Simple username/password with session tokens
|
|
|
|
## Development Steps
|
|
|
|
### Phase 1: Core Infrastructure and Testing Setup
|
|
|
|
#### Step 1: Project Setup and Dependencies
|
|
**Scope**: Initialize Dart project with required dependencies
|
|
**Deliverable**: Working Dart project with all dependencies configured
|
|
**Test Criteria**:
|
|
- `dart pub get` runs without errors
|
|
- All imports resolve correctly
|
|
- Basic main.dart can be executed
|
|
|
|
**Dependencies to add**:
|
|
```yaml
|
|
dependencies:
|
|
dumble: ^latest_version
|
|
shelf: ^1.4.0
|
|
shelf_router: ^1.1.0
|
|
shelf_static: ^1.1.0
|
|
sqlite3: ^2.1.0
|
|
crypto: ^3.0.3
|
|
path: ^1.8.3
|
|
logging: ^1.2.0
|
|
args: ^2.4.0
|
|
json_annotation: ^4.8.0
|
|
|
|
dev_dependencies:
|
|
test: ^1.24.0
|
|
json_serializable: ^6.6.0
|
|
build_runner: ^2.4.0
|
|
```
|
|
|
|
#### Step 2: Docker Test Environment
|
|
**Scope**: Create Docker Compose setup for local Mumble server testing
|
|
**Deliverable**: Docker Compose file and configuration for local testing
|
|
**Test Criteria**:
|
|
- `docker-compose up` starts local Mumble server
|
|
- Server is accessible on localhost with known credentials
|
|
- Configuration allows multiple bot connections for testing
|
|
|
|
**Docker Compose Structure**:
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
mumble-server:
|
|
image: coppit/mumble-server
|
|
ports:
|
|
- "64738:64738"
|
|
- "64738:64738/udp"
|
|
environment:
|
|
- MUMBLE_SERVERPASSWORD=testpass
|
|
volumes:
|
|
- ./test/mumble-config:/opt/mumble/config
|
|
- ./test/mumble-data:/opt/mumble/data
|
|
```
|
|
|
|
#### Step 3: Configuration Management
|
|
**Scope**: Create configuration system for bot settings
|
|
**Deliverable**: Configuration class that loads from JSON file
|
|
**Test Criteria**:
|
|
- Can load configuration from `config.json`
|
|
- Validates required fields (server, username, password, etc.)
|
|
- Provides sensible defaults for optional fields
|
|
|
|
**Configuration Structure**:
|
|
```json
|
|
{
|
|
"mumble": {
|
|
"server": "localhost",
|
|
"port": 64738,
|
|
"username": "MusicBot",
|
|
"password": "optional_password",
|
|
"channel": "Music"
|
|
},
|
|
"bot": {
|
|
"command_prefix": "!",
|
|
"default_permission_level": 0,
|
|
"max_queue_size": 50,
|
|
"cache_directory": "./cache",
|
|
"max_cache_size_gb": 5
|
|
},
|
|
"dashboard": {
|
|
"port": 8080,
|
|
"admin_username": "admin",
|
|
"admin_password": "changeme"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Step 4: Logging System
|
|
**Scope**: Implement structured logging throughout the application
|
|
**Deliverable**: Centralized logging configuration with different log levels
|
|
**Test Criteria**:
|
|
- Logs can be written to console and file
|
|
- Different log levels work correctly (debug, info, warn, error)
|
|
- Log rotation works for file output
|
|
|
|
### Phase 2: Mumble Protocol Implementation
|
|
|
|
#### Step 5: Basic Mumble Connection with dumble
|
|
**Scope**: Establish connection to Mumble server using dumble library
|
|
**Deliverable**: Class that can connect and authenticate to Mumble server
|
|
**Test Criteria**:
|
|
- Successfully connects to test Mumble server using dumble
|
|
- Authenticates with username/password
|
|
- Handles connection failures gracefully
|
|
- Can disconnect cleanly
|
|
|
|
#### Step 6: Mumble Message Handling and Sending
|
|
**Scope**: Listen for chat messages and send responses using dumble
|
|
**Deliverable**: Message listener and sender that can receive and send chat messages
|
|
**Test Criteria**:
|
|
- Receives all chat messages from server
|
|
- Can send chat messages back to channel/users
|
|
- Correctly parses message content and sender
|
|
- Filters messages by configurable command prefix
|
|
- Handles different message types appropriately
|
|
|
|
#### Step 7: Mumble Audio Streaming
|
|
**Scope**: Stream audio data to Mumble server using dumble
|
|
**Deliverable**: Audio streaming functionality
|
|
**Test Criteria**:
|
|
- Can send audio packets to Mumble server via dumble
|
|
- Audio plays correctly in the channel
|
|
- Handles audio format conversion (PCM)
|
|
- Manages audio timing and buffering
|
|
|
|
### Phase 3: Command Processing
|
|
|
|
#### Step 8: Command Parser with Configurable Prefix
|
|
**Scope**: Parse and validate bot commands from chat messages with configurable prefix
|
|
**Deliverable**: Command parsing system with validation
|
|
**Test Criteria**:
|
|
- Uses command prefix from configuration
|
|
- Correctly identifies commands with prefix
|
|
- Parses command arguments
|
|
- Validates command syntax
|
|
- Returns appropriate error messages for invalid commands
|
|
|
|
**Commands to support**:
|
|
- `<prefix>play <url>` - Clear queue and immediately play song
|
|
- `<prefix>queue <url>` - Add song to queue
|
|
- `<prefix>skip` - Skip current song
|
|
- `<prefix>list` - Show current queue
|
|
- `<prefix>clear` - Clear queue (requires permissions)
|
|
- `<prefix>shuffle` - Shuffle downloaded songs and start playing
|
|
- `<prefix>help` - Show available commands (sent as chat response)
|
|
|
|
#### Step 9: User Permission System
|
|
**Scope**: Implement dynamic user permission system
|
|
**Deliverable**: Permission system that auto-creates users and manages access levels
|
|
**Test Criteria**:
|
|
- Auto-creates users when they first send commands
|
|
- Assigns default permission level from config
|
|
- Validates user permissions for protected commands
|
|
- Provides clear error messages for insufficient permissions
|
|
- Supports permission levels: 0=no access, 1=view only, 2=read/write, 3=admin
|
|
|
|
### Phase 4: Audio Processing
|
|
|
|
#### Step 10: YouTube Audio Downloader
|
|
**Scope**: Download audio from YouTube URLs using yt-dlp
|
|
**Deliverable**: Service that downloads audio files from URLs
|
|
**Test Criteria**:
|
|
- Successfully downloads audio from YouTube URLs
|
|
- Extracts audio in appropriate format (WAV/MP3)
|
|
- Handles invalid URLs gracefully
|
|
- Provides download progress feedback
|
|
- Supports other platforms (SoundCloud, direct MP3 links)
|
|
|
|
#### Step 11: Audio Format Conversion
|
|
**Scope**: Convert downloaded audio to Mumble-compatible format
|
|
**Deliverable**: Audio converter using FFmpeg
|
|
**Test Criteria**:
|
|
- Converts various audio formats to PCM
|
|
- Maintains acceptable audio quality
|
|
- Handles conversion errors gracefully
|
|
- Supports different sample rates and bit depths
|
|
|
|
#### Step 12: Audio Cache Management
|
|
**Scope**: Cache downloaded audio files with size limits
|
|
**Deliverable**: Caching system for audio files
|
|
**Test Criteria**:
|
|
- Stores downloaded files in cache directory
|
|
- Implements LRU eviction when cache size limit reached
|
|
- Prevents duplicate downloads of same URL
|
|
- Provides cache statistics (size, file count)
|
|
- Can manually purge cache
|
|
|
|
### Phase 5: Queue Management
|
|
|
|
#### Step 13: Music Queue Implementation
|
|
**Scope**: Implement thread-safe music queue with play vs queue distinction
|
|
**Deliverable**: Queue system for managing song playback order
|
|
**Test Criteria**:
|
|
- Supports adding songs to queue (`queue` command)
|
|
- Supports clearing queue and immediate play (`play` command)
|
|
- Maintains FIFO ordering for queued songs
|
|
- Thread-safe for concurrent access
|
|
- Supports queue manipulation (skip, clear, shuffle)
|
|
- Enforces maximum queue size limit
|
|
|
|
#### Step 14: Playback Controller with Shuffle
|
|
**Scope**: Control music playback, queue progression, and shuffle functionality
|
|
**Deliverable**: Playback manager that handles audio streaming and shuffle
|
|
**Test Criteria**:
|
|
- Automatically plays next song when current finishes
|
|
- Handles pause/resume functionality
|
|
- Manages audio streaming to Mumble via dumble
|
|
- Provides playback status information
|
|
- Handles empty queue gracefully
|
|
- Implements shuffle from cached songs
|
|
|
|
### Phase 6: Data Persistence
|
|
|
|
#### Step 15: Database Schema
|
|
**Scope**: Design and implement SQLite database schema with permissions tables
|
|
**Deliverable**: Database schema for storing bot data
|
|
**Test Criteria**:
|
|
- Creates all required tables successfully
|
|
- Provides data access layer
|
|
- Handles database connection errors
|
|
|
|
**Tables**:
|
|
```sql
|
|
CREATE TABLE users (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
username TEXT UNIQUE NOT NULL,
|
|
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
|
|
CREATE TABLE permissions (
|
|
id INTEGER PRIMARY KEY,
|
|
name TEXT NOT NULL,
|
|
description TEXT
|
|
);
|
|
-- Insert default permissions: (0, 'none'), (1, 'view'), (2, 'read_write'), (3, 'admin')
|
|
|
|
CREATE TABLE user_permissions (
|
|
user_id INTEGER,
|
|
permission_level INTEGER DEFAULT 0,
|
|
granted_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
|
FOREIGN KEY (user_id) REFERENCES users (id),
|
|
FOREIGN KEY (permission_level) REFERENCES permissions (id)
|
|
);
|
|
|
|
CREATE TABLE cache_entries (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
url TEXT UNIQUE NOT NULL,
|
|
file_path TEXT NOT NULL,
|
|
title TEXT,
|
|
duration INTEGER,
|
|
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
|
last_accessed DATETIME DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
|
|
CREATE TABLE settings (
|
|
key TEXT PRIMARY KEY,
|
|
value TEXT,
|
|
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
```
|
|
|
|
#### Step 16: Data Access Layer
|
|
**Scope**: Implement repository pattern for data access
|
|
**Deliverable**: Repository classes for database operations
|
|
**Test Criteria**:
|
|
- Provides CRUD operations for all entities
|
|
- Uses prepared statements for security
|
|
- Handles database exceptions gracefully
|
|
- Auto-creates users with default permissions
|
|
|
|
### Phase 7: Web Dashboard
|
|
|
|
#### Step 17: Dashboard Authentication
|
|
**Scope**: Implement simple authentication for admin dashboard
|
|
**Deliverable**: Login system with session management
|
|
**Test Criteria**:
|
|
- Login form accepts username/password
|
|
- Creates secure session tokens
|
|
- Validates sessions on protected routes
|
|
- Provides logout functionality
|
|
- Sessions expire after inactivity
|
|
|
|
#### Step 18: Dashboard API Endpoints
|
|
**Scope**: Create REST API for dashboard functionality including user permission management
|
|
**Deliverable**: API endpoints for dashboard operations
|
|
**Test Criteria**:
|
|
- GET /api/queue - Returns current queue
|
|
- DELETE /api/queue - Clears queue
|
|
- GET /api/cache - Returns cache statistics
|
|
- DELETE /api/cache - Purges cache
|
|
- GET /api/users - Returns user list with permission levels
|
|
- PUT /api/users/:id/permissions - Update user permission level
|
|
- POST /api/users - Manually create user (admin only)
|
|
|
|
#### Step 19: Dashboard Frontend
|
|
**Scope**: Create simple HTML/CSS/JS frontend for dashboard with user management
|
|
**Deliverable**: Web interface for bot administration
|
|
**Test Criteria**:
|
|
- Displays current queue with song information
|
|
- Shows cache usage statistics
|
|
- Provides buttons for queue/cache management
|
|
- User management interface for permission levels
|
|
- Responsive design for mobile devices
|
|
- Permission level selector for each user
|
|
|
|
### Phase 8: Integration Testing
|
|
|
|
#### Step 20: Integration Test Bot
|
|
**Scope**: Create automated test bot that simulates user interactions
|
|
**Deliverable**: Test bot that can join Mumble and send commands
|
|
**Test Criteria**:
|
|
- Connects to test Mumble server
|
|
- Sends various commands to music bot
|
|
- Verifies expected responses in chat
|
|
- Confirms audio playback occurs
|
|
- Tests permission levels by simulating different users
|
|
- Validates queue operations work correctly
|
|
|
|
#### Step 21: End-to-End Integration Testing
|
|
**Scope**: Test complete bot functionality using test bot
|
|
**Deliverable**: Comprehensive integration tests
|
|
**Test Criteria**:
|
|
- Bot connects to Mumble and processes commands correctly
|
|
- Audio download and playback works with test bot verification
|
|
- Queue management functions properly (play vs queue distinction)
|
|
- Permission system works (test bot tries restricted commands)
|
|
- Dashboard controls affect bot behavior as expected
|
|
- Cache management operates within limits
|
|
- Shuffle functionality works with cached songs
|
|
|
|
#### Step 22: Error Handling and Documentation
|
|
**Scope**: Implement comprehensive error handling and create documentation
|
|
**Deliverable**: Robust error handling and complete documentation
|
|
**Test Criteria**:
|
|
- Graceful handling of network failures
|
|
- Recovery from Mumble disconnections
|
|
- Proper error messages to users via chat
|
|
- Logging of all errors for debugging
|
|
- README with setup instructions including Docker usage
|
|
- API documentation for dashboard endpoints
|
|
- Configuration file documentation
|
|
|
|
## Testing Strategy
|
|
|
|
Each step should include:
|
|
1. **Unit Tests**: Test individual components in isolation
|
|
2. **Integration Tests**: Test component interactions
|
|
3. **Manual Testing**: Verify functionality works as expected using Docker environment
|
|
4. **Automated Integration Tests**: Use test bot to verify end-to-end functionality
|
|
|
|
## Success Criteria
|
|
|
|
- Bot successfully connects to Mumble server via dumble library
|
|
- Commands are processed correctly with configurable prefix and proper authorization
|
|
- Audio downloads and plays without significant delay
|
|
- Queue vs play distinction works correctly
|
|
- Permission system auto-creates users and manages access levels properly
|
|
- Dashboard provides useful administrative control over user permissions
|
|
- System handles errors gracefully and provides chat feedback
|
|
- Cache management prevents unlimited storage growth
|
|
- Docker environment enables easy local testing
|
|
- Integration test bot can verify functionality automatically
|
|
|
|
## Development Workflow
|
|
|
|
1. Start each development session with `docker-compose up` to run local Mumble server
|
|
2. Develop and test individual components using unit tests
|
|
3. Test integration using manual connections to Docker Mumble server
|
|
4. Use integration test bot to verify end-to-end functionality
|
|
5. Validate dashboard functionality affects bot behavior correctly
|
|
|
|
## Risk Mitigation
|
|
|
|
- **External Dependencies**: yt-dlp and FFmpeg failures should be handled gracefully with chat notifications
|
|
- **Network Issues**: Implement retry logic and connection recovery with dumble
|
|
- **Resource Limits**: Monitor memory and disk usage to prevent system overload
|
|
- **Security**: Validate all user inputs and sanitize file paths
|
|
- **Permission Management**: Default to restrictive permissions and require explicit grants
|