Crate sim_lib_midi_core

Expand description

Core MIDI data model and in-memory I/O for the SIM music stack.

This crate defines the protocol-agnostic MIDI types shared across the constellation: tick-based timing (TickTime), the bounded integer domains used by MIDI bytes (U7, U14, Channel), the event model (MidiEvent, MidiPayload, ChannelMessage, MetaEvent, SysExEvent), and the streaming MidiSource/MidiSink traits with in-memory implementations. It also provides the NoteEchoPlayer transform, controller-number constants, tempo conversions, and the host-registered MidiIoLib that exposes the in-memory cards to a running SIM Cx.

Higher layers (Standard MIDI File, SysEx, live transports) build on this model rather than redefining it.

§Examples

use sim_lib_midi_core::{Channel, ChannelMessage, U7};

let note = ChannelMessage::NoteOn {
    ch: Channel::new(0).unwrap(),
    key: U7(60),
    vel: U7(100),
};
assert!(matches!(note, ChannelMessage::NoteOn { .. }));

use sim_lib_midi_core::TickTime;

// 480 ticks at 480 tpq is exactly one quarter note.
let one_quarter = TickTime::new(480, 480).unwrap();
assert_eq!(one_quarter.as_f64_quarters(), 1.0);
// Rebasing to a coarser resolution is exact here.
assert_eq!(one_quarter.rebase(96).unwrap().ticks, 96);

Modules§

meta_view: Typed views over raw MetaBucket payloads.
wire: Canonical MIDI channel-message wire bytes.

Structs§

Channel: A MIDI channel number in the range 0..=15.
MemoryMidiSink: An in-memory MidiSink that collects written events in tick order.
MemoryMidiSource: An in-memory MidiSource backed by a time-sorted event vector.
MemoryTrackedMidiSource: An in-memory TrackedMidiSource backed by a time-sorted, track-tagged event vector.
MetaBucket: A raw meta event: its type byte plus payload bytes.
MidiEvent: A timestamped MIDI event with provenance.
MidiIoLib: Host-registered lib exporting the in-memory MIDI I/O cards and registry, built on the shared SurfacePackLib substrate.
NoteEchoConfig: Configuration for the NoteEchoPlayer echo/delay transform.
NoteEchoPlayer: Renders rhythmic note echoes from an input event stream per a NoteEchoConfig.
NoteEchoRender: The result of a NoteEchoPlayer render: emitted events plus per-echo traces.
NoteEchoTrace: A record of a single emitted echo, linking it back to its source note.
RawBytes: An uninterpreted run of bytes with a status byte, used as a fallback.
SmpteOffset: An SMPTE timecode offset, as carried by the SMPTE-offset meta event.
TickTime: A point in musical time measured in ticks at a given resolution.
TrackedMidiEvent: A MidiEvent tagged with the track it belongs to.
U7: A 7-bit MIDI data value in the range 0..=127.
U14: A 14-bit MIDI data value in the range 0..=16_383, as used by pitch bend.

Enums§

ChannelMessage: A MIDI channel-voice message, carrying its target Channel and payload.
MetaEvent: A meta event: track-scoped information that is not transmitted over the wire, recognised types plus an Other escape hatch.
MidiError: Errors produced when constructing or converting core MIDI values.
MidiPayload: The payload of a MidiEvent: one of the four event families.
NoteEchoChannelPolicy: Controls which channel each echoed note is emitted on.
NoteEchoScaleSnap: Controls whether echoed notes are snapped to a scale.
PumpError: An error raised while pumping events from a source into a sink, recording which side failed.
SysExEvent: A system-exclusive event, distinguished by its leading status byte.

Constants§

CC_ALL_NOTES_OFF: All Notes Off (channel mode), controller 123.
CC_ALL_SOUND_OFF: All Sound Off (channel mode), controller 120.
CC_BALANCE_MSB: Balance (MSB), controller 8.
CC_BANK_SELECT_MSB: Bank Select (MSB), controller 0.
CC_BREATH_MSB: Breath Controller (MSB), controller 2.
CC_DATA_ENTRY_MSB: Data Entry (MSB), controller 6.
CC_EXPRESSION_MSB: Expression Controller (MSB), controller 11.
CC_FOOT_MSB: Foot Controller (MSB), controller 4.
CC_LOCAL_CONTROL: Local Control On/Off (channel mode), controller 122.
CC_MOD_WHEEL_MSB: Modulation Wheel (MSB), controller 1.
CC_PAN_MSB: Pan (MSB), controller 10.
CC_PORTAMENTO_SWITCH: Portamento On/Off switch, controller 65.
CC_PORTAMENTO_TIME_MSB: Portamento Time (MSB), controller 5.
CC_RESET_ALL_CONTROLLERS: Reset All Controllers (channel mode), controller 121.
CC_SOFT_PEDAL: Soft Pedal, controller 67.
CC_SOSTENUTO: Sostenuto Pedal, controller 66.
CC_SUSTAIN_PEDAL: Sustain (damper) Pedal, controller 64.
CC_VOLUME_MSB: Channel Volume (MSB), controller 7.
DEFAULT_US_PER_QUARTER: The default MIDI tempo of 500_000 microseconds per quarter (120 BPM).

Traits§

MidiSink: A push-based sink that accepts MidiEvents at a fixed resolution.
MidiSource: A pull-based stream of MidiEvents at a fixed resolution.
TrackedMidiSource: A MidiSource that also reports per-track membership.

Functions§

bpm_to_us_per_quarter: Converts beats per minute to microseconds per quarter note (rounded).
install_midi_io_lib: Installs MidiIoLib into cx once and registers the in-memory source, sink, and tracked-source export records.
pump: Drains every event from source into sink, re-timing events to the sink’s resolution, and returns the number of events transferred.
stable_midi_event_order: Sorts events into a stable, deterministic order by time and then by a payload tiebreak (note-offs before note-ons at the same tick).
synthetic_origin: Returns an Origin tagging events synthesised by the music stack rather than read from an input codec.
us_per_quarter_to_bpm: Converts microseconds per quarter note to beats per minute.