Read a MIDI file
curl -X POST https://aisenseapi.com/services/v1/midi_decode \
-H "Content-Type: audio/midi" --data-binary @phrase.mid
{"format":1,"tracks":2,"timing":{"ticks_per_quarter":480},"duration_seconds":2.5,"tempos":[{"seconds":0,"value":120}],"time_signatures":[{"seconds":0,"value":"4/4"}],"key_signatures":[],"track_names":[],"programs":[{"channel":0,"program":0,"name":"Acoustic Grand Piano"}],"note_count":6,"notes_listed":6,"truncated":false,"notes":[{"track":2,"channel":0,"note":60,"name":"C4","start_seconds":0,"duration_seconds":0.5,"velocity":96},{"track":2,"channel":0,"note":64,"name":"E4","start_seconds":0.5,"duration_seconds":0.25,"velocity":96},{"track":2,"channel":0,"note":67,"name":"G4","start_seconds":0.75,"duration_seconds":0.25,"velocity":96},{"track":2,"channel":0,"note":60,"name":"C4","start_seconds":1.5,"duration_seconds":1,"velocity":96},{"track":2,"channel":0,"note":64,"name":"E4","start_seconds":1.5,"duration_seconds":1,"velocity":96},{"track":2,"channel":0,"note":67,"name":"G4","start_seconds":1.5,"duration_seconds":1,"velocity":96}]}That is the file midi_encode makes from C4:4,E4:8,G4:8,R:4,C4+E4+G4:2: a phrase and a chord at 120 beats a minute. The file can also go as a multipart field named file, -F file=@phrase.mid, or as base64 in {"data": "..."}. At most 1 MiB; a JSON body is at most 256 KiB, so through data the file can be about 190 KB.
Try it
Read a MIDI file here: drop a .mid file, or read the sample, the phrase and chord of the quick start. Your browser uploads the file as a form field named file.
What is read, and how
Format 0, 1 and 2 files are read, with quarter-note or SMPTE timing, running status, system exclusive and meta events. Seconds come from the tempo map, so a tempo change halfway through moves every note after it. A note on with velocity 0 ends a note, as many files write it, and a note still sounding at the end of its track ends there. In a format 2 file each track is a sequence of its own, with its own tempo and programs, and the sequences follow one another.
At most 5000 notes are listed, in the order they start; note_count says how many there are and truncated whether the list was cut. A file of more than 200000 events is refused. For a real file to try, J. S. Bach's Invention 1, BWV 772 on the Mutopia Project has a MIDI download, typeset by Jeff Covey under CC BY-SA 3.0.
What the free MIDI decode API endpoint returns
| Field | Type | Description |
|---|---|---|
| format | integer | 0, 1 or 2. |
| tracks | integer | The tracks in the file. |
| timing | object | ticks_per_quarter, or smpte_frames_per_second and ticks_per_frame. |
| duration_seconds | number | Where the last note or track ends. |
| tempos | array | seconds and value in beats a minute, 120 when the file sets none. |
| time_signatures, key_signatures | array | seconds and value, such as 3/4 or F# minor. |
| track_names | array | The names the tracks give themselves. |
| programs | array | Each channel and General MIDI program used, with its name; channel 9 is Drums. |
| note_count, notes_listed, truncated | integer, integer, boolean | All notes, the notes listed, and whether the list was cut. |
| notes | array | Each note: track, channel, note, name, start_seconds, duration_seconds, velocity. |
HTTP 400 when the file is not MIDI
curl -X POST https://aisenseapi.com/services/v1/midi_decode \
-H "Content-Type: application/octet-stream" --data-binary "hello"
{"error":"This is not a Standard MIDI File: it does not start with MThd.","fix":"POST a Standard MIDI File (.mid) of at most 1 MiB: a multipart field named file, the raw body as audio/midi, or Base64 in {\"data\": \"...\"}."}Also HTTP 400: a header or track cut short, fewer tracks than the header names, a length of more than four bytes, data without a status byte. HTTP 413: more than 1 MiB or 200000 events. HTTP 415: a content type other than multipart, JSON, application/octet-stream or audio/midi and its spellings audio/x-midi and audio/mid.
Where reading MIDI earns its keep
Agents that study music
An agent reads the notes of a file as data and talks about the melody, the chords or the form.
Checks before playback
Length, tempo and instruments of an uploaded file, read before it is played or sold.
Exercises
Compare a student's file with the expected notes, note by note.
Conversions
Notes in seconds are the start of a light show, a game level or a piano roll.
Privacy and limits
The file is read in memory and not stored; nothing remains after the answer.
The service-wide limit is 5000 requests per IP per day, with no key and no account behind it. Every endpoint is listed in the free public REST APIs reference.