最近把音乐刮削流程跑通了 Solara → music-tagger → ZonyLrcToolsX → 元数据写入四个阶段，FLAC 与 MP3 前三个阶段共用，仅第四阶段分叉。过程中踩了不少坑，记录下来给同样想给自己音乐库打标签的朋友。
流水线概览
工作流 Skill 位于 /home/cao/Music/music-pipeline/SKILL.md，另有脚本 music-pipeline/embed_lyrics.py。四阶段，FLAC 与 320k MP3 前 3 阶段共用，仅第 4 阶段分叉：
- 下载：Solara/GD 音乐台，FLAC 用
br=999/.flac，MP3 用br=320/.mp3，校验bit_rate≈320000。直链带时间戳需立即下载。 - 刮削标签/封面：music-tagger MCP（AcoustID 指纹 + MusicBrainz）。FLAC 与 MP3 完全通用。
- 下 LRC：在
ZonyLrcToolsX/目录内跑./ZonyLrcTools.Cli download -d "<dir>" -l -n 4。实测 local 扫描器把.lrc写在源文件旁、与源文件同名，-o/-p对 local 不生效。 - 写入歌词：FLAC →
metaflac --remove-tag=LYRICS --set-tag-from-file="LYRICS=$lrc"；MP3 →python3 embed_lyrics.py <mp3> <lrc>（mutagen 写真 USLT，默认 ID3v2.3 并把 TDRC 转 TYER+TDAT）。
关键坑与修复
music-tagger 依赖 ffmpeg-static 失败
postinstall 常失败报 spawn ffmpeg-static/ffmpeg ENOENT。
修复：ln -sf /usr/bin/ffmpeg ~/.npm/_npx/*/node_modules/ffmpeg-static/ffmpeg，或设 FFMPEG_BIN=/usr/bin/ffmpeg。不需要 fpcalc（rusty-chromaprint-wasm）。
music-tagger 读 FLAC 报 Unsupported format
music-tagger_read_tags 读 FLAC 报 Unsupported format；改用 metaflac --export-tags-to=- 解决。
music-tagger 写入网易云源 FLAC 必败
这是最大坑：写入网易云源的 FLAC 会报 Unsupported format: mimetype ... (taglib/flac) is not supported（taglib 对该文件的 PICTURE 块 mimetype 不满，dry_run 能读、写必败）。
FLAC 全流程退化为：metaflac 手工写全部标签 + --import-picture-from 内嵌封面；MB recording/release ID 可用 MusicBrainz API 核对后照写。
根因：node-taglib-sharp（1.x）未注册 taglib/flac 类型（只注册 aac/aiff/ape/asf/riff/mpeg），File.createInternal 查表失败即抛错，与文件本身无关——任何 FLAC 写入都会失败。实测可用 mutagen（FLAC + Picture 内嵌图片）替代，比 metaflac 更适合批量与多值 genre。
AcoustID 指纹可能命中错误发行版
实测《Breathe》命中现场盗版；草东《丑奴儿》命中英文版 The Servile eeea85fd。必须核对 dry_run 的 album/releaseId。同一专辑在 MB 常有中文名发行版（丑奴儿→醜奴兒 TW Digital 042b6349 2016-04-30 / TW CD 53b74bc7 2016-03-15），recording ID 两版共享，可链接中文 release 并手工写中文标签。
MusicBrainz 限流
MusicBrainz 会返回 503 限流，等 30-60s 重试即可；连续查 MB 时每次间隔 2-3s。
coverArtFetched 常因 CAA 404
coverArtFetched
常因 Cover Art Archive 404，不是失败。CAA 取封面用/front-500、/front-1200 可靠，/front-2500 源图小时会静默降级到 250px；直链 archive.org 文件名会报 400。
metaflac 1.5.0 混用操作报错
metaflac 1.5.0 一次调用不能混用 major（--remove/--remove-all-tags?）与 shorthand（--set-tag）操作，报 you may not mix shorthand and major operations，须分开调用；--remove --block-type=PICTURE --block-type=VORBIS_COMMENT 可清空旧标签+旧封面。
MP3 写歌词的正确方式
MP3 写歌词不能用 ffmpeg（只写非标准 TXXX
），也不能用 mid3v2 —USLT（按: 切分，LRC 时间轴冒号会被切碎）；必须用 mutagen 直接写 USLT。
顺序不可换
先刮标签再下歌词，否则匹配错歌。
已跑通案例
萬能青年旅店 - 河北墨麒麟 MP3：标签 + 封面 + 34 行 USLT。注意 MusicBrainz 把 artist 规范化：萬能青年旅店→简体「万能青年旅店」。
草东没有派对 - 丑奴儿 FLAC：12 首（/home/cao/Music/草东没有派对 - 丑奴儿/，2026-09-11），简体标签、DATE=2016-04-30、MB 指向 042b6349、内嵌 CAA 1200×1200 封面；歌词全流程已跑通：ZonyLrcToolsX 11 首下到 LRC、Intro 纯音乐跳过、LYRICS 已用 metaflac 写入并校验。草东在 MB 是繁体「草東沒有派對」/No Party For Cao Dong。
指定发行版刮削 + 网易云英汉双语歌词
2026-09-11，King Crimson《In the Court of the Crimson King》MP3 5 首（/home/cao/Music/The Court of the Crimson King/）。
用户指定 MB release 时，别用 AcoustID（会命中其它发行版/503）；直接 MusicBrainz API 取 release（?inc=recordings+artist-credits+release-groups+labels）核对曲目，再手工写全部标签。本例最终采用 2014 Expanded & Remastered Original Album Mix：release=035aae28-0ce9-4198-820f-c0ceac24eae3，DATE=2014-09-30，label=Discipline Global Mobile，共 8 轨（本地只有前 5 轨，故 TRCK=n/8），RG=a50636b5-5233-3329-a7f3-dba3d0e00ef7。内嵌 CAA front-500（本 release 有 500×500）。ID3 用 TXXX 写 MusicBrainz Album/Release Group/Release Track/Recording Id。
网易云歌词直连 API（无需 key，需 UA + Referer: https://music.163.com/）：
- 搜索：
https://music.163.com/api/search/get/web?s=<歌+歌手>&type=1&limit=20，按 album 名（如 “expanded & remastered original album mix”）+ 时长最接近筛选。 - 歌词：
https://music.163.com/api/song/lyric?id=<id>&lv=1&kv=1&tv=-1，lrc.lyric=原文，tlyric.lyric=中文翻译（即英汉双语）。用两方 ms 时间戳对齐合并；跳过[by:...]及「作词/作曲/编曲」credit 行。
本例 5 首网易云 id：2112750583/2112750584/2112753206/2112750585/2112750586，翻译覆盖 100%。
MP3 双写歌词元数据：USLT（英中逐行交替的纯文本）+ SYLT 同步（每时间戳一行「英文 / 中文」，text=[(str, int_ms), ...]）。SYLT 元素是 (字符串, 整数ms)，写成 tuple-of-tuple 会报 struct.error: required argument is not an integer。同时落同名 .lrc（同时间戳先英后中，标准双语格式）。tags.save(v2_version=3) 会自动把 TDRC 转 TYER/TDAT。
读回校验：music-tagger_read_tags 对 MP3 正常；或 python mutagen ID3(path) 看 USLT/SYLT/APIC/TXXX 数量。注意文件原有 REPLAYGAIN_TRACK_GAIN 等 TXXX 会被保留。
Undertale 两首 FLAC 刮削
2026-09-11，/home/cao/Music/Undertale/。再次撞上 taglib/flac 写入限制，dry_run 成功（AcoustID 命中正确）但写盘报 Unsupported format。改用 mutagen 写 Vorbis 注释 + 内嵌 CAA front-500（500×500）封面，并用 MusicBrainz release API（inc=recordings）取 disc1 曲序号。
两首：MEGALOVANIA（TRACK=100，genre meme/symphonic metal，rec cdd3681b-cb54-4eeb-98b5-29c8baa1edd8）与 Your Best Nightmare（TRACK=79，genre breakcore/chiptune，rec 0d337fdb-3588-414a-873e-b8c1afce7f59）；album=UNDERTALE: Soundtrack，date=2015，albumid=8a6f776f-31f1-42f0-b25e-402f193d0d58。
核心教训：FLAC 写入别指望 music-tagger 一步到位，mutagen 才是跨格式批量写入的可靠选择；AcoustID 命中后要人工核对发行版，否则可能拿到盗版或英文版标签。