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.