L- 音乐刮削器
给 Emby 补中文音乐元数据:从网易云音乐和QQ音乐抓专辑/艺术家信息与封面, 并按曲目导出 .lrc 歌词。
仓库 / 更新源:https://gitee.com/lxsol/emby-music-plugin (公开,匿名可读)
产物:
Emby.Plugin.MusicCN.dll(单个 DLL,约 200 KB,无任何第三方依赖)目标:Emby Server 4.10.1.0
编译目标:
netstandard2.0,SDK 契约包MediaBrowser.Server.Core 4.9.1.90作者 / 版权:李先生ol(Copyright © 2026 李先生ol)
一、安装方法
把
dist/Emby.Plugin.MusicCN.dll复制到 Emby 的 plugins 目录。 常见位置(取决于镜像):官方镜像 / 大多数 Docker:
/config/plugins/程序目录方式:
EmbyServer/system/plugins/在 QNAP 上是容器里的那个路径,通常是/share/docker/emby/config/plugins(用 File Station 找名字里带plugins的目录,放进去即可)。 ⚠️ 只放这一个 DLL,不要连带别的文件。
重启 Emby 容器。
仪表盘 → 插件 → 确认「中文音乐元数据」出现在列表里。
资料库 → 选中音乐库 → 编辑 → 元数据 页面:
专辑 / 艺术家 的「元数据下载源」里勾选 中文音乐元数据;
勾选 中文音乐元数据 作为图片来源(否则封面不会换);
建议把「刷新元数据」设为替换所有元数据,否则 Emby 会跳过已有封面的条目。
触发一次刷新(资料库 → 刷新元数据)。首次全库会慢一点:每个专辑/艺术家各一次搜索。
二、样式图



三、高级刮削:单文件夹 / 单歌曲重新替换(v1.1 新增)
全库扫描太慢、或者只有某几张专辑抓错了的时候用这个。
入口:仪表盘左侧菜单 →「音乐刮削高级设置」(服务器分类下)。
两种定位方式:
每行一个「重新刮削」按钮;曲目行还有「刷新本曲」(主要补 `.lrc 歌词)和 「刷新专辑」(补专辑级元数据)两个入口,另有「刷新以上全部曲目」批量按钮。
「强制替换已有元数据」复选框(默认勾选):
勾选 = 丢弃该条目现有元数据与封面后重新抓取(包括用户锁定的字段),即真正的「替换」;
不勾 = 只补空缺字段。
刷新是同步逐条执行的,一次别超过几十个条目;大批量请用资料库自带的刷新。
四、自动更新(v1.2 新增)
Emby 启动约 2 分钟后,插件会去码云拉一次 version.json:
https://gitee.com/lxsol/emby-music-plugin/raw/master/version.json
发现新版本就下载 DLL,SHA256 与清单一致才原地替换(plugins/Emby.Plugin.MusicCN.dll), 之后每 24 小时自查一次。替换完成后需要重启 Emby 才能加载新版本 —— 插件不替用户重启服务器(那是主机级动作)。
配置页(音乐刮削高级设置)里有对应的开关和手动操作:
更新源细节对用户不可见(地址用 XOR+Base64 混淆内嵌,和 L-MUSIC 一个套路), 也没有任何运行时配置文件 —— 全部通过改源码重新发布来管理。
发新版本(维护者流程)
# 1. 改 Emby.Plugin.MusicCN.csproj 的 FileVersion(如 1.3.0.0)
# 2. 编译 + 冒烟测试 + 更新 dist/
DOTNET_CLI_TELEMETRY_OPTOUT=1 "F:/work/2026-10-05-13-04-43/.toolchain/dotnet-sdk/dotnet" \
build Emby.Plugin.MusicCN.csproj -c Release
# 3. 发布(建发行版、传 DLL、刷新 version.json、匿名回读校验、只留最新 2 个发行版)
python publish_update.py "本次改了什么"
⚠️ 已发布的版本号不能复用(否则老客户端看不到更新)。 ⚠️ 仓库必须是公开的,插件匿名才能读到清单(空仓库不允许设公开, 所以建仓后要先推一次代码再 PATCH,publish_update.py --create-repo 已内置这个顺序)。
五、数据源实测结论(2026-10-17,全部亲自验证过)
网易云 /weapi/* 完全没用:要 AES+RSA 双重加密,而老的 /api/* 至今直连可用、字段更全。
六、两个必须知道的限制
1. 插件改不了曲名和艺术家名。 Emby 的 Album / Artist 实体是按文件标签建出来的,外部 Provider 只能补 封面、简介、年份、流派、厂牌、外部 ID。想连标签一起改,需要另做一个写标签的工具 (那是另一件事,不在这个 DLL 里)。
2. 歌词是唯一会写磁盘的东西。 写在音频文件旁边,同名的 .lrc。策略默认「仅缺失时写」,且写入失败(只读挂载、 权限不足)会被静默吞掉 —— 最多是歌词没刷出来,不影响元数据。
七、匹配策略
专辑/艺术家名来自文件标签,跟上游的名字经常对不上(简繁、版本后缀、全半角)。 所以不是简单相等判断,而是:
归一化(去掉标点空格 + 转小写)后算相似度;
专辑名权重 75%,艺术家名 25%;
相似度 < 0.72 直接当作没匹配上。
刻意偏保守:宁可漏匹配(保留 Emby 原有信息),也不要把错的封面套上去 —— 后者会被直接当成 bug。
另外一处实测带来的设计:网易云按专辑名单独搜的召回质量很差 (搜「七里香」前 12 条全是翻唱和 beat),所以带艺术家时会拼成 「周杰伦 七里香」一起搜,命中率立刻正常。
八、本机编译 / 测试
工具链在项目外的 F:/work/2026-10-05-13-04-43/.toolchain/dotnet-sdk (本机只装了运行时,SDK 是单独解压的,没有污染 C:\Program Files)。
# 编译插件
DOTNET_CLI_TELEMETRY_OPTOUT=1 \
"F:/work/2026-10-05-13-04-43/.toolchain/dotnet-sdk/dotnet.exe" \
build -c Release -o bin/out
# 冒烟测试:不装 Emby,直接把抓取链路跑一遍(JSON 解析 / 打分 / 两家接口 / 歌词)
DOTNET_CLI_TELEMETRY_OPTOUT=1 \
"F:/work/2026-10-05-13-04-43/.toolchain/dotnet-sdk/dotnet.exe" \
run --project tools/smoketest -c Release
冒烟测试全绿时输出示例:
== 专辑:网易云优先 ==
来源 : qq / id=003DFRzD192KKD
专辑名 : 七里香 艺术家 : 周杰伦 年份 : 2004
封面 : https://y.gtimg.cn/.../T002R500x500M000003DFRzD192KKD.jpg
== 单曲 + 歌词 ==
曲名 : 七里香 - 周杰伦
歌词 : 43 行,首行 -> [ti:七里香]
全部通过。
评论区