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

ServerMusicManager - Central music library and playlist management
ServerMusicCommands - Brigadier-based command registration and handling
ServerMusicSender - Network streaming engine with chunk scheduling
MusicStreamClientReceiver - Client-side packet handling and playback
Mp3Player - JLayer-based MP3 decoder and audio playback
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

Install Fabric Loader and Fabric API
Place mod JAR in mods folder
Create music folder (default: music_mp3 in server directory)
Add MP3 files
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

mp3 music server/client side

📖About mp3 music server/client side