Skip to content

ADR-0006: Three-Way Track Identity in Standard Tag Frames

Status

Accepted

Date

2026-08-12

Context

Deduplication is the central goal of the project (see ADR-0005): one recording must never be downloaded twice, even when it appears in multiple playlists of different providers.

The pre-rewrite code stored a single provider ID under a custom passive-music-dl UFID owner, and only for MP3. That design had three shortcomings:

  1. No cross-provider identity. A Spotify ID and a YouTube Music ID for the same recording are unrelated strings. Deduplicating across providers needs a provider-neutral key, and a custom single-ID tag could not carry one.
  2. No interop. The custom owner was opaque to other tagging tools, so files the user downloaded and tagged manually (e.g. with MusicBrainz Picard) could not be recognised.
  3. Not portable. A tagged file handed to someone else carried no useful identity, so a fresh database could not deduplicate it against tracks downloaded through other providers.

The MusicBrainz recording ID is the natural provider-neutral key: it identifies the recording itself, independent of where it was discovered. Using it also matters for API rate limits — the MusicBrainz and provider APIs are strictly rate limited, so any ID already recorded in a file's tags is an API call the program can skip.

Decision

Every downloaded file stores three identifiers in tag locations that match common ecosystem tooling, specifically what MusicBrainz Picard writes:

  • MP3 (ID3): UFID frames with owners http://musicbrainz.org, https://music.youtube.com, and https://spotify.com.
  • M4A (MP4): iTunes freeform keys ----:com.apple.iTunes:MusicBrainz Track Id, ----:com.apple.iTunes:YouTube Music Id, and ----:com.apple.iTunes:Spotify Id.
  • OGG / FLAC / Opus (Vorbis comments): the MUSICBRAINZ_TRACKID, YOUTUBE_MUSIC_ID, and SPOTIFY_ID comment keys.

The MusicBrainz recording ID is the canonical cross-provider identity: the same recording downloaded via Spotify and via YouTube Music should carry the same MBID, enabling dedup regardless of which provider a track came from.

The full scan (ADR-0005) reads all three IDs from each file when rebuilding the database, so a file's identity is always recoverable from its tags alone.

Consequences

Positive

  • Interop: files tagged by Picard or other tools are picked up and deduplicated correctly.
  • Portability: a file handed to another user or another instance carries everything needed to rebuild the database and deduplicate against other providers, without re-querying any API.
  • Cross-provider dedup: the MBID unifies a recording regardless of its source and opens the door to future providers that have no YouTube lookup.
  • Rate-limit friendly: IDs already present in file tags are never re-looked-up, minimising MusicBrainz and provider API traffic.

Negative

  • Three tag locations per format must be written and read consistently; a per-format key mismatch silently breaks identity extraction.
  • MusicBrainz matching is probabilistic (see ADR-0010); a misidentified MBID can wrongly deduplicate two different recordings.
  • Recordings with no MusicBrainz entry can't be deduplicated between providers.

Neutral

  • Files tagged by the old custom-owner scheme are not migrated; they are treated as unrecognised and re-downloaded/re-tagged. Acceptable because no meaningful pre-rewrite library exists.

Alternatives Considered

Keep a single provider ID under a custom owner

Rejected: opaque to other tools, no cross-provider dedup, and not portable to another user's database.

YouTube video ID as the canonical cross-provider key

Rejected: Slightly less flexible than MusicBrainz. Plus, the MusicBrainz ID adds real value in the form of access to more metadata and compatibility with Picard tagged files.

Store identities in the database only, not in files

Rejected: contradicts the filesystem-as-source-of-truth model (ADR-0005) and makes a rebuilt database re-query the provider APIs for every file.