安装与上手
四步装好，第一次启动会进设置向导。
- 装好对应版本的 Fabric / Forge / NeoForge。注意 1.20.1 用的是 Forge 而不是 NeoForge。
- 装前置 —— Fabric 侧是 Fabric API + Fabric Language Kotlin，Forge / NeoForge 侧是 Kotlin for Forge。不同版本的下限不同，见下载页的清单。
- 把对应的 jar 丢进
.minecraft/mods/。
- 启动游戏 → 首次启动进设置向导（选默认音源、登录账号、调界面外观）→ 进游戏按 右 Shift 打开播放器。
向导里选的东西之后都能在游戏内改，不用担心选错。
可选组件
| 组件 | 装了能干什么 | 不装会怎样 |
|---|
| FFmpeg | 动态封面、部分特殊音频容器、哔哩哔哩音频解析 | 普通播放与静态封面不受影响，上述三项不可用 |
OneConfig
Fabric 1.21.1 / 1.21.11 / 26.2 | HUD 设置可以在 OneConfig 的界面里调 | 用内置 HUD 编辑器，功能一样 |
mpsync
服务端 | 启用「服务器一起听房间」 | 房间功能整体空转，其余功能不受影响 |
FFmpeg 放进系统 PATH，或直接丢进 .minecraft/config/muonium/bin/。
只发布 Windows x64。发布包只内置 Windows x64 的图形原生库；其他系统下渲染层会整体停用，表现为「游戏能进、界面出不来」，且日志里不一定有异常。
默认按键
全部可以在游戏的「选项 → 控制」里改，都在 MuoniumPlayer 分组下。
| 操作 | 默认键 | 说明 |
|---|
| 打开音乐界面 | 右 Shift | 仅在未打开 GUI 时响应 |
| 编辑 HUD 位置 | H | 内置编辑器 / OneConfig 页面 |
| 上一曲 | Page Up | 与播放器按钮同一条路径 |
| 下一曲 | Page Down | 同上 |
| 音量 + / − | 小键盘 + / 小键盘 − | 每次 5%，持久化 |
| 暂停 / 继续 | 小键盘 * | 与界面空格共用入口 |
键位沿用 LWJGL2 的码值（构造时转换为 GLFW），与 1.8.9 老版本一致；检测用上升沿触发，长按不会连续切歌。
音源与账号
6 个内置平台，外加自定义音源脚本。
| 平台 | 登录方式 | 能力 |
|---|
| 网易云音乐 | 扫码 / Cookie | 本地多账号切换、会员状态、听歌历史同步、私人 FM、排行榜、实时热搜、数字专辑、音乐盘识别 |
| QQ 音乐 | 扫码（手机 QQ / 微信两条链路） | 账号歌单、QRC 逐字歌词 |
| 酷狗音乐 | 扫码 | 账号歌单、榜单、公开歌单搜索、KRC 逐字歌词 |
| YouTube Music | 免登录 | 补海外曲库；无排行榜与账号歌单 |
| 哔哩哔哩 | 免登录 | 粘贴 BV 号或视频链接，支持分 P；音频解析依赖 FFmpeg |
| GD音乐台 | — | 聚合音源，子页面选具体平台，显示平台状态与请求额度 |
账号凭据只存在本机 config/muonium/ 下，界面不显示 Cookie 明文。
灰色歌曲处理
「音乐来源」菜单里有个开关。开启后，官方链路取不到音频时会按歌名与歌手尝试其他解析链路；关闭则只保留官方结果。
自定义音源脚本（1.4.6+）
支持导入 lx-music-desktop 的 .js 音源脚本。
- 从文件导入，或从剪贴板导入（是脚本正文就直接用，是下载链接就自动下载）
- 单个脚本可启用 / 关闭、删除、重新加载
- 可单独控制是否显示作者更新提示
- 运行状态卡显示：声明的平台、是否经过转译、脚本输出的日志
失败自动回退：自定义音源排在所有内置链路最前面，取不到链接时安静退回网易云 / QQ / 酷狗 / YouTube / GD —— 一份坏脚本不会让你没歌听。播出来的歌会带一枚源徽标，标着脚本自己声明的名字。
脚本没有沙箱。自定义脚本在你本机的 JVM 里由 Rhino 直接执行，能发任意网络请求 —— 只导入你信得过的来源。
已知限制
- 不支持
#私有字段 语法
- 没有单独的代理设置
- 个别返回 GBK 的老接口会乱码
- 自定义源目前只接管取流，歌词与封面仍走内置链路
搜索 · 发现 · 歌单
搜索与发现
- 歌曲搜索 + 搜索联想
- 歌单搜索（网易云 / 酷狗）
- 网易云实时热搜、排行榜、最近播放、我的数字专辑
- 私人 FM：运动 / 专注 / 夜间三种场景，可刷新推荐
歌单
- 我的歌单、收藏歌单、QQ 与酷狗账号歌单
- 歌单详情播放、收藏 / 取消收藏
- Coverflow 封面墙浏览、把歌加入歌单
- 网易云音乐盘歌曲识别与标识
播放 · 音质 · Automix
内置解码器支持 MP3 / AAC / M4A / FLAC。
八档音质
标准、高品质、极高、无损、Hi-Res、高清环绕、沉浸音质、母带。
实际拿到什么音质会如实显示在歌曲行和全屏播放页的徽标上，不会虚标。
元数据徽标
歌曲行与全屏播放页可显示：音源、实际音质、歌词类型、VIP、专辑、网盘、全景声、伴奏、解灰来源。全屏页徽标语言支持中英切换。
播放队列
- 加入「下一首播放」、拖动排序、删除单曲、清空队列、显示队列数量
- 临时队列播完会自动回到进入队列前的那个歌单继续放
Automix 无缝切歌
| 可调项 | 作用 | 范围 / 说明 |
|---|
| 总开关 | 启用无缝过渡 | 关闭即普通切歌 |
| 重叠时长 | 两首交叠时间 | 1.5 s ~ 10 s，默认 4 s；手动切歌自动缩短 |
| 跳过前奏 | 直接进入主歌 | — |
| 小节对齐 | 按节拍网格对齐切点 | — |
| 低频交换 | 交叠期低频互换 | 200 Hz 以下，−18 dB / −12 dB |
| 去人声淡入 | 淡入期压低人声 | 下压深度 0.62 |
| 节奏锁定 | 微调速率对齐 BPM | 0.94× ~ 1.06× |
| 音高跳跃 | 按半音比例匹配调性 | 半音比 1.0594630… |
处理方案：原版淡化 / Folia Automix（1.4.9+）
HUD 的「无缝切换 → 过渡模式 → 处理方案」可以在两套引擎之间切换，两个引擎共用上面的可调项。
- 原版智能淡化：等功率淡化 + 节拍 / 调性分析 + 低架处理。旧配置没有
engine 字段时会自动迁移到这一档，不会静默切换到 Folia。
- Folia Automix：用证据分析挑
beatCut / bassSwap / tailRide / plainBlend 四类过渡，重叠时长按拍、小节或乐句量化，并在空闲 Deck 上提前预滚，避免关闭播放器和解码造成的空档。
可选分析模型
Folia 优先使用下列模型，任一模型不可用都会自动回退到内置确定性分析，分析失败不会阻断播放。
| 模型 | 用途 | 说明 |
|---|
| Beat This! | BPM、拍点、小节相位 | ONNX 模型，由随包管理的 Python 运行组件执行 |
| HTDemucs | 人声、鼓、贝斯与其它分轨时间点 | 仅在表现模式开启时分析歌曲首尾窗口，不处理整首 |
| 必要组件 | Python / ONNX 推理运行时 | 由 HUD 自动下载，不需要预装系统 Python |
- 下载显示进度条、百分比、已下载大小与速度，支持 Hugging Face 镜像、官方源与 GitHub Release 备用源。
- 可指定自定义模型目录、扫描本机模型、做 SHA-256 校验与删除；分析结果进本地档案缓存，同一文件不会重复推理。
- 首次启动向导新增可选的 Automix 模型安装步骤，支持一键按顺序补齐缺失组件；跳过也能继续用原版智能淡化，之后在 HUD 里随时补装。
- 「分析模型 → 模型推理状态」默认开启：推理时在灵动岛显示当前歌曲与运行中的模型，全部成功后显示耗时；用缓存或未安装模型时不会发送通知。
缓存与下载
- 上限可选：不限制 / 2 / 4 / 8 / 16 / 32 / 64 GB（默认 16 GB）
- 超限后从最久未播放的开始清理；正在播放与预备播放的曲目永不清理
- 手动「立即清理」会同时删除中断的下载与转码残留
- 下载时显示进度与速度（灵动岛 + 下载岛）
歌词系统
解析优先级：AMLL TTML → QRC（QQ） → KRC（酷狗） → YRC（网易云） → LRC（行级兜底）。
能力
- 结构：行级、逐字、翻译、音译 / 罗马音、对唱分行、和声标识
- 动效：首字强调、逐字上浮（亚像素平滑）、逐字填涂、动态发光（真高斯）、边缘淡出、滚动柔和度
- 可调：译文 / 音译行透明度、当前行与普通行的缩放与透明度、行间距、发光强度与扩散
全屏歌词 10 种样式
逐行滚动、律动词云 · 心象、浮名、流光、云阶、群唱、倾诉、镜台、时计、苹果。
每种有专属参数 —— 例如「心象」有 6 槽调色板与每色节拍数，「倾诉」有气泡宽度 / 头像来源 / emoji 概率，「时计」有摆弧半径与角度。
桌面歌词 OSD
经典 与 Blossom。Blossom 是毛玻璃卡片，支持可见行数、模糊强度、面板底色、踩点描边与强度；
卡拉 OK 过渡的填涂宽度 / 脉冲 / 平滑 / 对唱展开度均可调。
逐字歌词的动态发光采用真高斯实现，非叠加模糊近似。
主题 · 字体 · HUD · 灵动岛
15 套主题预设
曜石红、极光海、丝绒玫瑰、瓷白墨、液态玻璃、极光霜蓝、午夜石墨、暮色琥珀、鼠尾草雾、
珍珠晨曦、缃云晴川、沧溟玉釉、霜纨岫烟、玫瑰月白、青岚云脂。
调色板支持实时预览与逐项覆盖（背景 / 文字 / 强调色 / 输入框 / 导航栏 / 边框），可一键恢复原色。
界面字体
可选内置字体（随 jar 附带 17 TTF + 2 OTF）、系统已安装字体、外部 TTF / OTF 文件，
或丢进 config/muonium/fonts/。点一行立刻生效，不用重启；行高锁住不会乱排版，
缺字由内置字体接住，不会出现豆腐块。一起听、灵动岛、桌面歌词、HUD 的文字都跟着一起换。
界面行为
- 缩放 70%~100%（5% 步进）+ 窗口自适应
- 打开关闭淡入淡出（速度可调）、栏目切换动画
- 左侧导航 + 内容页滚动、全屏播放页、Coverflow 封面浏览
- 播放器收起时动画连续合并进灵动岛，带 Apple 式撞击反馈
HUD 编辑器
按 H 打开：开关歌曲信息栏与桌面歌词；拖动定位、滚轮缩放、一键恢复默认；
实时调整歌词颜色、发光、缩放、间距、透明度与动画参数。编辑器有经典与 Pro 两套界面。
歌曲信息栏显示封面、歌名、歌手、进度与播放状态。
灵动岛 7 种样式
经典胶囊、通透玻璃、紧凑状态、浮层卡片、系统通知、音乐聚焦、液态玻璃。
承接 11 类事件：下载进度与速度、播放状态、音质切换、主题与样式切换、音量变化、
歌单操作结果、音频转码状态、播放与网络错误、账号登录状态、最近播放同步、一起听状态。
常驻岛：帧率、服务器延迟、系统时间、正在播放信息；状态页与播放页轮换（停留时长可调）。
动画参数：整体大小、字体大小、基础宽度、进度条粗细、展开速度、收起速度、内容切换速度、
入场时长、回弹幅度、转子速度。
转场性能档位（1.4.7+）：按帧率自动进入 Balanced / Low / Minimal，
低配时降载扫光、液态玻璃、歌词装饰与舞台渲染；转场曲线预采样为 513 点查找表。
OneConfig 集成
未安装 → 用内置 HUD 编辑器；已安装 → 可在内置编辑器中切换，之后按 H 直接进入
MuoniumPlayer 页面；不可用时自动回退。配置仍由 MuoniumPlayer 保存，不会生成第二份 HUD 配置。
当前 v1 集成面向 Fabric 1.21.1 / 1.21.11 / 26.2。
一起听 · 玩家向
两条路，用途不一样。
| 网易云官方一起听 | 服务器一起听房间 |
|---|
| 需要什么 | 登录网易云账号，且当前是网易云源 | 服务器装了 mpsync 组件 |
| 谁能进 | 任何网易云用户（含没装 Mod 的） | 同服玩家 |
| 跟随暂停 / 切歌 | 不能自动跟随，要手动同步一次 | 自动跟随 |
| 点歌 / 排队 | — | 有，还有投票切歌、投票踢人 |
| 加入方式 | 分享链接、邀请码、房间号#邀请人ID | 邀请码、公开房间、服务器频道、直接邀请在线玩家 |
网易云官方一起听
创建房间生成分享链接 / 邀请码；可通过链接、邀请码或「房间号#邀请人ID」加入；
房间页显示成员、曲目与进度；可复制链接与邀请码、退出房间。
受官方接口限制，加入方无法自动跟随主机的暂停与切歌，
需在房间页点「同步一次」手动对齐。
服务器房间能干什么
- 房间与成员：创建房间、邀请码加入、发送与处理邀请、公开房间、服务器频道、查看在线玩家直接邀请、成员列表与状态、授予 / 撤销管理员、转让房主、移出成员
- 播放控制：链接点歌、点歌排队、投票切歌（>50%）、投票踢人（>80%）、个人暂停、手动同步、退出房间、房主与房管控制
界面在 播放器 → 一起听 → 一起听 · 服务器房间，顶部六个页签：房间 / 歌单 / 成员 / 在线 / 发现 / 邀请。
个人暂停是「我临时离开一下」的正确用法：只有你静音，房间照放，别人不受影响；
再按一次会直接跳到全房当前位置。不要用房间暂停，那会把所有人一起停掉。
与现代 MP 客户端互通
服务器房间可以和 modernMP 客户端混着用，同一个房间里两种客户端互通。
成员列表里 Mu 是 MuoniumPlayer，MP 是 modernMP，?? 是没上报身份的老版本客户端。
房间里没人有会员怎么办
两条路，服主可以都开：
- 服主自己配 Token —— 服务端自己解析，玩家侧完全无感
- 让玩家「贡献会员解析能力」 —— 玩家自己在设置里打开（默认关）。开启后房间缺链接时服务端优先问这些人，
他们的客户端在本机解析出直链再上传。账号 Cookie 永远不离开自己的电脑，
上传的只是一条带签名、有时效的临时地址，也不占贡献者的上行带宽
两条都没有的话，会员曲会被跳过。
常用命令
/mp create [房名] 创建房间 /mp join <邀请码> 加入
/mp channel 加入服务器频道 /mp public [on|off] 公开 / 私密
/mp invite <玩家> 邀请 /mp leave 离开
/mp info | queue | who 房间信息 | 歌单 | 在线在听
/mp vote skip | /mp vote kick <玩家> 发起投票
/mp agree | /mp deny 对投票表态
点歌在播放器界面里做，命令行不提供搜索点歌。
一起听 · 服主向（mpsync）
主 Mod 是纯客户端的，服务器不需要装。只有要用「服务器一起听房间」时，服主才需要装配套的 mpsync 组件。
要装什么
- 服务端安装 mpsync 1.2.0 以上（同步阈值由服务端统一下发，旧版阈值行为与新客户端不一致）
- 玩家侧不需要任何服务端适配；Fabric / Forge / NeoForge 三个加载器的通道协议逐字节一致
会员曲怎么解决
- 服务端 Token：服主自己配，服务端解析，玩家无感
- 贡献会员解析：由开启该功能的成员在本机解析后上传临时直链，Cookie 不上传
进度来回跳怎么办
先确认 mpsync 是 1.2.0 以上，再按需调整同步阈值（详见《一起听 v2 使用指导》第 6.3 节）。
房间功能在没有 mpsync 时会整体空转，其余功能不受影响 —— 也就是说，
不装 mpsync 的服务器上，玩家仍然可以正常使用播放器本体。
配置文件参考
统一在 .minecraft/config/muonium/ 下。
| 文件 / 目录 | 内容 |
|---|
hud.json | HUD 位置、缩放、歌词外观、灵动岛等全部显示参数 |
player.json | 播放器缩放、音质、默认音源、缓存上限、标签语言 |
theme.json | 主题预设与自定义调色板覆盖 |
ui_font.json / fonts/ | 界面字体选择与自备字体目录 |
music_auth.json
netease_accounts.json
netease_cookie.txt | 账号凭据 |
kugou_auth.json / gd_source.json | 酷狗凭据、GD音乐台平台选择 |
listen_together.json | 一起听设置 |
automix.json | Automix 开关与参数 |
netease_unblock.json | 灰色歌曲解灰开关 |
lx_sources.json | 自定义音源脚本清单 |
update_notice.json | 更新检查开关、跳过版本、清单缓存 |
ffmpeg_notice.json | FFmpeg 提示的「不再显示」状态 |
onboarding.json | 首次启动向导状态 |
cache/music/ · bin/ · native/skija/ | 音频缓存、FFmpeg 目录、Skija 原生库 |
更新检查
拉取公开更新清单（三个来源互为备份），缓存 6 小时，主菜单弹一次提示；
支持关闭检查、跳过版本、打开发布页。客户端永不自动下载或替换 jar，下载页有域名白名单。
已知限制
- 只发布 Windows x64
- 网易云官方一起听受官方接口限制，加入方无法自动跟随主机的暂停与切歌，需要手动同步一次
- 自定义音源脚本无沙箱、不支持
#私有字段、没有单独的代理设置，个别返回 GBK 的老接口会乱码；自定义源只接管取流，歌词与封面仍走内置链路
- YouTube 给的是有时效的高码率 AAC 流，不代表无损；直播与无可用音频流的结果会被跳过
- OneConfig 集成目前面向 Fabric 1.21.1 / 1.21.11 / 26.2
- 音频解码支持 MP3 / AAC / M4A / FLAC，不支持 WebM / Opus 容器
常见问题
装了没反应 / 游戏启动就崩
先确认 Kotlin 前置装了 —— Fabric 侧要 Fabric Language Kotlin，
Forge / NeoForge 侧要 Kotlin for Forge，版本不低于下载页清单的要求。
Kotlin 不再随 Mod 打包，这是最常见的原因。Fabric 侧还需要 Fabric API。
游戏能进，但按右 Shift 什么都不出来
当前发布包只带 Windows x64 的图形原生库。非 Windows 系统下渲染层会整体停用，
而且日志里不一定有异常。也顺手确认一下 jar 文件名里的 MC 版本与加载器和你的实际环境一致。
某首歌放不出来
可能是会员曲、地区限制、平台风控，或者是 YouTube / 哔哩哔哩上被版权方限制的内容。
开着「灰色歌曲处理」可以多一层兜底。服务器房间里还可以走服务端 Token 或贡献会员解析。
封面不会动 / 某个格式放不了
装 FFmpeg，放系统 PATH 或 .minecraft/config/muonium/bin/。
一起听里进度来回跳
先确认服务端 mpsync 是 1.2.0 以上（同步阈值是服务端统一下发的），
再让服主按《一起听 v2 使用指导》第 6.3 节调阈值。
我在成员列表里显示成 ??
用的是不上报身份的老版本客户端。功能不受影响。
点了「下一首」没切歌
你在服务器频道里且不是服务器管理员，这会触发投票 —— 需要超过 50% 同意，30 秒出结果。
能装在服务器上吗？
主 Mod 是纯客户端的，服务器不需要装。只有要用「服务器一起听房间」时，
服主才需要装 mpsync 服务端组件。
更新日志
近期版本的小史，完整发布说明见 MC 百科页面。
| 版本 | 重点 |
|---|
| 1.4.11 | 修复首次播放时暂停图标与进度条不跟随的状态错位：界面原先按引擎线程的播放状态判断，而播放命令要等下一个音频缓冲才生效，首播时这段空窗格外长；现改为按「播放意图」判定，界面不再随引擎延迟抖动。同时修正 Folia Automix 把「测不到落点」的哨兵值当成合法落点候选、导致锚点凭空出现的问题，并让模型目录扫描缓存「未安装」结果 |
| 1.4.10 | 首次设置向导重做为与官网一致的暗色玻璃与红橙品牌视觉，新增 Folia Automix 模型安装页，可逐项或一键安装 Beat This! / HTDemucs 与运行组件；同时修复部分 GUI Scale 与小窗口下内容过小、层级不清、文字难以阅读的问题 |
| 1.4.9 | 新增 Folia Automix 双引擎过渡（可选 Beat This! / HTDemucs 模型分析、四类过渡、双 Deck 预滚与圆环过渡动画）与模型推理状态通知；首次启动向导加入 Automix 模型一键安装。修复缺少 automix.json 时无缝切换被默认关闭、旧配置缺 engine 字段被误判为 Folia、模型下载进度不直观、交接期补偿未进双 Deck 处理链等问题 |
| 1.4.8 | 播放器与全屏歌词的低帧率表现优化（查表转场曲线 + 自动性能档位）；窗口自适应缩放，修正居中与视觉大小一致性；配置、缓存与凭据统一收进 config/muonium/ |
| 1.4.7 | 收起动画连续合并进灵动岛；灵动岛撞击反馈；转场性能档位；布局预热 |
| 1.4.6 / 1.4.5 | HUD 设置整改、歌词发光高斯重写、桌面歌词 Blossom 样式、灵动岛封面与间距、自定义音源脚本支持 |
| 1.4.4 | 全屏播放页曲目信息块、逐行滚动歌词动效 |
| 1.4.2 | 音源与账号界面重做 |
前往 MC 百科查看更新 ↗
MuoniumPlayer v1.4.11
