FreqBlog Music Metadata

Order a crate of 2-100 catalog tracks into a beat-matched DJ set that follows an energy arc, keeping each consecutive transition harmonically and tempo-smooth. `arc` is one of peak_time (default — builds to a peak then eases), warmup, cooldown, or flat. Returns the `arc`, `count`, an overall `flow_score` (0-100), the `tracks` in play order, the per-step `transitions` ({from_index, to_index, score, reason}), and `omitted` (ids not found in the catalog, or with no audio features on file yet). Feed tracks[].itunes_track_id into a Rekordbox/Serato export to drop the set straight into your DJ software. track_ids are catalog itunes_track_ids. Costs 5 quota units.

Find catalog tracks by criteria, with no seed track: tempo, key, genre, release year, chart placement and audio-feature ranges in one call — e.g. house at 122-126 BPM in 8A or its neighbours with energy above 0.7: min={"tempo": 122, "energy": 0.7}, max={"tempo": 126}, key="8A", harmonic=true, genre="house". At least one narrowing filter is required (a tempo/feature bound, key, mode, genre, year or chart). Returns `results` (one per recording, each with its bpm, camelot, energy, danceability, valence, acousticness and loudness_db plus catalog metadata), `total_matches` (exact up to 1,000; `total_matches_capped` above that), `next_offset` for the next page, and `filters` — what was applied and how many tracks each filter removed (`dropped_by`); if the list is short, loosen the largest one. energy, danceability and valence are on FreqBlog's own scales, so derive thresholds from values you have seen rather than from another service's. Results reach a depth of 500 per query; narrow the filters to go further. Pass a result's itunes_track_id to get_audio_features for every field, or to suggest_next_track / build_setlist. Costs 1 quota unit.

Given a Camelot key (e.g. "8A", "12B"), return the harmonically compatible keys for DJ mixing — the same key, the relative major/minor, and the adjacent +/-1 keys on the Camelot wheel. With `extended=true` also returns the +7/-7 energy-boost / energy-drop keys. Pure music theory — no catalog lookup and no quota cost. Pair with find_tracks_by_key to then pull actual tracks in each compatible key.

Tracks that SOUND like one seed track or a set of up to 10, optionally restricted by tempo, key, genre, year, chart or audio-feature ranges — e.g. "like these three, but 120-128 BPM in 8A or its neighbours": seed_tracks=[...], min={"tempo": 120}, max={"tempo": 128}, key="8A", harmonic=true. Ranked mainly on a PANNs audio embedding (how the recording sounds) blended with an audio-feature similarity. Results are one per recording, with `score`, `genre_relation` to the seed and, with several seeds, `matched_seed`. With filters, results are the closest-sounding tracks that pass every filter, and `filters` reports what was applied and how many catalog tracks each one removed (`dropped_by`) — loosen the largest if the list is short. Use get_recommendations instead when you want preferred target values (target energy etc.) rather than hard filters. Costs 1 quota unit. PANNs (Kong et al., 2020) is used under CC BY 4.0.

Find catalog tracks near a target tempo. Returns tracks whose BPM is within +/-`tolerance` of `bpm`, ordered by closeness then by an internal catalogue ordering key (not an audience metric) — useful for DJ set planning, workout playlists, or tempo-matching. Each returned track carries full audio features. To also constrain by musical key, combine with find_tracks_by_key.

Find catalog tracks in a given musical key — for harmonic mixing and key-locked playlists. `key` accepts Camelot ("8A"), Open Key ("1m"), or a key name ("A-Minor", "F#-Major"). Returns tracks ordered by an internal catalogue ordering key (not an audience metric), each with full audio features. To discover which keys mix well with a given key first, use find_compatible_keys.

Get audio features for ONE track — BPM, musical key (name + Camelot + Open Key), energy, danceability, valence, acousticness, loudness, mood, mood_vector, genre, time signature, duration and more. `preview_loudness.integrated_lufs` is the BS.1770 integrated loudness (LUFS) of the 30-second preview — often the chorus, so typically a little louder than the full track. Fields follow the layout of Spotify's retired /audio-features endpoint. Provide AT LEAST ONE identifier — if you know several, send them all rather than choosing; they resolve by precedence (`track` > `isrc` > `mbid` > `spotify_id`) and the rest are ignored: - `track` (optionally with `artist`) — e.g. track="Blinding Lights", artist="The Weeknd". - `isrc` — e.g. "USUM71900001". - `mbid` — a MusicBrainz recording UUID. - `spotify_id` — a Spotify track ID, URI, or URL (resolved per request by reading the track's title from Spotify's public embed page and matching it against our catalogue — no Spotify IDs are stored; ambiguous titles miss rather than guess — prefer `track`/`isrc` for full coverage). Returns a JSON object of features. Some feature fields may be null for tracks resolved via the fallback catalogs (only audio-derived values are present for fully analysed tracks). VALUES are FreqBlog's own analysis, NOT on Spotify's scale: energy and valence are models of how energetic / positive the preview sounds, both on our own scales (derive thresholds from our values, don't copy Spotify-tuned ones); danceability and acousticness are on AcousticBrainz's scale -- its classifier where available, else a model that listens to the preview, built on PANNs embeddings (Kong et al. 2020, CC BY 4.0); instrumentalness is a vocal-detection model's score for the 30-second preview (not the whole track); speechiness and liveness are currently null for catalogue tracks; time_signature is ASSUMED 4 (4/4) on every track, not measured. KEY: treat `key` as a best guess when `key_confidence` < 0.8 (measured against musicians' annotations: at >= 0.9 it is exact 77% / Camelot-compatible 88%). If a track name is not yet in the catalog, the API holds the request during the on-demand ingest and usually returns the fully analysed track inline in this same call; only if the ingest runs long does it fall back to a queued response you can re-poll shortly (~15s). If the track turns out not to be on any streaming source we can analyse, you get a definitive not-found instead — that verdict is terminal for ~7 days, so don't retry it. If you only have a fuzzy or partial name, call search_catalog first to find the exact track.

Get audio features for MANY tracks in one call (up to 50 processed) — ideal for analysing a whole playlist at once. Identify each item by name (`track`/`artist`), by `isrc` (matched exactly first — best for CJK / K-pop / niche tracks whose fuzzy name-match misses), or both (ISRC first, name as the fallback). One bad entry never fails the batch. Items beyond the 50-per-call cap come back with `found: false` and `backfill_status: "over_limit"`; an item missing BOTH `track` and `isrc` comes back `"invalid_no_query"`. Neither is processed or charged — the response's `skipped` field counts them, so split a long list into calls of <=50 and resubmit any skipped rows. Returns counts (`found` / `not_found` / `skipped`) plus a per-track `results` array, where each entry's `result` is the same feature object as get_audio_features (or null when not found), and `isrc` is echoed back. An item is billed only when it returns features or queues an on-demand ingest; an ISRC/name with no match anywhere is free. A track you queue and then collect costs ONE unit, not two — the call that collects it is free. For a `found: false` item, `backfill_status` `queued` / `processing` / `deferred` means retry later; `unavailable` is terminal (carries `terminal`, `reason`, `retry_after_days` — treat it as a miss until then); null means no match anywhere. For a single track, use get_audio_features.

Recommended tracks for one or more seed tracks, in the shape of Spotify's retired GET /v1/recommendations. Takes up to 5 catalog seed tracks and returns catalogue tracks that sound like the set as a whole — ranked on the same similarity as find_similar_tracks (mainly a PANNs audio embedding, blended with audio features), RE-RANKED by genre affinity (so a close-sounding cross-genre track doesn't outrank same-genre picks). Returns `seeds` (each {id, found}), `count`, and `tracks` (each {track, score, genre_relation}; each track carries its `genre`). `genre_relation` is "same", "compatible" (different but mixable family), "cross" (unrelated), or "unknown" (either side has no mapped genre), measured against the PRIMARY seed — the first of your seed_tracks we could actually use, so reordering seed_tracks changes it and a skipped seed never becomes the reference. With a SINGLE seed the field is the ranking's own verdict, so it explains the order (same as suggest_next_track). With SEVERAL seeds the ranking considers ALL of them while the label stays relative to your primary seed, so a "cross" label on a multi-seed call does NOT mean the track was pushed down — it may share a family with another of your seeds. `score` is the similarity to the seed set (the same blended similarity find_similar_tracks returns); genre affinity and target_ preferences influence the ORDER, not the score, so the list is NOT strictly score-descending. Use cross_genre=strict to return same-genre-family tracks ONLY (off-genre dropped server-side), or allow to disable the genre ranking. seed_tracks are catalog itunes_track_ids from search_catalog or the itunes_track_id field of a get_audio_features result. NO id? Pass `track` (+ optional `artist`) instead and we resolve the name to the best catalog match and seed on it — the resolved track is echoed back as `seed_query`; seed_tracks wins if both are given. TUNING: `min`/`max` are HARD filters and `target` is a preference (nearer ranks higher, nothing removed), over acousticness, danceability, duration_ms, energy, loudness, tempo and valence. NOTE: `popularity` (2026-08-27), `liveness`, `speechiness` (2026-09-26) and `instrumentalness` (2026-09-27) are RETIRED as tunables and return a 400 — popularity recorded how a track entered our catalogue, not audience size; the other three are returned as null for catalogue tracks. Values are FreqBlog's own (not Spotify's): energy and valence (models of how energetic / positive the preview sounds) on our own scales, danceability/acousticness on AcousticBrainz's scale — derive thresholds from our values rather than reusing Spotify-tuned ones. e.g. min={"tempo": 100}, max={"tempo": 130}, target={"energy": 0.8} for energetic 100-130 BPM tracks. When you tune, the response adds a `filters` block saying what applied, how many tracks each bound removed (`dropped_by`) and whether the bounds ran out of catalogue before `limit` (`limit_reached`) — if the list comes back short, read that BEFORE assuming the catalogue is thin. Costs 2 quota units.

Artists related to a seed artist, in the shape of Spotify's retired GET /v1/artists/{id}/related-artists. No artist graph exists, so we derive one: build the seed artist's track-vector centroid, take its nearest catalogue tracks, aggregate by artist (each scored on its top-3 track similarities so a prolific artist can't dominate) plus a same-genre lift and a cross-genre penalty. Returns `artist`, `count`, and `related` (each {artist_name, score, match_count, sample_track_id}). Pass a sample_track_id straight to get_audio_features or suggest_next_track. Costs 2 quota units.

Score how well one catalog track mixes into another (0-100) — the pairwise DJ transition score no raw key/BPM API gives you. Combines Camelot-wheel key compatibility, octave-aware BPM proximity (half/double-time counts as a match), and energy smoothness. Returns the overall `score`, per-component scores (`harmonic`/`tempo`/`energy`), a `detail` block (key_relation, both Camelot keys, both BPMs, bpm_delta, bpm_octave_matched, both energies, energy_delta), and a one-line human `reason` (e.g. "8A->9A adjacent (+1), 126->128 BPM (+2), energy +0.04 — clean uplifting mix"). Both ids are catalog itunes_track_ids — get them from search_catalog or the itunes_track_id field of a get_audio_features result. Costs 1 quota unit.

Find catalog tracks from a plain-language description of how they sound — e.g. "melancholic piano, slow", "dark ambient strings", "upbeat acoustic guitar, fast". Understands instruments and voice (piano, guitar, acoustic guitar, violin, cello, strings, harp, flute, sax, brass, organ, choir, a cappella, rap, 808/drum machine, orchestral), mood (sad/melancholic, dark/eerie, angry, ambient, happy/upbeat, chill/relaxed), character (acoustic, instrumental, with vocals, energetic, soft, danceable), tempo (slow <= 95 BPM, mid-tempo, fast >= 125 BPM, applied as filters) and any catalog genre. Sound words are scored from audio analysis of each track, not titles; every word has to hold. The response's `description.understood` shows how each word was read and `ignored_words` lists words that were NOT used — rephrase those. Each result has `match` (0-1) and a per-word `matched` breakdown. Costs 1 quota unit.

Full-text search the catalog by any mix of track / artist / album tokens. Use this to resolve a fuzzy, partial, or misspelled name into concrete tracks BEFORE calling get_audio_features. Each hit carries `chart_peak`: the best chart position we hold, 1-100 with 100 = a number-one. `null` means no placement we hold — treat that as UNKNOWN, not unpopular, and note it is NOT an audience-size figure. Placements come from the Apple Music and Deezer charts we track (since Aug 2026) and Billboard year-end charts (1960-2025). Returns lightweight stubs (itunes_track_id, track_name, artist_name, album, etc.) ranked by relevance — NOT audio features. Take the best match's track_name + artist_name and pass them to get_audio_features, or reuse its itunes_track_id as a `track_id` seed for discovery tools. ⚠ Each hit carries a `seedable` boolean. Only a hit with `seedable: true` can be used as a seed for get_recommendations / suggest_next_track / build_setlist / score_transition — those work off the similarity index, which holds only tracks we have analysed, and about a quarter of the catalogue is not analysed yet. **Prefer the highest-ranked hit with `seedable: true`.** Seeding with a `seedable: false` id returns a 404; if that track is the one you want, call get_audio_features on it first to queue analysis, then retry.

Given a seed track, return the top-N catalog tracks to play NEXT, ranked by transition score. Each suggestion carries the same `score`, per-component scores and human `reason` as score_transition (e.g. "11B->11B same key, 118->117 BPM (-0.29), energy +0.12"), plus its `genre` and `genre_relation` to the seed. GENRE-AWARE by default (cross_genre=auto): off-genre picks that only coincidentally share the seed's key/BPM sink to the bottom — use cross_genre=strict for same-genre-family only, or allow for the old harmonic-only ranking. It is the seed's sonic neighbours re-ranked for a clean mix. Returns `seed`, `count`, and a `suggestions` array of {track, score, components, reason}. seed_track_id is a catalog itunes_track_id from search_catalog or a get_audio_features result. Pair with build_setlist to order a whole crate. Costs 3 quota units.

Get a compact, clearly labelled tag list for a track — energy / danceability / valence / acousticness / instrumentalness (instrumental vs vocal, judged on the 30-second preview), plus a mood tag and a broad genre tag. It is a tag-shaped projection of the same open-data analysis get_audio_features returns (no audio upload, no extra compute), so it costs the same 1 quota unit, charged only on a served result. EVERY tag carries its own `confidence` and `provenance`: - confidence: measured (a numeric audio feature, source in provenance) | derived (MIREX mood from valence+energy) | model-estimated (AcousticBrainz mood SVM probability — research-grade, raw prob in `value`) | catalog-genre (broad catalogue tag, not fine-grained). - provenance: librosa | panns | valence+energy | acousticbrainz | catalog. `value` is the [0,1] score for numeric tags and null for label-only tags (mood category, genre). Provide AT LEAST ONE identifier: `track` (optionally with `artist`), `isrc`, `mbid`, `spotify_id`, or `track_id` (catalog itunes_track_id). If you know several, send them all — they resolve by precedence (`track` > `isrc` > `track_id` > `mbid` > `spotify_id`) and the rest are ignored, so you never have to pick. The broad, reliable coverage is the MEASURED tags from our own analysis (librosa + a PANNs-based model) over the analysed catalogue (plus on-demand by name); MBID/ISRC additionally reach 7.5M+ AcousticBrainz recordings WHEN you supply that identifier. Returns { track, count, tags:[{tag, category, value, confidence, provenance}], disclaimer }. For the full numeric feature set use get_audio_features; for nearest tracks use a discovery tool.