first commit
This commit is contained in:
90
docs/media/audio/midi/README.md
Normal file
90
docs/media/audio/midi/README.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# @suaveplan/midi - Universal MIDI primitives: 18-variant MidiMessage discriminated union, encode/decode with running-status, NRPN/RPN/CC14 reducers, SysEx framing with manufacturer registry, MidiPortLike contract, MIDI Clock helpers, General MIDI tables (Level 1, Level 2, GS, XG), and MIDI 2.0 UMP framing with lossless MIDI1<->UMP bridge. Zero browser/Node coupling.
|
||||
|
||||
Universal MIDI primitives for the Suaveplan platform. Owns the canonical types, byte parsers, message constructors, control-surface dispatchers (NRPN, RPN, 14-bit CC), SysEx framing with a manufacturer-id registry, MIDI Clock helpers, the General MIDI Level 1 / Level 2 / GS / XG patch tables, MIDI 2.0 UMP framing with a lossless MIDI1 ↔ UMP bridge, and an OpenTelemetry-shaped (structural) instrumentation surface. Zero browser/Node coupling — Web MIDI access lives in `@suaveplan/react-midi`, node-midi access in a future `@suaveplan/midi-node`.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [clock](./src/clock/clock.md) — Helpers for converting between MIDI Clock ticks, beats, and tempo. MIDI 1.0 defines 24 pulses per quarter note (`PPQN =…
|
||||
- [clock](./src/clock/clock.md) — Helpers for converting between MIDI Clock ticks, beats, and tempo. MIDI 1.0 defines 24 pulses per quarter note (`PPQN =…
|
||||
- [cc14](./src/dispatch/cc14.md) — `CC14Reducer` accumulates paired MIDI 1.0 control-change messages into 14-bit values. The wire convention is: CCs 0..31…
|
||||
- [nrpn](./src/dispatch/nrpn.md) — `NRPNReducer` accumulates the four-CC "dance" that MIDI 1.0 uses to express Non-Registered Parameter Number changes int…
|
||||
- [rpn](./src/dispatch/rpn.md) — `RPNReducer` is the sister of `NRPNReducer` for Registered Parameter Numbers — the parameter MSB and LSB CC numbers mov…
|
||||
- [running-status](./src/dispatch/running-status.md) — `RunningStatusDecoder` is the streaming MIDI 1.0 decoder that honours running status — the wire convention where succes…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines the `MidiError` class and the `MIDI_CODES` namespaced registry used by every `@suaveplan/midi` module that rais…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — Defines the `MidiError` class and the `MIDI_CODES` namespaced registry used by every `@suaveplan/midi` module that rais…
|
||||
- [gs](./src/gm/gs.md) — Roland's GS dialect predates GM2 and uses Bank-Select LSB (CC 32) to select instrument variations on top of the GM1 bas…
|
||||
- [level1](./src/gm/level1.md) — The General MIDI Level 1 patch and percussion tables — the canonical instrument-name lookups every GM-compliant playbac…
|
||||
- [level2](./src/gm/level2.md) — General MIDI Level 2 added a bank-select-driven variation layer on top of GM1. Each GM1 program (0..127) gains optional…
|
||||
- [xg](./src/gm/xg.md) — Yamaha's XG dialect uses Bank-Select MSB (CC 0) to select instrument variations on top of the GM1 base programs — the i…
|
||||
- [decode](./src/message/decode.md) — `decodeMessage` parses one MIDI 1.0 message starting at a given offset in a `Uint8Array` and returns both the typed mes…
|
||||
- [encode](./src/message/encode.md) — `encodeMessage` converts a strongly-typed `MidiMessage` value into the byte sequence a MIDI 1.0 wire format expects. It…
|
||||
- [sysex](./src/sysex/sysex.md) — `parseSysEx` and `buildSysEx` are the canonical helpers for working with MIDI System Exclusive payloads — the manufactu…
|
||||
- [manufacturers](./src/sysex/manufacturers.md) — The manufacturer-id registry maps the bytes that follow `F0` in a SysEx frame to a human-readable name. The MIDI Manufa…
|
||||
- [sysex](./src/sysex/sysex.md) — `parseSysEx` and `buildSysEx` are the canonical helpers for working with MIDI System Exclusive payloads — the manufactu…
|
||||
- [telemetry](./src/telemetry/telemetry.md) — OpenTelemetry-shaped instrumentation for `@suaveplan/midi` without taking a runtime dependency on `@opentelemetry/api`.…
|
||||
- [telemetry](./src/telemetry/telemetry.md) — OpenTelemetry-shaped instrumentation for `@suaveplan/midi` without taking a runtime dependency on `@opentelemetry/api`.…
|
||||
- [ump](./src/ump/ump.md) — MIDI 2.0 introduces the Universal MIDI Packet (UMP) format — fixed-width 32, 64, 96, or 128 bit packets that carry MIDI…
|
||||
- [ump](./src/ump/ump.md) — MIDI 2.0 introduces the Universal MIDI Packet (UMP) format — fixed-width 32, 64, 96, or 128 bit packets that carry MIDI…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/midi
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import {
|
||||
decodeMessage,
|
||||
encodeMessage,
|
||||
RunningStatusDecoder,
|
||||
} from "@suaveplan/midi";
|
||||
|
||||
// Encode a NoteOn.
|
||||
const bytes = encodeMessage({
|
||||
type: "noteOn",
|
||||
channel: 0,
|
||||
note: 60,
|
||||
velocity: 100,
|
||||
});
|
||||
|
||||
// Decode a buffer with running-status enabled.
|
||||
const decoder = new RunningStatusDecoder();
|
||||
decoder.push(bytes);
|
||||
const messages = decoder.drain();
|
||||
// messages = [{ type: "noteOn", channel: 0, note: 60, velocity: 100 }]
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [error-codes](./src/error-codes.md) — `MidiError` and stable `MIDI.*` code registry.
|
||||
- [message/encode](./src/message/encode.md) — `encodeMessage`, `STATUS` byte constants.
|
||||
- [message/decode](./src/message/decode.md) — `decodeMessage` with optional running-status.
|
||||
- [dispatch/running-status](./src/dispatch/running-status.md) — streaming decoder honouring MIDI 1.0 running status + real-time interleaving.
|
||||
- [dispatch/nrpn](./src/dispatch/nrpn.md) — Non-Registered Parameter Number reducer.
|
||||
- [dispatch/rpn](./src/dispatch/rpn.md) — Registered Parameter Number reducer.
|
||||
- [dispatch/cc14](./src/dispatch/cc14.md) — paired-CC 14-bit reducer.
|
||||
- [sysex/sysex](./src/sysex/sysex.md) — `parseSysEx`, `buildSysEx`, `SysExFrame`.
|
||||
- [sysex/manufacturers](./src/sysex/manufacturers.md) — manufacturer-id registry + `lookupManufacturer`.
|
||||
- [clock/clock](./src/clock/clock.md) — `bpmToClock`, `clockToBpm`, `PPQN`.
|
||||
- [gm/level1](./src/gm/level1.md) — General MIDI Level 1 patch + percussion tables.
|
||||
- [gm/level2](./src/gm/level2.md) — GM2 variation bank lookup.
|
||||
- [gm/gs](./src/gm/gs.md) — Roland GS variation lookup.
|
||||
- [gm/xg](./src/gm/xg.md) — Yamaha XG variation lookup.
|
||||
- [ump/ump](./src/ump/ump.md) — MIDI 2.0 UMP framing + MIDI1 ↔ UMP bridge.
|
||||
- [telemetry/telemetry](./src/telemetry/telemetry.md) — structural OTel-compatible counter + histogram.
|
||||
|
||||
## Tier and dependencies
|
||||
|
||||
- Tier: **universal** — no `window`, no `navigator`, no `node:*`.
|
||||
- Runtime deps: `@suaveplan/error`, `@suaveplan/types`, `tslib`, `zod`.
|
||||
- Test deps: `@suaveplan/testing`, `fast-check`.
|
||||
- No `@opentelemetry/api` runtime dep — OTel is consumed structurally per `MidiTelemetry`.
|
||||
|
||||
## Coverage gate
|
||||
|
||||
`bunx turbo test:coverage --filter=@suaveplan/midi` enforces 100/100/100/100 (statements / branches / functions / lines).
|
||||
|
||||
Reference in New Issue
Block a user