Module audio::midi

real-time MIDI I/O (in the spirit of RtMidi).

API                 platform        backend file
MIDI_API_ALSA       Linux           midi_alsa_linux.sc     (ALSA sequencer, libasound loaded at run time)
MIDI_API_JACK       Linux, macOS    midi_jack_posix.sc     (JACK MIDI, libjack loaded at run time)
MIDI_API_COREMIDI   macOS           midi_coremidi_macos.sc
MIDI_API_WINMM      Windows         midi_winmm_win32.sc    (the Windows multimedia MIDI API)
MIDI_API_WEBMIDI    wasm32          midi_webmidi_wasm.sc   (+ std/audio/audio_web.js)
MIDI_API_DUMMY      everywhere      midi_dummy.sc          (an in-process loopback, for tests)

A MidiIn or MidiOut is one client of an API. It lists the system's ports, connects to one (open_port) or creates its own that other programs connect to (open_virtual_port: ALSA, JACK, Core MIDI and dummy — WinMM and Web MIDI have no virtual ports and return AUDIO_ERR_UNSUPPORTED).

struct Result<MidiIn, AudioError> r = std::MidiIn::open(MIDI_API_UNSPECIFIED, "monitor", 0UL);
struct MidiIn in = r.unwrap_or(std::MidiIn::closed());
in.open_port(0U, "in");
in.set_callback(on_midi, (?&State)&state);      // or poll: in.get_message(...)

struct MidiOut out = std::MidiOut::open(MIDI_API_UNSPECIFIED, "synth").unwrap_or(std::MidiOut::closed());
out.open_port(0U, "out");
out.send(std::MidiMsg::note_on(0, 60, 100));

Input arrives on the backend's thread (the ALSA sequencer thread std starts, JACK's process thread, Core MIDI's and WinMM's callback threads, the browser's event loop). With a callback set, it is called there with each complete message — sysex reassembled, running status expanded — and must follow the same real-time rules as an audio callback (see audio.h): no allocation, no locks, no blocking. Without one, messages go into a lock-free single-producer/single-consumer queue (sized at open, default MIDI_DEFAULT_QUEUE_BYTES) that get_message() drains from any one thread; a message that doesn't fit is dropped and counted (dropped()). Sysex, MIDI clock/time code and active sensing are filtered out by default (ignore_types(1, 1, 1)), as RtMidi does.

Timestamps are seconds since the port was opened (monotonic); each event also carries the time since the previous delivered message.