网易云音乐播放器

Minecraft Music Player

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

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

功能特性

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

工作原理

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

推荐配置：

1. 在服务端安装 Minecraft Music Player
2. 在需要听到音乐的客户端上安装 Minecraft Music Player
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. 或在支持的列表页面中点击 [Burn]
4. 获得一张存储了曲目元数据和 URL 的自定义音乐唱片

唱片元数据

刻录后的唱片存储：

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

唱片机播放

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

刻录入口

当玩家主手持有可刻录唱片时，以下视图中会自动显示 [Burn] 操作：

• /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>	是否允许自定义 API URL
/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>	是否优先使用 IPv4
/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
}

中文

Minecraft Music Player 是一个面向 Minecraft 1.21.11 的 Fabric 音乐模组，提供基于网易云音乐的共享播放队列、搜索、点歌和播放同步能力。

服务端负责命令、队列、搜索、同步和配置管理；客户端负责实际的音频拉取和播放。因此这是一个双端协作的模组，而不是纯服务端音频模组。

功能概览

• 搜索歌曲、作者、歌单和用户
• 查看作者热门歌曲、歌单详情和用户歌单
• 所有主要列表支持分页与可点击导航
• 所有高频条目支持点击查看详情、点歌、刻录或下载
• 共享点歌、待播队列、自动下一首、投票切歌
• 重复点歌自动去重，待播歌曲支持提升为下一首
• 服务端队列预缓存，减少切歌解析等待
• 将歌曲刻录进原版唱片，并放入唱片机播放 URL 音乐
• /music random 每次生成 10 首随机热门音乐，可直接点歌和刻录
• 所有带战利品表的容器都可按配置随机生成热门音乐唱片

工作方式

• 服务端安装本模组后，负责命令处理、搜索请求、播放队列、战利品箱随机唱片和唱片机同步
• 客户端安装本模组后，负责实际播放音频和渲染唱片机封面
• 只有服务端安装时，命令和队列逻辑可以工作，但客户端听不到声音
• 需要听歌的玩家必须安装客户端模组

推荐部署方式：

1. 服务器安装 Minecraft Music Player
2. 所有需要听歌的客户端也安装 Minecraft Music Player
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/

安装

服务端

将模组主文件和 Fabric API 放入服务器的 mods 目录。

客户端

将模组主文件和 Fabric API 放入客户端的 mods 目录。

默认 API 地址

默认配置使用：

https://mycelis.dpdns.org/

管理员可以通过命令修改地址，也可以恢复到默认值。

音乐唱片

刻录流程

1. 主手持有任意原版唱片
2. 使用 /music burn 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 首随机热门音乐
• 来源是热门歌单分类下的热门歌单，再从歌单中随机抽歌
• 每次生成的列表都不同
• 列表中的每一首歌都支持：
  • 点歌
  • 刻录
  • 查看作者详情
  • 下载当前直链

战利品箱随机音乐唱片

本模组支持在所有带战利品表的容器第一次被打开时，按配置随机注入热门音乐唱片。

行为说明：

• 对所有带 loot table 的方块容器和实体容器生效
• 每个容器只会决策一次，不会重复生成
• 首次打开时会先放入“随机音乐唱片生成中”的占位唱片，后台异步生成真正的音乐唱片
• 如果玩家先把占位唱片拿走，生成完成后会自动在玩家背包或当前打开的容器里替换成真正的音乐唱片
• 生成完成后会保留原始唱片底盘类型，不会改变颜色和外观
• 生成的唱片内容来自热门歌单中的随机热门歌曲
• 可由管理员配置是否启用、生成概率和每个容器的数量

玩家命令

命令	说明
/music	显示帮助
/music now	查看当前播放，并提供下载入口
/music queue [page]	查看当前待播队列
/music queue next <歌曲ID>	将队列中的歌曲提升为下一首
/music join	加入当前播放
/music leave	退出当前播放
/music mute once	仅停止接收当前歌曲
/music vote next	投票切到下一首
/music play song <歌曲ID>	直接点播单曲
/music play playlist <歌单ID>	切换到歌单播放模式
/music burn song <歌曲ID>	将主手唱片刻录为音乐唱片
/music random	生成 10 首随机热门音乐
/music random refresh	重新生成随机热门音乐列表
/music search song <关键词>	搜索歌曲
/music search song page <页码> <关键词>	查看歌曲搜索指定页
/music search artist <关键词>	搜索作者
/music search artist page <页码> <关键词>	查看作者搜索指定页
/music search author <关键词>	artist 的别名
/music search playlist <关键词>	搜索歌单
/music search playlist page <页码> <关键词>	查看歌单搜索指定页
/music search user <关键词>	搜索用户
/music search user page <页码> <关键词>	查看用户搜索指定页
/music view artist <作者ID>	查看作者热门歌曲
/music view artist page <页码> <作者ID>	查看作者详情指定页
/music view author <作者ID>	artist 的别名
/music view playlist <歌单ID>	查看歌单详情
/music view playlist page <页码> <歌单ID>	查看歌单详情指定页
/music view user <用户ID>	查看用户歌单
/music view user page <页码> <用户ID>	查看用户歌单指定页

管理员命令

命令	说明
/music admin reload	重新加载配置
/music admin status	查看当前配置状态
/music admin clearqueue	清空待播队列
/music next	立即切到下一首
/music stop	停止播放
/music admin set baseUrl <地址>	设置音乐 API 地址，传入 default 恢复默认值
/music admin set allowCustomServer <true|false>	是否允许使用自定义 API 地址
/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>	是否优先使用 IPv4
/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
}