DEV Community: Christiaan Maks

Matching 90M+ music tracks across six platforms: ISRCs, fuzzy matching, and what breaks

Christiaan Maks — Thu, 06 Aug 2026 12:21:56 +0000

I run a music metadata API as a solo developer. Under it sits a catalog of 90M+ recordings aggregated from six platforms: Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz. The core job is cross-referencing: take whatever you know about a track (an ISRC, a platform ID, or a messy "artist + title" string from a DJ export) and resolve it to one canonical recording with everything else attached.

When I started, I assumed this was mostly a plumbing problem. Every platform has an API, recordings have a standard identifier, join on it, done. Almost none of that survived contact with real data. This post is the parts I had to learn the hard way: why one song legitimately carries many ISRCs, how fuzzy matching on artist and title actually has to work, why recording-to-composition mapping is many-to-many in both directions, and the failure modes I now check for routinely.

The ISRC almost solves it

The ISRC (International Standard Recording Code) is a 12-character identifier for a specific recording. Daft Punk's "One More Time" is GBDUW0000053: country prefix GB, registrant code DUW, year 00, then a designation number. Every commercially released recording is supposed to have one, and most platforms expose it. So the naive architecture writes itself: one isrc column on the track table, join all six platforms on it, ship.

That was my first schema, and it was wrong in a way that took a while to surface.

Labels mint a fresh ISRC for every commercial variant of a recording. The radio edit gets one. The extended mix gets one. The 2001 release and the anniversary remaster get different ones. A reissue through a new distributor often gets one even when the audio is bit-identical. Regional releases sometimes get their own. None of this is an error; it is how the system is designed to work, because each of those is a distinct commercial product even when it is the same performance.

The consequence: one canonical recording legitimately carries many ISRCs, and different platforms will report different ones depending on which release they ingested. Two things followed for my design:

ISRC is a junction table, not a column. One track row, many ISRC rows, each tagged with the source it came from. Deduplication collapses the radio edit, remaster, and reissue variants onto one canonical track while retaining every ISRC. Any of a track's ISRCs resolves to the same record.
Cross-source ISRC disagreement is not a data-quality signal. Early on I built a consistency check that flagged tracks where two platforms reported different ISRCs, on the theory that disagreement meant a bad merge. It flagged correct data almost everywhere it fired. I deleted the check. The thing that actually indicates a bad merge is the inverse: the same ISRC attached to two different canonical tracks. That should not happen, and a periodic GROUP BY isrc HAVING COUNT(*) > 1 over the junction table is one of the cheapest data-integrity checks I run.

Looking a track up by any of its ISRCs returns the canonical record, with one representative ISRC on the payload:

curl "https://api.sonovault.now/v1/tracks/isrc/GBDUW0000053" \
  -H "x-api-key: $SONOVAULT_API_KEY"

{
  "id": 123,
  "title": "One More Time",
  "releases": [
    {
      "id": 1,
      "title": "Discovery",
      "artist": { "id": 1, "name": "Daft Punk" },
      "label": { "id": 10, "name": "Virgin Records" },
      "release_date": "2001-03-12"
    }
  ],
  "artists": [
    { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false }
  ],
  "isrc": "GBDUW0000053",
  "duration": 320,
  "genre": ["House"],
  "subgenre": ["French House"]
}

Cross-platform resolution rides on top

Once recordings are deduplicated with all their ISRCs retained, cross-platform ID resolution is mostly a graph you maintain rather than compute. Each platform ingest attaches that platform's track ID to the canonical recording, keyed by ISRC when the platform exposes one. Where a source has no ISRC for a track, the fallback is artist + title matching (more on why that is hard below), verified against duration and release metadata before the link is written.

The payoff is that any single known identifier fans out to all the others. Give it an ISRC, a Spotify ID, or a Beatport ID, and you get back the full set:

curl "https://api.sonovault.now/v1/tracks/links?isrc=GBDUW0000053" \
  -H "x-api-key: $SONOVAULT_API_KEY"

{
  "track_id": 123,
  "title": "One More Time",
  "isrc": "GBDUW0000053",
  "links": [
    { "source": "spotify", "external_id": "0DiWol3AO6WpXZgp0goxAV", "url": "https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV" },
    { "source": "beatport", "external_id": "12345678", "url": "https://www.beatport.com/track/-/12345678" },
    { "source": "applemusic", "external_id": "1440650", "url": "https://music.apple.com/song/1440650" }
  ]
}

Fuzzy matching: the strings people actually have

A large share of lookups do not start from an identifier at all. They start from a text field in a rekordbox or Serato export, a radio automation log, or a CSV someone assembled by hand. The same recording shows up as:

Daft Punk - One More Time (Original Mix)
01. Daft Punk feat. Romanthony - One More Time [Clean]
DAFT PUNK "One More Time" (Radio Edit)

The matching pipeline that handles this is unglamorous: normalize casing and diacritics, pull feat. credits out of both fields, strip decoration tokens ((Original Mix), [Clean], track-number and "Part N" prefixes), then try an exact match on the normalized form before falling back to scored fuzzy search in Elasticsearch, with duration as a tiebreaker when the input has one. The lessons are all in the edge cases:

Decorations carry meaning, sometimes. Stripping (Radio Edit) is correct when the question is "which song is this" and wrong when the question is "which variant is this". You have to decide which question your matcher answers. Mine answers the first, because dedup already collapsed the variants onto one canonical track, so both strings should resolve to the same place.
Token stripping needs word boundaries and paranoia. [Clean] in brackets is a DJ-pool tag; the word "Clean" inside an artist name is not. Every rule in the strip list eventually meets an artist or title that uses it legitimately.
Titles are massively reused. There are enormous numbers of entirely unrelated songs called "Home" or "Stay". Title similarity alone is close to worthless as a match signal; the artist has to agree too. This sounds obvious written down. It cost me a cleanup pass to fully believe it (see the ISWC section).
Artist names fragment and conflate. "&" versus "and", a stray "The", diacritics dropped by one exporter and kept by another: these fragment one artist into several. The opposite failure is worse: two different artists with the same name. Discogs disambiguates those with numeric suffixes like (2), and merging them by name conflates real people. Never merge artists on name similarity alone; you need shared identifiers or shared release evidence.

From code, search takes artist and title as separate parameters and returns a results array plus a pagination cursor:

const res = await fetch(
  "https://api.sonovault.now/v1/tracks/search?" +
    new URLSearchParams({ artist: "Daft Punk", title: "One More Time" }),
  { headers: { "x-api-key": process.env.SONOVAULT_API_KEY! } }
);

const data = await res.json();
const track = data.results[0];
console.log(track.isrc);                     // "GBDUW0000053"
console.log(track.releases[0].release_date); // "2001-03-12"
// data.next_cursor pages through further matches, null on the last page

ISRC to ISWC: recordings versus compositions

An ISRC identifies a recording. An ISWC (format T plus ten digits) identifies the composition behind it, the written work. Mapping between them sounds like a lookup table and is actually the messiest part of the whole system, because the relationship is many-to-many in both directions:

One recording can carry several ISWCs. A medley embodies every work it contains. A track built on a substantial sample can be linked to the sampled work as well as its own.
One ISWC maps to many recordings. Every cover, live take, radio edit, and remaster of "Harder Better Faster Stronger" is a distinct recording (often with its own ISRC, per the earlier section) of the same work, T0701427997.

The reverse lookup makes the shape visible:

curl "https://api.sonovault.now/v1/tracks/iswc/T0701427997" \
  -H "x-api-key: $SONOVAULT_API_KEY"

{
  "iswc": "T0701427997",
  "title": "HARDER BETTER FASTER STRONGER",
  "total": 2,
  "recordings": [
    { "sonovault_id": 123, "isrc": "GBDUW0000059", "title": "Harder Better Faster Stronger", "artist": "Daft Punk" },
    { "sonovault_id": 456, "isrc": "GBDUW0000182", "title": "Harder Better Faster Stronger - Radio Edit", "artist": "Daft Punk" }
  ]
}

Two hard-won rules from building this mapping:

Never link on title alone. An early version of my matcher accepted a work-to-recording link when the titles matched, even if the artists did not. Because titles are so heavily reused, this quietly attached compositions to unrelated songs that happened to share a name. The fix was strict: the artist has to agree or the link is rejected, and I ran a cleanup pass over everything the old rule had written.
Distrust upstream links too. Source datasets for composition data contain their own mis-attributions; a recurring pattern is an entire album's recordings linked to a single work named after the album. If you ingest those links blindly you inherit the error, so I sanity-check that the work title actually resembles the recording title before accepting one.

What breaks, as a checklist

If you build something in this space, the recurring failure modes I now monitor for: the same ISRC on two canonical tracks (merge error, always a bug), title-only matches (unrelated songs sharing a name), artist conflation (same name, different people) and fragmentation ("&" versus "and"), release-level metadata sprayed onto every track of an album, and upstream identifier links that are simply wrong. Everything else in the pipeline is ordinary engineering. The data is the hard part.

Where this runs

All of the above powers SonoVault, the API the examples in this post hit. There is a free tier, auth is one x-api-key header, and there is no OAuth dance or approval queue. If you want to poke at the data without writing code, the ISRC lookup tool is the same endpoint behind a form, and the full endpoint reference is in the docs. If you are weighing an aggregated API against running MusicBrainz yourself (a reasonable choice for plenty of projects), I wrote an honest comparison here.

One caveat I put on everything: this is factual metadata aggregated from third parties. It can be wrong, incomplete, or mismatched, so verify it before you use it for anything contractual or financial. That is true of every metadata source in this industry; the difference is whether the vendor tells you.

Recognizing every song played on internet radio

Christiaan Maks — Mon, 13 Jul 2026 09:03:23 +0000

Internet radio stations need play logs. If you report to SoundExchange or a European collecting society, you need to know exactly which recordings aired and when, down to the ISRC. And if you just run a station, you want a now-playing feed that doesn't lie to you.

I run SonoVault, a music metadata API, and last year we added live stream monitoring: you give us an Icecast or Shoutcast URL, we tell you what's playing. This post is about everything that turned out to be harder than expected.

The metadata is right there. It's also wrong.

Icecast streams carry ICY metadata: a StreamTitle field injected into the byte stream every few kilobytes. In theory that's your now-playing feed for free.

In practice:

Stations tag ads and jingles as if they were songs.
Automation software pushes "Artist - Title" in whatever format the intern configured in 2014. Sometimes it's "Title - Artist". Sometimes it's the station slogan on repeat.
Some feeds just freeze. The stream plays on, the metadata shows the same track for six hours.

The one that really got us: a major station where the ICY metadata was consistently 10 minutes ahead of the audio. Their CDN buffers deep, the metadata injection happens at the source. So the "now playing" tag told us about a song that listeners would hear 10 minutes later. If you trust the tags and timestamp them on arrival, your entire play log is shifted by 10 minutes and every royalty line is wrong.

Conclusion after a few weeks: ICY metadata is a hint, not a source of truth. If you want a log you can put your name under, you have to listen to the audio.

Fingerprinting a stream that never ends

Audio fingerprinting against a known catalog is a solved problem for files. For live streams it gets messier, because you don't get a clean file. You get an endless byte stream that reconnects, drops, changes bitrate, and occasionally decays into noise without telling you.

Our pipeline looks roughly like this: ffmpeg decodes the stream to PCM, we cut it into overlapping chunks, fingerprint each chunk, and match against a reference index built from our catalog. A single chunk match means little. Radio edits, DJ transitions and voiceovers produce garbage matches all the time. A track only counts as playing when consecutive chunks agree on it. That one rule kills most false positives.

Two things surprised me about the matching itself.

First, genre changes everything. Electronic music on a current-hits station is the easy case: a small hot set of tracks covers most of the airtime, so you can keep the popular fingerprints in memory and match fast. Classical radio is the opposite: long works, dozens of recordings of the same piece, quiet passages that fingerprint poorly. The precision settings that work for one format actively hurt on the other, so this ended up as a per-stream configuration instead of a global one.

Second, your reference audio matters as much as your algorithm. Fingerprints made from 30-second preview clips match studio versions fine, but radio plays are sped up, pitched, and cut differently. We got a real recall jump from using fingerprint methods that tolerate time-warping, and another one from fingerprinting actual broadcast recordings instead of only previews.

The stream will gaslight you

The nastiest bug of the whole project: recognition on one station died, and stayed dead, while the stream sounded completely fine in a browser.

The cause took a while to find. The station's CDN was intermittently returning 404s for audio segments. Our long-running decoder survived the errors but silently lost sync with the HE-AAC stream, and from that point on it produced PCM that looked like audio, decoded without errors, and matched nothing. A freshly started decoder on the same URL was fine. So the source was pristine, our process was broken, and no error was raised anywhere.

The fix is humbling: watch your own recognition rate per stream, and when a stream that normally matches 15 tracks an hour matches zero for long enough, kill the decoder and start a new one. We tried being smarter. Restarting works.

Same lesson in smaller doses everywhere:

Set read timeouts on the stream connection. Some servers keep the socket open and send nothing forever.
Back off and retry when a stream goes down, but keep trying for a long time. Stations go offline for hours and come back.
Do the heavy matching off the main thread. We had alert storms that looked like network problems and were actually the Node event loop starving while a matcher chewed on a chunk.

What comes out the other end

Per stream we end up with a timestamped log of recognized plays, with adjacent detections of the same track collapsed into one airing. Because the recognition runs against a full metadata catalog, every play carries its ISRC, label, album and release date, which is exactly the set of fields royalty reports ask for and playout software doesn't export.

Registering a stream is one call:

curl -X POST https://api.sonovault.now/v1/streams \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/stream", "name": "My station"}'

Then you either poll the history endpoint, subscribe to webhooks, or open an SSE feed and watch plays arrive live.

This all runs behind sonovault.now/streams. The metadata API next to it has a free tier if you just want ISRC lookups or cross-platform track IDs without the stream part. Docs are at sonovault.now/docs.

If you're building anything in this space, or you run a station and your play logs are lying to you, I'm happy to compare notes in the comments.

The Spotify API is locking down. Here's how I resolve tracks across every platform instead

Christiaan Maks — Thu, 04 Jun 2026 13:05:48 +0000

If you've ever built anything music-related, you know the pain: you have a
track on one platform — a Spotify ID, an ISRC, whatever — and you need the
same track everywhere else. The Apple Music link. The Tidal ID. The
Beatport release. Plus clean metadata: label, release date, genre.

There's no single, affordable place to get that. And it just got worse:
Spotify has been locking down its API — the thing half of us reached for by
default. Audio features, related artists, recommendations, 30-second previews:
gone or gated. If you're a startup, a hobbyist, or an indie hacker, "apply for
extended access and maybe we'll get back to you" is a non-starter.

So I built SonoVault — a music metadata API that
aggregates open catalog data (Discogs, MusicBrainz, Wikidata, and the MLC)
and enriches it with cross-platform IDs. ~90M tracks. Search them, browse
them, pull artist info, and — the part I actually needed — resolve any ID or
ISRC to links on every supported platform.

The core problem: one track, many IDs

Say you've got Daft Punk's One More Time. Searching is just artist + title:

  curl -G "https://api.sonovault.now/v1/tracks/search" \
    --data-urlencode "artist=Daft Punk" \
    --data-urlencode "title=One More Time" \
    -H "x-api-key: YOUR_KEY"

  {
    "id": "282378616",
    "title": "One More Time",
    "isrc": "DEND21200535",
    "duration": 320,
    "genre": ["House"],
    "subgenre": ["Electronica"]
  }

Now the useful bit. Hand that track ID (or the ISRC, or a Spotify ID) to the
links resolver and you get every platform back in one call:

  curl -G "https://api.sonovault.now/v1/tracks/links" \
    --data-urlencode "id=282378616" \
    -H "x-api-key: YOUR_KEY"

  {
    "track_id": 282378616,
    "title": "One More Time",
    "isrc": "DEND21200535",
    "links": [
      { "source": "spotify",     "external_id": "0DiWol3AO6WpXZgp0goxAV", "url": "https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV" },
      { "source": "beatport",    "external_id": "6014288",                "url": "https://www.beatport.com/track/-/6014288" },
      { "source": "discogs",     "external_id": "2844-A",                 "url": "https://www.discogs.com/release/2844" },
      { "source": "musicbrainz", "external_id": "41829821-316a-46b7-9ba3-82a50296d3bc", "url": "https://musicbrainz.org/recording/41829821-316a-46b7-9ba3-82a50296d3bc" },
      { "source": "applemusic",  "external_id": "5468282",                "url": "https://music.apple.com/song/5468282" },
      { "source": "tidal",       "external_id": "124215",                 "url": "https://tidal.com/browse/track/124215" },
      { "source": "youtube",     "external_id": "0XTLs9IsmCg",            "url": "https://www.youtube.com/watch?v=0XTLs9IsmCg" }
    ]
  }

You can start from an ISRC instead — same result, because every ISRC for the
recording resolves to the same track:

  curl -G "https://api.sonovault.now/v1/tracks/links" \
    --data-urlencode "isrc=DEND21200535" \
    -H "x-api-key: YOUR_KEY"

"Listen on / Buy on" buttons in ~10 lines

The thing most people want this for — universal links — is now trivial:

  async function getLinks(isrc) {
    const res = await fetch(
      `https://api.sonovault.now/v1/tracks/links?isrc=${isrc}`,
      { headers: { "x-api-key": process.env.SONOVAULT_KEY } }
    );
    const { links } = await res.json();
    return Object.fromEntries(links.map((l) => [l.source, l.url]));
  }

  const links = await getLinks("DEND21200535");
  // { spotify: "...", applemusic: "...", tidal: "...", beatport: "...", youtube: "..." }

It's not just links — there's metadata too

Artist info: origin, formation, socials

Every artist comes with country, formation year, social handles, and a
Wikidata ID for further linking:

  curl "https://api.sonovault.now/v1/artists/1925615" -H "x-api-key: YOUR_KEY"

  {
    "id": 1925615,
    "name": "Daft Punk",
    "country": "France",
    "formation_year": 1993,
    "social_links": {
      "website": "https://daftpunk.com",
      "twitter": "daftpunk_music",
      "instagram": "daftpunk",
      "facebook": "daftpunk"
    },
    "wikidata_id": "Q185828",
    "release_count": 888
  }

(/v1/artists/search?name=... returns the same shape, so you can go from a
name straight to socials + origin.)

Browse: discover by genre, year, and label

Need "give me some House from 2001" — optionally random — instead of an exact
search? That's the browse endpoint (Starter tier and up):

  curl -G "https://api.sonovault.now/v1/tracks/browse" \
    --data-urlencode "genre=House" \
    --data-urlencode "year=2001" \
    --data-urlencode "randomize=true" \
    -H "x-api-key: YOUR_KEY"

  {
    "results": [
      { "title": "Work (Masters At Work Remix)", "artists": [{ "name": "Masters At Work" }], "genre": ["House"] },
      { "title": "Moments in Time (VW20 Mix)",    "artists": [{ "name": "Vince Watson" }],   "genre": ["House"], "subgenre": ["Deep House"] }
    ]
  }

Filter by any combination of genre (or genreId), year, labelId, and
artistId. Great for radio-style "more like this" features and seeded playlists.

New releases, scoped to a label

Want to follow a label's latest drops? Resolve the label, then page its
releases newest-first:

1. find the label id

  curl -G "https://api.sonovault.now/v1/labels/search" \
    --data-urlencode "name=Ed Banger" -H "x-api-key: YOUR_KEY"

 { "id": 604, "name": "Ed Banger Records", "release_count": 634 }

2. its newest releases

  curl "https://api.sonovault.now/v1/labels/604/releases?limit=5" \
    -H "x-api-key: YOUR_KEY"

  {
    "results": [
      {
        "id": 130298552,
        "title": "SAINT LAURENT WOMEN'S WINTER 26",
        "artist": { "id": 1236632, "name": "SebastiAn" },
        "label": { "id": 604, "name": "Ed Banger Records" },
        "release_date": "2026-05-07",
        "track_count": 1
      }
    ],
    "next_cursor": "2026-05-07:130298552"
  }

The same paginated, newest-first pattern exists for artists
(/v1/artists/:id/releases) — handy for "new from artists you follow" feeds.

The hard part: what counts as "one track"?

This was the real engineering challenge. A single recording exists as a dozen
near-identical rows across sources — radio edit, extended mix, remaster,
compilation reissue — each with its own ID and often its own freshly-minted
ISRC. If I returned all of them, every search would be a wall of duplicates.

So SonoVault collapses similar variants into one canonical track. Search
One More Time and you get one result, not fifteen. Every variant's ISRC
still resolves back to that canonical track, so a lookup from any source lands
in the same place. (Getting the normalization right — without merging genuinely
different recordings — took a lot of iterations.)

What it deliberately doesn't do

Being honest about the boundaries:

No album art. The cover images are copyrighted by the labels/DSPs.
No audio previews. Those belong to the streaming services.

It's metadata and cross-platform resolution — not a media CDN.

It's in open beta — kick the tyres

Free tier: 1,000 requests/month, no credit card.
Search, ISRC lookup, artist info, label/artist release feeds, and the cross-platform links resolver are all on the free tier. (Browse, charts, and the global new-releases feed unlock on Starter and up.)
Full docs here.

I'd genuinely love feedback — especially from anyone who's fought with the
Spotify or MusicBrainz APIs. And if you want to stress-test it, reply or
get in touch and I'll bump your limits for free while we're in beta.