skills/plugins/library-navigator/skills/sp-audio-controllers/SKILL.md

name, description

name	description
sp-audio-controllers	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:

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:

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

Bind to FX parameter:

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