Metadata Governance

元数据、歌词、封面、指纹

自动补齐是播放器的核心能力之一，但它必须有治理边界。LoFiBox 把 identity、lookup、candidate、acceptance、cache、writeback 拆开，避免“查到一个结果就写回文件”的危险行为。

推荐工作流

  1. 先读取当前 embedded/local/remote metadata。
  2. 生成 fingerprint 或使用文件名、路径、远程 server id 建立候选。
  3. lookup 获取 MusicBrainz、远程服务、歌词 provider、artwork provider 的候选。
  4. diff 显示当前值和候选值差异。
  5. apply 只写入 LoFiBox cache / library projection。
  6. writeback 需要用户明确确认，才写回 ID3/FLAC/Vorbis 等标签。

Metadata

metadata 命令关注 title、artist、album、album_artist、track number、disc、year、genre、composer、MusicBrainz id 等字段。 远程库缺少 ID3 时，应优先从远程 server item、文件名和 fingerprint 候选中补 projection。 

lofibox metadata show "/music/track.mp3"
lofibox metadata lookup "/music/track.mp3"
lofibox metadata diff "/music/track.mp3"
lofibox metadata apply "/music/track.mp3"
lofibox metadata writeback "/music/track.mp3"
lofibox metadata cache show 42
lofibox metadata cache purge 42

Lyrics

lyrics 命令区分 embedded lyrics、旁路 .lrc、online provider 和用户编辑文本。同步歌词应保存 timestamp； 无 timestamp 的歌词也应能展示为 plain lyrics。 

lofibox lyrics show 42
lofibox lyrics lookup 42
lofibox lyrics apply 42
lofibox lyrics edit 42
lofibox lyrics writeback 42
lofibox now --fields lyrics.available,lyrics.current_index,lyrics.status_message --json
LoFiBox GUI Lyrics
歌词投影：GUI/TUI 都应从 runtime lyrics snapshot 展示当前行。

Artwork

artwork 命令用于查看、查找、应用和导出封面。导出不改变媒体文件；writeback 类动作必须进入 metadata governance。 

lofibox artwork show 42
lofibox artwork lookup 42
lofibox artwork apply 42
lofibox artwork export 42 --output cover.jpg

Fingerprint

fingerprint 用于同录音判定、去重、跨本地/远程库匹配和元数据候选排序。它不是歌词匹配的唯一条件， 但可以显著降低文件名混乱时的误匹配。 

lofibox fingerprint show 42
lofibox fingerprint generate "/music/track.mp3"
lofibox fingerprint match "/music/track.mp3"
lofibox fingerprint index status
lofibox fingerprint index rebuild

显示失败时怎么排查

现象优先检查命令
ID3 未补齐 library projection 是否有 candidate、lookup 是否失败、fingerprint 是否生成、cache 是否写入。 lofibox metadata lookup <path> --json
远程库 artist/title UNKNOWN remote resolve 是否带 server metadata，source capability 是否支持 catalog metadata。 lofibox remote stream-info <profile> <item> --json
歌词找到了但不显示 lyrics snapshot 是否 available，current track id 是否匹配，offset/current_index 是否更新。 lofibox now --fields lyrics,playback.current_track_id --json
歌词完全没有候选 title/artist 是否为空、provider 是否启用、网络策略是否禁用在线查找。 lofibox lyrics lookup <id-or-path> --json
写回原则： apply 可以更新 LoFiBox 的 cache/projection；writeback 才会尝试修改媒体文件标签。 远程库通常不可写，应该把补齐结果保存到本地 metadata cache。