MP3 Music Mod - 项目文档
项目概述
MP3 Music Mod 是一款 Minecraft Fabric 模组,支持从本地目录在游戏中播放 MP3 音乐文件。该模组适用于单人及多人游戏环境,为服务器管理员提供了向所有连接玩家广播音乐的工具,从而增强社区游戏体验。
核心功能
? 音乐管理
- 本地库支持:播放指定服务器目录中的 MP3 文件
- 自动扫描:检测并索引配置文件夹中的所有 MP3 文件
- 实时刷新:无需重启服务器即可更新音乐库
- 双播放列表模式:顺序和随机播放列表系统,支持自动循环
? 游戏内命令
所有命令仅限 OP(操作员)使用,并通过聊天栏访问:
命令 描述
- /mp3 显示所有可用命令的帮助信息
- /mp3 folder [path] 显示或更改服务器音乐文件夹路径
- /mp3 list [page] 显示分页的可用 MP3 歌曲列表
- /mp3 play <name/number> 通过文件名或列表编号播放特定歌曲
- /mp3 random1 开始顺序播放列表(按顺序播放所有歌曲)
- /mp3 random2 开始随机播放列表(随机顺序)
- /mp3 next 播放播放列表或文件夹序列中的下一首歌曲
- /mp3 stop 停止所有玩家的背景音乐播放
- /mp3 status 显示当前播放器状态和播放列表信息
- /mp3 refresh 重新扫描音乐文件夹以查找新增或删除的文件
? 网络功能
- 服务端到客户端流式传输:基于分块的 MP3 高效流式传输
- 多人同步:所有玩家同时听到相同的音乐
- 自动音量管理:在模组播放时静音 Minecraft 原声音乐
- 连接感知:当没有玩家连接时自动停止播放
技术架构
核心组件
- ServerMusicManager - 中央音乐库和播放列表管理
- ServerMusicCommands - 基于 Brigadier 的命令注册和处理
- ServerMusicSender - 具有分块调度功能的网络流式传输引擎
- MusicStreamClientReceiver - 客户端数据包处理与播放
- Mp3Player - 基于 JLayer 的 MP3 解码器和音频播放
- Custom Payload System - 用于音乐数据传输的 Fabric 网络系统
关键技术细节
- 分块大小:每个网络数据包 32KB,以实现最佳流式传输效果
- 音频格式:通过 JLayer 解码器支持标准 MP3 格式
- 线程管理:为网络和音频处理分配专用执行器
- 内存高效:基于流的处理最大限度地减少 RAM 使用
- 错误处理:在网络问题发生时优雅降级
兼容性矩阵
- 组件 版本 备注
- Minecraft 1.21.10 主要测试版本
- Fabric Loader 0.18.1+ 模组加载必需
- Fabric API 0.138.3+ 网络和命令 API
- Java 21 运行时要求
- JLayer 1.0.1 MP3 解码库
开发工具与依赖项
主要工具
- Fabric Loom: 1.13.6 (构建系统)
- Gradle: 9.1.0 (依赖管理)
- IntelliJ IDEA: 推荐的具有 Fabric 支持的 IDE
关键依赖项
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"
}
构建配置
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
性能特征
服务端
- CPU 占用:空闲时极低,编码/流式传输期间中等
- 内存:音乐缓冲额外占用约 50-100MB
- 网络:流式传输期间每个连接玩家约 256-512 Kbps
- 磁盘 I/O:仅在初始文件扫描时进行,后续从内存缓冲区流式传输
客户端
- CPU:MP3 解码期间中等
- 内存:音频缓冲占用约 20-50MB
- 音频延迟:从服务器到开始播放小于 500ms
- 兼容性:可与其他音频模组共存
部署场景
单人游戏
- 可与集成 Fabric 服务器配合使用
- 直接从游戏目录访问文件
- 玩家可使用所有命令
多人服务器
- 支持专用服务器
- 仅限 OP 访问命令
- 向所有连接玩家广播
- 玩家断开连接时自动清理
整合包集成
- 不改变世界生成
- 与大多数 Fabric 模组兼容
- 可配置的权限级别
- 资源冲突极少
用户体验
设置流程
- 安装 Fabric Loader 和 Fabric API
- 将模组 JAR 文件放入 mods 文件夹
- 创建音乐文件夹(默认:服务器目录下的 music_mp3)
- 添加 MP3 文件
- 如有需要,使用 /mp3 folder 配置路径
典型使用流程
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
未来兼容性
升级至 1.21.11 的路径
- 预期:仅涉及少量 Fabric API 变更
- 需测试:验证网络数据包格式
- 迁移:更新 Fabric API 依赖版本
- 向后兼容:可能保留对 1.21.10 的支持
长期维护
- API 监控:跟踪 Fabric API 弃用情况
- 版本锁定:锁定稳定的 Minecraft 版本
- 社区反馈:采纳用户建议
- 性能优化:持续改进网络和内存性能
支持与社区
已知问题
- 播放列表转换期间歌曲之间存在间隙
- 大型 MP3 文件(>50MB)可能导致初始缓冲延迟
- 首次设置需要手动配置文件夹
最佳实践
- 使用小于 10MB 的 MP3 文件以获得最佳流式传输效果
- 将音乐组织在专用文件夹中
- 添加新文件后定期使用 /mp3 refresh
- 监控服务器日志以排查网络问题
- 项目状态: 生产就绪
- 许可证: GNU 通用公共许可证 v3.0
- 维护者: SPMATRIX
- 贡献: 欢迎社区反馈与改进
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
评论 0
登录后参与评分
还没有评论,来抢沙发吧