Control surfaces: MIDI and keyboard shortcuts
You can drive the app from the keyboard and from MIDI controllers (pad controllers, fader boxes, keyboards). Both run the same set of actions, and each action does exactly what the matching button in the app does, with the same checks and the same error messages in the status bar.
A Stream Deck (through an OBS plugin such as Multi OBS Controller or OBS Tools) and other obs-websocket tools use the same actions through the remote-control server: see Remote control.
Actions
| Action | What it does |
|---|---|
| Start / stop all outputs | Starts every enabled output when nothing is live; otherwise stops everything (Outputs ▸ Start all / Stop all). |
| Start all outputs | Outputs ▸ Start all. Each output that fails is listed in the status bar. |
| Stop all outputs | Outputs ▸ Stop all. |
| Start / stop streaming | The Controls panel’s Start streaming / Stop streaming button. |
| Start streaming, Stop streaming | The same, one way only (starting while live does nothing). |
| Start / stop recording | The Controls panel’s Start recording / Stop recording button. |
| Start recording, Stop recording | The same, one way only. |
| Next scene, Previous scene | Steps through the scene list, wrapping at either end. Normally the scene goes to Program with its transition (like the scene’s ▶ button). In Studio mode it becomes the Preview scene instead (like clicking the scene’s name), so you still press Publish — unless auto-publish is on. |
| Toggle / Enter / Exit Studio mode | The Studio mode toggle above the preview. Turning it off is refused while Preview has edits you have not taken or discarded. |
| Master output level (fader) | Moves the mixer’s Master fader. |
| Microphone level (fader) | Moves the Microphone strip’s fader (the default input). |
Starting an output, switching scenes and Studio mode wait until the app has finished discovering sources at launch, and starts wait while Settings are being applied; the status bar says so. Stopping always works.
Fader positions use the mixer’s own fader scale: from −60 dB just above the bottom to +12 dB at the top, in a straight line in dB. So 0 dB is a little over four-fifths of the way up. The bottom stop itself (a hardware fader at 0, or the on-screen fader dragged all the way down) is off: the strip is silent and reads −∞ dB.
Keyboard shortcuts
These are the default hotkeys; Settings ▸ Hotkeys changes them. Menu items show each action’s current key.
| macOS | Windows / Linux | Action |
|---|---|---|
| ⌘⇧S | Ctrl+Shift+S | Start / stop streaming |
| ⌘⇧R | Ctrl+Shift+R | Start / stop recording |
| ⌘⇧A | Ctrl+Shift+A | Start / stop all outputs |
| ⌘⇧T | Ctrl+Shift+T | Toggle Studio mode |
| ⌘] | Ctrl+] | Next scene |
| ⌘[ | Ctrl+[ | Previous scene |
| ⌘⇧Y | Ctrl+Shift+Y | Save replay (the replay buffer must be running) |
Other shortcuts are unchanged: ⌘, Settings, ⌘⇧P pause/resume recording (macOS menu), ⌘⇧M detach the mixer, ⌘↩ publish Preview to Program in Studio mode, ⌘Z / ⌘⇧Z undo and redo (Ctrl on Windows and Linux). These fixed shortcuts cannot be given to another action.
Choosing your own hotkeys
Settings ▸ Hotkeys lists every action that can have a hotkey (the same actions MIDI bindings and remote control use). For each one:
- + records a new hotkey: click it, then press the keys. Esc cancels. An action can have several hotkeys.
- Click a hotkey to record a replacement, or × to remove it.
- Global makes the action’s hotkeys work while another app is in front (see below).
- Reset puts the action back to its default keys; Reset all does that for every action.
A hotkey needs ⌘, ⌥ or ⌃ (Ctrl, Alt or the Windows/Super key elsewhere), unless it is a function key (F1-F24) or a keypad key, so it never fires while you type. A hotkey that two actions share, or that a fixed shortcut already uses, shows a warning; the action higher in the list keeps it. A hotkey without ⌘/Ctrl, or with ⌥/Alt, types a character in some layouts, so while you type in a text field it is left to the field (function keys always work). Changes take effect when you press Apply.
Global hotkeys
With Global on, an action’s hotkeys also work while another app is in front. The page’s Global line says whether they do:
- macOS asks for Accessibility access the first time: press Open Accessibility Settings and turn stream-concern on under System Settings › Privacy & Security › Accessibility. Until then the hotkeys work in the app only.
- Windows registers each hotkey with the system; one that another program already uses is named on the Global line.
- Linux uses the desktop’s global shortcuts service (GNOME 48 and later, KDE Plasma 5.27 and later, Hyprland), which shows its own confirmation and may let you change the keys there. Where the desktop has none, the line says so and the hotkeys work in the app window.
MIDI
MIDI input works on macOS (CoreMIDI), Windows (the Windows multimedia MIDI API) and Linux (the ALSA sequencer). It is off until you pick an input device; until then the app opens no MIDI port.
Setting up a controller
- Connect the controller, then open Settings ▸ MIDI. The page lists the MIDI inputs the system reports. If yours is missing (you plugged it in or switched it on after opening the page), press Rescan. The app never polls for new devices, so after plugging a controller in, press Rescan (or reopen Settings). Rescan also closes and reopens the selected inputs, so it is the fix for a controller that stopped responding after being unplugged and plugged back in; Apply and Learn leave inputs that are already open alone.
- Tick the input (or inputs) to listen on.
- Press Add binding. A new binding starts as Note 0 on channel 1 running Next scene.
- Choose the Action for the row.
- Press Learn on the row, then press the pad or move the fader or knob you want. The row’s type, channel and number are filled in from the first Note On, Control Change (CC) or Program Change the controller sends (releasing a pad is ignored). While a row is listening, no binding fires, so pressing a pad to learn it does not also start your stream. Click Listening… to cancel.
- Press Apply. The app reconnects to the chosen inputs and the bindings take effect.
You can also set the type (Note, CC or Program), channel (1–16) and number (0–127) by hand, turn a binding off with its checkbox without deleting it, and remove it with ✕. Several bindings can share one trigger; they all run, in order.
Two identical controllers have the same name; the second is listed as <name> #2 (then #3…) in the order the system reports them, so each can be ticked on its own. If you unplug them and plug them back in a different order, which one is #2 can change.
Last message shows the most recent message from any connected input
(for example CC · ch 1 · controller 7 · value 64), which helps when a
controller sends something other than what its manual says. A selected input
that is not plugged in stays selected and shows not connected; it
connects on the next Rescan or Apply.
How messages trigger actions
- Buttons on notes: an action fires when the note is pressed (Note On with velocity above 0). Holding the pad does not repeat it; it fires again only after the pad is released (a Note Off, or a Note On with velocity 0). A pad that sends only Note On and never a release therefore fires once, and then not again until a Note Off for that note arrives; set such a pad to send a release (momentary / gate mode) in its editor, or bind it as CC.
- Buttons on CC: an action fires on the rising edge, when the value goes above 63 from 63 or below (the first message after Apply counts as rising if it is above 63). A pad that sends 127 when pressed and 0 when released fires once per press. A pad in toggle mode (127 on one press, 0 on the next) fires on every other press. A pad that sends 127 on every press and never a low value fires only once; switch the pad to momentary mode in its editor.
- Buttons on Program Change: fire on every Program Change message.
- Faders: the two level actions take a CC’s value, 0–127, as the fader position from bottom to top. They need a CC trigger; bound to a note or Program Change they do nothing (the page reminds you).
Messages on any channel are accepted; a binding matches only its own channel. System Exclusive, MIDI clock and other system messages are ignored.
Where the bindings are saved
Bindings are saved in your profile (profile.toml, see
Getting started) under a [midi] section, which is only
written once you set something up:
[midi]
version = 1
ports = ["nanoKONTROL2 SLIDER/KNOB"]
[[midi.bindings]]
enabled = true
action = "toggle-recording"
trigger = { kind = "note", channel = 1, note = 36 }
[[midi.bindings]]
enabled = true
action = "master-output-level"
trigger = { kind = "cc", channel = 1, controller = 7 }
Action names are start-all, stop-all, toggle-all, start-recording,
stop-recording, toggle-recording, start-streaming, stop-streaming,
toggle-streaming, next-scene, previous-scene, enter-studio-mode,
exit-studio-mode, toggle-studio-mode, save-replay, play-last-replay,
toggle-replay-buffer, master-output-level and main-input-level. Trigger
kinds are note, cc and program-change.
Channels are 1–16. A profile written by a newer version loads without error:
unknown actions and trigger kinds are kept (and saved back unchanged) but do
nothing, a version or ports value of the wrong type falls back to its
default, and a binding this version cannot read at all is skipped.
Not yet
- Lights and motor faders on the controller do not follow the app (no MIDI output).
- Faders for other mixer strips, mute buttons and “go to scene name” are not available as actions yet.
- High-resolution (14-bit) faders are read as ordinary 7-bit CC.