DEV Community: Freqblog

Auto-Tag Your Music Library — With Confidence Scores

Freqblog — Tue, 14 Jul 2026 13:49:13 +0000

"Tag my whole catalogue by mood, energy and genre" is one of those jobs that sounds like a weekend script and turns into a procurement cycle. The enterprise tagging tools — Cyanite is the one people name — do the job well, but the shape of the deal is the friction: you upload your audio, you sign up for a seat, and what comes back is a confident flat label (energetic, happy, techno) with no indication of how it was decided or how much to trust any single tag. For a side project, an internal catalogue tool, or a feature you're still prototyping, that's a lot of ceremony for some adjectives.

This post is a practical walkthrough of the self-serve alternative: tag tracks by name (no audio upload) in about 30 lines of Python against the FreqBlog Music API's GET /tag — and, crucially, get a confidence and a provenance on every tag, so you know which ones are a measurement and which ones are a hint.

What /tag actually is. It's a tag-shaped projection of the same open-data analysis /lookup already returns — no audio upload, no new compute on your request. If you want the full numeric feature set (raw bpm, key, the [0,1] floats), use /lookup; if you want the nearest-sounding tracks to a seed, use /similar. /tag is the "just give me the labels, honestly" surface.

Why honesty is the feature

Audio tagging is not one problem — it's a stack of problems with very different reliability. A track's energy or danceability is a measurement off the waveform: reproducible, defensible, and the same every time. A one-word mood is a derivation from those measurements via a rule. A fine-grained mood like "aggressive: 0.71" is a model estimate from a research-grade classifier that was honest enough about its own limits that its authors deprecated it. Genre is a broad catalogue tag, not a taxonomy you should bet a recommender on.

Most taggers flatten all four into the same confident-looking string. FreqBlog's /tag refuses to: every tag in the response carries a confidence and a provenance, so a measured high-energy and a model-estimated aggressive never look equally authoritative. That's the differentiator — not "more tags," but tags you can reason about.

The call — one track, in

GET /tag resolves a track by exactly one of: track (plus optional artist), isrc, mbid, spotify_id, or track_id (a catalog itunes_track_id) — the same identifiers /lookup accepts. No Spotify account, no audio file.

import requests

API = "https://api.freqblog.com"
HEADERS = {"X-Api-Key": "sk_live_your_key_here"}

def tag(track, artist=None):
    params = {"track": track}
    if artist:
        params["artist"] = artist
    r = requests.get(f"{API}/tag", params=params, headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

data = tag("Blinding Lights", "The Weeknd")
for t in data["tags"]:
    val = "" if t["value"] is None else f"  ({t['value']})"
    print(f"  {t['category']:16} {t['tag']:18} [{t['confidence']}]{val}")

For Blinding Lights that prints a handful of tags across the categories — a measured high-energy (1.0), very-danceable and acoustic; a derived mood of tense; and a catalog genre of synthwave. The response envelope is { track, count, tags:[…], disclaimer }: track is the resolved stub (name, artist, ids), count is the number of tags, and disclaimer is a plain-English note about provenance you can surface in a tooltip.

The four confidence levels — what each one means

Every tag's confidence + provenance tells you which bucket it came from. There are exactly four, and they're ordered most-to-least authoritative:

confidence	provenance	what it is	value
`measured`	`essentia`	Our own Essentia analysis of the recording — energy, danceability, valence, acousticness, instrumentalness — bucketed to a human label.	the [0,1] score
`derived`	`valence+energy`	A single MIREX-style mood category computed from the measured valence + energy (e.g. `tense`, `calm`).	`null` (label only)
`model-estimated`	`acousticbrainz`	AcousticBrainz mood SVM probabilities (happy / sad / aggressive / relaxed / party). Research-grade — treat as a hint.	the raw probability
`catalog-genre`	`catalog`	The broad catalogue genre tag (iTunes / Last.fm chain). Coarse, not a fine taxonomy.	`null` (label only)

So the rule for a consumer is simple and the API does the heavy lifting of being honest: trust the measured tags as fact, treat derived as a reasonable summary, and gate any product decision on a model-estimated mood by its value — it's only emitted when the model's probability clears 0.5, and the raw number is right there for you to threshold higher.

Two things we deliberately do NOT serve — and why it makes the output better. (1) AcousticBrainz also ships a genre column, but it's roughly 80% mislabelled "electronic" — so we serve the broad catalogue genre instead and never expose the AB genre column. (2) AB ships a single argmax mood label ("this track is happy"); we don't serve that verdict either — we expose the per-axis SVM probabilities with the raw numbers, so you can see it's happy: 0.58 / relaxed: 0.55 rather than a confident coin-flip dressed as a fact. Leaving bad data out is part of the honesty.

Tagging a whole library

The endpoint is one track per call, so "tag my library" is a loop — resolve each (title, artist) once, keep the tags you care about, and you're done. A small, readable version that pulls just the high-confidence labels for a playlist:

library = [
    ("Blinding Lights", "The Weeknd"),
    ("Bohemian Rhapsody", "Queen"),
    ("One More Time", "Daft Punk"),
]

def trusted_tags(track, artist):
    """Measured + derived tags only — the ones safe to file on."""
    data = tag(track, artist)
    out = {}
    for t in data["tags"]:
        if t["confidence"] in ("measured", "derived", "catalog-genre"):
            out.setdefault(t["category"], t["tag"])
    return out

for title, artist in library:
    tags = trusted_tags(title, artist)
    print(f"{title} — {artist}")
    print(f"   {tags.get('energy')}, {tags.get('danceability')}, "
          f"mood={tags.get('mood')}, genre={tags.get('genre')}")

That's the whole pattern: a function per track, a filter on confidence, and a dict you write to your own store. If you want the model-estimated mood axes too, drop the filter and read value — the data's there, you just choose how much to trust it. Each successful call is one quota unit (it's a /lookup projection — same data, same cost), and you're only charged on a served 200; a miss (404) or a request with no/invalid identifier (422) costs nothing. The free tier's 1,000 requests/month is enough to tag a real playlist before you ever need a paid plan.

What you can and can't tag — the honest coverage

This is the part most "tag any track" pitches get wrong, so here it is plainly. There are two coverage stories and they're different:

The measured tags — the broad, reliable coverage. Energy, danceability, valence, acousticness, instrumentalness and the derived mood come from our own Essentia analysis over the pre-analysed catalogue (hundreds of thousands of tracks), and any track not yet in it gets pulled in on demand the first time you look it up. You can tag these by name. Lead with this — it's where /tag is dependable.
The model-estimated mood axes — reachable when you supply the identifier. The AcousticBrainz SVM probabilities sit over 7.5M+ recordings, but they're keyed by MusicBrainz ID. So you can reach that slice by passing an mbid or an isrc — when you supply the identifier — not by track name alone. Only a small fraction of AB rows are resolvable by name today.

The one-line version: tag any track by name (the full analysed catalogue + on-demand backfill) for the measured features, or by MBID / ISRC against 7.5M+ AcousticBrainz recordings when you supply the identifier for the model-estimated mood. It is not "7.5M tracks by name" — and we'd rather tell you that up front than have you discover it in production.

How it compares to enterprise auto-tagging — honestly

No upload, self-serve. You tag by name / ISRC / MBID against open-data analysis — there's no audio to upload, no seat to provision, and you can be tagging a playlist 60 seconds after you get a free key.
Confidence + provenance on every tag. This is the headline difference. A closed tagger gives you a label; /tag gives you a label plus where it came from and how much to trust it — so you can file the measured tags and gate the model-estimated ones.
Open data, not a black box. The measured tags are our Essentia pipeline; the mood axes are AcousticBrainz; the genre is the broad catalogue tag. Nothing here is a proprietary score you can't reason about — and we leave the known-bad fields (the ~80%-"electronic" AB genre column, the argmax mood verdict) out on purpose.
Coverage, not magic. The measured tags need the track in the catalogue (or pulled in on demand); the model-estimated mood needs an MBID/ISRC. A track we can't resolve simply comes back without those tags rather than with a confident guess — better an honest gap than a wrong label.

Try FreqBlog — free tier, no card: https://freqblog.com/

Mixed In Key vs Rekordbox vs Serato: Why DJ Platforms Disagree on Key 60% of the Time

Freqblog — Tue, 14 Jul 2026 13:48:32 +0000

Take a track. Run it through Mixed In Key, then Pioneer Rekordbox, then Serato. Compare the keys.

If they all agree, congratulations — you've picked a track that's harmonically unambiguous. If you spent an afternoon picking 20 tracks and ran the experiment, you'd find that all three platforms agree on the key for only about 39% of them. Mixed In Key disagrees with Serato on 45%. Mixed In Key disagrees with Rekordbox on 38%.

That isn't a typo. Three professional, paid DJ platforms produce three different answers for nearly two in three tracks. This article unpicks why — and what it means if you're building software that depends on key detection.

The numbers

The 39 / 45 / 38 percentages come from independent comparisons run by harmonic-mixing communities and reproduced multiple times since 2019. The methodology is straightforward: take a corpus of commercial music, run each platform's analyser on the same files, and tabulate exact-match agreement.

Pair	Agreement	Disagreement
All three platforms agree	~39%	61%
Mixed In Key vs Serato	~55%	45%
Mixed In Key vs Rekordbox	~62%	38%

"Disagreement" here means the platforms returned different keys (e.g. F# minor vs A major) — not minor numerical differences. The disagreement is categorical.

Why three pro tools produce three different answers

1. Different algorithms

Each platform implements key detection differently. Mixed In Key uses a proprietary algorithm trained on commercial music, often with manual curation in the training set. Rekordbox uses Pioneer's in-house engine that prioritises speed (analysis runs in the player). Serato uses a third approach optimised for live performance.

Most modern key detectors are chromagram-based: split the audio into short frames, compute a 12-bin pitch-class histogram, then correlate against a reference template (Krumhansl-Schmuckler is the classic). The differences come from how:

Frame size and hop — longer frames smooth out percussion, shorter frames pick up rapid modulations.
Harmonic peak detection vs. raw spectral energy — harmonic peak detection is more accurate but slower.
Low-pass filtering before chromagram — cuts cymbal hash, but can over-suppress melody.
Reference template choice — Krumhansl, Temperley, Bellman, or a neural-network alternative each give different priors.
Modal handling — relative major and minor share the same notes; algorithms decide differently between e.g. A minor and C major.

2. The relative-key flip

The single biggest source of disagreement: relative major and minor have identical pitch content. A minor uses the same seven notes as C major. Algorithms decide between them via priors that look at melody contour, downbeat emphasis, and chord voicing — signals that are easy to get wrong.

On the Camelot wheel, this flip means the same track gets tagged 8A or 8B by different platforms. Either is musically defensible; only one matches the producer's intent.

Practical effect: when two platforms disagree on a track, ~70% of the time it's a relative-key flip (same Camelot number, different letter). The other 30% is genuine pitch-class disagreement.

3. Different definitions of "in key"

Many tracks change key. A pop song might verse in A minor and chorus in C major. Some platforms report the dominant key by duration; others report the chorus key; others bias toward the more "harmonically rich" section. Each is a defensible choice.

4. Tuning frequency drift

Pre-1980 recordings, jazz, and a lot of indie / experimental music aren't tuned to A4 = 440 Hz. They might be at 432, 435, 442, or anywhere in between. A chromagram tuned to 440 will smear pitch-class energy across two adjacent bins for a track at 432 — and the algorithm picks whichever bin happens to win.

This is the dirty secret of key detection: the further you get from "modern recording, tuned to 440, clear melody", the more the algorithms diverge.

What to do about it

If you're a DJ

Pick one tool and trust its analysis end-to-end. Mixing across platforms produces inconsistent results because of the disagreement above. The Camelot wheel was designed to be tolerant — adjacent moves (±1 number, same letter) work even when the underlying key tag is slightly wrong — so consistency matters more than which platform you chose.

If you're building an app

You need a single source of truth that's API-accessible. The DJ tools above don't expose their analysis as an HTTP endpoint, so you're either:

Building your own detector with Essentia / Librosa / Madmom (weeks of tuning, then you have your own opinion to defend)
Paying Spotify (deprecated audio_features as of November 2024) or AcousticBrainz (frozen July 2022)
Using a managed API that handles the tuning, modal disambiguation and Camelot conversion for you

Try FreqBlog — free tier, no card: https://freqblog.com/

Confidence scores beat opinions

Every detector should expose a confidence score alongside the key. Mixed In Key colour-codes its output (green = confident, red = best-guess). Rekordbox does too internally but doesn't expose it. Serato hides it from users entirely.

This matters because for ~60% of tracks the algorithm knows it's not certain. Surfacing that lets your application:

Treat low-confidence detections as advisory rather than authoritative
Fall back to user override or alternative algorithms
Flag tracks that are likely to clash on a harmonic playlist regardless of platform agreement

Our own API returns a key_confidence field on every /lookup response. Below 0.4 means the track is likely atonal, modal, or harmonically ambiguous — treat that as "play it solo, don't try to mix it".

Camelot is robust to all of this

Here's the bright side. The Camelot wheel was specifically designed for the case where two algorithms disagree on the relative-key flip. 8A and 8B mix harmonically with each other — you can play the relative even when the algorithm got the modal wrong.

If you build playlists using Camelot adjacency rules (same number, ±1 number, same-or-opposite letter), you get a tolerant matcher that works with any of the three platforms above. The key detection accuracy stops mattering as much when the downstream consumer is robust to off-by-one errors.

The takeaway: stop chasing perfect key detection. Build robustness into your harmonic-mixing logic and accept that any single algorithm is a probability distribution, not an oracle.

Half-Time vs Double-Time BPM Detection: How We Fixed Spotify's Known Accuracy Gap

Freqblog — Tue, 14 Jul 2026 13:47:51 +0000

Run Blinding Lights by The Weeknd through Essentia's RhythmExtractor2013. It returns 85.4 BPM. The track is famously 171 BPM — one of the most-played tracks of the last decade, peer-reviewed by literally every DJ in the world.

This isn't a bug. It's a known property of beat-tracking algorithms: they pick the wrong tactus level for tracks where the perceived beat doesn't match the dominant onset rate. Spotify's deprecated audio_features had the same problem — entire genres came back at half their actual tempo.

This article unpicks why that happens and shows the 30-line heuristic we use to detect and correct it.

What "BPM" actually means

Most people think BPM is a single number per track. It isn't. A piece of music has a metric hierarchy — nested levels of regular pulse:

Tatum — the smallest regular subdivision. For a typical 4/4 dance track, this is the 16th note.
Tactus — the level you tap your foot to. This is what humans usually call "the BPM."
Measure — one bar.
Hyper-measure — phrase-level groupings (4-bar, 8-bar, 16-bar).

For most tracks the tactus is unambiguous. Bohemian Rhapsody is 72 BPM. Levels by Avicii is 126 BPM. Easy.

But for some tracks, especially modern pop with halftime drums or trap-influenced production, the tactus level is genuinely ambiguous. Blinding Lights has a synth-arp running at 16th notes (171 BPM × 4 = 684 BPM at the tatum), kicks every quarter note (171 BPM), but a snare on beats 2 and 4 only (85 BPM perceived as the snare-driven beat).

Whether you call it 85 or 171 depends on where you'd start a metronome. Most listeners and DJs say 171. Beat trackers often say 85.

Why algorithms get it wrong

Beat trackers like Essentia RhythmExtractor2013, BeatTrackerDegara, and Librosa's beat.beat_track all work the same way at a high level:

Compute an onset envelope — signal where each peak corresponds to a percussive event (kick, snare, transient).
Compute the tempogram — autocorrelation of the onset envelope across a range of candidate periods.
Pick the period with the highest score, weighted by a tempo prior (most algorithms prefer 90-180 BPM).

The failure mode for half-time tracks: the tempogram has a peak at both the perceived BPM (171) and at half (85.5). Both are mathematically valid — the snare on beats 2 and 4 forms a regular pulse at 85.5 BPM. The algorithm's tempo prior gently nudges toward higher BPMs (octave-aware priors typically peak at 120 BPM and fall off slowly), but for tracks where the kick-snare pattern strongly emphasises the half-time grid, the lower peak wins.

Why pop especially? Modern pop production deliberately crafts kicks and snares to feel "patient" against fast hi-hats. The snare landing on 2 and 4 (rather than every quarter note) creates a hypnotic 85-BPM feel even when the underlying tempo is 170. Producers do this on purpose. The algorithm just reports what it hears.

Detecting the wrong level

Once you know what's happening, detecting it is straightforward. A track that's "really" at 170 but reported as 85 has these tell-tale signatures:

BPM in 70-95 range (the suspect zone — where half-time pop typically lands)
High onset rate (>3 events per second — lots of percussion happening between the slow snares)
High energy (>0.4 RMS — not a slow ballad)
High danceability (>0.55 — not a smooth jazz track)

If all four are true, the track is almost certainly perceived at 2× the reported BPM. Conversely, a track reported at >170 BPM with low onset rate (sparse percussion) is likely double-time'd — the algorithm picked up a hi-hat pattern when the tactus is the slower kick.

The correction heuristic

Here's a faithful simplification of the heuristic we ship (the production version uses curated fast/slow genre sets). Returns a corrected BPM alternative when warranted, None otherwise. It never overwrites the raw BPM — we expose the corrected value as a sibling field bpm_alt so callers can choose.

def bpm_alt(bpm, onset_rate, energy, danceability, genre=None) -> float | None:
    """Half-time / double-time BPM correction. Conservative — false positives push
    customers off-grid, so we require multiple signals to agree before suggesting.
    onset_rate comes from AcousticBrainz and is null for most preview-analysed
    tracks, so genre carries the decision whenever onset_rate is missing."""
    if bpm is None:
        return None

    fast = genre in FAST_GENRES   # house, techno, drum & bass, synthwave, ...
    slow = genre in SLOW_GENRES   # hip-hop, r&b/soul, ballad, downtempo, ...

    # Half-time → suggest 2x (a track that *feels* like twice the reported tempo)
    if 70.0 <= bpm <= 95.0 and not slow:
        if onset_rate is not None and onset_rate > 3.0 \
           and (energy or 0) > 0.4 and (danceability or 0) > 0.55:
            return round(bpm * 2, 2)
        # onset_rate missing → lean on a fast-genre tag, else demand strong evidence
        if fast and (energy or 0) > 0.4 and (danceability or 0) > 0.55:
            return round(bpm * 2, 2)
        if onset_rate is None and (energy or 0) > 0.9 and (danceability or 0) > 0.65:
            return round(bpm * 2, 2)

    # Double-time → suggest 1/2x
    if bpm >= 165.0:
        if onset_rate is not None and onset_rate < 1.5:
            return round(bpm / 2, 2)
        if onset_rate is None and slow:
            return round(bpm / 2, 2)

    return None

Tested on the live catalog:

Track	Raw BPM	bpm_alt	Real BPM
Blinding Lights / The Weeknd	85.4	170.8	171
Levitating / Dua Lipa	102.8	—	103
Bohemian Rhapsody / Queen	72.0	—	72
Don't Stop the Music / Rihanna	123.6	—	124

The heuristic fires on Blinding Lights (correctly — it's tagged synthwave, a fast genre) and stays silent on the other three (correctly). The conservative thresholds — genre, onset rate, energy and danceability all have to agree — mean it rarely false-positives on tracks at 80-95 BPM that genuinely belong there.

Why not just multiply by 2 for everything in 70-95?

You'd break every R&B ballad, every downtempo track, and every hip-hop song that's actually at 90 BPM. Real 80-95 BPM music exists in volume. The whole point of the heuristic is to distinguish tracks that feel like 170 from tracks that are 85. The signal is the rest of the audio descriptors:

A real 85-BPM track has lower onset rate (sparse hi-hats, less internal pulse)
A real 85-BPM track has lower danceability (because beat strength is lower at the perceived tactus)
A 170-perceived-as-85 track will pin all four signals high

Production deployment notes

Don't overwrite cached results

If your existing API stores BPM in a database, applying correction in-place is a breaking change — customers' existing playlists, mixes, and analyses depend on the previous value. Always expose the corrected BPM as a sibling field (bpm_alt, bpm_corrected, bpm_perceived) and let callers opt in.

Make it derivable, not stored

The correction only depends on existing fields: bpm, onset_rate, energy, danceability and genre. Compute it at response build time, not at ingest. That way you can tune the heuristic without re-analysing your catalog.

Surface confidence

If you have a beat-detection confidence score (Essentia returns one), use it as a fifth gate. A low-confidence detection is more likely to be an octave error and benefits from the alternative.

What about machine-learned alternatives?

Several recent papers train neural networks to predict the tactus level directly — treating tactus selection as a classification problem rather than a peak-picking problem. Madmom's DBNDownBeatTracker does something similar by jointly tracking the beat and the downbeat with a Bayesian network.

These work well but they're slower, larger (60+ MB models), and require more inference compute. For a high-throughput API the heuristic above gets you 90% of the gain at literally zero extra cost — it's just four float comparisons on existing fields.

Try FreqBlog — free tier, no card: https://freqblog.com/

Camelot Wheel for Developers: Harmonic Mixing Without the Music Theory PhD

Freqblog — Tue, 14 Jul 2026 13:47:10 +0000

Here's the bargain music theory hands developers: take the circle of fifths — a 700-year-old chord-relationship diagram — rotate it slightly, replace the keys with numbers, and you get a tool that lets a 16-year-old DJ build a harmonic set without knowing what "fifth" means.

That tool is the Camelot wheel. It's the foundation Mixed In Key, Rekordbox, Serato, and Engine DJ all build on. And implementing the rules in your own software takes about 50 lines of code.

What the wheel does

Every musical key has a relationship to every other key. Some pairs sound great together (relative major/minor). Some clash horribly (a minor third apart). Music theory expresses these relationships in terms like "subdominant" and "tritone substitution" — useful if you're writing a fugue, useless if you're trying to mix two house tracks at 2am.

The Camelot wheel collapses all this into a clock face: 12 numbered positions, each with an A (minor) and B (major) variant. Two tracks mix harmonically if they share a position, are adjacent on the wheel, or are on the same number with different letters.

Camelot	Key name	Camelot	Key name
1A	A♭ minor	1B	B major
2A	E♭ minor	2B	F# major
3A	B♭ minor	3B	D♭ major
4A	F minor	4B	A♭ major
5A	C minor	5B	E♭ major
6A	G minor	6B	B♭ major
7A	D minor	7B	F major
8A	A minor	8B	C major
9A	E minor	9B	G major
10A	B minor	10B	D major
11A	F# minor	11B	A major
12A	C# minor	12B	E major

The four rules

Rule 1: Same key (perfect mix)

Track at 8A mixes with another track at 8A. Boring but harmonically perfect. Useful for back-to-back tracks where the mix focuses on rhythm rather than chord progression.

Rule 2: Relative key (mood swap)

8A mixes with 8B. Same number, opposite letter. Same notes, different mood — a minor track and its relative major share all seven scale degrees, so they're harmonically identical from a pitch-class perspective. Mixing 8A → 8B is the classic "go from melancholic to hopeful" move.

Rule 3: Adjacent (energy lift / drop)

8A mixes with 7A or 9A. Same letter, ±1 number. The fifth-relationship gives you a smooth modulation that feels like the energy is climbing or relaxing without ever clashing.

Wraparound matters: the wheel is a circle. 12A → 1A is one step, not eleven. 1A → 12A likewise.

Rule 4 (advanced): Energy boost / drop

8A → 3A is a +7 jump — a bigger key change that landing-DJs use to lift energy mid-set. 8A → 1A is -7. These aren't strictly harmonic but every commercial DJ tool exposes them as "energy boost / drop" because they're a staple of festival mixing.

The 50-line implementation

Here's a complete Python implementation. Drop it into your project, no dependencies.

def camelot_compatible(camelot: str, *, extended: bool = False) -> list[tuple[str, str]]:
    """Return [(camelot, relation), ...] for every key that mixes with `camelot`.
    `extended=True` adds the +7/-7 energy-boost variants."""
    import re
    m = re.fullmatch(r'(1[0-2]|[1-9])([AB])', camelot.upper())
    if not m:
        raise ValueError(f"invalid Camelot value: {camelot!r}")
    n = int(m.group(1))
    letter = m.group(2)
    other_letter = "B" if letter == "A" else "A"

    def wrap(x: int) -> int:
        return ((x - 1) % 12) + 1

    pairs = [
        (f"{n}{letter}",        "same"),
        (f"{n}{other_letter}",  "relative"),
        (f"{wrap(n + 1)}{letter}", "adjacent_up"),
        (f"{wrap(n - 1)}{letter}", "adjacent_down"),
    ]
    if extended:
        pairs.append((f"{wrap(n + 7)}{letter}", "energy_boost"))
        pairs.append((f"{wrap(n - 7)}{letter}", "energy_drop"))
    return pairs


# Example
>>> camelot_compatible("8A")
[('8A', 'same'), ('8B', 'relative'), ('9A', 'adjacent_up'), ('7A', 'adjacent_down')]

>>> camelot_compatible("12A", extended=True)
[('12A', 'same'), ('12B', 'relative'), ('1A', 'adjacent_up'),
 ('11A', 'adjacent_down'), ('7A', 'energy_boost'), ('5A', 'energy_drop')]

If you'd rather skip writing this yourself, our API exposes the same logic as GET /key/<camelot>/compatible?extended=true — no auth, no quota, pure-logic helper.

Distance: how do you score a transition?

Once you have compatibility, you need a distance metric for ranking transitions. Here's the rubric most DJ tools converge on:

0 hops — same Camelot exactly
1 hop — relative (same number, opposite letter), or adjacent (±1, same letter)
2-3 hops — "stretchy" but workable; many crowd-friendly mixes live here
4+ hops — clash territory, only attempt with a long mix or filter

def camelot_distance(a: str, b: str) -> int:
    """Distance in 'wheel hops' between two Camelot values."""
    import re
    ma = re.fullmatch(r'(1[0-2]|[1-9])([AB])', a.upper())
    mb = re.fullmatch(r'(1[0-2]|[1-9])([AB])', b.upper())
    if not ma or not mb:
        return 99    # treat as far
    an, al = int(ma.group(1)), ma.group(2)
    bn, bl = int(mb.group(1)), mb.group(2)
    nd = min(abs(an - bn), 12 - abs(an - bn))    # circular distance
    if nd == 0 and al != bl:
        return 1                                 # relative
    if al == bl:
        return nd
    return nd + 1                                # both differ

Watch out: the wraparound. 1A and 12A are one hop apart, not eleven. The min(diff, 12 - diff) trick handles it.

Building a harmonic playlist

Now you have compatibility and distance. The simplest playlist algorithm:

Pick a seed track
For each subsequent slot: filter the candidate pool to tracks within hop-distance ≤ K of the previous track's key
Among those, pick by a secondary criterion (BPM continuity, similarity, popularity)
Mark used, repeat

def harmonic_walk(seed_key: str, candidates: list[Track],
                  max_hops: int = 2, n: int = 20) -> list[Track]:
    playlist = []
    current_key = seed_key
    used = set()
    while len(playlist) < n:
        nexts = sorted(
            (t for t in candidates
             if t.id not in used
             and camelot_distance(current_key, t.camelot) <= max_hops),
            key=lambda t: (camelot_distance(current_key, t.camelot), -t.popularity),
        )
        if not nexts:
            break
        pick = nexts[0]
        playlist.append(pick)
        used.add(pick.id)
        current_key = pick.camelot
    return playlist

This is also exposed as a single API call — GET /radio?seed_track_id=...&n=20&max_key_distance=2 — if you'd rather not run the candidate pool yourself.

BPM continuity matters too

Harmonic compatibility on its own isn't enough. Two tracks in 8A at 95 BPM and 175 BPM can't be mixed together without a cue-point trick or a halftime drop. A real harmonic-mixing matcher needs both:

Camelot distance ≤ K (harmonic constraint)
BPM difference ≤ ±N BPM (rhythmic constraint)

For house and techno, ±5 BPM is forgiving (you can pitch ±3% on a player). For trance and DnB, you can be looser (±10 BPM). For hip-hop and R&B you usually want exact match because the swing pattern doesn't sound right pitched.

Open Key vs Camelot

Open Key is an alternative notation that some platforms (Mixed In Key, Serato) support alongside Camelot. The mapping is straightforward:

Camelot	Open Key	Camelot	Open Key
8A	1m	8B	1d
9A	2m	9B	2d
10A	3m	10B	3d
...	...	...	...

m = minor, d = major (dominant). Same circle, just rotated by 7 positions and re-labeled. The compatibility rules are identical — if your code uses Camelot, support both notations as input via a small lookup table and you're done.

Edge cases

Atonal / modal tracks — ambient, drone, and a lot of jazz don't have a clear key centre. Detection algorithms return low confidence; treat as "skip from harmonic constraints" in your matcher.
Key changes mid-track — some tracks modulate. Most detectors return the dominant key by duration; if your input source supports it, prefer the chorus/drop key for a DJ mix because that's what people will be hearing during a transition.
Half-time / double-time confusion — not a key issue but related: a track perceived at 170 BPM might be detected at 85. More on that here.

Try FreqBlog — free tier, no card: https://freqblog.com/

Build a Harmonic DJ Set Planner in 50 Lines

Freqblog — Tue, 14 Jul 2026 13:46:29 +0000

When Spotify deprecated audio_features and audio_analysis, the obvious loss was the per-track numbers — tempo, key, energy. The quieter loss was everything you used to build on top of them: the "what should I play next" logic, the harmonic-compatibility checks, the auto-ordered playlist. Plenty of people have written a host-swap guide to get the raw fields back. This post is about the layer above that — turning a crate of track names into an actual, beat-matched, key-compatible set.

We'll do it in about 50 lines of Python against the FreqBlog Music API, using four endpoints: /next-track (what mixes well after this?), /transition (how well do these two mix, exactly?), /setlist (order this whole crate into an energy arc), and /export/rekordbox (drop the result straight into Rekordbox or Serato). No audio files, no Spotify ID — you pass track names or catalog IDs.

New here? If you haven't migrated off Spotify's removed endpoints yet, start with Spotify Audio Features Is Dead. Here's What to Use Instead in 2026 for the landscape and the host swap, then the field-by-field threshold guide to re-tune your numbers. This post assumes you can already get a track's key and BPM and want to build set logic on top.

The idea: score the transition, not just the track

Every competing API that survived the Spotify shutdown gives you raw key and BPM and stops there. The interesting part of DJing isn't the value of one track — it's the relationship between two adjacent tracks: are the keys harmonically compatible on the Camelot wheel, are the tempos close (or a clean half/double-time match), and is the energy moving the way you want the room to move?

FreqBlog exposes that relationship directly. GET /transition takes two catalog tracks and returns a 0–100 score with the breakdown:

GET /transition?from_track_id=apple_ad1829eeccb70f9a&to_track_id=1443810719
X-Api-Key: sk_live_...

{
  "from_track": { "track_name": "Can't Stop Lovin' You",    "camelot": "11B", "bpm": 117.8, ... },
  "to_track":   { "track_name": "You Beat Me to the Punch", "camelot": "11B", "bpm": 117.5, ... },
  "score": 99,
  "components": { "harmonic": 100, "tempo": 98, "energy": 100 },
  "detail": {
    "key_relation": "same",
    "from_camelot": "11B", "to_camelot": "11B",
    "from_bpm": 117.77, "to_bpm": 117.48,
    "bpm_delta": -0.29, "bpm_octave_matched": false,
    "from_energy": 0.69, "to_energy": 0.81, "energy_delta": 0.12
  },
  "reason": "11B->11B same key, 118->117 BPM (-0.29), energy +0.12"
}

The score blends three components: harmonic compatibility (Camelot-wheel relationship — same key, relative major/minor, adjacent ±1, energy boost/drop), tempo proximity (octave-aware, so a 70→140 BPM half-time blend counts as a match), and energy smoothness. The reason string is human copy you can drop straight into a UI.

Step 1 — resolve your crate to catalog IDs

The set-builder endpoints work on catalog itunes_track_id values (e.g. apple_ad1829eeccb70f9a). You get those from any /lookup or /search response — so a crate of plain track names becomes a list of IDs with one lookup each:

import requests

API = "https://api.freqblog.com"
HEADERS = {"X-Api-Key": "sk_live_your_key_here"}

def resolve(track, artist):
    """Track name + artist -> catalog itunes_track_id (or None on a miss)."""
    r = requests.get(f"{API}/lookup",
                     params={"track": track, "artist": artist},
                     headers=HEADERS, timeout=30)
    if r.status_code != 200:
        return None                      # 202 = queued for ingest, try again shortly
    return r.json().get("itunes_track_id")

crate = [
    ("Can't Stop Lovin'", "Tom Browne"),
    ("Got To Be Real",    "Cheryl Lynn"),
    ("Ain't Nobody",      "Chaka Khan"),
    ("Square Biz",        "Teena Marie"),
    ("Forget Me Nots",    "Patrice Rushen"),
]
ids = [tid for (t, a) in crate if (tid := resolve(t, a))]

Note: A /lookup on a track that isn't analysed yet returns 202 and queues an on-demand ingest — it'll be ready in 30 s–2 min and resolve on a retry. For a planner, resolve your crate once and cache the IDs.

Step 2 — "what plays next?" with /next-track

Given any seed track, GET /next-track returns the seed's closest sonic neighbours re-ranked by transition score — each with the same score, components, and reason as /transition. This is your live "suggest the next tune" box:

def suggest_next(seed_id, n=5, min_score=85):
    r = requests.get(f"{API}/next-track",
                     params={"seed_track_id": seed_id, "n": n,
                             "min_score": min_score,
                             "exclude_same_artist": "true"},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()["suggestions"]

for s in suggest_next(ids[0], n=5):
    t = s["track"]
    print(f"{s['score']:>3}  {t['track_name']} - {t['artist_name']}  ({s['reason']})")

For our seed — "Can't Stop Lovin'" at 11B / 118 BPM — the top picks come back same-key (11B) and within a beat or two of 118 BPM, scoring 98–99 with reasons like "11B->11B same key, 118->117 BPM (-0.29), energy +0.12". The bpm_drift and max_key_distance query params let you widen or tighten the net.

Step 3 — order the whole crate with /setlist

The payoff endpoint. POST /setlist takes your list of IDs and returns them ordered into an energy arc, keeping every consecutive transition harmonically and tempo-smooth. Pick the arc: peak_time (build to a peak, then ease), warmup, cooldown, or flat.

def build_set(ids, arc="peak_time", start_id=None):
    body = {"track_ids": ids, "arc": arc}
    if start_id:
        body["start_track_id"] = start_id          # optional fixed opener
    r = requests.post(f"{API}/setlist", json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

plan = build_set(ids, arc="peak_time")
print(f"Flow score: {plan['flow_score']}/100   ({plan['count']} tracks, arc={plan['arc']})")
for i, t in enumerate(plan["tracks"]):
    print(f"  {i+1:>2}. {t['track_name']} - {t['artist_name']}")
for step in plan["transitions"]:
    print(f"     {step['from_index']}->{step['to_index']}  {step['score']:>3}  {step['reason']}")

ordered_ids = [t["itunes_track_id"] for t in plan["tracks"]]

You get back the tracks in play order, a per-step transitions list (each with its own score and reason), an overall flow_score (the mean of the step scores — how smooth the whole set is), and an omitted list of any IDs not in the catalog. That's a complete, defensible running order — not a shuffle.

Step 4 — export to Rekordbox in one call

Take the ordered IDs from /setlist and hand them to GET /export/rekordbox to get a Pioneer-format XML you can import into Rekordbox or Serato:

def export_rekordbox(ordered_ids, path="my_set.xml"):
    r = requests.get(f"{API}/export/rekordbox",
                     params={"track_ids": ",".join(ordered_ids)},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    with open(path, "w", encoding="utf-8") as f:
        f.write(r.text)
    print(f"Wrote {path} - import via Rekordbox > File > Import Collection")

export_rekordbox(ordered_ids)

That's the whole planner: resolve → suggest → order → export. Counting the import, the helpers, and the crate, it lands right around 50 lines — and the part that used to be impossible without Spotify's data (or a pile of your own DSP) is now four HTTP calls.

What each call costs

The set-builder endpoints run through the same monthly-quota model as /lookup, and you're only charged on a served 200 — a 404 (track not in catalog) or 422 (bad/missing params) costs nothing.

Endpoint	Quota	Why
`GET /transition`	1 request	A single A→B comparison, same as a `/lookup`.
`GET /next-track`	3 requests	Scores up to ~1,000 candidate neighbours to rank the top N.
`POST /setlist`	5 requests	An N² scoring problem — the premium "order my whole crate" call.

So a typical session — resolve a 12-track crate (12), order it once (/setlist, 5), then export (free) — is well under 20 quota requests. The free tier's 1,000/month covers a lot of set-building before you need a paid plan.

One honest note on scope. /setlist uses a greedy ordering with an energy-arc objective — it's built for clean, playable running orders, not a globally-optimal tour through your crate. For long sets, run it per-section (warmup / peak / cooldown crates) and stitch, or use /next-track interactively while you play. The flow_score tells you how smooth the result is so you can spot a weak link.

Why this works without Spotify

No audio upload. Everything is keyed by track name, ISRC, or catalog ID against a pre-analysed catalog — you never ship a file.
No Spotify ID. The crate is plain names; /lookup resolves them and queues an on-demand analysis for anything not yet in the catalog.
First-class harmonic data. Camelot and Open Key notation are returned directly, so the transition scoring has real harmonic relationships to work with — not just two raw key integers you have to compare yourself.
The set logic is the product. Raw key/BPM is table stakes; the differentiator is scoring the transition and ordering the set. That's what these three endpoints sell.

Try FreqBlog — free tier, no card: https://freqblog.com/

The Spotify /recommendations Replacement

Freqblog — Tue, 14 Jul 2026 13:45:48 +0000

When people talk about the Spotify Web API deprecations, they usually mean audio_features and audio_analysis — the per-track numbers. But the same November 2024 cull also took GET /v1/recommendations and GET /v1/artists/{id}/related-artists, and those two have arguably left the bigger hole. Eighteen months on, "Spotify recommendations endpoint deprecated" is still one of the most-asked questions on Stack Overflow and the developer forum, with no official replacement — for the seed-based recommender that powered a huge number of "discover" features and "fans also like" pages.

This post is a practical walkthrough of building both back, in about 40 lines of Python, against the FreqBlog Music API: GET /recommendations (seed tracks → similar tracks) and GET /related-artists (an artist → nearby artists). No Spotify account, no deprecated endpoint, no audio files — you pass catalog track ids and artist names.

What was removed, exactly. Spotify deprecated /v1/recommendations and /v1/artists/{id}/related-artists for apps created after 27 November 2024, and the broader audio-intelligence set (audio_features, audio_analysis, audio previews) with them. If you also need the raw per-track numbers, start with Spotify Audio Features Is Dead. Here's What to Use Instead in 2026 for the host swap, then come back here for the recommender layer.

Why there's no drop-in clone — and what to build instead

Spotify's recommender was a black box backed by its full collaborative-filtering graph — billions of listening sessions. Nobody outside Spotify has that signal, so any honest replacement is built differently. The approach that actually ships is content-based similarity: describe each track by its audio features (tempo, key, energy, danceability, valence, acousticness…), and find neighbours in that feature space. It doesn't know that two tracks share an audience; it knows they sound alike. For "here's a track, give me more like it" that turns out to be most of what you want — and it has a property the collaborative graph never did: it works on brand-new and long-tail tracks with zero listening history.

FreqBlog runs that similarity index over its own pre-analysed catalogue and exposes it as two Spotify-shaped endpoints. The one twist worth knowing up front: pure audio-feature similarity is genre-blind — an EDM track and a hard-rock track can sit close in feature space if their tempo and energy line up. So the ranking is genre-aware: it uses FreqBlog's own catalogue genre data (around 94% coverage) to lift same-genre matches and push down a coincidentally-close cross-genre track. That's the bit that makes the results feel right rather than merely numerically near.

/recommendations — seed tracks in, similar tracks out

GET /recommendations is the direct stand-in for /v1/recommendations. Give it 1–5 catalog seed tracks; it blends them into a single point in audio-feature space (a centroid) and returns the nearest catalogue tracks, re-ranked by genre affinity. Like Spotify's endpoint, you pass seed tracks — the difference is the id format: FreqBlog itunes_track_id values (e.g. apple_ad1829eeccb70f9a), which you get from /search or any /lookup response, not Spotify URIs.

import requests

API = "https://api.freqblog.com"
HEADERS = {"X-Api-Key": "sk_live_your_key_here"}

def recommend(seed_ids, limit=10, exclude_seed_artists=False):
    r = requests.get(f"{API}/recommendations",
                     params={"seed_tracks": ",".join(seed_ids),
                             "limit": limit,
                             "exclude_seed_artists": str(exclude_seed_artists).lower()},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

# Seed: "Jump" by Van Halen (hard rock). Catalog id from /search or /lookup.
data = recommend(["apple_ad1829eeccb70f9a"], limit=8)

for s in data["seeds"]:
    print(f"seed {s['id']}  found={s['found']}")
for rec in data["tracks"]:
    t = rec["track"]
    print(f"  {rec['score']:.3f}  {t['track_name']} - {t['artist_name']}  [{t.get('genre')}]")

The response echoes your seeds with a found flag (so you can tell which ids resolved), a count, and a tracks list of {track, score} objects. For the Van Halen seed, the picks come back all hard rock — Alice Cooper, Guns N' Roses, Aerosmith, David Lee Roth — scoring around 0.93–0.95. Each track is a full stub: itunes_track_id, track_name, artist_name, album_name, genre, release_date, isrc/mbid when known. Feed any of those ids straight into /lookup for the full audio features.

One thing that trips people up: the list is NOT strictly score-descending. score is the raw audio-feature cosine similarity (0–1); the genre lift affects ordering, not the printed number. So a same-genre track with a slightly lower cosine can — correctly — rank above a cross-genre track with a higher cosine. If you re-sort the list purely by score on the client you'll throw away the genre-aware ranking. Trust the order it comes back in.

Blending multiple seeds

Multiple seeds work exactly like Spotify's: pass up to five and you get recommendations for the blend, not for each one in turn. This is how you build a "based on your recent likes" row — take the last few tracks a user engaged with, blend them, and the centroid lands in the middle of their taste:

recent_likes = [
    "apple_ad1829eeccb70f9a",   # hard rock
    "dz_92720102",              # arena rock (AC/DC)
    "1443810719",               # classic rock
]
data = recommend(recent_likes, limit=20, exclude_seed_artists=True)
print(f"{data['count']} recommendations for the blend")

exclude_seed_artists=true drops anything by the seed artists themselves — the difference between "more of the same artist" and genuine discovery. Leave it off for a "more like this" box; turn it on for a "you might also like" row.

/related-artists — deriving an artist graph without one

GET /related-artists stands in for /v1/artists/{id}/related-artists — the endpoint behind every "fans also like" / "similar artists" panel. Spotify had an explicit artist-relationship graph to read from. FreqBlog has no such graph, so it derives one on the fly: it builds the seed artist's audio-feature centroid from their catalogue tracks, finds the nearest tracks across the catalogue, and aggregates those by artist.

def related(artist, limit=10):
    r = requests.get(f"{API}/related-artists",
                     params={"artist": artist, "limit": limit},
                     headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

data = related("Van Halen", limit=8)
for a in data["related"]:
    print(f"  {a['score']:.2f}  {a['artist_name']}  "
          f"({a['match_count']} matching tracks, sample {a['sample_track_id']})")

For Van Halen this leads with Danger Danger, AC/DC and Def Leppard — the right neighbourhood. Each result carries artist_name, a score, a match_count (how many of that artist's tracks landed in the seed's neighbourhood), and a sample_track_id — a representative catalog id you can hand straight to /lookup or to /next-track.

Two design choices keep the list sensible, and they're worth understanding because they explain results you might otherwise find surprising:

A per-artist cap. An artist's score sums only its top few track similarities, so a prolific catalogue artist with hundreds of near-tracks can't crowd out a tighter, more relevant match. Relevance, not catalogue size, wins.
A genre lift and a cross-genre penalty. Same as /recommendations: a candidate sharing the seed artist's dominant genre gets a lift; a candidate in a clearly different genre gets a penalty, which drops stragglers that are feature-close by coincidence.

Putting it together: a "discover" feed in ~40 lines

The two endpoints compose into the classic discovery surface — recommended tracks plus the artists behind them — with no extra plumbing:

def discover(seed_track_ids, seed_artist):
    recs = recommend(seed_track_ids, limit=10, exclude_seed_artists=True)
    arts = related(seed_artist, limit=6)

    print("Because you like that sound:")
    for rec in recs["tracks"]:
        t = rec["track"]
        print(f"  {t['track_name']} - {t['artist_name']}")

    print("\nFans also like:")
    for a in arts["related"]:
        print(f"  {a['artist_name']}")

discover(["apple_ad1829eeccb70f9a"], "Van Halen")

That's the whole thing. The seed ids come from one /search or /lookup per track name; everything else is two HTTP calls. The part that used to require Spotify's recommendation graph is now a content-based query you own.

What each call costs

Both endpoints run through the same monthly-quota model as /lookup, and you're only charged on a served 200 — a 404 (no seed in the catalog) or 422 (no/invalid seed supplied) costs nothing.

Endpoint	Quota	Why
`GET /recommendations`	2 requests	Blends up to 5 seeds into a centroid and scores the catalogue, then genre-re-ranks the pool.
`GET /related-artists`	2 requests	Builds the seed artist's centroid, scores the catalogue, and aggregates by artist with the per-artist cap + genre lift.

So a discover feed — one /recommendations (2) plus one /related-artists (2) — is 4 quota units a render. The free tier's 1,000 requests/month is plenty to prototype with before you need a paid plan.

How it differs from Spotify's endpoint — honestly

Content-based, not collaborative. It finds tracks that sound similar, not tracks that share an audience. For "more like this" that's usually what you want, and it works on brand-new tracks with no listening history — where a collaborative recommender returns nothing.
Genre-aware ranking. Raw audio-feature similarity is genre-blind; FreqBlog re-ranks with its own ~94%-coverage catalogue genre so a feature-close cross-genre track doesn't outrank same-genre picks. This is FreqBlog's own open data — not ListenBrainz or any external dependency, so there's no extra latency or third-party rate limit in the path.
No Spotify ID, no Spotify account. Seeds are catalog ids resolved from track names; the artist graph is derived from the catalogue. Nothing in the chain touches a deprecated Spotify endpoint.
Coverage, not magic. Similarity is computed over FreqBlog's pre-analysed catalogue, so a seed track has to be in it (or get pulled in via on-demand backfill on a prior /lookup). A seed that isn't analysed yet comes back in the seeds echo with found=false; resolve and cache your seeds once, the same way you would seed ids for any catalog API.

Try FreqBlog — free tier, no card: https://freqblog.com/

Why Music Metadata Matching Is Harder Than It Looks

Freqblog — Tue, 14 Jul 2026 13:15:57 +0000

Someone searched our API for YIPPEE-KI-YAY. (The Hosed Down Remix) — a Kesha remix from 2025. We returned nothing. Not "rate limited," not "service down" — just not found.

Here is the uncomfortable part. That track is on Apple Music. It is on Deezer. It is on Spotify. It is in MusicBrainz. Every major music database has it, and our pipeline pulls from those same sources. The track was never missing. Our matching layer — the code that decides "this record and that record are the same song" — couldn't see it.

This is the autopsy: three separate, completely mundane reasons a track that demonstrably exists failed to match, and how we fixed each. If you build anything that reconciles music metadata across sources, you will hit all three.

Matching is the actual hard part

A music API is a stitching job. No single source has everything: iTunes has preview clips, Deezer has wide coverage, MusicBrainz has identifiers and relationships, AcousticBrainz has audio features. You query several sources and you merge the results.

"Merge" hides the hard part. To merge, you first have to decide that Deezer's record and MusicBrainz's record describe the same recording. That decision is "matching," and it sounds like string equality. It is not.

The enemy is simple to state: the same song is written slightly differently in every database. Not wildly — slightly. And "slightly different" is exactly the gap a naive matcher falls straight through.

Failure mode 1 — Punctuation drift

The query was YIPPEE-KI-YAY (The Hosed Down Remix). Deezer's stored title is YIPPEE-KI-YAY. (The Hosed Down Remix). Spot the difference? There is a period after YIPPEE-KI-YAY — Kesha's 2025 album stylises the song with a trailing dot. An exact string compare fails. A substring compare fails too: yay ( is not a substring of yay. (.

It gets better. MusicBrainz stores the same title with typographic hyphens — Unicode U+2010 — where you typed the ASCII hyphen-minus, U+002D. They render identically in almost every font. They are different bytes. Every byte-level comparison between them fails, silently, forever.

Now add lowercase versus title-case ("remix" versus "Remix"), straight versus curly apostrophes, & versus "and", stray brackets, and the iTunes habit of writing Song - X Remix where Deezer writes Song (X Remix). Two records can describe the identical recording and disagree on a dozen characters.

The fix is a normalisation fold: before you compare anything, collapse every string to a canonical form. Lowercase it. NFKD-decompose so accented characters fold to their base (Beyoncé becomes beyonce). Replace every punctuation and dash variant — ASCII hyphen, typographic hyphen, en dash, em dash, the lot — with a space. Collapse runs of whitespace. Then compare.

import unicodedata

# every dash variant folds to one space; punctuation folds away
_DASHES = "-‐‑–—"   # ascii, U+2010, U+2011, en, em
_DROP   = str.maketrans({c: " " for c in _DASHES + ".,!?'()[]&"})

def fold(s):
    s = unicodedata.normalize("NFKD", s)            # accents -> base chars
    s = "".join(c for c in s if not unicodedata.combining(c))
    return " ".join(s.lower().translate(_DROP).split())

Run both titles through fold() and they collapse to the same eight words: yippee ki yay the hosed down remix. A match that was impossible at the byte level is trivial after the fold.

The lesson: never compare provider strings raw. Fold first. Punctuation in a music title carries almost no information and offers infinite room for disagreement.

Failure mode 2 — Your main source's search has blind spots

Our primary resolver is iTunes. It is an enormous, well-curated catalog. So when iTunes search returned zero results for the Hosed Down Remix, the obvious conclusion was "iTunes doesn't have it."

Wrong. iTunes has it. We pulled the track by direct ID lookup — that returns it instantly, with a preview clip, no problem. But the iTunes Search API returned nothing. Searching the song's plain title surfaced fourteen results; the remix was not one of them.

The iTunes Search API is not a window onto the whole iTunes catalog. It is a partial, recency- and popularity-weighted index. New releases, remixes, deluxe-edition cuts and long-tail tracks can be fully present in the store — buyable, previewable, reachable by ID — and simply absent from text-search results. Every catalog API has a version of this. A search surface is never the whole catalog.

Two lessons. First: "search returned nothing" is not "the track does not exist" — it is "this index did not surface it." Don't let one source's blind spot become your final answer. Second: have a fallback source — we use Deezer — and understand that the fallback is now load-bearing. Which means the fallback's matcher had better be solid. Ours wasn't.

Failure mode 3 — "Take the first result" is not a matcher

Here is the cheap way to resolve a track against MusicBrainz: search by title and artist, ask for one result, take recordings[0]. It is one line. It feels fine. We shipped it, and it was wrong in two distinct ways.

It picks silently wrong. recordings[0] trusts MusicBrainz's relevance ranking to put the right recording first. Often it does. When it doesn't — when a live album version, a compilation re-edit or a karaoke cover ranks first — you take that, with full confidence, and never know. An audit we ran put the wrong-recording rate of naive first-result matching at roughly one in seven. One match in seven pointed at a different recording than the one the customer asked about.

And a wrong match is worse than no match. This is the part that matters. If matching returns nothing, you see a null — and a null is honest: "we don't have this." If matching returns the wrong recording, every field you derive from it is now wrong: the release date, the ISRC, the genre, the audio features keyed off that identifier. And it all looks completely plausible. A wrong match does not fail loudly. It quietly poisons the record and everything downstream of it.

The fix is to stop taking the first result and start scoring. Pull a list of candidates — twenty-five, not one. Score each against the query on multiple independent signals:

Title, folded (see failure mode 1).
Artist, folded.
Duration. This is the signal that catches the wrong-cut problem. A studio single and its six-minute live version share a title and an artist; they do not share a length. If a candidate's duration is wildly off the one you expected, it is a different recording — score it down, hard.

def score(candidate, query, expected_ms):
    s = 0
    if   fold(candidate.title)  == fold(query.title):     s += 10
    elif fold(query.title)      in fold(candidate.title): s += 5
    if   fold(candidate.artist) == fold(query.artist):    s += 8
    if candidate.length_ms and expected_ms:
        off = abs(candidate.length_ms - expected_ms)
        s += 6 if off < 5000 else -8   # same cut, or a different one
    return s

Then — and this is the important rule — only accept a confident match. Set a threshold that requires real corroboration: a title match plus either an artist match or a duration match. A bare title match, with nothing else agreeing, is not enough — far too many songs share a title. If nothing clears the bar, return nothing. Decline to guess. A null you can fix on the next pass; a wrong ID you will never even notice.

The stylised-artist wrinkle. This is also why you cannot lean on any single signal. Deezer returns Kesha's name as Ke$ha. MusicBrainz says Kesha. The $ is not punctuation you can fold away — it is a deliberate substitution. So for this track the artist signal is simply unavailable: ke$ha and kesha will not match however you normalise. The match still succeeds — because the title folds clean and the duration agrees to within a second. Two signals out of three is enough. One never is.

The thread: corroboration beats cleverness

Step back and the three fixes are one idea. Punctuation folding, fallback sources, multi-signal scoring — every one of them is a way of saying: never trust a single signal, and never guess.

A music metadata pipeline has an asymmetric cost structure. A missing value is cheap: it is visible, it is honest, and it gets filled on the next pass. A wrong value is expensive: it is invisible, it looks right, and it spreads. Genre filters return the wrong tracks. ISRC lookups resolve to the wrong release. Audio features get attributed to the wrong recording. None of it throws an error.

So the discipline is conservative by design: fold before you compare, corroborate before you commit, and when the signals disagree, return null and move on. "I don't know" is a perfectly good answer from a metadata API. "Here is a confident wrong answer" is not.

This article was originally published on the FreqBlog blog. FreqBlog runs a music-metadata API that resolves tracks across iTunes, Deezer, MusicBrainz and more.

Harmonic mixing over MCP: the DJ set-builder Spotify never shipped

Freqblog — Tue, 14 Jul 2026 13:15:57 +0000

When Spotify deprecated Audio Features, Recommendations, and Related Artists for new apps in November 2024, a wave of "drop-in replacement" APIs appeared. Most stop at parity: you send a track, you get BPM, key and energy back. Useful — but that's the same lookup Spotify already gave you.

FreqBlog went a layer further. It rebuilt the dead endpoints, then shipped the thing Spotify never had: a set-builder. Pairwise transition scoring, next-track ranking, and full setlist ordering around the Camelot wheel. And the whole surface is exposed over an MCP server, so an LLM or agent can plan a DJ set by calling tools directly — no glue code between the model and the music theory.

This is for people building music or AI tooling. I'll show the harmonic-mixing model concretely, then call it two ways: plain REST and MCP.

Parity first: the endpoints Spotify killed

Before the interesting part, the boring-but-necessary drop-ins:

GET /recommendations (and the MCP tool get_recommendations) — the replacement for the removed /v1/recommendations, re-ranked by genre affinity so a feature-close cross-genre track can't outrank same-genre picks.
GET /related-artists — replaces the killed related-artists endpoint.
GET /v1/audio-features/{id} returns a bare Spotify AudioFeaturesObject; GET /v1/audio-features?ids= returns the {"audio_features":[...]} array envelope. Both mirror Spotify's own shapes, so porting existing code is a small diff.

The native lookup is flatter and richer. GET /lookup resolves a track by name, ISRC, MusicBrainz ID or Spotify ID and returns one flat object — over 40 fields, no nesting:

curl -s "https://api.freqblog.com/lookup?track=Strobe&artist=deadmau5&wait=10" \
  -H "X-Api-Key: $FREQBLOG_KEY"

// shape (values illustrative) — every feature is top-level, no "audio_features" wrapper
{
  "track_name": "Strobe",
  "artist_name": "deadmau5",
  "bpm": 128.0,
  "key": "B",
  "camelot": "1A",
  "mode": "minor",
  "energy": 0.61,
  "danceability": 0.72,
  "valence": 0.35,
  "genre": "progressive house"
}

Two things worth knowing: bpm and key are always present and non-null, and ?wait=10 opts into a bounded synchronous mode — up to 25 seconds — that returns the analysed track inline as a 200 instead of the default 202 + Retry-After when a track isn't cached yet.

The differentiator: harmonic mixing you can call

Camelot in 30 seconds

Every musical key maps to a clock position on the Camelot wheel: a number 1–12 plus a letter (A = minor, B = major). Two tracks mix without a key clash when they sit next to each other on the wheel: the same key, the relative major/minor (same number, flipped letter), or the adjacent +1/-1 neighbours. Jump +7 and you get the classic energy-boost mix.

find_compatible_keys is pure theory — no catalog hit, zero quota:

// find_compatible_keys(camelot="8A", extended=true)
{
  "camelot": "8A",
  "compatible": [
    { "camelot": "8A", "relation": "same" },
    { "camelot": "8B", "relation": "relative" },      // minor <-> major
    { "camelot": "7A", "relation": "adjacent_down" }, // -1
    { "camelot": "9A", "relation": "adjacent_up" },   // +1
    { "camelot": "3A", "relation": "energy_boost" },  // +7  (extended=true)
    { "camelot": "1A", "relation": "energy_drop" }    // -7  (extended=true)
  ]
}

Scoring an actual transition

Knowing which keys could mix is table stakes. score_transition rates how well one real track mixes into another, 0–100, blending Camelot key compatibility, octave-aware BPM proximity (half/double-time counts as a match), and energy smoothness — and it hands back a human reason:

// score_transition(from_track_id="apple_ad1829eeccb70f9a",
//                  to_track_id="apple_7c1120fbe0")  — costs 1 quota
{
  "score": 91,
  "components": { "harmonic": 95, "tempo": 92, "energy": 86 },
  "reason": "8A->9A +1 adjacent, 126->128 BPM (+2.0), energy +0.04"
}

There's no raw key/BPM endpoint anywhere that gives you that — the pairwise judgement is the product.

From one pick to a whole set

suggest_next_track takes the track that's playing and returns the top-N catalog tracks to play next, each with the same score, components and reason (e.g. "11B->11B same key, 118->117 BPM (-0.29), energy +0.12"). It's genre-aware by default, so an off-genre track that only coincidentally shares your key/BPM sinks to the bottom.

build_setlist orders an entire crate (2–100 tracks) into a beat-matched set that follows an energy arc — peak_time, warmup, cooldown, or flat — keeping every consecutive transition harmonically and tempo-smooth. It returns an overall flow_score, the tracks in play order, and the per-step transitions.

Letting an agent do it over MCP

Here's where it stops being an API and starts being a capability you hand to a model. Point any MCP client at:

https://mcp.freqblog.com/mcp

That exposes twelve tools — search_catalog, get_audio_features, get_audio_features_batch, find_tracks_by_bpm, find_tracks_by_key, find_compatible_keys, get_recommendations, get_related_artists, score_transition, suggest_next_track, build_setlist, tag_track. The agent orchestrates them itself. A single prompt like "build me a 90-minute peak-time set from these ten tracks" becomes:

search_catalog on each fuzzy name → concrete itunes_track_ids
build_setlist(track_ids=[...], arc="peak_time") → ordered set + flow_score
feed the ordered itunes_track_ids to GET /export/rekordbox (also traktor, m3u, cuesheet, csv) and drop the crate straight into your DJ software

No orchestration code on your side — the tool descriptions carry enough for the model to chain them. The set-builder tools cost a little more quota than a plain lookup (score_transition 1, get_recommendations 2, suggest_next_track 3, build_setlist 5), because each one is doing real combinatorial work.

Auth, REST, and pricing

Auth is an X-Api-Key header (a ?key= query fallback exists for browser and email links). Everything above is also available as plain REST — GET /transition, GET /next-track, POST /setlist, GET /similar?track_id=... — if you'd rather not run an MCP client. It's on RapidAPI too. Pricing starts at £0.17/1k, and the free tier is 1,000 requests/month, which is plenty to prototype a set planner.

Honest gaps

It's catalog-bound. The set-builder tools operate on catalog itunes_track_ids, so a track has to resolve first (search_catalog / /lookup). Coverage is deep but not universal — niche or regional catalogs have holes.
Spotify-ID lookups only hit a mapped subset. If you're keyed on Spotify IDs, expect misses; name or ISRC resolves far more reliably.
Features are computed, not gospel. BPM/key/energy come from audio analysis (Essentia); occasionally a lookup matches the wrong recording of a title.
No audio hosting or streaming. You get features and metadata back, plus an upload-based /analyze and /identify — not the audio itself.
No beatgrid/waveform editing. It plans and orders sets; it doesn't warp cue points for you.

Try it

Grab a free key and the OpenAPI docs at api.freqblog.com/docs, or read more about the API on freqblog.com. If you're building anything that recommends, sequences, or reasons about music — especially with an LLM in the loop — the MCP endpoint is the fastest way to give your agent an ear for what actually mixes.

Migrating from Spotify Audio Features: a Field-by-Field Threshold Guide

Freqblog — Mon, 11 May 2026 22:14:39 +0000

TL;DR: Spotify killed /audio-features on 2024-11-27. FreqBlog Music API offers a drop-in at api.freqblog.com/v1/audio-features/{id} — same path, same response shape. The numbers are ours (signal analysis via librosa + Essentia, not Spotifys ML classifiers), so a few field distributions shift. This is the field-by-field guide to re-tuning, with real distribution data from our ~57,000-track catalog.

This is a syndicated mirror — the canonical version with full formatting is at https://freqblog.com/blog/spotify-audio-features-migration-thresholds/ (where the table renders properly).

The migration shape

You swapped the host from api.spotify.com to api.freqblog.com. Your existing GET /v1/audio-features/{id} handler still parses the response unchanged, the unit tests pass. Then your downstream if features.danceability > 0.7 recommender starts surfacing weird tracks. Your acousticness > 0.5 rule fires on basically everything. Your liveness > 0.8 filter rejects the whole catalog.

The migration is byte-compatible at the shape level. Its directional at the value level. Spotify built their audio features by training ML classifiers on a labelled corpus; we compute ours from signal analysis. Same names, different beasts.

Threshold cheat sheet (catalog medians over ~8k tracks)

bpm / tempo — median 118.7 — drop-in. Plus bpm_alt corrects Spotifys known half-time bug.
key (0–11 / -1) — drop-in. Returned as key_int.
mode (0/1) — drop-in.
energy — median 0.73 — shifted up slightly; bump thresholds ~0.05–0.1.
valence — median 0.48 — closest to Spotifys distribution. Minimal re-tune.
danceability — median 0.74 — shifted up. Old 0.65 ≈ ours 0.80.
acousticness — median 0.98 — do not use as is-acoustic. Discriminates near 0.99.
instrumentalness — median 0.23 — signal-shape proxy, not a vocal classifier.
liveness — median 1.00 (saturated) — currently not diagnostic.
speechiness — median 0.45 — shifted up ~5–10×. Old 0.66 ≈ ours >0.85.
loudness — median -14 dB — 3–6 dB lower than Spotify (30s window vs full-track BS.1770); use relatively, not absolutely.
time_signature — always 4 in practice. Treat as informational, not as a filter.

Why `acousticness` is 0.98 for everything

Our formula is 1 - clip(spectral_flatness / 0.15, 0, 1). Low spectral flatness means the signal has strong tonal/harmonic peaks — which most music has, acoustic or electric. ~99% of our catalog scores >0.9. If your Spotify code said acousticness > 0.7 = acoustic track and triggered on ~20% of your library, the same threshold under FreqBlog will trigger on ~99% of it. The field is not a useless signal — it discriminates between tonal music and noise-floor content (white-noise tracks, pure ambient, recordings with heavy distortion) — but its useful threshold is up around 0.99.

Why `liveness` saturates

Formula: clip(noise_floor_ratio * 6.0, 0, 1) where noise_floor_ratio is the 5th-percentile RMS divided by the 95th-percentile RMS. The intuition is that live recordings have an elevated noise floor. The problem: modern mastered music has heavy dynamic-range compression, which compresses the RMS percentiles together — and the ×6 multiplier saturates at 1.0 almost immediately. Until we ship a better detector, drop the liveness filter.

What we get right

BPM + key/mode/key_int — Essentia is mature DSP; comparable to Spotifys ML for the common cases. Plus bpm_alt is a documented improvement over Spotifys known half-time detection bug (Blinding Lights: Spotify said 85; perceived is 171; we ship 85 in bpm and 171 in bpm_alt).
Camelot + Open Key — first-class fields, ready for harmonic-mixing tooling.
Identifier flexibility — /v1/audio-features/{id} accepts Spotify track IDs, ISRCs (with or without hyphens), spotify:track:… URIs, or open.spotify.com/track/… URLs. Pass whichever your data layer gives you.
Long-tail backfill — if a track isnt in the catalog, our backfill ingests it in 30s–2min and emails you when its ready. Spotifys API never had this.

The full doc (with worked examples + the formula per field) is here:

freqblog.com/blog/spotify-audio-features-migration-thresholds/

Free tier is 1,000 requests/month, no card. Comments / use-case feedback welcome — the caveated fields (acousticness/liveness etc.) are where concrete customer demand drives the next round of improvements.

AcousticBrainz Alternative in 2026: The Honest Insider's Guide

Freqblog — Fri, 08 May 2026 17:29:38 +0000

If you were one of the developers, researchers, or hobbyists who built on AcousticBrainz, you already know the story. The Music Technology Group at Universitat Pompeu Fabra announced the shutdown on 16 February 2022, took the live API offline, and published the entire dataset as a one-time public dump. Four years later, there's still nothing exactly like it.

This post is the honest insider's view of the post-AB landscape — written by a team that uses the frozen AcousticBrainz dump in production right now, as one of four fallback layers in our music-features API. We know what works in the dump, what doesn't, and what the realistic alternatives look like in 2026.

What you actually lost

AcousticBrainz had three things going for it that nothing has fully replaced:

Free, public, scriptable. No API key, no rate limit, no sign-up. GET /api/v1/<mbid>/low-level returned ~120 fields per recording. Researchers could pull millions of rows for a paper without negotiating commercial terms.
MBID-keyed. Every track was identified by its MusicBrainz ID, the open community-maintained identifier. That meant data from AcousticBrainz could be joined cleanly to MusicBrainz, Discogs, ListenBrainz, lyrics databases — the whole open-data ecosystem.
Crowd-contributed. Anyone could run the AcousticBrainz client on their own audio collection and submit features back. The dataset grew from real personal libraries, not a label-licensed catalog.

None of the commercial replacements has all three. Most have none.

The frozen dump — still extremely useful

This is the under-appreciated fact: the entire AcousticBrainz dataset is still freely downloadable. The official dump page hosts both the high-level (mood, genre, instrument-detection) and low-level (BPM, key, MFCCs, ~120 descriptors) tarballs as of June 2022, plus per-month deltas up to the shutdown.

What you get:

~7.5M unique recordings by MBID, with one or more contributed analyses each
~120 low-level descriptors per track — spectral centroid, MFCCs, rhythm features, tonal features, dynamic complexity, all the numbers Essentia's MusicExtractor outputs
11 high-level classifier outputs per track — genre, mood (happy/sad/aggressive/relaxed/party), instrumentalness, danceability, etc.
The AcousticBrainz JSON schema — same one the live API used, so existing client code works against the dump with zero changes if you stand up your own static endpoint

Practical setup: serve the dump as a local API

The dump is a giant tarball of one-JSON-per-MBID. The cleanest pattern is to extract it into SQLite and serve via a thin wrapper:

# Pseudocode for the loader
import json, sqlite3, tarfile

conn = sqlite3.connect("ab_features.db")
conn.execute("""
    CREATE TABLE ab_features (
        mbid TEXT PRIMARY KEY,
        bpm REAL,
        key TEXT,
        scale TEXT,
        danceability REAL,
        average_loudness REAL,
        dynamic_complexity REAL,
        onset_rate REAL,
        tuning_frequency REAL,
        mood_happy REAL,
        mood_sad REAL,
        mood_aggressive REAL,
        mood_relaxed REAL,
        mood_party REAL,
        genre TEXT,
        instrumentalness REAL,
        full_json TEXT
    )
""")

with tarfile.open("acousticbrainz-lowlevel-features-20220623.tar.zst") as tar:
    for member in tar:
        if not member.name.endswith(".json"):
            continue
        data = json.loads(tar.extractfile(member).read())
        mbid = member.name.split("/")[-1].replace(".json", "")
        conn.execute("INSERT OR IGNORE INTO ab_features ...", (mbid, ...))

Expect the resulting SQLite to land around 2.2 GB once you've extracted the columns you actually use. Full-JSON-per-row blows it up to ~50 GB; only do that if you need every descriptor.

The dump is frozen at June 2022. Nothing released after that has values. For 2024-2026 releases, you'll need a live source. Use the dump as the historical layer of a tiered system — check it first, fall back to live analysis on miss.

The MBID problem

The dump is keyed by MBID, but most of your queries will arrive with artist + title strings, not MBIDs. Resolution is a separate problem:

Hit the live MusicBrainz API: GET /ws/2/recording/?query=artist:"<artist>" AND recording:"<title>"
Score the candidates — usually the first hit is right but featured-artist strings ("Mark Ronson featuring Bruno Mars") and remixes/covers cause noise
If you find a match, take the MBID and look it up in your AB dump table

Realistic hit rate from name-only resolution to AB-dump features: ~50%. Half your tracks will resolve cleanly, the other half will be misses for one of: no MBID assigned, MBID exists but track not in AB, featured-artist confusing the resolver, or a release after June 2022.

The live alternatives

Five categories, ranked from "closest to AB's spirit" to "closest in functionality":

1. Build your own with Essentia

AcousticBrainz was Essentia + crowd contributions. The same toolkit is open-source, actively maintained, and runs on a VPS. MusicExtractor takes a 30-second audio clip and returns the same ~120 fields AB stored. Caveat: you need the audio. The dump worked because users contributed local libraries; your replacement needs an audio source — iTunes 30-second previews work but rate-limit hard, full-track licenses cost money.

2. Self-host with the dump as primary, Essentia as fallback

This is what we do at FreqBlog. ab_features.db covers ~50% of inbound name-based queries via the MBID resolution path; for misses we run Essentia on iTunes preview clips and cache the result. The two layers complement each other — the dump catches anything pre-2022 that has an MBID; Essentia catches everything else with a commercial preview. Coverage hits ~85% in practice. The remaining 15% is bootlegs, demos, and obscurities with no preview anywhere.

3. Hosted music-feature APIs

The post-AB market split into two camps:

Spotify-shim APIs — Musicae and similar, designed to feel like the deprecated Spotify audio_features endpoint. Field names match Spotify's vocabulary. Useful if you're a Spotify-deprecation refugee, but they don't expose AB's ~120 low-level descriptors — just the ~11 Spotify-style high-level fields.
Catalog-style APIs — including FreqBlog (full disclosure: ours). Pass artist + title, get back BPM, key, energy, mood-vector, the four AB low-level descriptors we backfilled (onset_rate, dynamic_complexity, tuning_frequency, average_loudness), and standard cross-link IDs. Different ergonomics from AB but covers most practical use cases.

4. Apple Music API

Apple's catalog API exposes tempo, key, timeSignature, and a few mood/genre tags. Free for developer accounts ($99/year to ship). Doesn't expose danceability, energy, valence, or anything below the high-level surface — closer to AB's high-level layer than its low-level descriptors.

5. Re-run the analysis on labelled academic datasets

For research/non-commercial work where licensing matters, the FMA, Million Song Dataset, GTZAN, and similar academic corpora ship with audio that you can run Essentia on yourself. None match AB's coverage but all are legally clean for paper-publishing.

Field-mapping table

For migrating code that previously called the AcousticBrainz live API, here's roughly how the field names translate:

AcousticBrainz field	Frozen dump	FreqBlog	Essentia (DIY)
`rhythm.bpm`	✓	`bpm`	`RhythmExtractor2013.bpm`
`tonal.key_key`	✓	`key`	`KeyExtractor.key`
`tonal.key_scale`	✓	`mode`	`KeyExtractor.scale`
`highlevel.danceability`	✓	`danceability`	SVM model, deprecated
`highlevel.mood_happy`	✓	`mood_vector.happy`	SVM model, deprecated
`lowlevel.average_loudness`	✓	`average_loudness`	`Loudness`
`lowlevel.dynamic_complexity`	✓	`dynamic_complexity`	`DynamicComplexity`
`rhythm.onset_rate`	✓	`onset_rate`	`OnsetRate`
`tonal.tuning_frequency`	✓	`tuning_frequency`	`TuningFrequency`
`highlevel.genre_*` (multiple)	✓	`genre` (single)	SVM models, deprecated
`lowlevel.mfcc.mean[0..12]`	✓	not exposed	`MFCC`
`lowlevel.spectral_*` (~30 fields)	✓	not exposed	various spectral algorithms

The dump is the only option if you need the deep low-level vector (~120 fields). Hosted APIs typically expose the ~10-15 fields that map cleanly to product use cases.

What no replacement gives you back

The crowd contribution loop. AB grew because users ran the client on their personal libraries and submitted back. No commercial replacement has that bottom-up data flow — it's all top-down catalog ingestion.
The high-level mood/genre classifiers. MTG's own shutdown post acknowledged the high-level model quality wasn't reliable enough — that's part of why they killed AB. Essentia's documentation now flags those SVM models as deprecated. Reproducing them locally reproduces a known-broken system. If you need genre/mood at production-grade quality, the modern path is the Essentia Labs MusiCNN models (TensorFlow-based, much better trained), not the deprecated SVMs.
The MBID-keyed open-data ecosystem. AB joined cleanly to MusicBrainz/Discogs/ListenBrainz because everyone shared the MBID identifier. Commercial APIs key on their own internal IDs (or Spotify track IDs, which are now deprecated for new apps). Cross-linking is harder.

How to choose

Academic / research / one-shot dataset analysis → download the dump. It's free, complete through June 2022, and citable.
Building a product that needs MIR data on current releases → tier the dump under a live source (Essentia self-hosted, or a hosted API). Use the dump as the cheap-and-deep layer.
Building a quick app that just needs BPM/key/energy → a hosted catalog API (FreqBlog, Musicae, or Apple Music) is faster to integrate than running Essentia yourself.
Need the deep low-level vector (MFCCs, spectral centroid, etc.) on every track → only the dump or your own Essentia worker will give you those. No hosted API exposes them at retail prices.

Originally published at freqblog.com. If you've got a specific MIR migration question (resolver issues, dataset licensing, etc.), drop it in the comments.

BPM API: Get BPM and Key From a Track Name (No Audio File Required)

Freqblog — Fri, 08 May 2026 17:29:37 +0000

Most "music analysis" APIs want a 30-second audio clip and a multipart upload. That's fine if you're building a DJ app where the user is dragging files in. It's a wall if you're building a fitness app trying to match treadmill cadence to a Spotify playlist, a music recommender that takes a track URL and returns "more like this," or honestly, any app where the user types Blinding Lights and expects the BPM back.

This is the architectural split nobody talks about: upload-based analysis APIs vs catalog-based lookup APIs. They look superficially similar (both return BPM, key, energy, etc.), but the failure modes are completely different and the right one for your app depends on what your user actually has in their hand.

The two architectures, in one paragraph each

Upload-based

You POST audio bytes; the API runs Essentia or librosa on them server-side; you get features back. Examples: AudD, Cyanite, AI Mastering. Hit rate is 100% (any audio works) but the user must have the file. No file means no answer. Pricing is usually per-call and on the higher end (compute-bound).

Catalog-based

You GET with ?track=Blinding+Lights&artist=The+Weeknd; the API looks the track up in a pre-analyzed library and returns the cached features. Hit rate is <100% (only works for tracks already in the catalog) but no audio file required, the response is fast (typically <100 ms), and pricing is usually per-lookup and lower (no per-call compute). When the catalog misses, the better APIs queue an on-demand analysis and email the user when it lands.

Spotify's audio_features endpoint was a catalog-based API: you passed a Spotify track ID, you got the features. It died in November 2024, which is why this post exists at all.

What "name-based lookup" actually does

The pattern, in code:

import requests

r = requests.get(
    "https://api.freqblog.com/lookup",
    params={"track": "Blinding Lights", "artist": "The Weeknd"},
    headers={"X-Api-Key": api_key},
)
data = r.json()
# {
#   "track_name": "Blinding Lights",
#   "artist_name": "The Weeknd",
#   "audio_features": {
#     "bpm": 171.0,
#     "bpm_alt": 85.5,           # half-time variant
#     "key": "C#-Minor",
#     "camelot": "12A",
#     "open_key": "5m",
#     "energy": 0.91,
#     "danceability": 0.85,
#     ...
#   }
# }

What's actually happening behind the request:

Catalog hit — the lookup matches by name and returns within ~10 ms. Most popular tracks are pre-analyzed and live here.
Catalog miss but reachable — the API can't find the track, but it can find the iTunes preview for it. It returns HTTP 202 ("queued"), kicks off a background analysis (download preview → run Essentia → cache result), and emails the user when the data is ready (typically 30 seconds to 2 minutes later). Subsequent calls hit the cache.
Genuinely unfindable — demos, bootlegs, alternate-takes that have no commercial release. The API returns 404 or an empty object. Plan for this in your UX.

The 202 path is the differentiator. Most catalog APIs return 404 on miss and leave you to figure it out. The "queue and email" pattern means a track that's missing today is in the catalog tomorrow — the catalog grows toward the long tail of what your users actually search for, instead of being frozen to whatever was popular when the dataset was built.

What you can ask for by name

The full set of fields a good name-based BPM API should return:

Field	Example	Why it matters
`bpm`	`171.0`	Tempo for sync/cadence/sorting
`bpm_alt`	`85.5`	Half-time variant when the detector reports the wrong octave
`key`	`"C#-Minor"`	Musical key (12 pitches × major/minor)
`camelot`	`"12A"`	DJ-friendly key notation for harmonic mixing
`open_key`	`"5m"`	Alternative DJ notation
`energy`	`0.91`	0-1 normalised intensity
`danceability`	`0.85`	0-1 rhythmic groove score
`valence`	`0.50`	0-1 musical positivity
`loudness`	`-5.2`	dB FS reference
`time_signature`	`4`	Beats per bar
`genre`	`"pop"`	Coarse Last.fm-style tag
`isrc` + `mbid`	`"USUM72003867"`	Cross-link IDs to other catalogs

The hit rate is the metric that matters

The single most important question to ask any catalog-based API: what fraction of the tracks my users will search for are actually in your catalog? Vendors will quote you a top-line track count ("10M tracks!") which is meaningless unless you know the distribution.

Three honest signals to look for:

Charts coverage — if the catalog has the current Apple Music / Spotify global top-200, you'll hit on most pop tracks people search for.
Decade depth — if 80% of the catalog is 2020+, anything pre-2010 will miss. Music apps that surface throwback tracks need 60s/70s/80s coverage too.
On-demand backfill — "we'll fetch and analyze if it's missing" turns a hard miss into a slow hit. Bigger long-term win than headline catalog size.

When the catalog misses, what do you do?

Three patterns work:

Pattern 1: Queue + notify

The 202-pattern. Show "Analyzing… we'll email you" in your UX. Comes back via webhook or the user re-querying. Best when users care about that specific track and will wait.

r = requests.get("https://api.freqblog.com/lookup",
                 params={"track": track, "artist": artist},
                 headers={"X-Api-Key": api_key})
if r.status_code == 202:
    # Queued. Show a "checking..." UI. Re-poll in 30s, or wire a webhook.
    return {"status": "queued"}
elif r.status_code == 200:
    return r.json()
else:
    return {"status": "unavailable"}

Pattern 2: Bulk pre-warm

If you know the user's library upfront (e.g. they uploaded a CSV of their playlist), POST the whole list to /bulk. The API returns immediately with a mix of hits + queued items, and the queued ones land via email/webhook over the next few minutes.

Pattern 3: Graceful degradation

If your UX doesn't need every field, the API returns what it has and nulls the rest. Render BPM and key when present; hide the energy/valence chips when null. Users don't know what they're missing if you don't show empty boxes.

BPM accuracy: a footnote that matters

BPM detectors get confused on roughly 20% of dance tracks. The Weeknd's Blinding Lights is the textbook example: the actual tempo is 171 BPM, but Spotify (and most DSP-based detectors) returns ~85.5 because the algorithm latches onto the half-time pulse. The fix: expose both the detected BPM and the half/double-time alternate, and let your app decide which to display based on the genre context.

Any BPM API you evaluate should either fix the half-time issue automatically or expose enough context (the alternate value, a confidence score, or both) for you to fix it client-side. Spotify's old audio_features didn't, which created a long tail of "this app says my song is 85 BPM" UX problems.

What no name-based API will give you

Per-bar/per-beat timing. Catalog APIs return whole-track features. If you need beat-level timing for visuals or sync, you need an upload-based API or you'll have to run a beat tracker on the audio yourself.
Tracks below a popularity floor. Bootlegs, demos, edit-only releases, and most non-commercial music isn't in any catalog. If your app routes around obscure music, you'll need either upload-based fallback or to live with the gap.
Real-time analysis of this microphone input. That's a DSP problem, not an API one. Use librosa or Essentia client-side.

How to choose

Users have audio files in hand? Upload-based API. Pay per call, accept the higher latency, get 100% coverage.
Users type a track name or paste a URL? Catalog-based. Fast, cheap, plan for ~80-95% hit rate plus a graceful "queued" path for the misses.
Both, sometimes? Most apps end up here. Use a catalog API as the fast path and an upload API (or your own Essentia worker) as the fallback for misses + obscure content.

Originally published at freqblog.com. The FreqBlog Music API has a free tier — no card required.

Got a specific catalog-vs-upload architecture question for your app? Drop it in the comments.

Spotify's audio_features API died in 2024. Here's what to use in 2026.

Freqblog — Sat, 11 Apr 2026 18:06:40 +0000

If you maintain anything that ever called GET /v1/audio-features/{id}, you already know how this story starts. On November 27, 2024, Spotify quietly killed audio_features, audio_analysis, recommendations, related artists, and featured playlists in a single developer-blog post. New apps got 403 the same day. Twenty months later there's still no official replacement, and the February 2026 changes made the rest of the Web API harder to use, not easier.

This post is the honest version of "what now?" — the real options, where they fall short, and a Python migration example.

What actually died

Endpoint	What it gave you	Status (July 2026)
`/audio-features/{id}`	BPM, key, mode, danceability, energy, valence, acousticness, instrumentalness, liveness, loudness, speechiness, time_signature	`403` for new apps
`/audio-analysis/{id}`	Per-bar / per-beat / per-segment timing	`403` for new apps
`/recommendations`	Genre-seed and feature-seed recommendations	`403` for new apps
`/artists/{id}/related-artists`	Up to 20 related artists	`403` for new apps
`/browse/featured-playlists`	Editorial curation lists	`403` for new apps
`/me/top/{tracks\	artists}`	User listening history

Apps that already had a quota extension in flight on Nov 27 2024 are still live. Everyone else gets 403. There's no waitlist, no path forward, and no public statement that this will change.

Why Spotify isn't bringing it back

The audio_features endpoint was a thin wrapper around analysis Spotify acquired when they bought The Echo Nest in 2014, plus features derived from the AcousticBrainz dataset (which itself shut down in 2022 for similar "we don't want to host this anymore" reasons). Returning eleven floats per track in a 100M-track catalog costs Spotify infrastructure for zero strategic value.

The recommendations endpoint was worse for them — letting any third-party build a Spotify-quality recommender by spamming seed_genres=house&target_energy=0.8 undermined the whole "premium algorithm" pitch.

Stop asking "will Spotify bring this back?" The right question is "what's the smallest dependency I can rebuild this on so I'm never one PR-merge away from being broken again?"

The realistic options

Five categories, ranked by how quickly you can ship the migration:

1. Apple Music API

Apple exposes tempo, key, timeSignature, contentRating, plus mood/genre tags. Free for dev accounts, $99/year to ship. Missing: danceability, energy, valence, acousticness, instrumentalness, liveness — six of the eleven Spotify fields gone. Best if you only need BPM + key from a major catalog and don't mind paying Apple.

2. Build your own with Essentia

Essentia is the open-source MIR toolkit Spotify itself used to derive most of the deprecated values. MusicExtractor takes a 30-second audio clip and returns BPM, key, danceability, average loudness, dynamic complexity, tuning frequency, onset rate. Compute cost only — but you need the audio. Spotify never let you download it; iTunes 30-second previews work but rate-limit hard (~25 RPM). Plan for a multi-week backfill on any catalog over 10k tracks.

3. AcousticBrainz public dump (free, frozen)

The MusicBrainz folks did exactly what Spotify won't: published the entire AcousticBrainz dataset (7.5M tracks, 11 high-level features and ~120 low-level descriptors per track) as a one-time public dump in July 2022 before shutting the live service down. Catch: frozen in time — nothing released after July 2022 has values. Coverage on tracks with a MusicBrainz ID is ~60% of recent commercial releases; without an MBID, nothing. Useful as a baseline layer.

4. Musicae API

Built specifically as a Spotify shim — same field names, same value ranges, similar ergonomics. The closest drop-in if minimising migration diff matters more than anything else.

5. FreqBlog Music API (full disclosure: ours)

Different design choice: a catalog first, not a wrap-an-id service. Pass a track-name + artist string (or an ISRC, MusicBrainz ID, or Spotify ID) to GET /lookup and get back a single flat object — BPM, key (name + Camelot + Open Key), energy, loudness, danceability, valence, mood, time signature, ISRC, MBID, genre, and 40-odd fields in total. From £0.17 per 1,000 requests; the free tier is 1,000 requests/month with no card. Missing tracks are backfilled via a queue — a miss on a name lookup returns 202 Accepted and the next call has the data, or you can pass ?wait=N (0–25 s) to block for the analysed result inline (HTTP 200) on the first call.

Two things it has that Spotify never did:

A set-builder layer, which steps into the gap left by the killed /recommendations: /recommendations (seed with tracks you already like) and /similar for nearest-neighbour discovery, plus /transition (score how well one track mixes into another), /next-track (ranked next picks for a seed) and /setlist (order a whole crate into a beat-matched, harmonic energy arc).
A remote MCP server at mcp.freqblog.com/mcp, so an LLM or agent can query the catalog directly — search, audio-features, BPM/key search, harmonic-key matching, recommendations and the set-builder tools — without you writing HTTP glue. There's also a RapidAPI listing if you'd rather consume it through that gateway.

It still won't give you per-segment analysis, and the Essentia-derived acoustic-model fields (speechiness, instrumentalness, liveness, acousticness) are approximations, not Spotify's proprietary numbers.

Migration walkthrough: Spotify → FreqBlog

Most apps that depended on audio_features were doing one of two things:

Look up known tracks — user pastes a Spotify URL, app shows BPM/key/energy
Filter by feature ranges — "give me upbeat tracks above 120 BPM in a major key"

Pattern 1: Single-track lookup

Before:

import requests

def get_features(spotify_id, token):
    r = requests.get(
        f"https://api.spotify.com/v1/audio-features/{spotify_id}",
        headers={"Authorization": f"Bearer {token}"},
    )
    r.raise_for_status()
    return r.json()

# >>> get_features("0VjIjW4GlUZAMYd2vXMi3b", token)
# {"danceability": 0.514, "energy": 0.730, "key": 1, "tempo": 171.005, ...}

After:

import requests

def get_features(track_name, artist, api_key):
    r = requests.get(
        "https://api.freqblog.com/lookup",
        params={"track": track_name, "artist": artist},
        headers={"X-Api-Key": api_key},
    )
    r.raise_for_status()
    return r.json()

# >>> get_features("Blinding Lights", "The Weeknd", api_key)
# {"track_name": "Blinding Lights", "artist_name": "The Weeknd",
#  "bpm": 171.0, "key": "C#-Minor", "camelot": "12A",
#  "energy": 0.91, "danceability": 0.85, ...}

The shape of the request changes — name+artist instead of a Spotify ID, because we're a catalog not a Spotify-wrapper. The response is a flat object like Spotify's old one (no audio_features wrapper), so the only real work is renaming a few fields: bpm not tempo, and key is a string like "C#-Minor" rather than a pitch-class integer. A 5-line adapter maps them across.

Field mapping

For the 11 Spotify fields, here's how they map to the replacement landscape:

Spotify field	Apple Music	Essentia (build-your-own)	FreqBlog
`tempo`	`tempo`	`bpm`	`bpm`
`key`	`key`	`key.key`	`key` + `camelot` + `open_key`
`mode`	— (in `key`)	`key.scale`	`mode`
`time_signature`	`timeSignature`	—	`time_signature`
`danceability`	—	`danceability`	`danceability`
`energy`	—	derived from RMS	`energy`
`valence`	—	via SVM model	`valence` (where available)
`loudness`	—	`average_loudness`	`loudness_db`
`acousticness`	—	via SVM model	`acousticness` (approx)
`instrumentalness`	—	via SVM model	`instrumentalness` (approx)
`liveness`	—	via SVM model	`liveness` (approx)
`speechiness`	—	via SVM model	`speechiness` (approx)

Spotify's exact speechiness and instrumentalness numbers only live in its frozen-in-time proprietary models — the open-source approximations (Essentia's SVM models, which FreqBlog runs) won't reproduce them. Be honest with users about which you actually need vs which were nice-to-haves.

Pattern 2: Recommendations and discovery

Spotify's /recommendations — the seed_genres=house&target_energy=0.8&min_tempo=120 dance — is gone too. There's no exact drop-in, because that endpoint let you filter a 100M-track catalog by target features. FreqBlog works from a seed track instead:

# Spotify (deprecated)
GET /v1/recommendations?seed_genres=house&target_energy=0.8&min_tempo=120

# FreqBlog: seed with tracks you already like
GET /recommendations?track=Music%20Sounds%20Better%20With%20You&artist=Stardust&limit=20

# ...or find the nearest neighbours to one track by cosine similarity
GET /similar?track_id=<itunes_track_id>&limit=10

/similar takes a catalog track id (track_id, not a Spotify id) and returns the acoustically nearest neighbours over an 18-feature embedding — no seed-genre tuning. If you'd rather discover by tempo or key first, /bpm?bpm=128 and /key query the catalog directly.

Set-builders go a step past a flat recommendation list: /transition scores how well two tracks mix, /next-track ranks the best follow-on for a seed, and /setlist orders a whole crate into a beat-matched energy arc — the harmonic-mixing layer Spotify never shipped.

What no replacement gives you

Be realistic about the gaps. None of the alternatives — including ours — replicate Spotify's old offering one-for-one:

Per-segment analysis with timestamps. Replicating /audio-analysis requires you to run a beat-tracker on the audio yourself. librosa.beat.beat_track or Essentia's RhythmExtractor2013 get you most of the way.
Speechiness, instrumentalness, liveness. Spotify trained these on internal labelled data nobody else has. Open-source Essentia models exist but Essentia's own docs flag them as deprecated due to data-quality concerns — reproducing them locally reproduces a known-noisy system. Where a replacement (FreqBlog included) returns these fields, treat them as approximations.
Coverage of obscure tracks. Spotify had every track in their catalog. Every alternative has a coverage gap on long-tail releases. Plan for a "no data yet, queue for analysis" path in your UX.

How to choose

Already on Apple Music? Use their API, accept the field reduction.
Need a 1:1 Spotify shim? Musicae is closest by design.
Have audio files already? Build with Essentia, pay only compute.
Need a queryable catalog by name+artist — BPM, key, Camelot, similarity, harmonic-mixing set-builders, even a remote MCP server your agent can call? Try FreqBlog — free tier, no card.
Building research/non-commercial work? AcousticBrainz dump is free and large enough.

Originally published at freqblog.com. If you found this useful, the FreqBlog Music API has a free tier — no card required.

Got questions about a specific migration scenario? Drop them in the comments and I'll do my best.

DEV Community: Freqblog

Auto-Tag Your Music Library — With Confidence Scores

Why honesty is the feature

The call — one track, in

The four confidence levels — what each one means

Tagging a whole library

What you can and can't tag — the honest coverage

How it compares to enterprise auto-tagging — honestly

Further reading

Mixed In Key vs Rekordbox vs Serato: Why DJ Platforms Disagree on Key 60% of the Time

The numbers

Why three pro tools produce three different answers

1. Different algorithms

2. The relative-key flip

3. Different definitions of "in key"

4. Tuning frequency drift

What to do about it

If you're a DJ

If you're building an app

Confidence scores beat opinions

Camelot is robust to all of this

Further reading

Half-Time vs Double-Time BPM Detection: How We Fixed Spotify's Known Accuracy Gap

What "BPM" actually means

Why algorithms get it wrong

Detecting the wrong level

The correction heuristic

Why not just multiply by 2 for everything in 70-95?

Production deployment notes

Don't overwrite cached results

Make it derivable, not stored

Surface confidence

What about machine-learned alternatives?

Further reading

Camelot Wheel for Developers: Harmonic Mixing Without the Music Theory PhD

What the wheel does

The four rules

Rule 1: Same key (perfect mix)

Rule 2: Relative key (mood swap)

Rule 3: Adjacent (energy lift / drop)

Rule 4 (advanced): Energy boost / drop

The 50-line implementation

Distance: how do you score a transition?

Building a harmonic playlist

BPM continuity matters too

Open Key vs Camelot

Edge cases

Further reading

Build a Harmonic DJ Set Planner in 50 Lines

The idea: score the transition, not just the track

Step 1 — resolve your crate to catalog IDs

Step 2 — "what plays next?" with /next-track

Step 3 — order the whole crate with /setlist

Step 4 — export to Rekordbox in one call

What each call costs

Why this works without Spotify

Further reading

The Spotify /recommendations Replacement

Why there's no drop-in clone — and what to build instead

/recommendations — seed tracks in, similar tracks out

Blending multiple seeds

/related-artists — deriving an artist graph without one

Putting it together: a "discover" feed in ~40 lines

What each call costs

How it differs from Spotify's endpoint — honestly

Further reading

Why Music Metadata Matching Is Harder Than It Looks

Matching is the actual hard part

Failure mode 1 — Punctuation drift

Failure mode 2 — Your main source's search has blind spots

Failure mode 3 — "Take the first result" is not a matcher

The thread: corroboration beats cleverness

Harmonic mixing over MCP: the DJ set-builder Spotify never shipped

Parity first: the endpoints Spotify killed

The differentiator: harmonic mixing you can call

Camelot in 30 seconds

Scoring an actual transition

From one pick to a whole set

Letting an agent do it over MCP

Auth, REST, and pricing

Why `acousticness` is 0.98 for everything

Why `liveness` saturates