Docs
Piano recordings to sheet music and MIDI, printed pages to MusicXML, and scores made easier.
Quickstart
Every request goes to https://api.fallingnoteapp.com/v1 with your key. The whole API is described for tools in openapi.json.
1. Make a key and add balance. Open API keys, press Create New Key and copy the key. It is shown once. Keep it on your server, in an environment variable. Then press Top Up and add $10 or more. New accounts start at $0.
export FALLING_NOTE_API_KEY="paste your key here"2. Send a recording.
curl https://api.fallingnoteapp.com/v1/transcriptions \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F file=@song.mp3Returns a transcription with an id and the status queued. A 402 means the balance is too low.
3. Download the sheet music. Ask for the transcription every 5 seconds. When its status is succeeded, download the file.
curl https://api.fallingnoteapp.com/v1/transcriptions/trn_... \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY"
curl -o song.mxl "https://api.fallingnoteapp.com/v1/transcriptions/trn_.../content" \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY"Open song.mxl in MuseScore, Dorico or Sibelius.
The same in one file:
Needs pip install requests.
import os
import time
import uuid
import requests
API = "https://api.fallingnoteapp.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['FALLING_NOTE_API_KEY']}"}
def check(response):
if response.ok:
return response
if response.headers.get("content-type", "").startswith("application/json"):
error = response.json()["error"]
raise RuntimeError(f"{error['code']}: {error['message']} ({error['request_id']})")
raise RuntimeError(f"HTTP {response.status_code}: {response.text[:200]}")
with open("song.mp3", "rb") as audio:
job = check(requests.post(
f"{API}/transcriptions",
headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
files={"file": audio},
data={"title": "My Song"},
)).json()
while job["status"] in ("queued", "processing"):
time.sleep(5)
job = check(requests.get(f"{API}/transcriptions/{job['id']}", headers=HEADERS)).json()
if job["status"] == "failed":
raise SystemExit(job["error"]["message"])
score = check(requests.get(f"{API}/transcriptions/{job['id']}/content",
headers=HEADERS, params={"format": "mxl"}))
with open("song.mxl", "wb") as out:
out.write(score.content)Authentication
Every request carries your key in the Authorization header.
Authorization: Bearer $FALLING_NOTE_API_KEY- Keys start with
fn_sk_and are 52 characters long. - Keep keys on your server. A key in a web page or an app can be copied by anyone who has the page or the app. Requests from a browser are refused.
- A key in the address is refused. Send it in the header.
- Make one key for each app or server. Delete a key on the API keys page; it stops working within 30 seconds.
- Jobs belong to your account, not to a key. Any of your keys can read them.
- All requests use HTTPS. Plain HTTP is refused.
Transcriptions
A transcription turns one recording of solo piano into sheet music and a MIDI file.
POST /v1/transcriptions
Send the recording as multipart/form-data.
| Field | ||
|---|---|---|
file | required | One audio file with one audio track: MP3, M4A, AAC, WAV, FLAC, OGG, Opus, AIFF, CAF, WebM or MP4. Up to 32 MB and 10 minutes. |
title | optional | Up to 200 characters. Written into the score. If you leave it out, the file's name is used when it reads as a title. |
composer | optional | Up to 200 characters. Written into the score. |
Returns 202 and the transcription. WAV files are large: 32 MB holds about three minutes of CD-quality WAV. For longer recordings send FLAC, M4A or MP3. Any other field is refused with 400.
GET /v1/transcriptions/{id}
The transcription. Ask every 5 seconds until its status is succeeded or failed.
GET /v1/transcriptions/{id}/content
The file. format=mxl (the default) is compressed MusicXML, musicxml is the same score uncompressed, midi is the performance.
DELETE /v1/transcriptions/{id}
Deletes the files now. It works once the transcription has finished.
The transcription:
| Field | Type | Meaning |
|---|---|---|
id | string | trn_ and 24 letters and digits. |
object | "transcription" | |
status | string | queued, processing, succeeded or failed. No other value will be added in v1. |
created_at | integer | When the request was accepted, in Unix seconds. |
started_at | integer or null | When the work started. |
completed_at | integer or null | When it succeeded or failed. |
expires_at | integer or null | 7 days after completed_at, once succeeded. From then /content answers 410 and outputs is null. |
title, composer | string or null | As written into the score. |
input.filename | string or null | The file's name; null after DELETE. |
input.bytes | integer | The upload's size. |
input.format | string | mp3, m4a, aac, wav, flac, ogg, opus, aiff, caf, webm or mp4, read from the file itself. |
input.duration_seconds | number | The length we measured, to 3 decimals. |
usage.billed_seconds | integer | The length billed: whole seconds, 30 at least. |
usage.cost | string | What the job costs now, in US dollars with 6 decimals. "0.000000" after a failure. |
result | object or null | On success, measures and notes, counted in the score. Notes count chord tones, not rests or grace notes. |
outputs | object or null | On success, until expires_at: the mxl, musicxml and midi URLs. Each needs the same Authorization header. |
engine_version | string | A date naming the engine release. Changes are listed in the Changelog. |
error | object or null | On failure, code and message. |
{
"id": "trn_7Qm2Xc9LpV4tK8wN1bR6zD3a",
"object": "transcription",
"status": "succeeded",
"created_at": 1792617600,
"started_at": 1792617604,
"completed_at": 1792617702,
"expires_at": 1793222502,
"title": "Nocturne in E-flat major",
"composer": "Frédéric Chopin",
"input": {"filename": "nocturne.m4a", "bytes": 4821337, "format": "m4a", "duration_seconds": 241.312},
"usage": {"billed_seconds": 242, "cost": "0.403334"},
"result": {"measures": 112, "notes": 2588},
"outputs": {
"mxl": "https://api.fallingnoteapp.com/v1/transcriptions/trn_7Qm2Xc9LpV4tK8wN1bR6zD3a/content?format=mxl",
"musicxml": "https://api.fallingnoteapp.com/v1/transcriptions/trn_7Qm2Xc9LpV4tK8wN1bR6zD3a/content?format=musicxml",
"midi": "https://api.fallingnoteapp.com/v1/transcriptions/trn_7Qm2Xc9LpV4tK8wN1bR6zD3a/content?format=midi"
},
"engine_version": "2026-11-14",
"error": null
}Use a recording of one piano, clearly audible. Other instruments and voices come out as piano notes.
The MIDI file is the performance as played — its timing, dynamics and pedal — on two tracks, Right Hand and Left Hand (one track, Piano, when the hands can't be told apart). The sheet music is written from it in measures, with its own split of the hands, so the two can differ.
Scans
A scan turns photos or a PDF of printed sheet music into MusicXML.
POST /v1/scans
| Field | ||
|---|---|---|
file | required | One PDF, or up to 10 images in reading order (repeat the field). JPEG, PNG, HEIC, TIFF, WebP or BMP. Up to 40 MB in total and 10 pages. Each image up to 50 megapixels. |
title | optional | Up to 200 characters. |
composer | optional | Up to 200 characters. |
curl https://api.fallingnoteapp.com/v1/scans \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F file=@page-1.jpg \
-F file=@page-2.jpgGET, /content (mxl or musicxml) and DELETE work as for transcriptions.
You pay for each page you send. A page that can't be read is refunded and counted in result.failed_pages.
Send printed music, not handwriting or tablature: flat, evenly lit, the page filling the frame. The result is a piano score on two staves.
Simplifications
A simplification rewrites a piano score at an easier level: Easy or Medium.
POST /v1/simplifications
| Field | ||
|---|---|---|
file | file or transcription_id | One MusicXML file (.musicxml, .xml or .mxl). A piano score with one or two parts, up to 400 measures, 20,000 notes and 15 MB. |
transcription_id | file or transcription_id | One of your transcriptions, within 7 days of its completion. |
levels | optional | easy, medium, or easy,medium. The default is easy. |
title, composer | optional | Up to 200 characters each. Otherwise the score's own. |
curl https://api.fallingnoteapp.com/v1/simplifications \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F transcription_id=trn_... \
-F levels=easy,medium
curl -o easy.mxl "https://api.fallingnoteapp.com/v1/simplifications/smp_.../content?level=easy" \
-H "Authorization: Bearer $FALLING_NOTE_API_KEY"GET /v1/simplifications/{id}/content
One level's file, for example ?level=easy&format=mxl.
Easy keeps about half of the notes; chords mostly become one or two notes. Medium keeps most of the right hand's rhythm. Neither keeps the melody whole: about half of its notes remain at Easy. A tempo above 99 BPM is marked slower. Repeats and endings, dynamics, pedal, lyrics, chord symbols and grace notes are left out. Notes of different lengths that start together in one voice can be lost, even in measures kept as written.
You pay for each level. A level that can't be made is refunded.
Balance
GET /v1/balance
Your API balance in US dollars.
{"object": "balance", "currency": "usd", "available": "9.597813"}Top up on the API keys page. The API balance is separate from a Falling Note subscription: Pro doesn't pay for API jobs, and the balance doesn't unlock the app.
Assistants
An AI assistant that runs commands on your computer, such as Claude Code, can use the API for you. Add the connector once, then ask in plain words: "Turn take.m4a into sheet music."
Claude Code. With your key in FALLING_NOTE_API_KEY:
claude mcp add --transport http falling-note https://api.fallingnoteapp.com/v1/mcp --header "Authorization: Bearer $FALLING_NOTE_API_KEY"Any other MCP client. The address is https://api.fallingnoteapp.com/v1/mcp (Streamable HTTP), with the same Authorization header as every request.
- The assistant gets tools for your balance, an upload, a job's status, a download, an easier version of a transcription and deleting a job's files.
- Your files don't pass through the connector. The assistant runs a
curlcommand that sends the file straight to the API, with a one-time pass in place of your key. A pass lasts 15 minutes and opens one request. - A job costs what it costs through the API, from the same balance. The assistant is told the prices, and to tell you the cost before it starts a job.
- The assistant needs a shell with
curlon your computer. Chat apps that sign you in instead of taking a key, such as Claude and ChatGPT on a phone, aren't supported yet.
Errors
Every error has the same body:
{"error": {"type": "invalid_request_error", "code": "audio_too_long",
"message": "The recording is longer than 10 minutes.",
"param": null, "request_id": "req_5bH8kP2mQ9vX4cT7nL1wR6zF"}}code names the problem; request_id is also in the x-request-id header. Send it with any question to aristotle@fallingnoteapp.com.
| Status | Code | Meaning |
|---|---|---|
| 400 | missing_file | No file part. For a simplification: neither file nor transcription_id. |
| 400 | empty_file | A file part of 0 bytes. |
| 400 | too_many_files | More than one file part on a transcription or a simplification. |
| 400 | mixed_file_types | A scan with a PDF and any other file, or two PDFs. |
| 400 | invalid_parameter | A field or query parameter breaks its rule, or is unknown. param names it. |
| 400 | invalid_idempotency_key | Idempotency-Key is longer than 255 characters or has a character outside printable ASCII. |
| 400 | api_key_in_url | A key in the path or the query. |
| 401 | missing_api_key | No Authorization header, or not Bearer. |
| 401 | invalid_api_key | The key is malformed, unknown or deleted, or its account is gone. |
| 402 | insufficient_balance | The job costs more than the balance. required and available give both amounts. |
| 403 | account_suspended | This account can't use the API. |
| 403 | account_frozen | The balance is on hold. New jobs are refused. |
| 403 | https_required | A request over plain HTTP. |
| 403 | browser_requests_not_supported | A browser's preflight request (OPTIONS). |
| 404 | not_found | An unknown path or id, another account's job, or a deleted job. |
| 405 | method_not_allowed | The path doesn't take this method. Allow lists the ones it takes. |
| 408 | upload_timeout | The upload took longer than 60 seconds. |
| 409 | job_not_finished | /content or DELETE before the job finished, or a simplification of a transcription still running. |
| 409 | job_failed | /content on a failed job, or a simplification of a failed transcription. |
| 410 | output_expired | Past expires_at, or the files were deleted. |
| 411 | length_required | A POST without Content-Length. |
| 413 | file_too_large | The upload is over the size limit. |
| 413 | audio_too_long | The recording is longer than 10 minutes. |
| 413 | too_many_pages | More than 10 pages. |
| 413 | image_too_large | An image is larger than 50 megapixels. |
| 413 | score_too_long | A score over 400 measures or 20,000 notes. |
| 415 | invalid_content_type | A POST that isn't multipart/form-data. |
| 415 | unsupported_file_type | Not a file type we take, or a recording with more than one audio track. The message says what to send. |
| 422 | unreadable_file | The file can't be decoded or opened. |
| 422 | encrypted_pdf | A password-protected PDF. |
| 422 | audio_too_short | The recording is shorter than 1 second. |
| 422 | silent_audio | The recording is silent. |
| 422 | unsupported_score | Not a piano score with one or two parts of equal length, a timewise score, a measure over 256 notes, or extreme divisions or durations. |
| 422 | idempotency_key_reused | The same Idempotency-Key with a different request, within 24 hours. |
| 429 | rate_limited | Over a per-minute limit, too many refused requests, or too many uploads at once. |
| 429 | too_many_active_jobs | 5 unfinished jobs. Retry-After is 30. |
| 429 | too_many_failed_jobs | 10 of the account's jobs failed in this hour (UTC). |
| 500 | internal_error | Something went wrong on our side. |
| 503 | service_unavailable | The API is unavailable for now. |
| 503 | overloaded | The API is busy: the queue is full, or every upload slot is in use. |
A job that fails is refunded in full.
| Code | Message |
|---|---|
unreadable_audio | This recording couldn't be decoded. The charge was refunded. |
no_notes_found | No piano notes were found in this recording. The charge was refunded. |
no_beat_found | No beat was found in this recording. The charge was refunded. |
not_writable | Sheet music couldn't be written from this recording. The charge was refunded. |
unreadable_pages | These pages couldn't be read. The charge was refunded. |
no_music_found | No printed music was found on these pages. The charge was refunded. |
unreadable_score | This score couldn't be read. The charge was refunded. |
not_simplified | An easier version of this score couldn't be made. The charge was refunded. |
timed_out | This job took longer than the limit. The charge was refunded. |
cancelled | This job was stopped before it ran. The charge was refunded. |
internal_error | Something went wrong on our side. The charge was refunded. |
Retries:
429,503: waitRetry-Afterseconds and send it again.409 job_not_finished: ask again in a few seconds.500: send it again (aPOSTwith the sameIdempotency-Key).- A job that failed keeps its
Idempotency-Keyfor 24 hours: to try it again, send a new key. - Other
4xx: change the request first. - New codes may be added. Handle an unknown code by its HTTP status.
- If you send more than 50 requests in 10 seconds from one address, the network answers
429with its own page instead of this JSON for 10 seconds.
Idempotency: send Idempotency-Key (any string of up to 255 printable ASCII characters; a UUID works) with each POST. If the connection drops or you get a 5xx, send the request again with the same key: you get the same job back and pay once. A key is kept for 24 hours. The same key with a different request is refused with 422. Large uploads need a steady connection: the upload must arrive within 60 seconds.
Rate limits
| New jobs | 20 a minute for each account |
| Unfinished jobs | 5 for each account |
| Failed jobs | 10 an hour for each account; then new jobs wait for the next hour |
| Other requests | 600 a minute for each account |
The limits are your account's, whatever the number of keys. When the service is busy, a new job gets 503 with Retry-After. Ask for a job every 5 seconds.
Pricing
| Transcription | $0.10 a minute of audio, billed per second, 30 seconds minimum |
| Scan | $0.10 a page |
| Simplification | $0.10 a version (Easy or Medium) |
Prices are in US dollars. The price is charged when the job is created, from the length or pages we measure. A job that fails is refunded in full. Top up from $10 to $500 on the API keys page. Top-ups are covered by the API Terms. Your balance doesn't expire.
Data and privacy
- We don't use the files you send to the API, or the results, to train or improve our models.
- We delete the files you upload from our storage when the job finishes. Copies handled by our processing provider during the job are deleted by it within 7 days.
- We keep results for 7 days so you can download them, then delete them.
DELETEdeletes them sooner. - We keep a record of each job for 30 days: when it ran, its size, its length or pages, its price, its outcome, and the title, composer and file name you sent (
DELETEremoves those three). - Each charge, refund and top-up stays in your balance's history until you delete your account.
- Logs record what happened, never what your files contain.
- Send only recordings and scores you have the right to use.
Changelog
- 2026-11-17 — Assistants: Claude Code and other MCP clients can use the API as tools.
- 2026-11-14 — The API opens: transcriptions, scans, simplifications, balance.