Crate midly

Overview

midly is a full-featured MIDI parser and writer, focused on performance.

Parsing a .mid file can be 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());
}

Parsing Standard Midi Files (.mid files)

Parsing Standard Midi Files is usually done through the Smf struct (or if working in a no_std environment without an allocator, through the parse function).

Note that most types in this crate have a lifetime parameter, because they reference the bytes in the original file (in order to avoid allocations). For this reason, reading a file and parsing it must be done in two separate steps:

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();

Writing Standard Midi Files

Saving .mid files is as simple as using the Smf::save method:

// Parse file
let bytes = fs::read("test-asset/Clementi.mid").unwrap();
let smf = Smf::parse(&bytes).unwrap();

// Rewrite file
smf.save("test-asset/ClementiRewritten.mid").unwrap();

SMF files can also be written to an arbitrary writer:

let mut in_memory = Vec::new();
smf.write(&mut in_memory).unwrap();

println!("midi file fits in {} bytes!", in_memory.len());

Parsing standalone MIDI messages

When using an OS API such as midir, LiveEvent can be used to parse the raw MIDI bytes:

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);
            }
            _ => {}
        },
        _ => {}
    }
}

Writing standalone MIDI messages

Raw MIDI message bytes can be produced for consumption by OS APIs, such as midir, through the LiveEvent::write method:

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

fn note_on(channel: u8, key: u8) {
    let ev = LiveEvent::Midi {
        channel: channel.into(),
        message: MidiMessage::NoteOn {
            key: key.into(),
            vel: 127.into(),
        },
    };
    let mut buf = Vec::new();
    ev.write(&mut buf).unwrap();
    write_midi(&buf[..]);
}

About features

The following cargo features are available to enable or disable parts of the crate:

• parallel (enabled by default)

  This feature enables the use of multiple threads when parsing large midi files.

  Disabling this feature will remove the dependency on rayon.

• std (enabled by default)

  This feature enables integration with std, for example implementing std::error::Error for midly::Error, support for writing to std::io::Write streams, among others.

  Disabling this feature will make the crate no_std.

• alloc (enabled by default)

  This feature enables allocations both for ergonomics and performance.

  Disabling both the std and the alloc feature will make the crate fully no_std, but will reduce functionality to a minimum. For example, the Smf type is unavailable without the alloc feature. All types that are unavailable when a feature is disabled are marked as such in their documentation.

• strict

  By default midly will attempt to plow through non-standard and even obviously corrupted files, throwing away any unreadable data, or even entire tracks in the worst scenario. By enabling the strict feature the parser will reject uncompliant data and do additional checking, throwing errors of the kind ErrorKind::Malformed when such a situation arises.

Modules

io

Provides abstractions over writers, even in no_std environments.

live

Provides utilities to read and write “live” MIDI messages produced in real-time, in contrast with “dead” MIDI messages as stored in a .mid file.

num

Exotically-sized integers used by the MIDI standard.

stream

Provides support for the niche use case of reading MIDI events from a non-delimited stream.

Macros

stack_buffer

Define a stack buffer type, suitable for use with MidiStream.

Structs

Arena

Helps overcome limitations of the lifetime system when constructing MIDI events and files.

Error

Represents an error while parsing an SMF file or MIDI stream.

EventBytemapIter

An iterator over the events of a single track that keeps track of the raw bytes that make up each event. Created by the EventIter::bytemapped method.

EventIter

An iterator over the events of a single track. Yielded by the TrackIter iterator.

Header

A MIDI file header, indicating metadata about the file.

PitchBend

The value of a pitch bend, represented as 14 bits.

Smf

Represents a single .mid Standard Midi File. If you’re casually looking to parse a .mid file, this is the type you’re looking for.

SmfBytemap

A .mid Standard Midi File, but keeps a mapping to the raw bytes that make up each event.

SmpteTime

A timestamp encoding an SMPTE time of the day.

TrackEvent

Represents a parsed SMF track event.

TrackIter

An iterator over all tracks in a Standard Midi File. Created by the parse function.

Enums

ErrorKind

The type of error that occurred while parsing.

Format

The order in which tracks should be laid out when playing back this SMF file.

Fps

One of the four FPS values available for SMPTE times, as defined by the MIDI standard.

MetaMessage

A “meta message”, as defined by the SMF spec. These events carry metadata about the track, such as tempo, time signature, copyright, etc…

MidiMessage

Represents a MIDI message, usually associated to a MIDI channel.

Timing

The timing for an SMF file. This can be in ticks/beat or ticks/second.

TrackEventKind

Represents the different kinds of SMF events and their associated data.

Functions

parse

Parse a raw MIDI file lazily, yielding its header and a lazy track iterator. No allocations are made.

write

Encode and write a generic MIDI file into the given generic writer. The MIDI file is represented by a header and a list of tracks.

write_std

Similar to write, but writes to a std::io::Write writer instead of a midly::io::Write writer.

Type Definitions

BytemappedTrack

A track, represented as a Vec of events along with their originating bytes.

Result

The result type used by the MIDI parser.

Track

A single track: simply a list of track events.