使用文档

安装与上手

四步装好，第一次启动会进设置向导。

1. 装好对应版本的 Fabric / Forge / NeoForge。注意 1.20.1 用的是 Forge 而不是 NeoForge。
2. 装前置 —— Fabric 侧是 Fabric API + Fabric Language Kotlin，Forge / NeoForge 侧是 Kotlin for Forge。不同版本的下限不同，见下载页的清单。
3. 把对应的 jar 丢进 .minecraft/mods/。
4. 启动游戏 → 首次启动进设置向导（选默认音源、登录账号、调界面外观）→ 进游戏按 右 Shift 打开播放器。

向导里选的东西之后都能在游戏内改，不用担心选错。

向导外壳与播放器同一副骨架，进播放器不会重排。开场招呼字有约 5 秒门禁， 期间点击不响应；按 ESC 可连引导一起跳过。

可选组件

FFmpeg 放进系统 PATH，或直接丢进 .minecraft/config/muonium/bin/。

默认按键

全部可以在游戏的「选项 → 控制」里改，都在 MuoniumPlayer 分组下。

播放器界面里的快捷操作

• 空格 —— 暂停 / 继续（与界面按钮同一条路）
• Ctrl+F —— 呼出快捷搜索栏，找歌不用回主页
• 音量也可以在界面右下角滚轮调；进度条直接拖

按键没反应？

• 右 Shift 没反应：先确认没有打开其他界面（聊天框、背包、容器都会挡）；再确认键位没被别的 Mod 占用。
• 改键位：游戏「选项 → 控制」→ 拉到 MuoniumPlayer 分组，全部可改。
• 笔记本没有小键盘：音量与暂停直接在播放器界面里点，或改键到顺手的键。

音源与账号

8 个内置平台，外加自定义音源脚本。

账号凭据只存在本机 config/muonium/ 下，界面不显示 Cookie 明文。

酷狗取流、收藏与上报都依赖账号登录；未登录时行为与网易云一致，只降到行级歌词与静态封面。「删除酷狗歌单」这条端点尚未证实，请不要当作可用功能。

灰色歌曲处理

「音乐来源」菜单里有个开关。开启后，官方链路取不到音频时会按歌名与歌手尝试其他解析链路；关闭则只保留官方结果。

跨平台自动换源

放不出、或只有试听的歌，可以按歌名与歌手去别的平台找同一首换过来 —— 取流失败时自动换，也可以在歌曲行右键强制换一次。开关在音源面板的「跨平台自动换源」，默认开；一起听房间里不启用（谁点的歌用谁的账号播）。

YouTube：登录、歌单与电台

YouTube 是唯一一个不登录也能搜能播的平台，所以登录是能力增强而不是前置条件。入口在 「音乐来源」的 YouTube 卡片上（钥匙图标），粘贴浏览器里 music.youtube.com 的整串 Cookie， 点「验证并登录」—— 这一步会真打一次账号接口，成功才落盘。没有扫码这条路（YouTube 没有可用的扫码端点）， 也不做设备码登录：那要求把第三方凭据内置进分发包。

凭据只用于元数据（歌词、歌单、账号信息），取流仍走匿名的 Android 客户端：实测登录态对取流 没有必要，而把 Cookie 发给每一个 CDN 请求反而是多余的暴露面。已登录且 YouTube 自己给出歌词时，它排在 跨平台按名字匹配之前 —— 现场版、翻唱与录音室版常常同名不同曲，按名字匹配会给出另一版的词。

粘贴歌单链接（含 ?list=）会导入成歌单；粘贴单首歌的链接会导入成「这首歌的电台」， 曲目来自自动电台队列。排行榜与首页推荐流仍然没有。

汽水的两条登录路

两条路都需要先下载取码工具：夸克网盘（下载后打开，按界面流程走）。

扫码（推荐）：打开取码工具 → 用抖音 / 汽水音乐 App 扫码 → 正常走官方登录流程 → 工具自动取得 Cookie，粘进游戏即可。扫码走的就是官方登录流程，账号安全不受影响； 触发二次验证时工具自己弹窗，在游戏外处理完再回游戏等着就行。

Cookie 导入：工具里也能直接复制 Cookie 文本粘贴进游戏 —— 裸 k=v、带 Cookie: 前缀、devtools 里复制的一整串都能认。两条路最后都真打一次账号接口， 拿到昵称才写入本地会话。

取码工具常驻复用：一次扫码结束只转入空闲，下次直接出码；空闲超过 5 分钟自己退出。 请使用 0.3.1 及以后的工具版本。

Apple Music 登录

用自己的 Apple Music 订阅听完整歌曲 —— 内置纯 Java 引擎，不需要装任何外部程序； 放不了时自动换到能播的平台，实在不行也有 30 秒试听。

登录三步（都在游戏内「账号管理 → Apple Music」页面完成）：

① 登录 Apple 账号：页面里直接走 Apple 官方登录流程，拿到 cookies。

② 贴入 cookies：按页面提示粘贴，验证通过即登录成功。

③ 开听：排行榜（8 个地区）、资料库歌曲与歌单、逐词歌词同步解锁。

音质 AAC 256k，与官方 App 相同码率；没订阅也能用——非订阅账号走 30 秒试听； 放不了的歌会自动换到别的平台找同一首。

音源支持情况一览

按当前版本实测情况如实标注 —— 没有的能力不写「支持」。

灰色歌曲处理与跨平台自动换源（默认开）是所有内置源共用的兜底；一起听房间内不启用换源（谁点的歌用谁的账号播）。各平台账号凭据只存本机。

自定义音源脚本（1.4.6+）

支持导入 lx-music-desktop 的 .js 音源脚本。

• 从文件导入，或从剪贴板导入（是脚本正文就直接用，是下载链接就自动下载）
• 单个脚本可启用 / 关闭、删除、重新加载
• 可单独控制是否显示作者更新提示
• 运行状态卡显示：声明的平台、是否经过转译、脚本输出的日志
• 1.6.0 起脚本可额外提供 搜索 / 歌词 / 封面 三个动作，在音源页「允许脚本提供搜索 / 歌词 / 封面」里打开（默认关）；取流与搜索是脚本优先，歌词与封面是内置兜底取不到时才问脚本
• 常见脚本兼容问题已内置处理（http→https 跟跳、现代 JS 垫片），失败时日志会讲清是哪一次请求、哪一行脚本

失败自动回退：自定义音源排在所有内置链路最前面，取不到链接时安静退回网易云 / QQ / 酷狗 / YouTube / GD —— 一份坏脚本不会让你没歌听。播出来的歌会带一枚源徽标，标着脚本自己声明的名字。

已知限制

• 不支持 #私有字段 语法
• 没有单独的代理设置
• 个别返回 GBK 的老接口会乱码
• 用到 BigInt 字面量的脚本仍然加载不了 —— 这是引擎级硬缺口（Rhino 1.7.15 不支持）， 不是脚本写错了
• 默认只接管取流；歌词 / 封面 / 搜索要在音源页显式打开「允许脚本提供搜索 / 歌词 / 封面」才会问脚本

搜索 · 发现 · 歌单

搜索与发现

• 歌曲搜索 + 搜索联想（联想开关按平台分别控制）
• 歌单搜索（网易云 / 酷狗）
• 网易云实时热搜、排行榜、最近播放、我的数字专辑；酷狗热搜、最近播放、私人 FM、每日推荐（1.4.12 起）
• 网易云私人 FM：模式选择补全（1.6.0 按官方文档全量 42 项场景子模式、分 4 组流式换行），选中的模式会记住，下次进来还在
• 私人 FM 在 1.7.0 整页重排：当前推荐改成一张 hero 卡（大封面直接点进播放，曲名 / 艺人 / 时长与专辑、VIP、云盘、解灰徽标分行排好，动作行是红心、换一首、播放）， 场景标签按 默认 / 风格 / 场景 / 人群 / 私密 拆成每组一行、行内横向滚动、整块可展开收起，播放模式与标签统一成「轨道 + 滑块」那一条控件
• FM 新增「刚才推荐过」：最多留 20 首，跳过与换一批都会退进这里，可以回头点

歌单

• 我的歌单、收藏歌单、QQ 与酷狗账号歌单
• 歌单详情播放、收藏 / 取消收藏
• Coverflow 封面墙浏览、把歌加入歌单
• 网易云音乐盘歌曲识别与标识

导入歌单：粘贴链接，平台自己认

在播放器侧栏「导入歌单」一栏点「＋」，把链接粘进去就行：B 站 / 酷狗 / QQ / 网易云 / 汽水 / YouTube 的歌单或分享链接按域名识别，只填一串 ID 时按位数猜平台、猜错还有一次邻位重试。

导入项只存引用（键是「平台名:平台歌单 ID」），曲目点开才由各自平台现拉， 所以导入与登录、与账号完全解耦。侧栏由此分成两栏：上面「导入歌单」，下面「我的账号歌单」。

本地歌单：在自己电脑上攒一张单子

侧栏「Mu本地歌单」一栏：新建、重命名、删除都在本机完成，不用登录任何平台。 一张单子里可以混着放各个音源的歌 —— 每一首连「该去哪个平台、用哪个键取流」一起存在本机， 播放混合单不需要先切平台。

播放 · 音质 · Automix

内置解码器支持 MP3 / AAC / M4A / FLAC。

八档音质

标准、高品质、极高、无损、Hi-Res、高清环绕、沉浸音质、母带。 实际拿到什么音质会如实显示在歌曲行和全屏播放页的徽标上，不会虚标。

元数据徽标

歌曲行与全屏播放页可显示：音源、实际音质、歌词类型、VIP、专辑、网盘、全景声、伴奏、解灰来源。全屏页徽标语言支持中英切换。

播放队列

• 加入「下一首播放」、拖动排序、删除单曲、清空队列、显示队列数量
• 临时队列播完会自动回到进入队列前的那个歌单继续放
• 待播角标与插入位置始终准确；从搜索结果起播会把后面的曲目续上待播
• 自动换源不会弄断待播：换源就地改写队列那一格，「紧跟当前这首」的下一首不受影响

系统播放器镜像（1.7.0 新增）

让游戏里的界面去跟随Windows 上正在播的那一首，而不是本模组自己的队列。 位置在 HUD 设置 →「界面与主题」→「外部播放器镜像」→「播放态来源」，选「系统播放器镜像」。 之后全屏歌词页、桌面歌词、灵动岛、信息栏的封面与背景取色读的都是外部那一首， 而模组自己的播放器与排版一行不改仍然可用。

• 能反过来控制外部播放器：暂停、上一首 / 下一首、拖进度都真的作用过去。 对方不接受就如实提示，不做假进度 —— 浏览器播放器的拖进度就是这种「答应但不干活」的情况之一。
• 封面与歌词：外部播放器自己报的那张封面排第一，没有才回落到按曲名歌手在本模组曲库里匹配。 歌词同样按曲名歌手回曲库匹配，匹配上就与平常听歌完全一样（含逐字）。
• 音量：拖滑块调的是 Windows 音量合成器里那一个程序的音量，不会去动系统主音量； 对不上对应程序时一动不动并提示你原因。
• 需要什么：Windows 10 / 11，加一个支持系统媒体控制的播放器（网易云、QQ 音乐、浏览器一般都可以）。 第一次启用会拉起一个很小的助手子进程，源码随模组打包、在本地编译，不需要联网。

Automix 无缝切歌

处理方案：原版淡化 / Folia Automix（1.4.9+）

HUD 的「无缝切换 → 过渡模式 → 处理方案」可以在两套引擎之间切换，两个引擎共用上面的可调项。

• 原版智能淡化：等功率淡化 + 节拍 / 调性分析 + 低架处理。旧配置没有 engine 字段时会自动迁移到这一档，不会静默切换到 Folia。
• Folia Automix：用证据分析挑 beatCut / bassSwap / tailRide / plainBlend 四类过渡，重叠时长按拍、小节或乐句量化，并在空闲 Deck 上提前预滚，避免关闭播放器和解码造成的空档。

可选分析模型

Folia 优先使用下列模型，任一模型不可用都会自动回退到内置确定性分析，分析失败不会阻断播放。

• 下载显示进度条、百分比、已下载大小与速度，支持 Hugging Face 镜像与官方源。
• 可指定自定义模型目录、扫描本机模型、做 SHA-256 校验与删除；分析结果进本地档案缓存，同一文件不会重复推理。
• 首次启动向导新增可选的 Automix 模型安装步骤，支持一键按顺序补齐缺失组件；跳过也能继续用原版智能淡化，之后在 HUD 里随时补装。
• 「分析模型 → 模型推理状态」默认开启：推理时在灵动岛显示当前歌曲与运行中的模型，全部成功后显示耗时；用缓存或未安装模型时不会发送通知。

进阶模式（默认关）

打开后切歌前会先扫一遍整曲，出场点与进场点成对打分选最优接缝；分不够就不硬切， 宁可用普通淡化。扫描在后台低优先级进行，不挡播放；拖进度条也不会作废已经排好的混音。

• Flow 一键智能排列：整条歌单按情绪贴合、BPM 衔接与能量平滑一次排好序。
• 人声让路：交叠期压低的是这首歌实测的人声段，不是固定曲线；有分轨模型时效果更好。

切点标记：把接缝画到进度条上

一条竖线是「从哪里开始切」，一段半透明带子是「这一段两首歌叠在一起」。 只在系统真的排出了交接时才画 —— 没预备好就什么都不画，不猜一个位置给你。 开关在 HUD 设置 →「无缝切换」→「切点标记」，出厂是开的。

手动切歌也走无缝

手动点歌或切下一首走专用的即时混音计划：交叠窗内旧曲低频主动让路、新曲带动态余量进场， 不会出现两首鼓点撞在一起的爆音；点歌时新曲在后台先预备、原曲不停，就绪后才无感交接。 交叠窗口在进度条上有平滑流光与交接环动效。

音效与预设：兼容 ViPER 预设文件格式

播放条右下角多了一个调音入口（位置在音质选择右侧、音量滑条左侧，任何面板宽度下都不与两者重叠）。 点开是一张单页浮层：总开关、预设列表、从文件导入、删除与状态行。

• 兼容 ViPER 预设文件格式：旧 XML 布局、v1、schema 2 与 2.1 四代预设都能直接导入， 按字段逐条换算到你自己的配置目录，不需要手工转换。这是格式互通 —— 你自己的预设文件怎么写的， 这里就怎么读。
• 即改即存即生效：选用、取消、导入、删除都立刻作用到下一个音频缓冲，不用等下一首歌装载， 也不用手动「应用」。
• 随包内置 8 个卷积核与对应预设：首次装载曲目或第一次打开面板时自动补缺铺设到 config/muonium/viper/，只补缺失、绝不覆盖你自己改过的同名文件。 删掉的内置项不会自己复活；想全部恢复，删掉同目录下的 .builtin-bundle 即可。
• 调参界面：面板页脚进「调参」，24 组参数按字段类型分发 —— 开关、可拖滑条、 档位步进，以及从 kernels/ 与 ddc/ 目录里现算的候选清单。 拖动静默改工作副本、松手才落盘一次；「重载底稿」丢弃全部修改从磁盘重读。
• 内核格式：卷积核支持 16/32-bit、PCM/float、单/立体声，44.1 kHz 与 48 kHz 直接可用。

缓存与下载

听过的歌会缓存到本地，二次播放不重新拉流。入口：播放器 → 侧栏 → 缓存。

缓存上限

• 可选：不限制 / 2 / 4 / 8 / 16 / 32 / 64 GB，默认 16 GB。
• 超限后从最久未播放的歌开始清理；正在播的和排在队里马上要放的永远不会被清。
• 「立即清理」按钮会连中断的下载、转码残留一起删干净。

下载进度在哪看

• 字体、原生库、汽水组件这类自动下载：进度画在游戏内的缺库提示上，装好自动生效，不用重启。
• 点播的歌曲下载：灵动岛弹进度（百分比只报最快那一路，不会回跳）。
• 下载失败会原样告诉你包名、下载页和目标目录，照着手动补即可。

常见问题

• 缓存目录在哪：.minecraft/config/muonium/ 下的缓存目录，删掉整个目录也能自动重建。
• 想全部重下：侧栏缓存页「立即清理」后重播即可。
• 磁盘够但提示下载失败：2.1.0 起自动下载走多条镜像同时拉，一般是被安全软件拦了 —— 把 Minecraft 目录加入白名单。

歌词系统

解析优先级：AMLL TTML → QRC（QQ） → KRC（酷狗） → YRC（网易云） → LRC（行级兜底）。

能力

• 结构：行级、逐字、翻译、音译 / 罗马音、对唱分行、和声标识
• 动效：首字强调、逐字上浮（亚像素平滑）、逐字填涂、动态发光（真高斯）、边缘淡出、滚动柔和度
• 可调：译文 / 音译行透明度、当前行与普通行的缩放与透明度、行间距；发光只有「强度 + 扩散」两个滑块，见 HUD 设置 · 歌词发光
• 歌词搜索与手动钉住（1.6.0）：播放列表中键点一首歌，或全屏歌词页的快捷面板，都能打开歌词候选页 —— 四个来源、逐字预览、按「保存」即钉住这份歌词（之后不再走自动匹配），右键取消钉住

全屏歌词 10 种样式

逐行滚动、律动词云 · 心象、浮名、流光、云阶、群唱、倾诉、镜台、时计、苹果。 每种有专属参数 —— 例如「心象」有 6 槽调色板与每色节拍数，「倾诉」有气泡宽度 / 头像来源 / emoji 概率，「时计」有摆弧半径与角度。

桌面歌词 OSD

经典 与 Blossom。Blossom 是毛玻璃卡片，支持可见行数、模糊强度、面板底色、踩点描边与强度； 卡拉 OK 过渡的填涂宽度 / 脉冲 / 平滑 / 对唱展开度均可调。

动态发光是真高斯实现（不是叠加模糊），所以只需要强度和扩散两个滑块就能调到位。

主题 · 字体 · 界面

换主题、换字体、调窗口缩放 —— 播放器看着顺眼就行。

15 套主题预设

曜石红、极光海、丝绒玫瑰、瓷白墨、液态玻璃、极光霜蓝、午夜石墨、暮色琥珀、鼠尾草雾、 珍珠晨曦、缃云晴川、沧溟玉釉、霜纨岫烟、玫瑰月白、青岚云脂。

• 入口：播放器 → 侧栏 → 主题。点一套立刻整套换上，不用重启。
• 想微调：主题页右上角进调色板，背景 / 文字 / 强调色 / 输入框 / 导航栏 / 边框逐项改，实时预览；一键恢复原色随时回退。
• 每套主题各自记住你的调色，互不干扰。

界面字体

• 入口：播放器 → 侧栏 → 字体。内置 17 款 + 2 款随包字体，也可以选系统已装字体，或把 TTF / OTF 文件丢进 config/muonium/fonts/。
• 点一行立刻生效，不用重启；行高锁住不会乱排版；缺的字由内置字体接住，不会出现方块。
• 播放器、桌面歌词、HUD、灵动岛的文字一起换。

窗口与缩放

• 播放器窗口大小 70%~100%（5% 步进），也可以直接拉伸边缘。
• 窄窗口下界面自动收紧（紧凑标题、按钮外溢、浮层贴底），小屏不用硬凑。

液态玻璃质感

面板是整面液态透镜：玻璃后面的游戏画面会被真实折射弯折。播放器主面板、二级弹窗、灵动岛、 引导页全部同款。1.9.0 起默认就是调好的效果，一般不用动；老配置升级自动迁移。

HUD 设置（玩家手册）

游戏画面上的歌词、灵动岛、歌曲信息栏，全部在 HUD 设置里调。 按 H 打开编辑器摆位置，设置项本身在「HUD 设置」里。

怎么打开

• 调设置：按 H 打开 HUD 编辑器 → 左下角「设置」进入 HUD 设置面板；共 7 大类 89 项。
• 摆位置：编辑器里直接拖动定位、滚轮缩放，改完自动保存。
• 设置界面有三套皮（内置经典 / Pro / Folia），内容完全一样，切换会被记住。

7 大类，找东西先看这里

2.1.0 起设置从 12 页收成上面 7 类；设置文件不受影响（存的是字段名不是页码），升级不用重调。

歌词发光：只有两个滑块

发光就两个旋钮，桌面歌词和全屏歌词共用同一套光晕：

• 当前行发光（默认 0.62）—— 读数就是「唱到时」的亮度，拉满最亮、拉到 0 关掉；
• 发光扩散（默认 1.0）—— 光晕铺多远，按字号等比缩放，大字小字都合适；
• 其它行发光（默认 0.14，上限 0.65）—— 非当前行更淡一些，0 就是不亮；
• 全屏歌词页另有全屏逐字发光（默认 0.55），只管全屏那一页。

这些项去哪了

• 呼吸动画、当前行染色过渡：已移除（旧画法的冗余参数，真高斯下互相重复）。
• 逐字放大、全屏逐字发光：只在全屏歌词页的样式面板起作用，不在 HUD 编辑器。

恢复默认

• HUD 设置面板右上角有「恢复默认」：一键把歌词外观全部回到出厂值。
• 注意：恢复默认不影响升级上来的老玩家已经调过的值——只有全新安装和主动点恢复的人会用新默认值。

常见问题速查

音乐频谱

入口：HUD 设置 →「界面与主题」→「音乐频谱」。打开后有两处：

• 游戏底部全宽频谱：64 根柱子跟着音乐实时跳动；
• 播放器控制栏微型频谱：底边一条细律动，不挡任何操作。

颜色可跟随主题或专辑封面取色，透明度、高度、样式可调。 呼出播放器、开聊天框、开背包、按 F1 时底部频谱自动让位，不会挡视线。

一起听 · 玩家向

三种开法，按你们的场景挑：服务器房间（服主装了 mpsync）、 局域网房间与直连房间（都只装客户端，服主什么都不用装）、 网易云官方一起听（走网易云自己的房间）。点歌、投票切歌、无缝交接在三种房间里功能一致。

局域网房间 / 直连房间（不用求服主）

在别人的服务器上玩、服主没装 mpsync，也想和朋友一起听？让你的电脑当房间引擎： 房主开房，成员凭邀请串直连进来。同步质量、投票、无缝交接与服务器房间完全一致。

• 房主开房：一起听面板 → 房间页 → 「直连房间」→ 填端口（默认 24500）→ 开房 → 复制邀请串。同一局域网的朋友可打开「局域网可直连」直接进。
• 成员进房：一起听面板 → 「直连房间」→ 把整串粘进输入框（长这样 cn-zhejiang.xxx.com:51234#abcdef12）→ 加入。
• 跨网络：让房主配一条内网穿透（樱花 frp 等任意 TCP 隧道，本地端口 24500），邀请串里填穿透地址。隧道里每秒只有几 KB 信令，音频不走隧道（各人直接从音乐平台拉流），免费额度够用。
• 要知道的：房主退出游戏服务器房间不会断（引擎在房主电脑里）；房主关房所有人断开；只装客户端也能当房主。

网易云官方一起听

创建房间生成分享链接 / 邀请码；可通过链接、邀请码或「房间号#邀请人ID」加入； 房间页显示成员、曲目与进度；可复制链接与邀请码、退出房间。

服务器房间能干什么

• 房间与成员：创建房间、邀请码加入、发送与处理邀请、公开房间、服务器频道、查看在线玩家直接邀请、成员列表与状态、授予 / 撤销管理员、转让房主、移出成员
• 队列三档与批量灌歌单：支持整张歌单一次排进房间；队列分为「插队」（房主/管理员 priority=2，连续插队先到先得）、「普通点歌」（priority=1）与「整单灌入」（priority=0）三档优先级
• 分层代解析与跨平台救援：串行逐层推进（L0 原链 → L1 会员贡献 → L2 LX 脚本 → L3 跨平台换源替换）；无法解析当场弃权（不干等超时）；非网易云估试听长度，试听自动交回房间改派救援直链当场出声
• 音频预热与预分析：后台根据前瞻窗口预拉音频（RoomAudioPreloader），LRU 缓存单曲特征，换歌时钟静默窗按交叠长度开启，平滑淡入无缝衔接
• 个人暂停：只有你静音，房间照放，别人不受影响；解除时严格跟随服务端权威位置开声（带安全兜底）

界面在 播放器 → 一起听 → 一起听 · 服务器房间，顶部七个页签：房间 / 歌单 / 成员 / 在线 / 发现 / 邀请 / 一起听歌单。

整张歌单排进房间，与队列三档（1.8.0）

两个入口：一起听面板的歌单页多了一颗「播放歌单」，播放器里的歌单面板多了一颗「排进房间」 （只在房间支持时出现，中途建房 / 进房 / 退房它自己长出来或收回去）。一次把整张单排进去， 不会打断正在播的那一首。

• 队列分三档优先级：房主与管理员的插队 > 别人一首首点的歌 > 整张灌进来的歌单待播。 排序全在服务端定，客户端不参与 —— 版本不一致时同一个房间才会给出同一个顺序。
• 点歌不再插队：在房间里点任意一行播放只是排到队尾，只有按「下一首播放」才带插队位。 此前每一次点行播放都会把别人已经排好的歌整体往后挤。
• 灌单时条目只带元数据不带直链，链接由服务端按前瞻窗逐首要 —— 一次排一百首不会拿点歌人的账号 猛抽一遍上游，也不至于等到几十分钟后用到过期链接。
• 房间里开 Automix 时交叠不再被心跳薅断：让路窗按实际剩下的淡入长度开，卡流也不会再被当成 进度落后而硬跳一下。

与现代 MP 客户端互通

服务器房间可以和 Melodify (modernMP) 客户端混着用，同一个房间里两种客户端互通。 成员列表里 Mu 是 MuoniumPlayer，MP 是 Melodify，两边共同遵守分层代解析、跨平台救援与三档队列协议。

房间里没人有会员怎么办

四层代解析与跨平台救援机制：

• L0 点歌人本机：点歌时若本机能出完整流，直接带直链进房
• L1 贡献会员解析：默认开启（老玩家自动迁移生效）。房间缺链时服务端派单给开着贡献的会员成员，客户端在本机解析后上传临时直链。账号凭据永远不离开自己的电脑，只上传带签名的临时流地址
• L2 LX 自定义源贡献：由安装了对应脚本的成员解析（按脚本覆盖渠道数排序），答不上即刻弃权
• L3 跨平台救援：全层未果时，放开点歌人本机跨平台匹配其它源（如 QQ/酷狗/B站/网易云互替），替换帧带直链当场出声

常用命令

/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.3.0 以上：五个 MC 版本 × Fabric / Forge / NeoForge / Paper 共 20 个模块，挑与你服务器完全对应的那一个放进 mods/（Paper 放 plugins/）。
• 不同 MC 版本的服务器也能同房（跨版本互通）；玩家客户端版本可以和服务器不同。
• 玩家侧什么都不用多装——客户端 Mod 本体就有完整房间功能。

开服要检查什么

• 装好后开服日志里确认 mpsync 加载成功、版本号正确。
• 玩家进房走邀请码 / 公开房间 / 服务器频道（/mp channel）。
• 不装 mpsync 也不影响玩家用播放器本体——只是「服务器房间」这个功能整体空转，玩家还可以用直连房间自行开房。

会员曲怎么解决

• 服务端 Token：服主在配置中填入，服务端解析，玩家无感
• 分层代解析与救援：mpsync 1.3.0 具备分层串行派单能力，会员成员、LX 脚本与跨平台换源按序接力，无需服主额外买会员

进度来回跳怎么办

升级至 mpsync 1.3.0 与客户端最新版。新版实现了换歌交叠静默窗与个人暂停权威位对齐，杜绝了心跳抢跑导致的进度抖动。

配置文件参考

统一在 .minecraft/config/muonium/ 下。

更新检查

拉取公开更新清单（三个来源互为备份，全部并发拉取后取版本号最高的那一份），清单缓存 30 分钟，主菜单弹一次提示； 可以「先不更新」跳过版本，但更新检查本身不可关闭，旧配置里的检查开关键会被忽略；「前往下载」统一打开官网下载页。客户端永不自动下载或替换 jar，下载页有域名白名单。

公告中心

公告与更新提示读同一份远端清单、同一次匿名 GET，但各管各的。三个入口： 主菜单按钮、播放器侧栏图标（带未读红点）、HUD 设置里的「公告」一行。 有未读公告时每次启动弹一次，窗口一关即整批记为已读 —— 每条公告只有一次主动触达的机会。 没有「关闭公告」的开关；拉不到清单时一条都不弹，也不报网络错。

已知限制

• 主包只内置 Windows x64 的图形原生库；Linux / macOS / 安卓缺少时会自动下载对应平台的伴生包（见上方安装一节），下载不下来才需要手动补；安卓还需渲染器选 MobileGlues 并关闭 ANGLE
• 网易云官方一起听受官方接口限制，加入方无法自动跟随主机的暂停与切歌，需要手动同步一次
• 自定义音源脚本不支持 #私有字段、没有单独的代理设置，个别返回 GBK 的老接口会乱码；脚本仍可发网络请求
• YouTube 给的是有时效的高码率 AAC 流，不代表无损；直播与无可用音频流的结果会被跳过；能不能播完整还取决于当前出口 IP 拿到的字节窗口（实测「出口 IP × 视频」只放行 1 MiB，重新解析不续），取不满时表现是这首播不了
• OneConfig 集成目前面向 Fabric 1.21.1 / 1.21.11 / 26.2 / 26.3
• 系统播放器镜像只在 Windows 10 / 11 可用，且要求那个播放器支持系统媒体控制。 镜像开着时本模组队列不起播（模组自己不出声）；外部播放器报什么就显示什么， 它不接的控制会原样告诉你，不做假进度。
• ModernUI 一档目前只编进 Fabric 1.20.1 / 1.21.1 / 1.21.11 —— 26.2 与 26.3 还没有对应的构件， 那两版即使装了 ModernUI 也仍用内置界面。
• 设置分类收成 7 页收的是设置页；按 H 打开的 HUD 布局编辑器（经典 / Pro / Folia） 分组是另一套代码，看到的仍是收页之前的结构。
• Minecraft 26.3 是这一版刚加的第五棵工程：能构建、静态检查都在，但真机跑的量最少， 遇到渲染或按键问题请带着日志到群里说一声。
• 音频解码支持 MP3 / AAC / M4A / FLAC，不支持 WebM / Opus 容器

常见问题

按症状找。找不到答案就带版本号 + 日志来 交流群，定位最快。

安装与启动

界面与 HUD

音源与播放

一起听

升级与账号