这是什么
Melodify 是另一份 Minecraft 音乐播放器 Mod，与本站的 MuoniumPlayer 同源同协议。
modernMP 是它在 Git仓库 上的名字（仓库沿用旧名）；用户面前的 mod 名是 Melodify，
mod_id 也是 melodify。两边指同一个项目。
和 MuoniumPlayer 的差别一句话讲完：
- MuoniumPlayer——做国内曲库 + 全功能 + 多版本。客户端主力。
- Melodify——在 MuoniumPlayer 基础上加了海外曲库 + 词云 + 环境感知切歌 + 节拍同步。视觉党与"听感党"。
三者（MuoniumPlayer / Melodify / MusicParty (mpsync)）由 心事抱抱、云杉、N0ne 共同开发，
房间协议互通——你可以和朋友一个用 MuoniumPlayer、一个用 Melodify 进同一个房间。
选哪个？
要全功能 + 多版本（1.20.1 → 26.3）→ MuoniumPlayer；
要海外曲库 + Cadenza 词云 + 自动切歌 + 节拍同步 → Melodify。
房间互通协议一致，所以两个都装也无所谓。
能力一览
Melodify 在 MuoniumPlayer 的全套能力之上，多了四样东西。
YouTube Music 源 独有
内置 YouTubeMusicService。签名时间戳在本机生成、不上传第三方；
只取 audio/mp4 自适应流，主动跳过 Opus；和站内平台一样本地缓存，不连远端解析服务。
- 无 API key、无 OAuth；登录走浏览器扫码/输入 cookie
- 下载到本地时落盘
.mp4，播放器内统一转码
- 搜索、播放列表、收藏夹可用；推荐/电台不可用（API 不暴露）
Cadenza 全屏歌词 独有
词云样式（hero 词居中、唱到的字描光晕、唱完的词向外漂移），独立于 MuoniumPlayer 的 10 种全屏样式。
风格见 CadenzaLyricsView。
- 每行的"hero 词"由服务端按重要度选，不一定是首词
- 当前字的光晕颜色取自主题色的二级亮度
- 不支持逐字时退化成普通整行高亮
Ambient · Mood 自动切歌 独有
按游戏状态打 13 个标签（mood），由决策树强制优先级选下一首。
标签体系见 Mood.java，决策树见 MoodDecider.java。
- 标签示例：
combat · nether · underwater · night · building · mining · peace · victory
- 决策规则：战斗 > 下界 > 水底 > 夜晚 > 建造 > 探险 > 自由
- 可以一键关掉，回到手动/随机/列表模式
Beat · AutoCue · Flow 独有
BeatAnalyzer 离线估计 BPM + 相位；新增 AutoCue 接缝候选打分（成对精选并进行八项加权打分，分不够不硬切）与 Flow 智能排列（按情绪、BPM 与能量平滑度一键重排歌单顺序）。
- 本地确定性计算，不联网、不上传播放历史
- 歌单页一键「智能排列」，队列平滑顺畅
- 无缝交接时若关闭则干净撤除 Deck，避免异步发声
房间互通与独立歌单栏 与 MuoniumPlayer 共享
用同一套 varint+JSON 协议，两个客户端可进同一房间。「一起听歌单」单独成栏，支持整张灌歌单、队列插队/点歌/歌单三档排序、房间音频预热与单曲预分析、分层代解析与跨平台救援。
见 文档 · 一起听。
构建 / 依赖 与 MuoniumPlayer 共享
Maven 包 yun.shan:musicplayer；1.20.1（Fabric / Forge）与 1.21.11（Fabric / NeoForge）两套分支，
共产出 4 个 jar。26.2 与 26.3 请使用 MuoniumPlayer。
vs MuoniumPlayer
功能差异表。房间协议相同，安装时可并存。
| 能力 | MuoniumPlayer | Melodify |
|---|
| 国内平台（网易云/QQ/酷狗/汽水/B站） | 内置多个国内平台 | — |
| YouTube Music | 内置 | 内置 |
| 10 种全屏歌词样式 | ✓ | ✓ |
| Cadenza 词云 | — | ✓ |
| 环境感知切歌 (Mood) | — | ✓ |
| 节拍同步 (Beat) + AutoCue / Flow | 进阶模式 | 内置 |
| 一起听房间（独立歌单/三档队列/代解析） | ✓ | ✓ |
| HUD / 灵动岛 / 桌面歌词 | ✓ (液态透镜) | ✓ |
| 15 套主题 | ✓ | ✓（同款预设） |
| 支持版本 | 1.20.1 / 1.21.1 / 1.21.11 / 26.2 / 26.3 | 1.20.1 / 1.21.11 |
| 加载器 | Fabric / Forge / NeoForge | 1.20.1: Fabric / Forge
1.21.11: Fabric / NeoForge |
| 作者 | 心事抱抱、云杉、N0ne、eyz2021 | 心事抱抱、云杉、N0ne |
| 协议 | Apache-2.0 | Apache-2.0 |
一句话：Melodify = MuoniumPlayer + 海外曲库 + 词云 + 环境感知 + 节拍感知与智能排列。少了国内平台和 26.x 支持。
安装与前置
四步装好。Melodify 不发布 26.2 与 NeoForge。
- 装好对应版本的 Fabric 或 Forge（1.20.1 两种都行；1.21.11 两种都行）。
- 装前置 —— Fabric 侧是 Fabric API + Fabric Language Kotlin，Forge 侧是 Kotlin for Forge。
- 从 MC 百科 Melodify 页面 下载 jar，放进
.minecraft/mods/。
- 启动游戏 → 首次启动进设置向导（选默认音源、登录账号、调界面外观）→ 进游戏按 右 Shift 打开播放器。
前置清单（详细）
| MC 版本 | 加载器 | 前置 |
|---|
| 1.20.1 | Fabric | Fabric Loader 0.18.2+ · Fabric API 0.92.11+1.20.1 · Fabric Language Kotlin 1.13.12+kotlin.2.4.0 |
| 1.20.1 | Forge | Forge 1.20.1-47.0.0+ · Kotlin for Forge 4.3.0+ |
| 1.21.11 | Fabric | Fabric Loader 0.17.3+ · Fabric API 0.141.6+1.21.11 · Fabric Language Kotlin |
| 1.21.11 | NeoForge | NeoForge 21.11.x · Kotlin for Forge 6.0.0+ |
如果和 MuoniumPlayer 同版本共存，需要确保两份 mod 的 Kotlin 前置版本一致（都吃 Fabric Language Kotlin 同一份就行）。
音源与账号
Melodify 自带 YouTube Music。其他平台需要装 MuoniumPlayer。
- YouTube Music（内置）——设置向导里点"添加账号"，会打开浏览器走 OAuth/扫码/cookie 任一方式。账号仅存本机。
- 本地文件——
.minecraft/config/melodify/local/ 目录里丢 mp3/flac/mp4，播放器自动扫描。
- URL 直链——粘贴可访问的 mp3/mp4 链接，可作为临时播放源（不在缓存里留）。
- 自定义脚本——参考 文档 · 自定义音源脚本，写
.js 注册成新源。Melodify 与 MuoniumPlayer 共用脚本接口。
凭据仅本机。Melodify 把 YouTube Music 的登录态写到 config/melodify/credentials/，加密存储；
你可以从设置向导里"导出"或"擦除"，不会上传到任何服务器——这是和官方客户端一样的做法。
首次启动
- 启动游戏 → 看见 设置向导。
- 选音源（默认 YouTube Music，可留到以后再加）。
- 登录（浏览器跳走，回来后向导继续）。
- 选主题（15 套之一，预选 Muonium Default）。
- 选歌词样式（默认 / Cadenza / 其他 9 套中任意）。
- 选 HUD 模式（默认 / 灵动岛 / 全屏 / 关）。
- Ambient Mood 默认开，会弹一条提示告诉你怎么关。
所有选项都可在游戏内 设置 → Melodify 里随时改。
Cadenza 全屏歌词
Melodify 独有的全屏样式，代号 Cadenza。视觉特征：
- hero 词：每行有一个最重要的词（不一定首词），居中放大。决定方式见服务端
CadenzaToken。
- 唱到的字描光晕：当前字的边缘加一道同色高光，颜色取自主题色二级亮度。
- 唱完漂移：唱完的字向上、向左或向右小距离飘出，给下一行腾地方。
- 不支持逐字时：整行高亮，不做漂移。
切换：游戏内按 F7 循环切全屏样式；或在 设置 → 外观 → 全屏歌词样式 里挑。
Cadenza 在低帧率场景会自动降级——关掉漂移、保留高亮；不卡顿优先。
Ambient · Mood 自动切歌
13 个 mood 标签 + 决策树。强制优先级，组合不冲突。
标签清单
| 标签 | 触发条件 |
|---|
combat | 正在攻击/被攻击/视野里有敌对生物 |
nether | 在下界（含下界要塞/堡垒/熔岩地带） |
underwater | 完全浸没水中 ≥3 秒 |
night | 主世界时间 ≥12000 + 没有敌对生物 |
victory | 击杀凋灵/末影龙 |
building | 连续放置 ≥10 个方块 |
mining | 连续挖掘 ≥10 个方块 |
explore | 奔跑 ≥20 秒且不在以上场景 |
peace | 闲置 ≥30 秒 |
creative | 创造模式下默认 |
death | 刚死亡 30 秒内 |
rain | 下雨/下雪 |
spawn | 刚重生 / 切换世界 30 秒内 |
决策树
优先级：victory > death > combat > nether > underwater > night > rain > mining > building > explore > peace > spawn > creative。
同一时间多个标签命中时，取优先级最高的。
关掉：设置 → Ambient → 自动切歌 → 关。关掉后回到列表/随机/单曲循环。
Beat + EmbeatMLP
离线算 BPM + 相位，跨歌过渡落在 kick 上。
BeatAnalyzer
首次播放时本地算 BPM 与每个小节的相位，缓存 7 天；纯人声/纯钢琴曲目会被识别成"无 kick"，跳到 fallback 渐弱过渡。
EmbeatMLP
"心灵感应"——预测下一首歌的开头是否能接到当前曲尾；纯 Java 前向传播，不联网、不依赖 ONNX 运行时，jar 体积不增加。
怎么开关
- 游戏内：
设置 → 播放 → 节拍同步，默认开。
- 房间内：服从房主设置，成员无法独立关闭（避免错位）。
房间协议
Melodify 和 MuoniumPlayer 共用一套协议——同一个房间可混用。
- 帧格式：
varint length + JSON payload。详细说明见 文档 · 一起听。
- 消息类型：加入/退出/播放/暂停/seek/队列/聊天/投票跳过
- 客户端识别：MuoniumPlayer 发
"mu"、Melodify 发 "mp"、老客户端发空。
- 服务端：MusicParty (mpsync)，由 心事抱抱、云杉、N0ne 共同开发。
更新日志
Melodify 这一线的版本小史，完整发布说明见 MC 百科页面。
-
2.2
正在出包
新增
- 一起听房间里也能无缝交接：房间里换歌不再硬切，由一台真分析、全房执行同一份计划
- 一起听整张灌歌单：房间页那颗「播放歌单」把一整张账号歌单排进队列，不打断正在播的那一首；队列分插队 / 点歌 / 歌单三档，服务端不认这个功能时那颗按钮根本不出现
- 房间队列预热：从当前这首往后最多 10 首提前下好，换歌那一刻不再全房一起等下载
- 歌单页「智能排列」：一键把整条播放顺序按接缝重排，正在播的那首钉住不动（默认关，少于 3 首不亮）
- 「衔接接缝打分」：退场点与进场点配成候选逐对打分，量不出可靠接缝时照原来的方式选点（默认关）
优化
- 同一首歌不再反复重算：交接要用的三份产物各留一层缓存，队列越长越明显
修复
- 关掉「智能衔接」之后不再出现本机在叠、别人在切
- 房间换错歌：后台算完的交接计划上报前先复核它仍然是当下那一首，不再把为别的曲子算的计划报上去
- 房间页拉回歌单列表后第一行被切掉半截
这一版要配 mpsync 1.3.0 服务端；包传上来之前，能下到的还是 2.1。
-
2.1
当前版本
新增
- 一起听界面重写为五页，接上 v2 协议：在线与身份 / VIP、邀请、公开房间、个人暂停、贡献会员
- YouTube Music 音源：1.20.1 与 1.21.11 两版都有
优化
- 构建产物文件名带上 Minecraft 版本，四个 jar 不再同名互相覆盖
修复
- 打开一起听时游戏启动即崩（心跳线程碰了游戏界面）
- 窄面板下迷你播放条的一起听入口消失 —— 改成常驻
前往 MC 百科查看更新
构建产物
每版发 4 个 jar。两个版本 × 两个加载器。
| 文件名 | MC 版本 | 加载器 |
|---|
musicplayer-1.20.1-fabric-2.2.jar | 1.20.1 | Fabric |
musicplayer-1.20.1-forge-2.2.jar | 1.20.1 | Forge |
musicplayer-1.21.11-fabric-2.2.jar | 1.21.11 | Fabric |
musicplayer-1.21.11-neoforge-2.2.jar | 1.21.11 | NeoForge |
Maven 包坐标：yun.shan:musicplayer:2.2。本地源码路径：src/main/java/yun/shan/musicplayer/。
配置文件
配置文件路径 .minecraft/config/melodify/。
目录结构
config/melodify/
├── melodify.json # 主配置
├── credentials/ # 账号凭据（AES 加密）
├── cache/ # 解码后的音频缓存
├── lyrics/ # 下载的歌词文件
├── scripts/ # 自定义音源脚本
└── themes/ # 自定义主题 JSON
关键字段（melodify.json）
| 字段 | 默认值 | 说明 |
|---|
version | 2 | 配置格式版本 |
theme | muonium-default | 主题 id |
hudMode | island | off / text / hud / island |
lyricsStyle | cadenza | 全屏歌词样式（Melodify 默认 Cadenza） |
ambient.enabled | true | Ambient Mood 自动切歌 |
ambient.mood | auto | 手动指定某时 |
beat.enabled | true | 节拍同步 |
room.id | "" | 进入的房间 id（来自房主口令） |
room.url | "" | 房间服务器地址（mpsync） |
和 MuoniumPlayer 的字段大部分通用，主题 id / 歌词样式 id 完全相同。
常见问题
能和 MuoniumPlayer 同时装吗？
可以。两者共用同一份 Kotlin 前置，且房间协议相同。功能有重叠（同一曲两个 mod 都尝试播放），
实务上建议二选一，或者把一个的音源清空只留另一个。
为什么没有 26.2 / NeoForge？
Melodify 只维护 1.20.1 + 1.21.11 两套；NeoForge 不在维护范围。需要 26.2 / 26.3 或 NeoForge 就用 MuoniumPlayer。
Cadenza 词云在哪里切换？
设置 → 外观 → 全屏歌词样式，或按 F7 循环切。
Ambient 怎么关掉？
设置 → Ambient → 自动切歌 → 关。关掉后回到列表/随机/单曲循环。
房间和 MuoniumPlayer 互通吗？
互通。同一个 mpsync 服务器，MuoniumPlayer 客户端和 Melodify 客户端都能进。
客户端识别 tag 是 mu / mp，参见 文档 · 一起听。
没找到我想要的功能怎么办？
先看 MuoniumPlayer 大概率有。两个 mod 由同一批人开发，功能会在两边同步出现。
没同步的话，看一下 关于 · 免责声明，Melodify 的功能取舍以"环境感知 + 视觉党"为主。
开始使用
下载与发布说明统一在 MC 百科提供——这是最稳定的链接，每次发版时链接地址不变。
