README.md

Midly

Midly is a feature-complete MIDI decoder and encoder designed for efficiency and ease of use.

See the crate-level documentation for examples, detailed documentation and available cargo features.

Features

• Supports both .mid files and real-time MIDI packets.
• Very complete, supports reading and writing while handling all edge cases in the MIDI spec.
• Simple API, just load your data and call Smf::parse or LiveEvent::parse.
• Optional no_std and no alloc support.
• Zero-copy, all MIDI types simply reference the original buffer.
• Fast! See the speed section below.

Getting started

First add the following line to your Cargo.toml file, under the [dependencies] section:

midly = "0.5"

Then use the Smf type in the crate root:

// Load bytes first
let data = std::fs::read("Pi.mid").unwrap();

// Parse the raw bytes
let mut smf = midly::Smf::parse(&data).unwrap();

// Use the information
println!("midi file has {} tracks!", smf.tracks.len());

// Modify the file
smf.header.format = midly::Format::Sequential;

// Save it back
smf.save("PiRewritten.mid").unwrap();

Or use the LiveEvent type to parse real-time MIDI events:

use midly::{live::LiveEvent, MidiMessage};

fn on_midi(event: &[u8]) {
    let event = LiveEvent::parse(event).unwrap();
    match event {
        LiveEvent::Midi { channel, message } => match message {
            MidiMessage::NoteOn { key, vel } => {
                println!("hit note {} on channel {}", key, channel);
            }
            _ => {}
        },
        _ => {}
    }
}

Most types to be imported are on the crate root and are documented in-place. Check the crate documentation for more information.

Speed

Although performance is not critical in a MIDI library, it still is an important objective of the midly library, providing automatic multithreading for large files and minimal allocations. The following chart presents benchmark results against other MIDI libraries in the ecosystem capable of reading .mid files.

File name	File size	rimd 0.0.1	nom-midi 0.5.1	augmented-midi 1.3.0	midly 0.5.3
Clementi.mid	4 KB	4 ms	Error	0.06 ms	0.07 ms
CrabRave.mid	53 KB	4 ms	0.48 ms	0.53 ms	0.15 ms
Beethoven.rmi	90 KB	Error	Error	Error	0.48 ms
Pi.mid	24 MB	20575 ms	253 ms	214 ms	60 ms
PiDamaged.mid	64 KB	Freeze	Error	Error	0.41 ms

The above results are only referential, actual performance depends wildly on the hardware and operating system. The benchmarks were done on a Linux x64 machine with a warm file cache. The benchmark code is available in the /benchmark directory in the source.