Skip to content

ADR-0010: Fuzzy MusicBrainz Recording Matching

Status

Accepted

Date

2026-08-12

Context

The original lookup returned zero results for tracks that were known to exist on MusicBrainz (e.g. Talk To Me by Champion, Four Tet, Skrillex, Naisha).

Root cause: the search query treated the comma-joined artist string as a single quoted name — artist:"Champion, Four Tet, Skrillex, Naisha" — but MusicBrainz stores each artist as a separate credit. The track was recorded as Champion / Four Tet / Skrillex / Naisha. The fix is to split the artist string and OR the names in the query:

recording:"Talk To Me" AND (artist:"Champion" OR artist:"Four Tet" OR artist:"Skrillex" OR artist:"Naisha")

Fixing the query alone was not enough. With a working query, blindly taking the first result returned the wrong recording (the same title by a different artist, e.g. Talk to Me Baby by Champion Jack Dupree). The candidate list needs validation.

Two query strategies were tested against real cases:

  • Strict AND (artist:X AND artist:Y): returned only correct recordings in every case tested, but is brittle — it fails whenever the provider's artist list differs from MusicBrainz's credit set (extra remixers, "feat." granularity).
  • OR + artist coverage: tolerant of exactly those differences.

The MBID is the canonical cross-provider dedup key (ADR-0006). A wrong match is therefore worse than no match: it would merge two distinct recordings into one.

Decision

  • Search with an OR query over the split, individually-quoted artist names, combined with the quoted title.
  • Validate candidates by scoring before accepting any MBID:
  • Title similarity: exact match scores 1.0; a candidate that extends the expected title only with version qualifiers ("Extended Mix", "Remix", "Live", ...) scores 0.9; partial overlaps score 0.85/0.5.
  • Artist coverage: the fraction of expected artists present in the recording's artist credit.
  • A candidate is accepted only if title ≥ 0.9 and artist coverage ≥ 0.5; the highest-scoring passing candidate wins.
  • Prefer tolerance over strictness: OR + coverage is chosen over a strict AND query specifically so artist-list mismatches don't miss real matches.
  • Degrade gracefully: if nothing scores above threshold, or the lookup fails, the track is still downloaded and tagged with no MBID — the provider IDs in the file are sufficient identity (ADR-0006). MusicBrainz availability never blocks a download.
  • Transient MusicBrainz 503s are retried with backoff in the client (see ADR-0011).

Consequences

Positive

  • Tracks with multiple or featured artists now resolve correctly.
  • A wrong-MBID is unlikely to be accepted, protecting cross-provider dedup.

Negative

  • Conservative thresholds can reject valid matches, leaving cross-provider dedup gaps for those tracks.
  • A wrong-but-passing match is still possible and would merge distinct recordings.
  • The scoring logic is more complex than the observed problem demands. The session that produced it acknowledged it is over-built: boolean title/artist predicates plus "first passing candidate" would express the same decision in roughly half the code, and a title-only fallback was added speculatively without a demonstrated need.

Neutral

  • Matching quality depends on MusicBrainz search and artist-credit data.

Alternatives Considered

Take the first result (the original behaviour)

Rejected: with a working query this demonstrably returns wrong recordings.

Strict AND query, no scoring

Rejected: brittle against artist-list differences (extra remixers, "feat." granularity), even though it returned only correct results in the cases tested.

Exact-match-only matching

Rejected: version qualifiers and credit differences would miss valid matches.

Boolean predicates + first passing candidate

Acknowledged as equivalent for every case observed, and simpler. Not implemented; the scoring was left as-is pending real-world validation.

Future Enhancements

  • Tracks that miss on first lookup are never re-queried (the full scan only reads tags). A periodic re-lookup for files without an MBID is a candidate enhancement.