标签刮削

标签刮削用 MusicBrainz 补齐曲库缺失的元数据，并在写入前把每个字段的判断摆出来。

匹配顺序

1. MBID。 文件已有 MUSICBRAINZ_TRACKID 时直接查录音，最可靠。
2. 目录共识。 同一专辑目录里的曲目共享发行信息时，用多数结果补发行级字段。
3. 标题搜索。 用标题、艺人、专辑和时长组合搜索，按分数和时长闸门筛选。
4. AcoustID 指纹。 缺 MBID 或搜索有歧义时，用音频指纹确认录音。

候选必须通过硬性闸门：

• 时长差不超过 policy.matching.max_duration_delta_seconds，默认 5 秒。
• 标题、艺人、版本信息不能明显冲突。
• 最优候选与次优的分差达到 min_score_margin，除非时长差很小。

不满足时进入「待审查」，不会猜。

字段判断

每个字段只有四种结果：

结果	含义	默认行为
same	本地与来源相同	不写
fill	本地为空，来源有值	可自动写入
correct	发行级字段，按同目录专辑统一	可批量写入
conflict	两边都有值且不同	默认勾选，人工确认

「纠正」只用于发行级字段，例如专辑、日期、厂牌、目录号、发行类型、介质、总轨数。标题、艺人、作词作曲等字段不会因为目录共识被批量覆盖。

冲突处理

冲突字段默认勾选，表示「采用来源值」。可以：

• 逐字段取消勾选；
• 一键全选；
• 一键取消全选；
• 只写「可补」和「纠正」，跳过冲突。

写入前的确认框会列出字段、来源值和影响。标题、艺人、专辑等关键字段发生变化时会额外提示。

以下情况仍会进入人工复核：

• 版本不同，例如现场版、重制版、伴奏版。
• 本地多出合作艺人，或艺人名单明显不同。
• 时长差超过标签写入容差。
• 来源本身有歧义。

自动扫描与自动写入

监控进程按 scan_interval_hours 扫描全库。设置页可以修改间隔、自动写入、指纹和单轮上限，保存后一分钟内生效。

自动写入只做两件事：

• 补本地为空的字段；
• 按可信目录簇纠正发行级字段。

冲突永不自动覆盖。单轮写入数量受 max_auto_write_per_run 限制。

写入安全

• 只改目标字段。音频数据、封面、歌词、作词人、未知标签保持不变。
• FLAC 使用 Vorbis comment 块级改写；MP3 使用 ID3v2 目标帧改写；OGG 重排 comment 页。
• 写入前备份；写入后校验音频哈希和非目标标签。
• 校验失败自动回滚，并保留失败原因。
• 撤销按字段恢复原值，不会把整份标签覆盖回旧版本。

按链接指定

「按链接指定」支持 MusicBrainz 的发行、录音、发行组和艺人链接。查询只读，不会改文件。

适合以下情况：

• 自动搜索没有命中；
• 同名曲目太多；
• 想指定某个发行版或某个现场版本。

链接会校验域名必须是 musicbrainz.org 或其子域，避免 SSRF。

写入历史与撤销

每次写入记录文件名、写入时间、变更字段、原值和新值。可以在标签页的「写入记录」里逐条撤销。

撤销只还原这次写入涉及的字段。如果之后有人手动改过同一字段，撤销会跳过或提示冲突，不会盲目覆盖。

常见问题

扫描显示 MusicBrainz 未配置。

检查 providers.musicbrainz.enabled 和 base_url。默认是 https://musicbrainz.org；容器内能访问公网即可。

扫描全部未匹配。

先确认 MusicBrainz 是否可达。Lyra 在扫描前会做健康检查；不可用时会拒绝扫描，避免把上一轮结果覆盖成未匹配。

自动写入没有发生。

检查写入开关、auto_write、单轮上限和时长容差。冲突字段永远不会自动写入。

MP3 的 MusicBrainz ID 读不出来。

确认文件里是 UFID 帧或对应的 TXXX 帧。Lyra 会读取 UFID 的原始字节并解码为 UUID。