Controllers

The Controllers view is where you map a physical MIDI controller (faders, knobs, buttons, LEDs) to your show, without writing a script. Open it from the Controllers tab in the top toolbar, next to Wiring, Stage and Logic.

It is the no-code counterpart to the Logic view: the same hardware-to-control wiring you could hand-write as a script is offered here as a visual surface, with bidirectional LED feedback handled for you.

How a controller is detected

Stagewright ships controller profiles, declarative descriptions of known hardware (the AKAI MIDI Mix is the first). A profile knows the device's physical layout: which control sends what, and which note lights each LED.

A controller appears in the Controllers view automatically when a MIDI-in card on the Wiring view is assigned a device whose name matches a profile. For the AKAI MIDI Mix, that is the card named MIDI Mix. The same logical name a script would use with midi.input('MIDI Mix') is what the view matches on, so a profile keeps working across rigs as long as the card name stays the same.

Every matching card is listed in the left rail, so several controllers can be configured side by side.

Nothing in the Controllers view yet?

If the rail is empty, add a MIDI-in card in the Wiring view and pick your controller as its device. The view refreshes when you open the tab.

What you map to: stage controls

Each hardware control is mapped to a stage control, the knobs, faders and buttons you place on the Stage. The dropdown lists them by their on-screen label; behind the scenes each is addressed by its Name (set in the control's inspector), which is the same identifier a script uses with widget('NAME'). See Widgets API for the underlying model.

So the chain is: hardware control, to stage control, to whatever that control is itself bound to (a plugin parameter, a mixer strip, a script macro). The stage control stays the single source of truth, and the view, the hardware and any script all stay in sync through it.

Mapping a control

1. Pick the device in the left rail.
2. For a button (mute / solo / rec), choose a stage control from its dropdown. The button's signature is already known from the profile, so the binding is immediate, and the LED lights to match the control's current state.
3. For a fader or knob, the profile cannot know the CC under your personal controller remap, so the view learns it: pick a control, then move the fader/knob once. Stagewright captures the CC live and binds it.

Choosing — none — removes the mapping.

LED feedback, automatic

When a mapped button's control changes (from the hardware, the UI, or a script), Stagewright sends the matching LED message back to the device. This is the bidirectional feedback an AKAI MIDI Mix script would normally hand-roll with sendNoteOn; here it falls out of the profile. The on-screen dot on each slot mirrors the hardware LED.

Feedback runs for the lifetime of the app, not just while the view is open, so the lights stay correct during a show with the Controllers tab closed.

Persistence

Mappings are saved in the project file (under the per-project extras) and restored on load, keyed by the device's card name so two controllers never collide. On load, Stagewright replays the bindings and re-syncs the device LEDs to the project's state.

Relationship to scripting

Anything the Controllers view does can also be expressed in the Logic view, and the two coexist: use the view for the common cases (buttons to mutes, faders to volumes, LEDs that track state) and drop into a script for bespoke logic (exclusive-solo groups, macro pairs, conditional routing). See MIDI input & output for the scripting equivalent.