Everything Twist Commando can do, and how.

Getting started

1. Move Twist Commando to your Applications folder and open it. It lives in the menu bar: click its icon to open the window.
2. Plug in your Twister. The window's header says Connected, and Twist Commando reads the Twister's own settings (push modes, ring styles, MIDI numbers, brightness) so you don't set anything twice.
3. Click a knob's line under its ring to pick what it controls. That's it: turn the knob.

The Twister's own setup

Twist Commando works with the Twister's factory settings. If you've changed them in the Midi Fighter Utility, keep these in mind:

• Encoders should send CC (absolute), not relative messages.
• Switch action can be CC Hold (the factory setting), CC Toggle, Note Hold or Note Toggle. Hold modes allow long press, double press and push-and-turn.
• Every knob needs its own number. Two knobs sharing one would drive the same setting.

Settings › Twister lists anything set on the Twister that would stop a knob working. When you change settings in the Utility, Twist Commando reads them again a few seconds later.

Sharing the Twister

Knobs you haven't assigned are left alone: Twist Commando never sends them anything, so another app (UA Midi Control, a DAW) can keep using them. To reserve a knob for another app, lock it (the lock in its corner, or right-click › Lock Knob) and note what uses it.

The window

The window shows one bank at a time as a 4 × 4 grid, laid out like the Twister (knob 1 top-left). Each card draws the knob's ring as the Twister shows it, with the switch colour below and a line saying what it does.

• Banks: the pills 1 2 3 4 switch banks, on the Twister too. The window follows when you change banks on the hardware. Click the bank's title to name it.
• Knob settings open beside the window: double-click a knob, click the selected knob again, or use the sliders button in the header.
• Copy and paste a knob's setup from its right-click menu.
• Keep it open: click the pin, or drag the window by an empty spot. Unpinned, it closes when you click elsewhere or press Esc.
• Header buttons: knob settings, scenes, meter view, Shift, the pin, and a "…" menu with Settings, Resync LEDs, LED Test and Quit.

Keyboard: the arrow keys move between knobs, Return opens the knob's settings, L locks or unlocks it, ⌘Z / ⇧⌘Z undo and redo any change, and ⌘, opens Settings.

Setting up a knob

A knob's settings have three parts:

• Header: its name (click to rename; unnamed knobs are named after what they control), its icon, and its switch colours: Off for while it's unlit and On for while it's lit. The ⇧ button edits its Shift layer.
• Control: what it controls and what that needs (a channel, a light, a shortcut), with its status.
• Press: what pressing does, the switch LED, and gestures.

Colours use the Twister's own colour wheel, and are sent to its switch LEDs so the hardware matches the window. Off turns the LED dark.

What knobs control

Settings › General › Targets hides the ones you don't use from the menus.

System volume

Turning sets your Mac's output volume; pressing mutes. The switch lights while muted, and the on-screen indicator names the output device. To switch outputs from a knob, use a wheel of audio outputs.

Spotify and Apple Music

Turning sets the player's volume; pressing plays or pauses. The switch lights while music plays, and follows when you pause in the app itself. The knob shows the app's icon. The first time, macOS asks to let Twist Commando control the app: click OK.

UA Console

Twist Commando talks to UAD Console directly (no MIDI setup, no UA Midi Control). Pick a channel, what turning adjusts and what pressing toggles:

• Map a whole bank at once: "…" › Map UA Console Channels… fills the bank with your Console channels in Console's order: fader to turn, mute to press, and optionally a send or pan on each knob's Shift layer.
• Learn: click Learn… in a knob's settings and move a fader or switch in Console.
• Coming from UA Midi Control: Settings › UA Console imports its Twister mappings.
• Solo: a soloed channel's switch blinks, and the other channels' rings dim while they're silenced by the solo.

Changes made in Console or on the Apollo show on the rings straight away. Levels show in real units (−6.2 dB). Phantom power (48V) isn't offered on purpose.

Philips Hue

In Settings › Philips Hue, click Connect next to your bridge and press the bridge's round button within 30 seconds. Then a Hue knob can control a light, room or zone:

• Knob controls brightness (all the way down turns it off), colour, saturation or colour temperature. Put two knobs on one room for brightness and colour.
• Pressing switches it on and off; the switch shows the light's own colour.
• Changes from the Hue app, a switch or an automation show within a second.

Apple Shortcuts

A Shortcut knob can run up to three shortcuts: one on press, one while turning, and a status shortcut that reads the state back onto the ring and switch every few seconds. Each run gets a small JSON input:

{"event": "turn", "value": 62, "previous": 59, "delta": 3, "on": true, "bank": 1, "knob": 5}

What a shortcut returns updates the knob: a number 0–100 sets the ring, on / off sets the switch, or return both as {"value": 45, "on": true}. Good for HomeKit lights and scenes; each run takes a moment, so it's less suited to fast audio control.

Keyboard shortcuts

Sends a key combination per step of turning (one for each direction) and one on press, or a media key like Volume, Next or Play/Pause. That makes any app with keyboard shortcuts controllable, such as SoundSource's per-app volume. Record the combination in Twist Commando first, then assign it in the other app. Needs Accessibility permission.

Run Command

Runs shell commands in your login shell, so your PATH and ssh keys work as in Terminal:

• On press: e.g. ssh amp 'power on'.
• On turn: with TWIST_VALUE (0–100), TWIST_PREVIOUS and TWIST_DELTA.
• Level from: a command whose output sets the ring (a number) and switch (on/off), after use or every few seconds.

Wheel

A Wheel knob opens a radial menu in the middle of the screen, like a game's weapon wheel. Hold the knob, turn to an item and let go; or turn to open it, turn to an item and press. Landing on No Choice, or leaving it for 4 seconds, cancels. A wheel can show:

• My Items: up to seven apps to open, shortcuts, key presses, commands or audio outputs.
• Audio Outputs: your Mac's output devices, with the current one marked.
• App Switcher: macOS's own ⌘-Tab switcher. A quick press switches to the last app.

Wheel Speed in the "…" menu sets how much turning moves one item.

Presses and gestures

Switch LED sets what the switch shows: LED = state lights it while the target is on (muted, playing, light on), inverted lights it while off, and Twister LED leaves it to the Twister.

With a hold switch action (the factory CC Hold), each knob can do more:

• Push + turn: turning while holding the knob gives fine adjust (a quarter of the speed) or switches the knob to its Shift layer until you let go.
• Long press (half a second) and double press can open an app, run a shortcut, press keys, set a level, recall a scene, toggle Shift, or on UA Console knobs reset the level or toggle another switch (tap to mute, hold to solo).

With a double press set, a single press acts a moment later, once it's clear no second press is coming.

Shift layers

Any knob can have a Shift layer: a second setup with its own target, press and colours. While Shift is on, those knobs use it, and their rings and switches show it. For example, a knob's main layer controls a channel's fader and mute in cyan, its Shift layer the channel's AUX 1 send in amber.

Switch Shift with:

• the ⇧ button in the window's header;
• a side button: Settings › Buttons › Shift › Learn…, then press it (toggles, or follows the button while you hold it);
• the Twister's own shift (a side button set to Shift in the Midi Fighter Utility);
• a gesture (Toggle Shift on a long or double press), or push + turn for one knob at a time.

Meters

The meter view (the waveform button in the header, or a side button learned in Settings › Buttons) turns every UA Console knob's ring into its channel's live meter. Presses still work, so you can mute while you watch levels; turning does nothing until you switch it off.

Settings › General › Meters adds meters for Spotify, Music and System Volume knobs, from what those apps are playing. macOS asks once for permission; Twist Commando only reads levels and never records.

Scenes

A scene saves the knobs in all banks or the ones you choose, and brings them back later. The theatre-masks button in the header saves and restores them; Settings › Scenes renames, updates and removes them.

• Recall (on for new scenes) also sets what the knobs control: Hue lights, volumes, Spotify and Music.
• With Recall off, a scene only repaints the rings, e.g. after the Midi Fighter Utility reset them.

On-screen indicator

Turning or pressing a knob briefly shows what it controls and its new value, like macOS's volume indicator: DJ Mixer · AUX 1 −6.2 dB, Spotify Playing, Living Room 40%. Only your own turns and presses show it. Settings › General puts it in one of nine spots on screen, in the menu bar next to the icon, or turns it off.

Settings

Permissions

macOS asks for each of these the first time a feature needs it. None are needed for MIDI.

• Automation: controlling Spotify and Music.
• Accessibility: sending keys, and the App Switcher.
• Local Network: finding and controlling your Hue bridge.
• Audio capture: only if you turn on meters for apps.

If you declined one, turn it on under System Settings › Privacy & Security, or use Settings › Permissions.

Troubleshooting

A knob's presses fire at the wrong time

The knob's switch action on the Twister doesn't match what Twist Commando expects. Twist Commando reads it from the Twister, so check Settings › Twister for a warning, and Read Again after changing it in the Midi Fighter Utility.

The rings don't match

Choose Resync LEDs from the "…" menu. It re-reads every value (from UA Console too, without changing anything there) and repaints the rings.

"Twister not found"

Check the USB cable, then choose Rescan MIDI Devices from the "…" menu.

Spotify or Music knobs do nothing

Twist Commando needs Automation permission for them: System Settings › Privacy & Security › Automation › Twist Commando.

Two knobs move together

They share a MIDI number. The window marks them with a warning; give each its own number in the Midi Fighter Utility.