Initial Commit

packages/media/audio/audio-controllers/README.md

@@ -0,0 +1,75 @@
+# @suaveplan/audio-controllers - Universal MIDI hardware controller plugins (Kontrol S88, Maschine, Traktor S4): MidiControllerPlugin base with injectable MidiAccessAdapter, hot-plug FSM via @suaveplan/fsm, transport-synced Sequencer + Arpeggiator, CC-mapping DSL, learn mode, LED feedback, bindParameter integration with @suaveplan/audio-fx-plugin-base, AUDIO_CONTROLLERS.* error registry, full OTel surface.
+
+Universal MIDI hardware controller plugins. Built on
+`@suaveplan/audio-core`, `@suaveplan/audio-transport`, `@suaveplan/events`,
+`@suaveplan/fsm`, and `@suaveplan/audio-fx-plugin-base`. Ships three
+concrete controllers (Kontrol S88, Maschine, Traktor S4) plus a shared
+`MidiControllerPlugin` base, `Sequencer`, `Arpeggiator`, learn-mode helper,
+and `bindParameter` integration with the FX plugin family.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [arpeggiator](./src/arpeggiator/arpeggiator.md) — `Arpeggiator` is the transport-synced note-walker shared between the Kontrol S88's hardware arpeggio mode and any consu…
+  - [arpeggiator](./src/arpeggiator/arpeggiator.md) — `Arpeggiator` is the transport-synced note-walker shared between the Kontrol S88's hardware arpeggio mode and any consu…
+- [connection-fsm](./src/base/connection-fsm.md) — Builds the controller connection-state machine consumed by every `MidiControllerPlugin`. The FSM models the lifecycle o…
+- [midi-controller-plugin](./src/base/midi-controller-plugin.md) — The abstract `MidiControllerPlugin` is the universal base class shared by every concrete MIDI controller integrati…
+- [otel](./src/base/otel.md) — Centralises the OpenTelemetry surface consumed by every module in the package. The `getControllerOtel()` accessor lazil…
+- [binding](./src/binding/bind-parameter.md) — `bindParameter` wires a typed `MidiSource` (a controller CC, note-velocity, or future hardware source) to a parameter o…
+  - [bind-parameter](./src/binding/bind-parameter.md) — `bindParameter` wires a typed `MidiSource` (a controller CC, note-velocity, or future hardware source) to a parameter o…
+- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical `AUDIO_CONTROLLERS.*` error-code registry for the `@suaveplan/audio-controllers` package. Every e…
+  - [error-codes](./src/error-codes/error-codes.md) — Defines the canonical `AUDIO_CONTROLLERS.*` error-code registry for the `@suaveplan/audio-controllers` package. Every e…
+- [learn](./src/learn/learn-mode.md) — Functional helper around the `MidiControllerPlugin.enterLearnMode` / `exitLearnMode` toggle. The base class natively sw…
+  - [learn-mode](./src/learn/learn-mode.md) — Functional helper around the `MidiControllerPlugin.enterLearnMode` / `exitLearnMode` toggle. The base class natively sw…
+- [kontrol-s88](./src/plugins/kontrol-s88/kontrol-s88.md) — `KontrolS88Plugin` is the concrete `MidiControllerPlugin` subclass for Native Instruments Kontrol S88 MK2/MK3 — an 88-k…
+  - [kontrol-s88](./src/plugins/kontrol-s88/kontrol-s88.md) — `KontrolS88Plugin` is the concrete `MidiControllerPlugin` subclass for Native Instruments Kontrol S88 MK2/MK3 — an 88-k…
+- [maschine](./src/plugins/maschine/maschine.md) — `MaschinePlugin` is the concrete `MidiControllerPlugin` subclass for Native Instruments Maschine: a 16-pad grid with pe…
+  - [maschine](./src/plugins/maschine/maschine.md) — `MaschinePlugin` is the concrete `MidiControllerPlugin` subclass for Native Instruments Maschine: a 16-pad grid with pe…
+- [traktor-s4](./src/plugins/traktor-s4/traktor-s4.md) — `TraktorS4Plugin` is the concrete `MidiControllerPlugin` subclass for the Native Instruments Traktor Kontrol S4 MK3 — a…
+  - [traktor-s4](./src/plugins/traktor-s4/traktor-s4.md) — `TraktorS4Plugin` is the concrete `MidiControllerPlugin` subclass for the Native Instruments Traktor Kontrol S4 MK3 — a…
+- [sequencer](./src/sequencer/sequencer.md) — `Sequencer` is the transport-synced step engine consumed by every `MidiControllerPlugin`. It schedules every active ste…
+  - [sequencer](./src/sequencer/sequencer.md) — `Sequencer` is the transport-synced step engine consumed by every `MidiControllerPlugin`. It schedules every active ste…
+<!-- end:auto-docs -->
+
+## Shipped controllers
+
+- `KontrolS88Plugin` — 88-key weighted keyboard with scale modes, arp,
+  pitch-bend, mod-wheel, and per-key RGB LED feedback.
+- `MaschinePlugin` — 16-pad grid with per-pad velocity, step sequencer
+  rows, and slot-based sample loading.
+- `TraktorS4Plugin` — 4-channel DJ controller with mixer, crossfader, and
+  four decks.
+
+## Features
+
+- Injectable `MidiAccessAdapter` seam — the package never reaches for
+  `navigator.requestMIDIAccess` directly, so tests run under happy-dom
+  with a fake-device fixture and zero mocks.
+- Connection-state FSM via `@suaveplan/fsm` with hot-plug recovery.
+- Declarative CC mapping DSL with Zod-validated bytes.
+- Learn mode for runtime CC capture.
+- Transport-synced sequencer and arpeggiator — sample-accurate, offline
+  renderable, no `setInterval`.
+- OpenTelemetry counters, histograms, and spans (no-op without an exporter).
+- Zod schemas at every public boundary.
+- Six `AUDIO_CONTROLLERS.*` error codes with severity metadata.
+
+## Subpath exports
+
+| Path | Module |
+|---|---|
+| `.` | barrel |
+| `./base/midi-controller-plugin` | `MidiControllerPlugin` + types |
+| `./sequencer/sequencer` | `Sequencer` |
+| `./arpeggiator/arpeggiator` | `Arpeggiator` |
+| `./learn/learn-mode` | `captureNextLearn` |
+| `./binding` | `bindParameter`, `bindPluginPreset` |
+| `./plugins/kontrol-s88` | `KontrolS88Plugin` |
+| `./plugins/maschine` | `MaschinePlugin` |
+| `./plugins/traktor-s4` | `TraktorS4Plugin` |
+| `./error-codes` | `AUDIO_CONTROLLERS_*` registry |
+
+## Status
+
+`0.1.0` — Wave 1 migration. 100/100/100/100 coverage.
+