Metadata Governance

Metadata, Lyrics, Artwork, Fingerprints

Automatic completion is a core player capability, but it needs governance boundaries. LoFiBox separates identity, lookup, candidate selection, acceptance, cache, and writeback so "found a result" never silently becomes "modified the music file."

Recommended Workflow

Read current embedded, local, and remote metadata first.
Generate a fingerprint or use filename, path, and remote server id to build candidates.
Run lookup against MusicBrainz, remote services, lyrics providers, and artwork providers.
Show a diff between current values and candidate values.
Apply only to the LoFiBox cache / library projection.
Write back to ID3/FLAC/Vorbis tags only after explicit user confirmation.

Metadata

Metadata commands cover title, artist, album, album_artist, track number, disc, year, genre, composer, MusicBrainz ids, and related fields. When a remote library lacks embedded tags, LoFiBox should prefer remote server items, filenames, and fingerprint candidates for the 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 commands distinguish embedded lyrics, sidecar .lrc files, online providers, and user-edited text. Synchronized lyrics should preserve timestamps; lyrics without timestamps should still render as 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 — Lyrics projection: GUI and TUI should both render the current line from the runtime lyrics snapshot.

Artwork

Artwork commands view, find, apply, and export cover art. Export does not modify media files; writeback-like actions must stay under metadata governance.

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

Fingerprint

Fingerprints support same-recording judgment, deduplication, local/remote matching, and metadata candidate ranking. They are not the only condition for lyrics matching, but they reduce mismatches when filenames are messy.

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

Troubleshooting Display Failures

Symptom	Check first	Command
ID3 was not completed	Whether the library projection has candidates, lookup failed, fingerprint was generated, and cache was written.	`lofibox metadata lookup <path> --json`
Remote artist/title is UNKNOWN	Whether remote resolve includes server metadata and the source capability supports catalog metadata.	`lofibox remote stream-info <profile> <item> --json`
Lyrics were found but do not display	Whether the lyrics snapshot is available, the current track id matches, and offset/current_index is updating.	`lofibox now --fields lyrics,playback.current_track_id --json`
No lyrics candidates	Whether title/artist are empty, providers are enabled, or network policy disables online lookup.	`lofibox lyrics lookup <id-or-path> --json`

Writeback principle: apply may update LoFiBox cache/projection; writeback is the action that attempts to modify media file tags. Remote libraries are usually not writable, so completion results should be stored in local metadata cache.