主题
MusicHud TuneWeave
在 Minecraft 里搜索、播放音乐，显示逐字歌词，与服务器里的朋友共享播放队列。
本项目基于 MusicHud，使用 TuneWeave 接入音乐平台。支持 Fabric、NeoForge 客户端，以及 Paper、Velocity、BungeeCord 服务端/代理插件。
可以做什么
- 搜索歌曲、歌单、专辑和歌手，浏览并管理平台支持的个人收藏。
- 在账户页查看最近播放的歌曲、专辑和歌单，并继续点歌或打开详情。
- 使用桌面式音乐界面、HUD、逐字歌词、封面和播放来源跳转。
- 点歌、管理队列、投票切歌；将歌单或专辑设为空闲播放源，按随机或顺序模式播放。
- 重抽自己提供的“下一首”空闲歌曲，同时保持当前音乐和歌词继续播放。
- 单人独立使用，或在多人服务器、群组服中同步听歌。
- 使用 TuneWeave 提供的多平台搜索、云盘、Uni 歌单，以及支持的视频、播客、电台等内容。
具体功能、可用音质与 VIP/云盘访问取决于 TuneWeave 的平台支持及音乐账号权限。音乐账号保存在客户端；公共听歌不要求每位玩家都登录音乐账号。
桌面 HUD（Companion）
客户端提供独立 Windows x64 桌面 HUD（默认关闭），继续复用游戏原 HUD Renderer；音乐、歌词、播放队列和多人同步仍由游戏处理。服务源码与 Windows 构建位于独立的 companion 分支，运行时随完整程序包提供，不需要另装 Java。桌面窗口依赖不打入 Minecraft 模组。
在 MusicHud 设置菜单的“桌面 HUD（Companion）”分类中启用。标准版会在首次启用时下载并校验完整程序包，由 Mod 启动；同处提供手动下载、程序路径、版本检查、停止和重启。下载页可以选择安装目录，也可以选择已经完整解压的 Companion.exe。关闭导出或退出游戏会结束 Mod 启动的服务；外部手动启动的进程不被接管。CF 版仅提供画面导出和锁定、帧率、缩放设置，服务仍须自行下载、自行启动。
启用状态、帧率和缩放会保存，并在下次启动游戏后恢复。关闭锁定开关后可以拖动桌面 HUD；重新锁定后整窗鼠标穿透。位置保存在本机，每次连接默认锁定。桌面画布不随游戏窗口或 GUI 缩放改变，最小化游戏后继续更新。游戏必须保持运行。
1.21.1 的桌面 HUD 导出要求 OpenGL。使用 VulkanMod 时，游戏内 HUD 和音乐界面仍可使用，桌面导出会在本次会话停用，已保存的开关不会被清除。
目前尚未发布包含 Companion 的正式 Release；在官方发布 companion-latest.json 与 Windows 包之前，自动下载会明确提示不可用，手动选择完整程序包仍可使用。标准完整发布流程已准备 ZIP、来源提交、校验和及机器清单；CF 和历史范围发布不附带该服务，也不上传到 CurseForge 或 Hangar。
客户端账户
每个平台的用户页可通过带文字图标的“切换账户”按钮选择已保存账户或添加账户，同一平台可保存多个账户。切换不注销旧账户；“退出登录”只删除当前账户，不会自动启用另一个身份。
登录凭据和本地账户资料存放在 API 可执行文件所在目录的 client-accounts.json；默认是游戏目录下的 musichud-tuneweave/client-accounts.json，CF 也使用这个默认目录。旧客户端配置会在私有文件成功持久化后自动清除凭据字段。迁移成功后，只导出 config/ 不再包含这些凭据；导出整个游戏目录时仍须排除该私有文件。首次安装并选择自定义 API 目录时，尚未产生账户文件的客户端会直接使用所选目录。已有账户文件后修改 API 程序目录，需要同时保留并移动该文件，再重启游戏；程序不会搜索其他目录的账户数据，也不会自动合并两个目录中的账户文件。
选择下载文件
当前源码的所有客户端版本推荐使用 ModernUI Lumen 3.13.0.12。历史发行包仍按各自 Release 的依赖说明安装。
| Minecraft | MusicHud 文件后缀 | Java | 推荐 ModernUI |
|---|---|---|---|
| 1.21.1 | +1.21.1.jar | 21 | Lumen 1.21.1-3.13.0.12 |
| 1.21.6–1.21.8 | +1.21.6-1.21.8.jar | 21 | Lumen 1.21.8-3.13.0.12，支持该整个范围 |
| 1.21.9–1.21.10 | +1.21.9-1.21.10.jar | 21 | Lumen 1.21.9-3.13.0.12 / 1.21.10-3.13.0.12，按游戏版本分别选包 |
| 1.21.11 | +1.21.11.jar | 21 | Lumen 1.21.11-3.13.0.12 |
| 26.1–26.1.2 | +26.1-26.1.2.jar | 25 | Lumen 26.1.2-3.13.0.12，支持该整个范围 |
| 26.2 | +26.2.jar | 25 | Lumen 26.2-3.13.0.12 |
| 26.3 | +26.3.jar | 25 | Lumen 26.3-3.13.0.12 |
例如，Minecraft 1.21.7 Fabric 使用 musichud-tuneweave-fabric-<发行版本>+1.21.6-1.21.8.jar。
客户端依赖
Fabric： Fabric Loader（26.3 为 0.19.5+；26.1–26.2 为 0.18.4+；1.21.x 按 Lumen 声明为 0.15.0+，Fabric API 等依赖可能要求更高版本）、Fabric API、对应版本的 ModernUI，以及 MusicHud TuneWeave。26.2 的 Fabric API 最低为 0.160.0+26.2，26.3 最低为 0.160.5+26.3；其他版本选择与游戏版本匹配的 Fabric API。
NeoForge： NeoForge、对应版本的 ModernUI，以及 MusicHud TuneWeave。加载器最低版本与 Lumen 对齐：1.21.6–1.21.8 为 21.6.20-beta，1.21.9 为 21.9.16-beta，1.21.10 为 21.10.64，1.21.11 为 21.11.48，26.1–26.1.2 为 26.1.0.1-beta，26.2 为 26.2.0.0-beta，26.3 为 26.3.0.101；1.21.1 使用对应的 NeoForge 21.1。
所有版本均推荐 ModernUI Lumen 3.13.0.12。选择与 Minecraft 版本及 Fabric/NeoForge 加载器对应的文件，再选择字体版本：
- 普通版：文件名以
-universal.jar结尾，支持自定义字体，无需安装 MiSans。 - MiSans 版：文件名以
-universal-misans.jar结尾，保留 MiSans 字体安装和字重设置；缺少字体时需主动下载并重启。
两版的模组 ID 都是 modernui。升级或切换时替换旧 JAR，不可同时安装。MusicHud TuneWeave 本身无需按字体版本另选 JAR。所有 Lumen Fabric 文件均不需要 Forge Config API Port；Fabric API 仍然必需。
代码同时支持以下已适配的官方 ModernUI：1.21.1 的 3.13.0.1、1.21.6–1.21.8 的 3.13.0.3、26.1–26.1.2 的 3.13.0.5。这些官方 Fabric 文件仍需要 Forge Config API Port。使用官方 Modern UI 时，每次启动会在游戏内显示一次 ModernUI Lumen 推荐页，可选择“继续游戏”。1.21.9、1.21.10、1.21.11、26.2、26.3 使用 Lumen。其他分支及未适配版本会直接拒绝启动，显示“Modern UI 版本过低”和 Lumen 下载地址。
Mod Menu 为 Fabric 可选依赖。不要同时安装多份 ModernUI，也不要与原版 MusicHud 同时安装。
已知外部兼容性
NeoForge 26.2 与原生 Vulkan： 受早期加载窗口（ELS）冲突影响的实例可能无法启动，已记录的案例包括 26.2.0.0-beta。受影响实例可在 config/fml.toml 中设置 earlyWindowControl=false 后重启。上游已在 26.3.0.26-beta 修复，维护者说明该修复不能回移到 26.2；不要将旧版绕过措施套用于已修复的 26.3。参见原问题、重复报告及修复与回移说明。
Linux 日志： 部分 NeoForge、Log4J 与 KQueue 组合可能出现 DebugFile Appender 或 KQueue 初始化错误，上游问题 #3224 仍开放。此类日志不能一概视为无害，应结合当前实例的网络、播放和正常退出情况判断。
首次使用
以下内置下载步骤适用于普通版。CF 版请在模组外安装并启动 TuneWeave，再在设置中填写服务地址；详见下方“构建发行版本”。
- 将模组和对应依赖放入游戏实例的
mods目录，进入世界或服务器，按 M 打开界面。 - 首次使用需要准备 TuneWeave 本地服务。打开设置中的 API 服务区域，点击“下载 TuneWeave 服务端”，选择保存目录和下载方式，再点击“下载”。内置下载会按系统选择发布文件并校验 SHA-256。
- 下载完成后，在“使用该文件并立即（重新）启动 TuneWeave？”提示中选择“是”。确认设置页中的 TuneWeave 状态正常；以后可使用已经保存的服务配置。
- 选择音乐平台；需要个人收藏、云盘等账号功能时，在客户端完成该平台支持的登录流程。
- 搜索歌曲并加入播放队列，或打开歌单/专辑，将其设为空闲播放源。点歌队列优先播放，队列为空后使用空闲播放源。
在账户页点击“最近播放”，可切换歌曲、专辑和歌单记录，显示最近最多 100 条及其时间、可用的设备信息。点击歌曲加入队列，点击专辑或歌单卡片打开详情；时间按本机时区显示。此功能需要 TuneWeave 0.1.0-alpha.11 或更新版本及音乐平台登录，目前由网易云提供支持。
普通版也可以自行下载 TuneWeave 发布文件，在设置中选择可执行文件；已有独立实例时可直接配置其服务地址，默认地址为 http://127.0.0.1:7832。TuneWeave 是运行在客户端机器上的独立程序，不是放进 mods 或 plugins 的 JAR。
普通版下载较慢时可在下载窗口选择 GitHub 下载代理，包括 Axis Now CDN；连接或启动失败时，可查看服务状态、版本和日志。CF 版仅连接已在模组外启动的服务，不提供程序下载或进程日志管理。
常用按键
| 默认按键 | 功能 |
|---|---|
| M | 打开音乐界面 |
| . | 投票跳过当前歌曲 |
| , | 显示/隐藏 HUD |
| 右 Shift | 切换公共连接与客户端隔离模式 |
按键可以在 Minecraft 控制设置中修改；静音、增减音量也可自行绑定。隔离模式下独立播放，不与服务器同步。
多人服务器与群组服
玩家仍需安装客户端模组及其依赖。通常按同一发行版本搭配客户端与插件；1.3.1.1 是客户端热修订，沿用 1.3.1 的 Paper、Velocity、BungeeCord 插件，通信协议不变。
| 环境 | 插件安装位置 | 选择的文件 |
|---|---|---|
| 单人游戏 | 无需独立插件 | 客户端模组即可 |
| 独立 Paper 服务器 | Paper 的 plugins 目录 | musichud-tuneweave-paper-<发行版本>.jar |
| Velocity 群组服 | 仅 Velocity 的 plugins 目录 | musichud-tuneweave-velocity-<发行版本>.jar |
| BungeeCord 群组服 | 仅 BungeeCord 的 plugins 目录 | musichud-tuneweave-bungeecord-<发行版本>.jar |
群组服只在代理层安装本插件，所有后端都不要安装。 代理与后端双装会被检测并阻止连接。代理负责共享队列和公共播放，切换后端时继续由同一个代理协调。
插件采用 Java 21 字节码，实际 Java 版本还要满足服务器或代理自身要求。Paper 的 API 基线为 1.21.1。服务器和代理不安装 ModernUI、不运行 TuneWeave，也不保存音乐平台账号。完整说明见部署说明。
获取更新与反馈
交流与问题反馈请加入荷花的小群：QQ 群 702211431。
全量 CI 和发布流程由默认分支 26.3 管理。当前矩阵覆盖七个客户端版本组的双加载器 JAR，以及 plugin 分支的三个跨版本插件，完整发行版每种各有 17 个部署文件，普通版与 CF 版合计 34 个；1.3.1.1 仅发布上述两个客户端版本组的 4 个普通版及 4 个 CF 文件。发行包附带 SHA256SUMS 与构建来源清单。
GitHub Release 在推送匹配版本标签，或从 26.3 手动运行 CI 并选择 publish 时发布。CurseForge、Hangar 使用独立的 Platform publishing 工作流：从 26.3 运行，填写已发布的 GitHub Release 标签，先 prepare 再 publish。1.3.1.1 使用显式 release_scope=modernui-1.3.1.1 发布范围；仍运行全矩阵检查，仅分发目标客户端，平台发布仅涉及 CurseForge。该流程也保留对旧版 15 文件发布包的校验和重试支持。
Actions 中的 release-bundle 可用于获取开发构建。报告问题时请提供 Minecraft、加载器、MusicHud、ModernUI 和 TuneWeave 的版本，以及复现步骤和相关日志片段；发送前请移除账号凭证。
构建发行版本
CF 专版仅连接已有 TuneWeave 服务，不负责外部程序的下载、更新、启动或管理；完整功能请使用普通版。平台说明见 CF 版 README。
默认构建为普通版。使用 -Pdistribution=cf 构建仅连接已有 TuneWeave 服务的 CF 送审版：
bash
./gradlew common:test fabric:build neoforge:build -Pdistribution=cf --rerun-tasksWindows 使用 gradlew.bat。gradle.properties 中的 mod_version 保持原值；例如 1.3.0-beta-3 会生成 1.3.0-beta-3-cf.1+26.3，其他分支使用各自的 Minecraft 版本范围。省略参数或使用 -Pdistribution=standard 可构建普通版，无需先执行 clean。
CF 版请在模组外自行安装并启动 TuneWeave，再在设置中填写服务地址，通常为 http://127.0.0.1:7832。CF 版没有可执行文件路径、自动启动、子进程控制或进程日志管理设置。服务地址使用独立的 musichud_tuneweave-cf-server.toml，切换发行版时保留普通版的进程配置。
两种版本使用相同的模组标识及通信协议，请只安装其中一种。CF 后缀标识发行方式，不代表已经通过 CurseForge 审核。构建会检查最终 JAR、嵌套依赖和源码 JAR，防止 CF 版残留下载实现。
插件分支也接受该参数并添加 -cf 后缀，功能不变：服务器和代理始终不运行 TuneWeave。Actions 手动运行时可选择 distribution=cf 获取全版本送审产物；该模式不自动发布 GitHub Release 或上传平台；平台发布由前述独立的 Platform publishing 工作流控制。
致谢与许可
感谢 Ephern / Etern 的 MusicHud、ModernUI、mVUS 维护者，以及 TuneWeave。本项目由 MOPELotus 维护，保留上游署名，按 LGPL-3.0 发布。
客户端更新
26.3 客户端启动后检查 GitHub Release 中匹配当前发行版、游戏版本和加载器的更新，正式版与测试版都会提示；设置页也提供手动检查。普通版只自动更新普通版，CF 版只提示匹配的 CF 更新，选择“去看看”仅打开项目主页，不打开 Release 下载页，也不下载或安装文件。普通版选择“立即更新”后下载并校验文件，退出游戏后由独立 Java 进程安装，下次启动生效。请正常退出并稍等安装完成后再启动；旧版 JAR 与安装日志保留在 mods/.musichud-tuneweave-updates/。开发目录、符号链接或非 mods 目录安装不执行自动替换。
更新目录只接受本仓库发布流程产生、含有客户端身份元数据的文件。历史版本没有更新目录时不会被作为自动更新候选。CF 首次提示与更新提示均说明精简范围，并提供项目主页入口查看源码及其他内容；请只安装一种发行版。
普通版更新备份只保留到新版首次正常启动：进入主菜单或游戏并持续正常运行一秒后，验证当前 JAR 与安装记录一致，清理对应更新会话目录（旧 JAR、安装器和日志）；更新根目录为空时一并移除。失败、待安装、身份不匹配或含未知文件的目录不自动删除。
1.21.9–1.21.11 的 CI 构建会从固定提交构建对应版本的 ModernUI 独立 port，再使用这些宿主编译与测试；不会退回 mVUS。手动构建对应客户端分支时，可用 -PmodernuiForkDirectory=/path/to/modernui-jars 指定同时包含匹配 Fabric 和 NeoForge 普通版 JAR 的目录。