skills/docs/media/audio/audio-controllers/README.md

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

Documentation tree

• arpeggiator — Arpeggiator is the transport-synced note-walker shared between the Kontrol S88's hardware arpeggio mode and any consu…
  • arpeggiator — Arpeggiator is the transport-synced note-walker shared between the Kontrol S88's hardware arpeggio mode and any consu…
• connection-fsm — Builds the controller connection-state machine consumed by every MidiControllerPlugin. The FSM models the lifecycle o…
• midi-controller-plugin — The abstract MidiControllerPlugin is the universal base class shared by every concrete MIDI controller integrati…
• otel — Centralises the OpenTelemetry surface consumed by every module in the package. The getControllerOtel() accessor lazil…
• binding — bindParameter wires a typed MidiSource (a controller CC, note-velocity, or future hardware source) to a parameter o…
  • bind-parameter — bindParameter wires a typed MidiSource (a controller CC, note-velocity, or future hardware source) to a parameter o…
• error-codes — Defines the canonical AUDIO_CONTROLLERS.* error-code registry for the @suaveplan/audio-controllers package. Every e…
  • error-codes — Defines the canonical AUDIO_CONTROLLERS.* error-code registry for the @suaveplan/audio-controllers package. Every e…
• learn — Functional helper around the MidiControllerPlugin.enterLearnMode / exitLearnMode toggle. The base class natively sw…
  • learn-mode — Functional helper around the MidiControllerPlugin.enterLearnMode / exitLearnMode toggle. The base class natively sw…
• kontrol-s88 — KontrolS88Plugin is the concrete MidiControllerPlugin subclass for Native Instruments Kontrol S88 MK2/MK3 — an 88-k…
  • kontrol-s88 — KontrolS88Plugin is the concrete MidiControllerPlugin subclass for Native Instruments Kontrol S88 MK2/MK3 — an 88-k…
• maschine — MaschinePlugin is the concrete MidiControllerPlugin subclass for Native Instruments Maschine: a 16-pad grid with pe…
  • maschine — MaschinePlugin is the concrete MidiControllerPlugin subclass for Native Instruments Maschine: a 16-pad grid with pe…
• traktor-s4 — TraktorS4Plugin is the concrete MidiControllerPlugin subclass for the Native Instruments Traktor Kontrol S4 MK3 — a…
  • traktor-s4 — TraktorS4Plugin is the concrete MidiControllerPlugin subclass for the Native Instruments Traktor Kontrol S4 MK3 — a…
• sequencer — Sequencer is the transport-synced step engine consumed by every MidiControllerPlugin. It schedules every active ste…
  • sequencer — Sequencer is the transport-synced step engine consumed by every MidiControllerPlugin. It schedules every active ste…

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.