# @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.