---
name: sp-audio-controllers
description: MIDI hardware controller plugins — Kontrol S88, Maschine, Traktor S4. MidiControllerPlugin base, hot-plug FSM, sequencer, arpeggiator, CC-mapping DSL, LED feedback, bindParameter integration.
---

# sp-audio-controllers

| Symbol | Kind | Responsibility |
|---|---|---|
| `MidiControllerPlugin` | Class | Base class for MIDI hardware controller plugins with hot-plug FSM |
| `createConnectionMachine` | Function | FSM factory for MIDI connection lifecycle (disconnected → connecting → connected → error) |
| `KontrolS88Plugin` | Class | Native Instruments Kontrol S88 integration with LED color and scale modes |
| `MaschinePlugin` | Class | Native Instruments Maschine integration with sample loading |
| `TraktorS4Plugin` | Class | Native Instruments Traktor S4 DJ controller integration with deck tracking |
| `Sequencer` | Class | Transport-synced step sequencer with `StepCallback` |
| `Arpeggiator` | Class | Transport-synced arpeggiator with multiple arp modes |
| `captureNextLearn` | Function | Learn mode — captures the next incoming CC message and returns a `LearnResult` |
| `bindParameter` / `bindPluginPreset` | Function | Binds a MIDI source to an audio-fx parameter or preset |
| `AUDIO_CONTROLLERS_CODES` | Constant | Error-code registry via `@suaveplan/error` `defineCodes` |

**File Structure:** `packages/media/audio/audio-controllers/src/{base,plugins,sequencer,arpeggiator,learn,binding,error-codes}/`

**Sibling packages:**
- `@suaveplan/audio-fx-plugin-base` — FX plugin base (bindParameter target)
- `@suaveplan/audio-transport` — transport sync for sequencer/arpeggiator
- `@suaveplan/fsm` — hot-plug connection state machine
- `@suaveplan/midi` — MIDI message parsing and generation

**Patterns:**

*Quick Start:*
```ts
import { KontrolS88Plugin } from "@suaveplan/audio-controllers/plugins/kontrol-s88";
const controller = new KontrolS88Plugin({ adapter: webMidiAdapter });
await controller.connect();
controller.setLED(0, { r: 255, g: 0, b: 0 });
```

*Learn mode:*
```ts
import { captureNextLearn } from "@suaveplan/audio-controllers/learn";
const result = await captureNextLearn(controller); // { cc, channel, value }
```

*Bind to FX parameter:*
```ts
import { bindParameter } from "@suaveplan/audio-controllers/binding";
bindParameter({ cc: 1, channel: 0 }, filterPlugin.cutoff);
```

**Constraints:**
- `MidiAccessAdapter` is injectable for testability (Web MIDI API wrapper)
- Hot-plug FSM via `@suaveplan/fsm` handles connect/disconnect/reconnect
- Subpath exports: `/base/midi-controller-plugin`, `/plugins/kontrol-s88`, `/plugins/maschine`, `/plugins/traktor-s4`, `/sequencer/sequencer`, `/arpeggiator/arpeggiator`, `/learn/learn-mode`, `/binding`, `/error-codes`
- Sequencer and arpeggiator are transport-synced via `@suaveplan/audio-transport`
- LED feedback is bidirectional — controller state reflected on hardware LEDs

**Checklist:**
- [ ] `MidiControllerPlugin` base handles connection lifecycle via FSM
- [ ] `KontrolS88Plugin` sets LED colors and scale modes correctly
- [ ] `Sequencer` fires step callbacks in sync with transport
- [ ] `captureNextLearn` returns the next incoming CC message
- [ ] `bindParameter` maps MIDI CC to FX parameter with smooth interpolation