Zinadin Zidan
45a8e16669
read_smf_lenient keeps what comes before MAX_EVENTS events or MAX_TRACKS tracks and only says so in a warning. Those warnings are words, and at most MAX_WARNINGS of them are kept: when earlier damage has filled them, nothing tells the caller that the file was cut. LenientRead gets over_limit, set whenever either limit left something out, full warnings or not. A caller that refuses over-limit files, as read_smf does, can now do so after a lenient read. LenientRead is non_exhaustive, so the new field breaks no caller.
craft-midi
MIDI file formats. Bytes in, a neutral model out, and back. No file access: callers pass bytes, so the crate builds for wasm32.
| Format | Read | Write |
|---|---|---|
Standard MIDI File (.mid, .midi), formats 0 and 1 |
yes | format 0 or 1 |
| Standard MIDI File, format 2 | best effort (all tracks share one timeline) | no |
RIFF-wrapped MIDI (.rmi), System Exclusive dumps (.syx) and karaoke lyrics are not here; no
app reads or writes them.
The neutral model
Note: pitch, note-on velocity, release velocity, channel, start and length in ticks.CtrlEvent: a channel event at a tick: control change, pitch bend (centred, -8192..=8191), channel pressure, polyphonic pressure or program change.Sequence: the notes and channel events of one track, with sorting, range queries and duplicate removal.Smf: the file: its format, its tracks (SmfTrack: a name and aSequence) and the file-wide tempo, meter, marker and key-signature lists.Smf::default()is an empty format-1 file.
All ticks are at PPQ (960) per quarter note, whatever the file's division. The serde feature
derives Serialize and Deserialize on Note, CtrlEvent, CtrlKind and Sequence.
Reading
read_smf(bytes):
- converts the file's division to 960 ticks per quarter note; an SMPTE division (24, 25, 29.97 or 30 frames per second) is approximated at 120 bpm;
- pairs note-ons with note-offs: running status, note-on with velocity 0 as note-off, overlapping notes of one pitch first in first out, an unmatched note-off ignored, a note still sounding at the end of its track closed there, a zero-length note given one tick;
- folds the leading conductor track of a format-1 file (no notes, no channel events) into the file-wide lists; its name is not kept;
- skips unknown chunks, unknown meta events and System Exclusive events;
- accepts a header track count that differs from the number of
MTrkchunks and reads every chunk present.
Input is hostile. Every length is checked against the data that is left, a variable-length
quantity is at most four bytes, and a file is refused beyond MAX_TRACKS (4096) track chunks or
MAX_EVENTS (5,000,000) events. Malformed structure (bad header, truncated chunk, a data byte
without running status, a system real-time status in a track) is a MidiError, never a panic.
Reading a damaged file
read_smf_lenient(bytes) returns a LenientRead: the Smf, a list of warnings (at most
MAX_WARNINGS, 32), the Instrument Name of each track and end, the last tick any track
reaches (its End of Track). It does not fail on damage after the header. Only a file that is not a Standard MIDI File
(no MThd, a header cut short, an unusable division) is an error. Otherwise:
- a header length beyond the file is ignored; an unknown format is read as format 1;
- a track whose events stop making sense (cut short, a data byte without a status, a system message, the event limit reached) keeps what came before, and its open notes end there; a track without End of Track is kept with a warning;
- a track length beyond the file reads the rest of it; a length that disagrees with the track's End of Track is not believed, and the next chunk is looked for where the events ended;
- bytes that are no chunk are skipped to the next
MTrk; trailing bytes are ignored; - past
MAX_TRACKSthe rest is left out; lyrics are counted in a warning; a format-2 file is read side by side, with a warning saying so.
On a sound file both readers return the same Smf and the lenient one no warnings. The lenient
rules come from LoopCraft's reader.
Writing
write_smf(&smf) writes format 1 at 960 ticks per quarter note: a conductor track with tempos,
meters, key signatures and markers, then one track per SmfTrack. When smf.format is 0 it writes format 0: all of that in one track. Negative ticks are clamped to
0 and data bytes to their MIDI ranges; a note-on velocity of 0 is written as 1. Notes of one
pitch that overlap are trimmed so that the file reads back with the same starts, and of two that
start together the longer is written. An invalid tempo, a meter denominator that is not a power
of two, more than 65535 tracks or a gap beyond the 28-bit delta limit is an error.
Sources and clean room
Written from the public Standard MIDI Files 1.0 specification (the MIDI Association). No other
product's code, assets or strings were used. The code comes from SoundCraft's soundcraft-midi
crate; the tests build every file they read in code, so the crate ships no binary test data.