自定义音乐播放器

Minecraft 音乐播放器

Minecraft 音乐播放器是一款适用于 Minecraft 1.21.11 的 Fabric 音乐模组。它提供网易云音乐搜索、点歌、共享队列播放、歌单播放、自定义音乐唱片以及基于 URL 的唱片机播放功能。

服务端负责处理指令、队列逻辑、搜索请求、同步、随机战利品唱片注入以及唱片机控制。客户端负责实际的音频下载、播放和唱片机封面渲染。这是一个双端模组，并非纯粹的服务端音频模组。

功能特性

• 搜索歌曲、艺术家、歌单和用户
• 查看艺术家热门歌曲、歌单详情和用户歌单
• 所有主要列表页面均支持统一分页和可点击导航
• 支持点击操作：点歌、烧录、查看详情和下载
• 共享点歌、队列播放、自动切歌和投票跳歌
• 重复点歌去重以及将队列曲目移至下一首的支持
• 服务端队列预取以减少曲目间延迟
• 将歌曲烧录为原版音乐唱片，并从唱片机播放基于 URL 的音乐
• /music random 每次生成 10 首随机热门歌曲
• 所有基于战利品表的容器均可根据管理员设置生成随机热门音乐唱片

工作原理

• 服务端负责指令执行、搜索请求、播放队列、战利品唱片生成和唱片机同步
• 客户端负责实际音频播放和唱片机封面渲染
• 如果只有服务端安装模组，指令和队列逻辑可以工作，但客户端无法听到音乐
• 想要听到音乐的玩家必须在客户端安装模组

推荐配置：

1. 在服务端安装 Minecraft 音乐播放器
2. 在需要听到音乐的客户端安装 Minecraft 音乐播放器
3. 确保服务端或客户端可以访问可用的音乐 API 端点

前置要求

• Minecraft 1.21.11
• Fabric Loader 0.18.4 或更新版本
• Fabric API 0.141.3+1.21.11 或兼容版本
• Java 21
• 可访问的网易相关音乐 API 服务，默认为 https://mycelis.dpdns.org/

安装方法

服务端

将模组 jar 文件和 Fabric API 放入服务端的 mods 文件夹。

客户端

将模组 jar 文件和 Fabric API 放入客户端的 mods 文件夹。

默认 API 地址

默认配置使用：

https://mycelis.dpdns.org/

管理员可以通过指令覆盖该地址，之后也可以恢复默认值。

音乐唱片

烧录流程

1. 主手持有任意原版音乐唱片
2. 执行 /music burn song <song_id> 指令
3. 或在支持的列表页面中点击 [烧录]
4. 获得一张存储了曲目元数据和 URL 的自定义音乐唱片

唱片元数据

烧录的唱片会存储：

• 歌曲 ID
• 歌曲标题
• 艺术家名称
• 艺术家 ID
• 封面 URL
• 时长
• 可用的来源 URL

唱片机播放

• 将烧录的唱片插入唱片机后，会自动播放存储的 URL 音乐
• 播放是围绕唱片机进行空间定位的，而非全局背景音乐
• 唱片机的四个侧面会渲染旋转的唱片风格封面效果
• 当唱片被弹出、更换、唱片机被破坏、区块卸载或玩家离开可听范围时，播放会停止
• 待处理的占位唱片无法插入唱片机，如果对其使用唱片机则不会产生任何效果

烧录入口

当玩家主手持有可烧录的唱片时，以下界面会自动显示 [烧录] 操作：

• /music now
• /music queue
• /music random
• /music search song ...
• /music view playlist ...
• /music view artist ...
• /music view author ...

随机热门音乐

使用指令：

/music random

行为说明：

• 每次生成 10 首随机热门歌曲
• 歌曲来源为从热门歌单分类中选出的热门歌单
• 每次刷新都会生成不同的列表
• 每个条目都支持：
  • 点歌
  • 烧录为唱片
  • 查看艺术家详情
  • 打开直接下载 URL

战利品容器随机音乐唱片

该模组可以在所有基于战利品表的容器首次被打开时，向其注入随机热门音乐唱片。

行为说明：

• 适用于基于战利品表的方块容器和实体容器
• 每个容器只判定一次
• 首次打开时，会先插入一个临时"生成中"的占位唱片，随后在后台异步解析真实唱片
• 如果玩家提前取出占位唱片，它仍会在稍后于玩家背包或当前打开的容器中完成解析
• 解析完成后保留原版唱片物品类型，因此颜色和外观不会改变
• 生成的唱片来自从热门歌单中选出的随机热门歌曲
• 管理员可以配置是否启用此功能、生成概率以及每个容器最多生成的唱片数量

玩家指令

指令	描述
/music	显示帮助
/music now	显示当前曲目并附带可点击的下载入口
/music queue [page]	显示当前播放队列
/music queue next <song_id>	将已排队的歌曲移至下一首位置
/music join	加入当前播放
/music leave	离开当前播放
/music mute once	仅停止接收当前歌曲
/music vote next	投票跳到下一首曲目
/music play song <song_id>	点播单首歌曲
/music play playlist <playlist_id>	切换为歌单播放模式
/music burn song <song_id>	将持有的唱片烧录为音乐唱片
/music random	生成 10 首随机热门歌曲
/music random refresh	生成另一组随机热门歌曲列表
/music search song <keyword>	搜索歌曲
/music search song page <page> <keyword>	查看特定页的歌曲搜索结果
/music search artist <keyword>	搜索艺术家
/music search artist page <page> <keyword>	查看特定页的艺术家搜索结果
/music search author <keyword>	artist 的别名
/music search playlist <keyword>	搜索歌单
/music search playlist page <page> <keyword>	查看特定页的歌单搜索结果
/music search user <keyword>	搜索用户
/music search user page <page> <keyword>	查看特定页的用户搜索结果
/music view artist <artist_id>	查看艺术家热门歌曲
/music view artist page <page> <artist_id>	查看特定页的艺术家详情
/music view author <artist_id>	artist 的别名
/music view playlist <playlist_id>	查看歌单详情
/music view playlist page <page> <playlist_id>	查看特定页的歌单详情
/music view user <user_id>	查看用户歌单
/music view user page <page> <user_id>	查看特定页的用户歌单

管理员指令

指令	描述
/music admin reload	重新加载配置
/music admin status	显示当前配置状态
/music admin clearqueue	清空排队的曲目
/music next	立即跳到下一首曲目
/music stop	停止播放
/music admin set baseUrl <url>	设置音乐 API 基础 URL，或使用 default 恢复默认值
`/music admin set allowCustomServer <true	false>`
`/music admin set allowSongRequest <true	false>`
`/music admin set allowPlaylistRequest <true	false>`
`/music admin set autoAdvance <true	false>`
`/music admin set announceQueueChanges <true	false>`
`/music admin set showLoadingHints <true	false>`
`/music admin set useSystemProxy <true	false>`
`/music admin set preferIpv4 <true	false>`
/music admin set proxy <host:port>	设置 HTTP 代理
/music admin set proxy none	清除代理设置
/music admin set connectTimeoutSeconds <3-60>	设置连接超时时间
/music admin set readTimeoutSeconds <3-120>	设置读取超时时间
/music admin set searchLimit <3-20>	设置列表页面大小
/music admin set maxQueueSize <1-200>	设置队列大小限制
/music admin set playlistQueueLimit <1-100>	设置每个歌单最大导入歌曲数
/music admin set queueCacheSize <0-20>	设置服务端队列预取大小
`/music admin set enableLootMusicDiscs <true	false>`
/music admin set lootMusicDiscChance <0.0-1.0>	设置随机战利品音乐唱片的生成概率
/music admin set lootMusicDiscCount <0-5>	设置战利品容器可生成的随机音乐唱片数量
/music admin set voteSkipPercent <0.1-1.0>	设置投票跳歌比例

配置说明

配置文件路径：

config/minecraft-music-player.json

默认配置示例：

{
  "neteaseBaseUrl": "https://mycelis.dpdns.org/",
  "proxy": "",
  "useSystemProxy": true,
  "preferIpv4": true,
  "allowCustomServer": true,
  "allowSongRequest": true,
  "allowPlaylistRequest": true,
  "autoAdvance": true,
  "announceQueueChanges": true,
  "showLoadingHints": true,
  "connectTimeoutSeconds": 10,
  "readTimeoutSeconds": 20,
  "searchLimit": 8,
  "maxQueueSize": 40,
  "playlistQueueLimit": 20,
  "queueCacheSize": 3,
  "enableLootMusicDiscs": true,
  "lootMusicDiscChance": 0.3,
  "lootMusicDiscCount": 1,
  "voteSkipPercent": 0.6
}