mp3 音乐服务器/客户端

mp3 音乐服务器/客户端

该模组设计用于单人和多人游戏环境。当广播模式激活时,操作员(OPs)可以利用服务器端功能向所有连接的玩家传输音乐,从而增强共享的游戏体验。

工具

MP3 音乐模组 - 项目文档

项目概述

MP3 音乐模组是一个 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 音乐
  • 连接感知:无玩家连接时停止播放

技术架构

核心组件

  1. ServerMusicManager - 中央音乐库和播放列表管理
  2. ServerMusicCommands - 基于 Brigadier 的命令注册和处理
  3. ServerMusicSender - 带分块调度的网络流式传输引擎
  4. MusicStreamClientReceiver - 客户端数据包处理和播放
  5. Mp3Player - 基于 JLayer 的 MP3 解码器和音频播放
  6. 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:推荐的 IDE,支持 Fabric

关键依赖

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 模组兼容
  • 可配置权限等级
  • 资源冲突极少

用户体验

安装流程

  1. 安装 Fabric Loader 和 Fabric API
  2. 将模组 JAR 放入 mods 文件夹
  3. 创建音乐文件夹(默认:服务器目录中的 music_mp3)
  4. 添加 MP3 文件
  5. 如需配置路径,使用 /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 General Public License v3.0
  • 维护者: SPMATRIX
  • 贡献: 欢迎社区反馈和改进