Get Audio Features
get_audio_featuresRead-only
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.
This is the drop-in replacement for Spotify's deprecated /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 on
our own raw scale (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, speechiness and liveness are currently
null for catalogue tracks.
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| isrc | No | ISRC, e.g. 'USUM71900001'. | |
| mbid | No | MusicBrainz recording ID (UUID). The precise key when there is no ISRC, e.g. pre-1986 recordings. | |
| track | No | Track title. Use with `artist` when known. Supply AT LEAST ONE of track/isrc/mbid/spotify_id. Sending several is fine — they resolve by precedence (track > isrc > mbid > spotify_id) and the rest are ignored. | |
| artist | No | Artist name. Only used with `track`; required when the title is <=2 characters. | |
| spotify_id | No | Spotify track ID, 'spotify:track:...' URI, or open.spotify.com 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) — a title several artists share is ambiguous and misses rather than guessing; prefer track (+artist) or isrc. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||