mumbullet/ROADMAP.md

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:

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:

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:

{
  "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:

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