Crate midly[−][src]
Expand description
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 implementingstd::error::Error
formidly::Error
, support for writing tostd::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 thealloc
feature will make the crate fullyno_std
, but will reduce functionality to a minimum. For example, theSmf
type is unavailable without thealloc
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 thestrict
feature the parser will reject uncompliant data and do additional checking, throwing errors of the kindErrorKind::Malformed
when such a situation arises.
Modules
io | Provides abstractions over writers, even in |
live | Provides utilities to read and write “live” MIDI messages produced in real-time, in contrast
with “dead” MIDI messages as stored in a |
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 |
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 | An iterator over the events of a single track.
Yielded by the |
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 |
SmfBytemap | A |
SmpteTime | Encodes 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 |
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 |
Type Definitions
BytemappedTrack | A track, represented as a |
Result | The result type used by the MIDI parser. |
Track | A single track: simply a list of track events. |