suaveplan/openspec/archive/2026-05-23-enterprise-midi/proposal.md

@suaveplan/midi — universal MIDI primitives

• Target path: packages/media/audio/midi/
• Tier: universal (zero browser/Node coupling)
• Date: 2026-05-23
• Status: PROPOSED

Why

The audio family ships codecs, plugins, analysers, an engine, and a React surface — but no MIDI primitives. Every downstream surface that wants to drive plugin parameters via control surfaces (@suaveplan/react-control-surface), accept input from hardware controllers (Maschine, Traktor, KORG nanoKONTROL), expose virtual instruments (SoundFont synth, drum machines), or replicate parameter state across a network session needs a shared MIDI vocabulary. Without this package every consumer hand-rolls byte parsers and types, which inevitably diverges (status nibble vs. channel masking, running status, SysEx framing edge cases, NRPN vs. RPN dispatch).

This change introduces a universal-tier, zero-runtime-dependency package owning the canonical MIDI types, byte parsers, message constructors, CC/NRPN/RPN/Pitch/SysEx dispatchers, GM/GS/XG patch tables, MIDI 1.0 + MIDI 2.0 UMP differentiation, and a structural MidiPortLike contract that browser/Node adapters implement. No Web MIDI calls live here — that lives in @suaveplan/react-midi (browser) and a future @suaveplan/midi-node (server).

What changes

1. NEW package @suaveplan/midi at packages/media/audio/midi/.
2. Message types — MidiMessage discriminated union: NoteOn, NoteOff, PolyPressure, ControlChange, ProgramChange, ChannelPressure, PitchBend, SystemExclusive, TimeCode, SongPosition, SongSelect, TuneRequest, Clock, Start, Continue, Stop, ActiveSensing, Reset. Each carries the parsed fields (channel 1-16 or null for system messages, plus type-specific payload).
3. Encoders / decoders — encodeMessage(msg): Uint8Array, decodeMessage(bytes, offset): { msg, next }. Round-trip property tests via fast-check. Handles running-status decode (when a stream omits the status byte and reuses the previous one).
4. High-level dispatch — NRPNState and RPNState reducers that accumulate the four-CC dance into a single NRPNChange / RPNChange event. Same for 14-bit CCs (MSB + LSB on pairs 0-31 / 32-63).
5. SysEx framing — SysExFrame type + universal manufacturer-id registry (Yamaha, Roland, Korg, NI, Ableton, generic non-commercial). parseSysEx(bytes), buildSysEx(manufacturer, deviceId, payload).
6. Port contract — MidiPortLike { send(bytes): void; onMessage(handler): Unsubscribe; name: string; id: string; manufacturer?: string; state: "connected" | "disconnected" }. Adapters in @suaveplan/react-midi (Web MIDI) and future @suaveplan/midi-node (node-midi) implement this.
7. MIDI Clock helpers — clockToBpm(intervalsMs[]): number, bpmToClock(bpm): clockMs. 24 PPQN per the spec.
8. General MIDI tables — GM Level 1 (128 patches + 128 percussion notes), GM2 extensions, GS/XG dialects as separate exported tables.
9. MIDI 2.0 UMP — Universal MIDI Packet framing types (UMP32, UMP64, UMP96, UMP128), high-resolution velocity/CC, per-note controllers. Encode/decode + bridge helpers (midi1ToUmp, umpToMidi1 where lossless).
10. Error codes — MIDI.{INVALID_MESSAGE, INVALID_SYSEX, BUFFER_UNDERRUN, UNSUPPORTED_UMP_VARIANT, NRPN_INCOMPLETE} via defineCodes.
11. OTel instrumentation — counter midi_messages_decoded_total{type}, histogram midi_decode_duration_ns{type}.

Impact

• New package; nothing else changes today.
• Unblocks @suaveplan/react-midi (browser Web MIDI adapter), @suaveplan/audio-fx-plugin-spessasynth (consumes MIDI for SF2 playback), @suaveplan/control-surface-schema (bindings can reference MIDI CC/note ids), @suaveplan/network-midi (transport over WebRTC/WebSocket).
• Zero external runtime deps beyond @suaveplan/error + @suaveplan/types + tslib + zod.

Out of scope (later changes)

• Web MIDI API access — @suaveplan/react-midi.
• Node MIDI access — @suaveplan/midi-node (Wave 3+).
• Wire transport — @suaveplan/network-midi.
• SoundFont loading — @suaveplan/audio-fx-plugin-spessasynth.