mp3 music server/client side

MP3 Music Mod - Project Documentation

Project Overview

MP3 Music Mod is a Minecraft Fabric modification that enables in-game playback of MP3 music files from local directories. Designed for both single-player and multiplayer environments, it provides server operators with tools to broadcast music to all connected players, enhancing the communal gaming experience.

Core Features

🎵 Music Management

• Local Library Support: Plays MP3 files from specified server directories
• Automatic Scanning: Detects and indexes all MP3 files in configured folders
• Real-time Refresh: Update music library without server restart
• Dual Playlist Modes: Sequential and shuffled playlist systems with automatic looping

🎮 In-Game Commands

All commands are OP-only and accessible via chat:

Command Description

• /mp3 Display help with all available commands
• /mp3 folder [path] Show or change server music folder path
• /mp3 list [page] Display paginated list of available MP3 songs
• /mp3 play <name/number> Play specific song by filename or list number
• /mp3 random1 Start sequential playlist (plays all songs in order)
• /mp3 random2 Start shuffled playlist (random order)
• /mp3 next Play next song in playlist or folder sequence
• /mp3 stop Stop music playback for all players
• /mp3 status Display current player status and playlist info
• /mp3 refresh Rescan music folder for new/removed files

🌐 Network Features

• Server-to-Client Streaming: Efficient chunk-based MP3 streaming
• Multiplayer Synchronization: All players hear the same music simultaneously
• Automatic Volume Management: Mutes Minecraft music while mod is playing
• Connection-Aware: Stops playback when no players are connected

Technical Architecture

Core Components

1. ServerMusicManager - Central music library and playlist management
2. ServerMusicCommands - Brigadier-based command registration and handling
3. ServerMusicSender - Network streaming engine with chunk scheduling
4. MusicStreamClientReceiver - Client-side packet handling and playback
5. Mp3Player - JLayer-based MP3 decoder and audio playback
6. Custom Payload System - Fabric networking for music data transmission

Key Technical Details

• Chunk Size: 32KB per network packet for optimal streaming
• Audio Format: Supports standard MP3 formats via JLayer decoder
• Thread Management: Dedicated executors for network and audio processing
• Memory Efficient: Stream-based processing minimizes RAM usage
• Error Handling: Graceful degradation on network issues

Compatibility Matrix

• Component Version Notes
• Minecraft 1.21.10 Primary tested version
• Fabric Loader 0.18.1+ Required for mod loading
• Fabric API 0.138.3+ Networking and command APIs
• Java 21 Runtime requirement
• JLayer 1.0.1 MP3 decoding library

Development Tools & Dependencies

Primary Tools

• Fabric Loom: 1.13.6 (Build system)
• Gradle: 9.1.0 (Dependency management)
• IntelliJ IDEA: Recommended IDE with Fabric support

Key Dependencies

gradle

dependencies {
    // Core Fabric
    modImplementation "net.fabricmc.fabric-api:fabric-api:0.138.3+1.21.10"
    
    // MP3 Decoding
    implementation "javazoom:jlayer:1.0.1"
    
    // Audio Processing
    implementation "com.googlecode.soundlibs:jlayer:1.0.1.4"
}

Build Configuration

properties

# Project Properties
archives_base_name = mp3_music
mod_version = 1.2.2
minecraft_version = 1.21.10
yarn_mappings = 1.21.10+build.1
loader_version = 0.18.1
fabric_version = 0.138.3+1.21.10

Performance Characteristics

Server-Side

• CPU Usage: Minimal during idle, moderate during encoding/streaming
• Memory: ~50-100MB additional for music buffering
• Network: ~256-512 Kbps per connected player during streaming
• Disk I/O: Initial file scan only, streaming from memory buffer

Client-Side

• CPU: Moderate during MP3 decoding
• Memory: ~20-50MB for audio buffers
• Audio Latency: <500ms from server to playback start
• Compatibility: Works alongside other audio mods

Deployment Scenarios

Single-Player

• Works with integrated Fabric server
• Direct file access from game directory
• All commands available to player

Multiplayer Server

• Dedicated server support
• OP-only command access
• Broadcast to all connected players
• Automatic cleanup on player disconnect

Modpack Integration

• No world generation changes
• Compatible with most Fabric mods
• Configurable permission levels
• Minimal resource conflicts

User Experience

Setup Process

1. Install Fabric Loader and Fabric API
2. Place mod JAR in mods folder
3. Create music folder (default: music_mp3 in server directory)
4. Add MP3 files
5. Use /mp3 folder to configure path if needed

Typical Usage Flow

text

Operator: /mp3 folder music_mp3
[System]: Music folder set, contains 15 MP3 files
Operator: /mp3 list 1
[System]: Displaying songs 1-10...
Operator: /mp3 random2
[System]: Started shuffled playlist: Song1.mp3
[All Players]: Music begins playing simultaneously

Future Compatibility

Upgrade Path to 1.21.11

• Expected: Minor Fabric API changes only
• Testing Required: Network packet format verification
• Migration: Update Fabric API dependency version
• Backward Compatibility: Likely maintains 1.21.10 support

Long-term Maintenance

• API Monitoring: Track Fabric API deprecations
• Version Pinning: Lock to stable Minecraft versions
• Community Feedback: Incorporate user suggestions
• Performance Optimization: Ongoing network and memory improvements

Support & Community

Known Issues

• Gap between songs during playlist transitions
• Large MP3 files (>50MB) may cause initial buffering delay
• First-time setup requires manual folder configuration

Best Practices

• Use MP3 files under 10MB for optimal streaming
• Organize music in dedicated folders
• Regular /mp3 refresh after adding new files
• Monitor server logs for network issues

• Project Status: Production Ready
• License: GNU General Public License v3.0
• Maintainer: SPMATRIX
• Contributions: Open to community feedback and improvements