Audio - Music

Free MIDI Decode API Endpoint

The free MIDI decode API endpoint reads a Standard MIDI File and answers what is in it as JSON: format and tracks, tempos, time and key signatures, the instruments, and every note with its start and length in seconds. Upload the .mid file and parse nothing yourself.

  • No API key
  • MIDI to JSON
  • Seconds, not ticks
  • Nothing stored

Read a MIDI file

POST/midi_decode

https://aisenseapi.com/services/v1/midi_decode

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.

Drop a MIDI file here or click to choose one, up to 1 MiB

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

FieldTypeDescription
formatinteger0, 1 or 2.
tracksintegerThe tracks in the file.
timingobjectticks_per_quarter, or smpte_frames_per_second and ticks_per_frame.
duration_secondsnumberWhere the last note or track ends.
temposarrayseconds and value in beats a minute, 120 when the file sets none.
time_signatures, key_signaturesarrayseconds and value, such as 3/4 or F# minor.
track_namesarrayThe names the tracks give themselves.
programsarrayEach channel and General MIDI program used, with its name; channel 9 is Drums.
note_count, notes_listed, truncatedinteger, integer, booleanAll notes, the notes listed, and whether the list was cut.
notesarrayEach 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.