Falling Note

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.

Shell
export FALLING_NOTE_API_KEY="paste your key here"

2. Send a recording.

cURL
curl https://api.fallingnoteapp.com/v1/transcriptions \
  -H "Authorization: Bearer $FALLING_NOTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@song.mp3

Returns 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
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.

HTTP
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
filerequiredOne 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.
titleoptionalUp to 200 characters. Written into the score. If you leave it out, the file's name is used when it reads as a title.
composeroptionalUp 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:

FieldTypeMeaning
idstringtrn_ and 24 letters and digits.
object"transcription"
statusstringqueued, processing, succeeded or failed. No other value will be added in v1.
created_atintegerWhen the request was accepted, in Unix seconds.
started_atinteger or nullWhen the work started.
completed_atinteger or nullWhen it succeeded or failed.
expires_atinteger or null7 days after completed_at, once succeeded. From then /content answers 410 and outputs is null.
title, composerstring or nullAs written into the score.
input.filenamestring or nullThe file's name; null after DELETE.
input.bytesintegerThe upload's size.
input.formatstringmp3, m4a, aac, wav, flac, ogg, opus, aiff, caf, webm or mp4, read from the file itself.
input.duration_secondsnumberThe length we measured, to 3 decimals.
usage.billed_secondsintegerThe length billed: whole seconds, 30 at least.
usage.coststringWhat the job costs now, in US dollars with 6 decimals. "0.000000" after a failure.
resultobject or nullOn success, measures and notes, counted in the score. Notes count chord tones, not rests or grace notes.
outputsobject or nullOn success, until expires_at: the mxl, musicxml and midi URLs. Each needs the same Authorization header.
engine_versionstringA date naming the engine release. Changes are listed in the Changelog.
errorobject or nullOn failure, code and message.
JSON
{
  "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
filerequiredOne 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.
titleoptionalUp to 200 characters.
composeroptionalUp 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.jpg

GET, /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
filefile or transcription_idOne 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_idfile or transcription_idOne of your transcriptions, within 7 days of its completion.
levelsoptionaleasy, medium, or easy,medium. The default is easy.
title, composeroptionalUp 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.

JSON
{"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:

Shell
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 curl command 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 curl on 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:

JSON
{"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.

StatusCodeMeaning
400missing_fileNo file part. For a simplification: neither file nor transcription_id.
400empty_fileA file part of 0 bytes.
400too_many_filesMore than one file part on a transcription or a simplification.
400mixed_file_typesA scan with a PDF and any other file, or two PDFs.
400invalid_parameterA field or query parameter breaks its rule, or is unknown. param names it.
400invalid_idempotency_keyIdempotency-Key is longer than 255 characters or has a character outside printable ASCII.
400api_key_in_urlA key in the path or the query.
401missing_api_keyNo Authorization header, or not Bearer.
401invalid_api_keyThe key is malformed, unknown or deleted, or its account is gone.
402insufficient_balanceThe job costs more than the balance. required and available give both amounts.
403account_suspendedThis account can't use the API.
403account_frozenThe balance is on hold. New jobs are refused.
403https_requiredA request over plain HTTP.
403browser_requests_not_supportedA browser's preflight request (OPTIONS).
404not_foundAn unknown path or id, another account's job, or a deleted job.
405method_not_allowedThe path doesn't take this method. Allow lists the ones it takes.
408upload_timeoutThe upload took longer than 60 seconds.
409job_not_finished/content or DELETE before the job finished, or a simplification of a transcription still running.
409job_failed/content on a failed job, or a simplification of a failed transcription.
410output_expiredPast expires_at, or the files were deleted.
411length_requiredA POST without Content-Length.
413file_too_largeThe upload is over the size limit.
413audio_too_longThe recording is longer than 10 minutes.
413too_many_pagesMore than 10 pages.
413image_too_largeAn image is larger than 50 megapixels.
413score_too_longA score over 400 measures or 20,000 notes.
415invalid_content_typeA POST that isn't multipart/form-data.
415unsupported_file_typeNot a file type we take, or a recording with more than one audio track. The message says what to send.
422unreadable_fileThe file can't be decoded or opened.
422encrypted_pdfA password-protected PDF.
422audio_too_shortThe recording is shorter than 1 second.
422silent_audioThe recording is silent.
422unsupported_scoreNot a piano score with one or two parts of equal length, a timewise score, a measure over 256 notes, or extreme divisions or durations.
422idempotency_key_reusedThe same Idempotency-Key with a different request, within 24 hours.
429rate_limitedOver a per-minute limit, too many refused requests, or too many uploads at once.
429too_many_active_jobs5 unfinished jobs. Retry-After is 30.
429too_many_failed_jobs10 of the account's jobs failed in this hour (UTC).
500internal_errorSomething went wrong on our side.
503service_unavailableThe API is unavailable for now.
503overloadedThe API is busy: the queue is full, or every upload slot is in use.

A job that fails is refunded in full.

CodeMessage
unreadable_audioThis recording couldn't be decoded. The charge was refunded.
no_notes_foundNo piano notes were found in this recording. The charge was refunded.
no_beat_foundNo beat was found in this recording. The charge was refunded.
not_writableSheet music couldn't be written from this recording. The charge was refunded.
unreadable_pagesThese pages couldn't be read. The charge was refunded.
no_music_foundNo printed music was found on these pages. The charge was refunded.
unreadable_scoreThis score couldn't be read. The charge was refunded.
not_simplifiedAn easier version of this score couldn't be made. The charge was refunded.
timed_outThis job took longer than the limit. The charge was refunded.
cancelledThis job was stopped before it ran. The charge was refunded.
internal_errorSomething went wrong on our side. The charge was refunded.

Retries:

  • 429, 503: wait Retry-After seconds and send it again.
  • 409 job_not_finished: ask again in a few seconds.
  • 500: send it again (a POST with the same Idempotency-Key).
  • A job that failed keeps its Idempotency-Key for 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 429 with 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 jobs20 a minute for each account
Unfinished jobs5 for each account
Failed jobs10 an hour for each account; then new jobs wait for the next hour
Other requests600 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. DELETE deletes 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 (DELETE removes 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.