Crate sim_lib_midi_smf

Expand description

Standard MIDI File (SMF) reading and writing for the SIM music stack.

This crate parses the on-disk .mid/.smf byte format into the in-memory SmfFile model and serialises it back, reusing the event types from sim_lib_midi_core. It covers the three SMF formats (SmfFormat), the variable-length quantity encoding (encode_vlq/decode_vlq), running status, and track canonicalisation/merging. Reading is read_smf; writing is write_smf (or write_smf_with_options for running-status control). Metrical and valid SMPTE divisions are retained losslessly.

§Examples

Round-tripping a minimal single-track file:

use sim_lib_midi_smf::{
    read_smf, write_smf, SmfDivision, SmfFile, SmfFormat, SmfTrack,
};
use sim_lib_midi_core::{
    MetaEvent, MidiEvent, MidiPayload, TickTime, synthetic_origin,
};

let file = SmfFile {
    format: SmfFormat::SingleTrack,
    division: SmfDivision::metrical(480).unwrap(),
    tracks: vec![SmfTrack {
        events: vec![MidiEvent {
            time: TickTime::new(0, 480).unwrap(),
            origin: synthetic_origin(),
            payload: MidiPayload::Meta(MetaEvent::EndOfTrack),
        }],
    }],
};
let bytes = write_smf(&file).unwrap();
let parsed = read_smf(&bytes).unwrap();
assert_eq!(parsed.format, SmfFormat::SingleTrack);
assert_eq!(parsed.division, SmfDivision::metrical(480).unwrap());

The variable-length quantity codec is reversible:

use std::io::Cursor;
use sim_lib_midi_smf::{decode_vlq, encode_vlq};

let bytes = encode_vlq(0x4000);
assert_eq!(decode_vlq(&mut Cursor::new(bytes)).unwrap(), 0x4000);

Structs§

SmfFile: A parsed Standard MIDI File: its format, time division, and tracks.
SmfMergeCursor: An iterator that merges all tracks of an SmfFile into a single time-ordered, track-tagged stream.
SmfReadLimits: Defensive resource bounds applied while parsing an SMF byte slice.
SmfTrack: One track: an ordered list of timestamped events.
SmfWriteOptions: Options controlling SMF serialisation.

Enums§

SmfDivision: The lossless time-division field from an SMF header.
SmfError: Errors raised while reading or writing a Standard MIDI File.
SmfFormat: The SMF header format field: how the file’s tracks relate.
SmfLimitKind: Defensive parser resources that can be bounded with SmfReadLimits.
SmfTempoMaps: Tempo-map topology implied by an SMF file’s format.
SmfTimeSemantics: How track-local event times relate in an SMF format.
SmpteRate: A valid SMPTE frame rate encoded by the signed high byte of an SMF division.

Statics§

RECIPES: Cookbook recipes for this lib, embedded at build time.

Functions§

decode_vlq: Decodes a MIDI variable-length quantity from reader.
encode_vlq: Encodes value as a MIDI variable-length quantity (big-endian, 7 bits per byte with the high bit marking continuation).
read_smf: Parses a complete Standard MIDI File from bytes using defensive default resource bounds.
read_smf_with_limits: Parses a complete Standard MIDI File from bytes under explicit resource bounds.
write_smf: Serialises file to SMF bytes using default options.
write_smf_with_options: Serialises file to SMF bytes under the given SmfWriteOptions.