Send a song, get back everything a video needs: Song DNA, a beat grid, sections, the best moments, timed lyrics, the story, and a shot plan that cuts on the beat. Base URL https://api.songbrain.ai/v1. Machine-readable: OpenAPI 3.1 · interactive docs · llms.txt · SDKs for Python and TypeScript: pip install songbrain · npm install songbrain · github.com/songbrain-ai/songbrain.
id. The analysis plus shot plan typically takes 60–90 seconds for a 3-minute song (up to ~2 minutes when many songs run at once). Poll GET /v1/songs/{id} or pass a webhook_url."mode": "full" (default, $0.50) returns Song DNA plus the video direction (story and shot plan); "mode": "dna" ($0.20) returns Song DNA only. A Song DNA song can get its direction later. See Modes.songbrain.song/1. New fields can appear and existing fields don't change meaning.start_in_clip).livemode. It is false only for test-mode songs.Songbrain-Request-Id header. Quote it when you contact support.Create a key in the Developer Console (Keys). It is shown once. Send it with every request in either header:
Authorization: Bearer sb_live_…
X-API-Key: sb_live_…Keys can be revoked at any time. Each account can have up to 5 active keys. Keep keys on your server and never ship them in a browser or app bundle.
# 1. send a file (or JSON {"audio_url": "https://…"})
curl -X POST https://api.songbrain.ai/v1/songs \
-H "Authorization: Bearer $SONGBRAIN_KEY" \
-F "file=@song.mp3" -F "title=My Song"
# 2. poll until status is "done"
curl https://api.songbrain.ai/v1/songs/$ID -H "Authorization: Bearer $SONGBRAIN_KEY"import os, time, requests
API = "https://api.songbrain.ai/v1"
H = {"Authorization": f"Bearer {os.environ['SONGBRAIN_KEY']}"}
with open("song.mp3", "rb") as f:
song = requests.post(f"{API}/songs", headers=H, files={"file": f}).json()
while True:
doc = requests.get(f"{API}/songs/{song['id']}", headers=H).json()
if doc["status"] in ("done", "failed"):
break
time.sleep(10)
for scene in doc["shot_plan"]["clip"]["scenes"]:
print(scene["start_sec"], scene["end_sec"], scene["act"], scene["prompt"])const API = "https://api.songbrain.ai/v1";
const H = { Authorization: `Bearer ${process.env.SONGBRAIN_KEY}` };
const created = await fetch(`${API}/songs`, {
method: "POST",
headers: { ...H, "Content-Type": "application/json" },
body: JSON.stringify({ audio_url: "https://example.com/song.mp3", webhook_url: "https://your.app/songbrain" }),
}).then(r => r.json());
// later (or in your webhook handler):
const plan = await fetch(`${API}/songs/${created.id}/shot-plan`, { headers: H }).then(r => r.json());The SDKs wrap auth, polling, webhook verification and retries. They send an Idempotency-Key automatically, so a retried upload is never charged twice.
pip install songbrain # https://pypi.org/project/songbrain/
npm install songbrain # https://www.npmjs.com/package/songbrainapi_key).my-app/1.0 (agent: claude-code), and send clientInfo when it connects to the MCP server. The SDKs (0.3.3+) do this on their own when they run inside a coding agent; SONGBRAIN_NO_AGENT_HINT=1 turns it off. It only tells us which tools developers build with (privacy).| Field | Type | Meaning |
|---|---|---|
| GET /v1/examples | no key | List example analyses (Songbrain's own songs). |
| GET /v1/examples/{id} | no key | Full example document. ?view=summary · ?include=… · ?mode=dna (the Song DNA view) |
| GET /v1/examples/{id}/shot-plan | no key | Example story + shot plan. |
| POST /v1/songs | key | Analyse a song. mode: full (default) or dna. 202 → { id, status: "processing", mode }. |
| GET /v1/songs | key | Your songs, newest first. ?limit=1–100 & starting_after (see Pagination). |
| GET /v1/songs/{id} | key | Status while processing, then the full document. |
| GET /v1/songs/{id}/shot-plan | key | Story + shot plan only (full songs; a dna song answers 409 no_direction). |
| POST /v1/songs/{id}/direction | key | Add the video direction to a finished Song DNA song (15 credits). |
| DELETE /v1/songs/{id} | key | Delete audio and analysis now. |
| GET /v1/account | key | Free songs left this month, credit balance, prices per mode. |
| GET /v1/pricing | no key | Prices and limits as JSON. |
| POST /v1/webhooks/test | key | Send a signed ping event to a URL right now. |
| GET /v1/webhooks/deliveries | key | Your latest webhook deliveries. ?limit=20. |
| GET /v1/status | no key | Live status of API, pipeline and webhooks. |
| POST /v1/mcp | optional | MCP server (streamable HTTP). See below. |
Query options on document endpoints: view=summary drops word timings and beat arrays (≈ 3× smaller). include=song_dna,shot_plan returns only the named sections. The sections are song_dna, timeline, best_moments, lyrics, scores, story and shot_plan.
Send either multipart/form-data with file, or JSON (or form fields) with audio_url.
| Field | Type | Meaning |
|---|---|---|
| file | binary | MP3, WAV, FLAC, M4A, AAC, OGG or AIFF. Up to 100 MB, 30 s to 10 min. |
| audio_url | string | Public http(s) URL of the audio file. Redirects are followed (max 3). |
| mode | string | Optional. "full" (default): Song DNA + video direction, 25 credits. "dna": Song DNA only, 10 credits. See Modes. |
| title | string | Optional. Defaults to a cleaned file name. |
| artist | string | Optional. |
| webhook_url | string | Optional. Receives song.done / song.failed (see Webhooks). |
| external_ref | string | Optional. Your own id, echoed back in responses and webhooks. |
| lyrics | string | Optional. The song's lyrics as plain text, up to 20,000 characters. Your exact words are placed on the transcription's timing (see below). |
| test | boolean | Optional. true = free test song with example data, no audio needed (see Test mode). |
| Idempotency-Key | header | Optional. 1–255 printable characters. Makes retries safe (see below). |
{ "object": "song", "id": "8f0c…", "status": "processing", "mode": "full", "eta_sec": 75, "livemode": true,
"billing": { "type": "free", "credits": 0 }, "url": "https://api.songbrain.ai/v1/songs/8f0c…" }While processing, GET /v1/songs/{id} returns { "status": "processing", "progress": 0.6, "eta_sec": 75 }.
Every song is analysed the same way. The mode decides whether the video direction (the story and the beat-synced shot plan) is written on top. Your 5 free songs a month cover either mode.
| mode | Price | Sections in the document |
|---|---|---|
| full (default) | 25 credits ≈ $0.50 | song_dna, timeline, best_moments, lyrics, scores, story, shot_plan |
| dna | 10 credits ≈ $0.20 | song_dna, timeline, best_moments, lyrics, scores |
| POST /v1/songs/{id}/direction | 15 credits ≈ $0.30 | adds story + shot_plan to a finished dna song |
Every document carries "mode". A dna document also has a direction object that says what the upgrade adds and what it costs. See a real one without a key: /v1/examples/sugar-rush?mode=dna.
# 1. Song DNA only (10 credits, typically under a minute)
curl -X POST https://api.songbrain.ai/v1/songs -H "Authorization: Bearer $SONGBRAIN_KEY" -H "Content-Type: application/json" -d '{"audio_url": "https://example.com/song.mp3", "mode": "dna"}'
# GET /v1/songs/$ID → { "mode": "dna", "song_dna": …, "timeline": …, "best_moments": …,
# "direction": { "included": false, "add": "POST …/v1/songs/$ID/direction", "credits": 15 } }
# 2. Later: add the video direction (15 credits, about 30 seconds, no new upload)
curl -X POST https://api.songbrain.ai/v1/songs/$ID/direction -H "Authorization: Bearer $SONGBRAIN_KEY"
# → 202 { "status": "processing", "mode": "full", "billing": { "type": "credits", "credits": 15 } }GET /v1/songs/{id} shows processing; then it is done with story and shot_plan.webhook_url gets a second song.done event with its own id and data.direction_added: true.409 direction_included (already full), 409 not_done, 409 direction_in_progress, 402 insufficient_credits.Without lyrics, the words are transcribed from the vocals, and sung words can be misheard. If you have the lyrics (your own text, or the lyrics from Suno), send them as lyrics. The timing still comes from the audio; the words come from your text. Words the singer can't be heard on are left out, never guessed. Works the same in the MCP tool analyze_song.
curl -X POST https://api.songbrain.ai/v1/songs \
-H "Authorization: Bearer $SONGBRAIN_KEY" \
-H "Content-Type: application/json" \
-d '{"audio_url": "https://example.com/song.mp3",
"lyrics": "First line of the verse\nSecond line of the verse\n…"}'The result says what happened in lyrics.source: provided_lyrics, with lyrics.alignment = { match_ratio, reference_words, corrected_words }. If your text doesn't match the recording well enough, the transcription is kept (source: "transcribed") and alignment is { match_ratio, used: false, reason }.
If a POST /v1/songs times out, you can't know whether we got it. Send an Idempotency-Key header (any unique string, e.g. a UUID) and retry with the same key: you get the original song back instead of a second, paid one.
curl -X POST https://api.songbrain.ai/v1/songs \
-H "Authorization: Bearer $SONGBRAIN_KEY" \
-H "Idempotency-Key: 5d2f8c1e-upload-42" \
-H "Content-Type: application/json" \
-d '{"audio_url": "https://example.com/song.mp3"}'
# same command again → same id, header Idempotent-Replayed: true, no new charge| Case | Status | What happens |
|---|---|---|
| Same key + same request, within 24 h | 202 | The original body again (same song id, no charge). Header Idempotent-Replayed: true. |
| Same key, different request | 409 | idempotency_key_reused: other audio_url, other file bytes or other test flag. |
| First request still being accepted | 409 | idempotency_in_progress: retry after a second. |
| First request failed (4xx/5xx, no song) | — | Not stored. Retry with the same key. |
Keys are scoped to your account and kept for 24 hours. The Python and TypeScript SDKs send one automatically per call and reuse it on their own retries; pass your own to make retries safe across processes.
Add "test": true (JSON) or the form field test=true. No audio is needed and anything you send is ignored. You get a test_… id back right away; it is done immediately and returns a complete example analysis with your title and external_ref, "livemode": false and billing: { type: "test", credits: 0 }. With a webhook_url, a signed song.done arrives within about 5 seconds.
curl -X POST https://api.songbrain.ai/v1/songs \
-H "Authorization: Bearer $SONGBRAIN_KEY" \
-H "Content-Type: application/json" \
-d '{"test": true, "title": "CI check", "external_ref": "build-1234",
"webhook_url": "https://staging.your.app/songbrain"}'
# → { "id": "test_9a1c…", "status": "processing", "livemode": false,
# "billing": { "type": "test", "credits": 0 } }Use it in CIto test your whole integration, webhook handler included, on every build. Test songs are never charged and don't use your free songs. They are rate-limited like real requests and count toward the daily cap.
Top level: object, schema, id, status, livemode, song, song_dna, timeline, best_moments, lyrics, scores, story, shot_plan, provenance, external_ref, billing. See a full one at /v1/examples/old-truck-home.
| Field | Type | Meaning |
|---|---|---|
| genre / subgenre | string | Genre and one of 37 subgenres, with genre_confidence (0–1). |
| tempo_bpm | number | Tempo, with tempo_confidence. |
| key | string | e.g. "C minor", with key_confidence. key_changes[]: { at_sec, to }. |
| mood | string[] | e.g. ["epic","powerful","melancholic"]. |
| vocals | string | Vocal style, or "instrumental". |
| instruments | object[] | { name, confidence } for confidence ≥ 0.25. |
| energy / brightness | number | 0–1. |
| loudness_lufs / true_peak_dbfs | number | Integrated loudness (EBU R128) and true peak. |
| streaming_loudness | object | Per platform: { loudness_ok, delta_lufs } against its target. |
| tagline / description / sounds_like | … | One-line character, a sentence and comparable tracks. Written from the final genre, so they don't contradict song_dna.genre. |
| Field | Type | Meaning |
|---|---|---|
| beats | number[] | Every beat in the song, in seconds. |
| downbeats | number[] | First beat of each bar (4/4 assumed, time_signature). |
| sections | object[] | { start_sec, end_sec, label, energy }. The same letter means the same music, e.g. A, B, A. energy 0–1 is relative to the song's loudest part. |
| vocal_timeline | object[] | { at_sec, label }: where the vocal changes character. |
| lyric_hooks | object[] | { at_sec, line, role, strength }: lines that work as hooks. |
| Field | Type | Meaning |
|---|---|---|
| rank | int | 1 = strongest. |
| start_sec / peak_sec / end_sec | number | The window and its peak. |
| score | int | 0–100. |
| reason | string|null | One sentence: why this moment works. |
| signals | string[]|null | The measured audio signals behind the pick, e.g. “strong sustained energy after impact”. |
| sung | string|null | The words sung inside the window. |
| beat_grid_sec | number[] | Beats inside the window (omitted in view=summary). |
| Field | Type | Meaning |
|---|---|---|
| lyrics.lines[] | object[] | { start, end, text, confidence, words: [{ w, start, end }] }. { hidden: true } for recognised commercial recordings. |
| lyrics.lines[].confidence | number|null | 0–1: how sure the transcription is of this line (exp of Whisper's average log-probability). null when the words are not transcribed (your provided lyrics). |
| lyrics.source | string | "transcribed" (heard from the vocals) · "provided_lyrics" (your lyrics field) · "suno_lyrics" (lyrics from a Suno link). |
| lyrics.note / alignment | string / object | Plain-language note on where the words come from. alignment: { match_ratio, reference_words, corrected_words } when lyrics were used, or { match_ratio, used: false, reason } when they didn't match. |
| scores.virality | object | { score 0–100, breakdown{7 parts}, basis }. Song strength for short-form video. It is not a view prediction. |
| scores.quality / scores.lyrics | object | Score + breakdown + basis. Plus summary, what_works[], what_to_fix[], audience[]. |
| scores.*.basis / basis_note | string | Always "model_estimate": the scores are an AI model's judgement (see provenance). |
| provenance | object | Which fields are measured, transcribed, model_estimate or generated, plus confidence_fields. See below. |
| story.meaning / why_these_visuals | string | What the song is about, and why the visuals fit it. |
| story.world / palette | string / string[] | One place and three colours for every shot. |
| story.element | object | { thing, before, event, after }: the one object the video is about, in three states. |
| story.story_beats | object | { setup, turn, payoff }: one sentence each. |
Not every number in the document is a measurement. Every song document carries a provenance object that lists, field by field, where each value comes from:
| Kind | Fields | What it means |
|---|---|---|
| Measured | Tempo, key, key changes, loudness (LUFS, true peak, streaming targets), energy, brightness, beats, downbeats, sections, best-moment windows (start, peak, end), moment signals, the beat grid inside moments, shot-plan cut times | Computed from the audio signal with signal processing. No AI judgement involved. |
| Transcribed | Lyrics (unless lyrics.source is provided_lyrics or suno_lyrics), best_moments[].sung | Speech recognition (Whisper large-v3) on the vocals. Sung words can be misheard: check lines[].confidence, or send lyrics. |
| Model estimate | Genre, subgenre, mood, vocals, instruments, vocal timeline, lyric hooks, moment score and reason, all scores | An AI model's listening judgement. Useful for comparing, but a judgement, not a measurement. |
| Generated | Tagline, description, sounds_like, story, shot-plan prompts and visuals | Creative text written by an AI model from the analysis. tagline and sounds_like are written from the final genre. |
Confidence fields (all 0–1): song_dna.tempo_confidence, key_confidence, genre_confidence, instruments[].confidence and lyrics.lines[].confidence.
"provenance": {
"measured": ["song_dna.tempo_bpm", "song_dna.key", "timeline.beats", "timeline.sections", …],
"transcribed": ["lyrics (unless lyrics.source is provided_lyrics or suno_lyrics)", "best_moments[].sung"],
"model_estimate": ["song_dna.genre", "song_dna.mood", "best_moments[].score", "scores", …],
"generated": ["song_dna.tagline", "song_dna.sounds_like", "story", "shot_plan.*.prompt", …],
"confidence_fields": ["song_dna.tempo_confidence", "lyrics.lines[].confidence", …],
"doc": "https://www.songbrain.ai/docs/api#provenance"
}About the scores, honestly:the virality, quality and lyrics scores (and each moment's score) are an AI model's listening judgement, calibrated on our own catalogue. They are good for comparing songs and moments with each other, for example which of your songs or which 15 seconds to lead with. They are not a measurement, and they are not a forecast of views or streams. Every score carries basis: "model_estimate", and scores.basis_note says the same in one sentence, so your code and your users can tell.
shot_plan.clip is a complete, beat-synced edit of the best moment (about 15 s, 9:16). It uses the same edit our own storyboard videos use: a setup that builds, a turn of hard cuts on the beat from the payoff on, and a payoff image held at the end. shot_plan.full_song extends it to every section of the song.
| Field | Type | Meaning |
|---|---|---|
| clip.window_sec | [number, number] | Where the clip sits in the song. |
| clip.beats_sec | number[] | Beats inside the window (grid_bpm is the grid's tempo; it can run at double time). |
| clip.phases_sec | object | tease_end, payoff_start, payoff_end, outro_start. |
| clip.hook_line | string|null | The repeated sung line the payoff lands on. |
| scenes[].start_sec / end_sec | number | Absolute seconds. start_in_clip and duration_sec are relative. |
| scenes[].kind | string | tease · build · cutaway · burst · strobe (≈4-frame flash) · hero · outro. |
| scenes[].act | string | setup · turn · payoff. |
| scenes[].transition_in / motion | string | How to cut into the scene and how the camera moves. |
| scenes[].framing / emotion / symbol | string|null | Shot size, the feeling and the visual symbol the shot carries. |
| scenes[].prompt | string | A ready image/video prompt with world, palette and style. visual is the readable part without the style tail. |
| scenes[].sung | string|null | The words sung during the scene. |
| full_song.sections[] | object[] | { start_sec, end_sec, section, energy_rank, act, cut_every_beats, cuts_sec[], role, prompt, sung }. |
| style | object | { palette, prompt_suffix, world }: apply the same suffix to your own prompts to stay in the look. |
Use it directly: render one image or clip per scene from prompt and cut at start_sec. The cuts already sit on beats. Or use it as the brief for your own model: the story.element and story_beats keep a longer video coherent.
If you pass webhook_url, we POST when the song is done or failed. The URL has to be public https.
{ "id": "evt_5f1d2c9a8b7e6d5c4b3a2f10", "type": "song.done", "created": 1791200000, "livemode": true,
"data": { "id": "8f0c…", "status": "done", "mode": "full", "external_ref": "your-id",
"url": "https://api.songbrain.ai/v1/songs/8f0c…",
"shot_plan_url": "https://api.songbrain.ai/v1/songs/8f0c…/shot-plan" } }| Header | Example | Meaning |
|---|---|---|
| Songbrain-Signature | t=<unix>,v1=<hex> | HMAC-SHA256 of "<t>.<raw body>" with your key's webhook secret (shown once at key creation). |
| Songbrain-Event-Id | evt_… | Same as the body's id. Stays the same on every retry of this event. |
| Songbrain-Event-Type | song.done | song.done · song.failed · account.low_balance · ping. |
Dedupe on the event id. A retry carries the same id, so store it and ignore events you have already handled. Answer with any 2xx quickly and do the work afterwards. Redirects (3xx) are not followed and count as a failure. shot_plan_url is only there for full songs; after adding the video direction a second song.done arrives with a new id and data.direction_added: true.
Retries. Up to 10 attempts over about 3 days, until one gets a 2xx:
| Attempt | After first attempt | |
|---|---|---|
| 1 | immediately | |
| 2 · 3 · 4 | +1 min · +5 min · +30 min | |
| 5 · 6 · 7 | +2 h · +6 h · +12 h | |
| 8 · 9 · 10 | +24 h · +48 h · +72 h | Last try. Then it shows as failed in the delivery log. |
Test your endpoint without sending a song: POST /v1/webhooks/test with {"url": "https://…"} sends a signed ping event right now. GET /v1/webhooks/deliveries?limit=20 lists your latest deliveries.
curl -X POST https://api.songbrain.ai/v1/webhooks/test \
-H "Authorization: Bearer $SONGBRAIN_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://your.app/songbrain"}'
# → { "delivered": true, "status_code": 200, "latency_ms": 143, "event_id": "evt_…" }
curl "https://api.songbrain.ai/v1/webhooks/deliveries?limit=20" -H "Authorization: Bearer $SONGBRAIN_KEY"
# → { "object": "list", "data": [ { "event_id", "type", "song_id", "url", "attempt",
# "status_code", "delivered", "latency_ms", "created_at" } ] }Account events. When your free songs for the month are used up and the credits cover fewer than 5 songs, the webhook URLs you used in the last 30 days get one account.low_balance event (same signature). You also get an email, and the console shows a banner. It fires once per dip and re-arms after you top up.
{ "id": "evt_…", "type": "account.low_balance", "created": 1791200000, "livemode": true,
"data": { "credits": 75, "songs_left": 3, "free_songs_left": 0, "threshold_songs": 5,
"price_per_song_credits": 25, "buy_credits_url": "https://app.songbrain.ai/developers/billing" } }import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > tolerance:
return False
mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, parts["v1"])Every response carries a Songbrain-Request-Id: req_… header (readable from the browser too). Every error has the same shape and repeats it as request_id. Log it; it lets us find your request in seconds.
{ "error": { "code": "insufficient_credits", "message": "…", "request_id": "req_6a0f3e2d1c9b8a7f6e5d4c3b" } }Invalid parameters (a bad query value, a missing field) return 400 invalid_request with one entry per problem:
{ "error": { "code": "invalid_request", "message": "Invalid request.",
"request_id": "req_…",
"errors": [ { "field": "limit", "message": "must be between 1 and 100" } ] } }| Field | Type | Meaning |
|---|---|---|
| 400 | invalid_request · invalid_mode · invalid_url · missing_audio · unsupported_format · format_mismatch · audio_too_short · audio_too_long · decode_failed · download_failed | Fix the request. Nothing was charged. |
| 401 | missing_api_key · invalid_api_key | Send a valid key. |
| 402 | insufficient_credits | The free songs are used up and the balance is below the song's price (25 credits full, 10 dna), or below 15 for adding the direction. |
| 404 | not_found | Unknown id or route, or not yours. |
| 409 | still_processing · idempotency_key_reused · idempotency_in_progress | DELETE before the analysis finished, or an Idempotency-Key conflict. |
| 409 | no_direction · direction_included · not_done · direction_in_progress · song_failed | Shot plan asked of a dna song, or an upgrade that can't run now (see Modes). |
| 413 | file_too_large | Over 100 MB. |
| 415 | unsupported_media_type | Use multipart/form-data or application/json. |
| 429 | rate_limited · too_many_in_flight · daily_cap · pipeline_busy | Back off. A Retry-After header says how long. |
If an analysis fails after it was accepted, its status becomes failed. Paid credits are refunded automatically, and a free song doesn't count against the month.
Every request made with a key returns its current budget:
| Header | Example | Meaning |
|---|---|---|
| X-RateLimit-Limit | 120 | Requests per minute for this key. |
| X-RateLimit-Remaining | 117 | Requests left in the current window. |
| X-RateLimit-Reset | 23 | Seconds until the window has room again. |
| Retry-After | 23 | On 429 only: wait this many seconds. |
Separate from the request rate: 3 songs in parallel per account and 200 songs per 24 h (too_many_in_flight, daily_cap).
GET /v1/songs returns newest first. Pass the next_cursor of one page as starting_after to get the next, until has_more is false.
{ "object": "list", "has_more": true, "next_cursor": "41be…",
"data": [ { "id": "…", "status": "done", "livemode": true, … } ] }/v2), with at least 6 months of overlap and an email to every key owner. Deprecations are announced in the changelog and in a Songbrain-Deprecation response header.GET /v1/status (no key) returns operational, degraded or down per component, the current queue and the median analysis time. History and incidents: songbrain.ai/status.{ "status": "operational",
"components": { "api": "operational", "pipeline": "operational", "webhooks": "operational" },
"queue": { "songs_processing": 2 }, "median_analysis_sec_24h": 74, "checked_at": "2026-10-07T09:00:00Z" }The short version of Terms §17.4:
| Field | Type | Meaning |
|---|---|---|
| Use it in a paid SaaS | yes | Including products that generate images or videos for your customers. |
| Pass results to end users | yes | Show, deliver, let them download, changed or unchanged. |
| White-label | yes | No attribution to Songbrain required. |
| Ownership of results | yours | Analysis, story, shot plans and prompts for your songs; we claim no rights in them. |
| Store results | forever | Even after you delete the song or close the account. |
| Train your own models on results | yes | Except a model built to reproduce the Songbrain API for third parties. |
| Resell raw API access / bulk dataset | no | Only with written consent. |
| Volume (1,000+ songs/month) | contract | Volume pricing, invoice, DPA, SLA. |
https://api.songbrain.ai/v1/mcp speaks the Model Context Protocol over streamable HTTP (stateless JSON-RPC). It works in Claude Code, Claude Desktop, Cursor and any MCP client. Without a key you get the example tools; add your key as a header to analyse your own songs. Apps that can only sign in (claude.ai, Claude Desktop, ChatGPT) use https://api.songbrain.ai/v1/mcp/auth: it asks for a Songbrain sign-in (OAuth 2.1 with PKCE), then has the same tools as a key. The connection appears as a key named "<app> (connector)" in the Developer Console; revoking it disconnects the app. Registry name: io.github.songbrain-ai/songbrain. Config snippets for Claude Desktop, Cursor and ChatGPT, and a comparison with the local librosa server: MCP server for music analysis.
claude mcp add --transport http songbrain https://api.songbrain.ai/v1/mcp \
--header "Authorization: Bearer sb_live_…"| Field | Type | Meaning |
|---|---|---|
| list_example_songs | no key | Example analyses you can open. |
| get_example_analysis | no key | An example document (summary view by default). |
| get_example_shot_plan | no key | An example story + shot plan, with prompts. |
| get_pricing | no key | Prices and limits. |
| analyze_song | key | Start an analysis from a public audio URL. mode: full (default) or dna. Optional lyrics for the exact words. |
| get_song | key | Status, then the document. |
| add_video_direction | key | Add story + shot plan to a finished dna song (15 credits). |
| get_account | key | Free songs left, credits. |
Connect, ask, read the answer: the MCP server on a real song in four minutes.
Click to load the player from YouTube (no-cookie mode). Your IP address is then sent to Google — details in our privacy policy.
Spotify closed /audio-features and /audio-analysis to new apps in November 2024. Here is where the fields you used live in Songbrain. The difference: you send the audio file, so it also works for unreleased songs. For these fields "mode": "dna" is enough ($0.20 a song).
| Field | Type | Meaning |
|---|---|---|
| tempo | → | song_dna.tempo_bpm |
| key + mode | → | song_dna.key ("C minor"), key_changes[] |
| energy | → | song_dna.energy (0–1) |
| loudness | → | song_dna.loudness_lufs (EBU R128, not dB average) |
| valence / danceability | → | song_dna.mood[] (words, not numbers) |
| instrumentalness | → | song_dna.vocals ("instrumental") + song.has_vocals |
| audio-analysis beats / bars | → | timeline.beats / timeline.downbeats |
| audio-analysis sections | → | timeline.sections (with repeat letters) |
| (not in Spotify) | + | best_moments, lyrics with word timing, story, shot_plan |