Skip to content

Add MusicBrainz identity enrichment with open-data provenance #309

Description

@guidefari

Related to #300

Research: docs/research/open-music-metadata-sources.md

Goal

Use MusicBrainz as typed identity evidence for artists, albums, and tracks, with open-data provenance and conservative automatic matching. Do not treat it as another broad link scraper.

Scope

  • Replace first-result MusicBrainz text matching with typed artist, release-group/release, and recording lookups.
  • Match by existing MBID, exact MusicBrainz URL relationship, or exact ISRC before metadata search.
  • Treat metadata search as candidate generation with a conservative acceptance policy.
  • Persist MusicBrainz links and provenance in existing entity-link metadata.
  • Add a runtime-wide one-request-per-second limiter, contactable User-Agent, retry/backoff, and positive/negative caching.
  • Add optional Cover Art Archive fallback only when a release MBID is known, without copying artwork by default.
  • Add source attribution in the product.
  • Document that commercial deployment requires a MetaBrainz service agreement or a separately designed CC0 dump ingestion path.

Identity model

  • Artist: artist MBID.
  • Album concept: release-group MBID.
  • Album edition and artwork evidence: release MBID.
  • Track: recording MBID plus ISRC evidence.
  • Playlist: no open-database or cross-platform matching.

Playlist invariant

Playlists make no requests to MusicBrainz, Cover Art Archive, Wikidata, ListenBrainz, AcoustID, or Odesli. They resolve only through the exact submitted source platform and source ID.

Acceptance criteria

  • Exact ISRC and exact external-URL matches can attach the correct recording, release, or artist MBID.
  • Ambiguous text searches do not create or merge an entity automatically.
  • Albums distinguish release-group identity from edition-specific release evidence.
  • Playlists make no open-database requests.
  • MusicBrainz traffic never exceeds one request per second per runtime egress IP and sends a contactable User-Agent.
  • Provider outages leave an exact Spotify or Deezer entity partially enriched rather than invalid.
  • Stored metadata records source, identifier type, confidence, matched identifiers, and lookup timestamp.
  • Refresh follows MusicBrainz identifier redirects without losing prior provenance.
  • Artwork fallback records its source and does not imply that approval grants reuse rights.
  • Attribution and commercial-use constraints are documented and visible to operators.
  • bun precommit passes.

Out of scope

  • MusicBrainz dump hosting or replication.
  • ListenBrainz recommendations or popularity.
  • AcoustID fingerprint generation.
  • Discogs API metadata ingestion.
  • Cross-platform playlist matching.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions