Crate midly

Overview

midly is a Standard Midi File (SMF) parser focused on speed and flexibility, parsing multi-MB files in tenths of a second.

Usage is as simple as:

use midly::Smf;

let smf = Smf::parse(include_bytes!("../test-asset/Clementi.mid")).unwrap();

for (i, track) in smf.tracks.iter().enumerate() {
    println!("track {} has {} events", i, track.len());
}

The Smf struct is the main type in the crate. See its documentation for the structure of parsed MIDI files.

About lifetimes

The Smf struct is used to store a parsed Standard Midi File (.mid and .midi files). Notice that it has a lifetime parameter, since it stores references to the raw file bytes. For this reason, the byte buffer must be created separately to the Smf structure:

use midly::Smf;

// Load bytes into a buffer
let bytes = include_bytes!("../test-asset/Clementi.mid");

// Parse file in a separate step
let smf = Smf::parse(bytes).unwrap();

When loading a file something similar has to be done:

use std::fs;
use midly::Smf;

// Load bytes into a buffer
let bytes = fs::read("test-asset/Clementi.mid").unwrap();

//Parse bytes in a separate step
let smf = Smf::parse(&bytes).unwrap();

About features

The mode in which the crate works is configurable through the use of cargo features. Three optional features are available: std, lenient and strict. Of these only std is enabled by default.

• The std feature

  This feature is enabled by default, and in turn enables the rayon dependency along with automatic parallelism for the Smf::parse and Smf::parse_with_bytemap functions.

  Disabling this feature with default-features = false will make the crate no_std + alloc.

• The lenient feature

  By default midly will reject obviously corrupted files, throwing an error with kind ErrorKind::Malformed. With the lenient feature enabled the parser will do a "best-effort" attempt at parsing the file, and will suppress any of these errors. Note that even though the file might parse successfully, entire tracks might be lost.

• The strict feature

  By default midly gives some leeway for uncompliant MIDI files, through the MetaMessage::Unknown event variant. Enabling the strict feature will promote these malformed events to an error of kind ErrorKind::Pedantic instead.

About generics

The Smf type is generic over T, a type implementing TrackRepr. This T indicates how should each track be represented in memory.

The default is Vec<Event>, produced by the Smf::parse method, but there are also two other methods: Smf::parse_with_bytemap and Smf::parse_lazy. Check the documentation for these methods for more information about each.

Parsing raw MIDI streams

The MIDI standard is independent from the Standard Midi File standard, even though the latter depends on the former. This means that raw, non-SMF, MIDI streams exist, for example those generating by MIDI keyboards.

midly provides partial support for parsing these MIDI messages, through the EventKind::parse method, however most System Common messages are unsupported.

Modules

number

Special-length integers used by the MIDI standard.

Structs

Error	Represents an error parsing an SMF file or MIDI stream.
Event	Represents a fully parsed track event, with delta time.
Header	A MIDI file header.
Smf	Represents a Standard Midi File (.mid and .midi files). Yields TrackRepr on a Vec, allowing for customization on what is stored in a track. References an outside byte array.
SmpteTime	Encodes an SMPTE time of the day.
TrackIter	Allows deferring track parsing for later, on a per-event basis.

Enums

ErrorKind	The type of error that occurred while parsing.
EventKind	Represents the different kinds of events.
Format	The different formats an SMF file can be.
Fps
MetaMessage
MidiMessage	Represents a MIDI message, not an event.
Timing	The timing for an SMF file. This can be in ticks/beat or ticks/second.

Traits

TrackRepr

Allows for customization on how tracks are stored in memory.