Create your first button covers a single action on Press. This page covers everything beyond that: running several actions per press, branching on a condition, repeating actions while a condition holds, generating a whole row of buttons from one, and using an encoder's rotation as an action's input.
Every action handler (Press, Release, Single click, Double click, Left, Right, Encoder, and any Hold group) runs its actions as numbered steps.
Select + next to Step 1 to add another step, or Duplicate Step to start from a copy of the current one.
Once there's more than one step, Reorder Steps and Delete Step appear next to them.
Double-click a step's name to rename it.
The cogwheel holds two settings for the whole button:
Relative Delays (on by default): each action's delay counts from when the previous action started. Turn it off to count every delay from when the button was pressed.
Auto Progress (on by default, once there's more than one step): advances to the next step on every press, instead of always running the same step.
A button can react to the moment it goes down, to how long it's held, or to how many times it's tapped. Pick the pattern that matches what the operator should do:
You want
Use
Real-world example
One action, the instant the button goes down
Press
A camera button on a cut bus: the cut happens the moment the button is hit.
One thing on a quick tap, something else on a longer hold
Short release plus a Hold group
Tap to put a camera on Preview, hold to cut it straight to Program.
An action that needs a deliberate hold, so brushing the button can't fire it
A Hold group with Run while held on
Fade to Black only after the button has been held for a full second.
Several actions on one button, picked by how long it's held
Several Hold groups
Play, stop, or record on one recorder button.
One thing on a single tap, something else on two quick taps
Single click and Double click
Tap to show a lower third, double-tap to show the full-screen version.
An action that a single stray tap must never fire
Double click on its own
Double-tap to release every route on a monitor wall.
Fire different actions based on how long a button is held#
Select Hold in the Add Action Handler row to add a duration-based action group, useful for a button that should do one thing on a quick tap and something else on a longer press.
Each Hold group has its own threshold in milliseconds, shown in its header: Release after 700ms while Run while held is off, Hold 700ms when it's on. Once at least one group exists, the plain Release handler relabels itself Short release to make clear it now only covers a press shorter than every configured group.
Run while held (off by default for a new group) decides when the group's actions fire:
Off: the group's actions fire on release, but only if the button was held at least that long, and only for the longest group whose threshold was reached. A shorter group's actions don't also fire.
On: the group's actions fire as soon as the button has been held that long, without waiting for release. If the button is released afterward, that same group's actions don't fire a second time.
Add more than one Hold group to cover several thresholds at once: for example a 1000 ms group and a 3000 ms group on the same button give you a short, a long and a longer press.
Important
Press still fires the instant the button goes down, on every press, including one that goes on to become a hold. For a tap-or-hold button, put the tap action on Short release, not Press. Keep Press for something that should happen either way, or leave it empty.
A camera button for a director who wants one button per camera:
Short release: put Camera 3 on Preview.
Hold group, 700 ms, Run while held off: cut Camera 3 to Program.
A quick tap previews Camera 3. Holding the button for at least 0.7 s and letting go cuts Camera 3 straight to air, without previewing it first. If the preview action were on Press instead, the long press would preview Camera 3 as well as cutting it.
Fade to Black takes the whole programme off air, so it shouldn't fire from a brushed button:
Leave Press and Short release empty.
Hold group, 1000 ms, Run while held on: Fade to Black.
A brush or a quick tap does nothing. Held for a full second, the fade starts at the one-second mark, without waiting for release, so the operator can see it has fired and let go. Add the Button Pushed feedback to the same button so it lights while held, which shows the operator the hold is registering.
Example: short, long, and longer press on one recorder button#
Three actions on one button, with the least common and most disruptive action behind the longest hold:
Short release: Play.
Hold group, 1000 ms, Run while held off: Stop.
Hold group, 3000 ms, Run while held off: Record.
With Run while held off, only the longest group reached fires, and only on release: a 3-second hold starts recording without also stopping first.
Groups with Run while held on each fire as their own threshold passes, while the button is still down. On release, Buttons fires the longest group reached, unless that group had Run while held on: it already fired, so nothing more happens on release.
For a button with a 1000 ms group that has Run while held on and a 3000 ms group that has it off:
Released after
What fires
Less than 1 s
Short release
Between 1 s and 3 s
The 1000 ms group, at the one-second mark. Nothing more on release.
More than 3 s
The 1000 ms group at the one-second mark, then the 3000 ms group on release.
A threshold counts as reached only once the press is strictly longer than it.
Select Single and/or Double in the Add Action Handler row for a simpler alternative to Press/Release: a Single click handler fires on any press you let go of, and a Double click handler fires on two quick taps close together. Use them on their own or alongside Press, Release, and Hold: they don't replace each other, they're an independent way of reacting to the same button.
A press held for 5 seconds or longer is never a click: this safety cap keeps a stuck or forgotten press from firing Single click or starting a Double click.
With only Single click configured, it fires as soon as you release, no matter how long the press was (short of the 5-second cap).
With only Double click configured, two presses each under 400 ms, released within 400 ms of each other, fire it. A lone tap with no second press within that window fires nothing.
With both configured, a quick tap (under 400 ms) waits up to 400 ms for a second quick tap: a second one arriving in time fires Double click; otherwise Single click fires once the window closes. A press of 400 ms or longer fires Single click immediately, since it can't be the first half of a double click.
Single click and Double click stay pinned to the step you were on when you pressed, even if Press or Release has since auto-progressed to a different step.
Warning
Single click fires on any release under 5 seconds, even after a hold that has already fired a Hold group. A 2-second hold on a button with a 1000 ms Hold group and a Single click handler fires both. For a tap-or-hold button, use Short release for the tap, not Single click.
Example: tap for a lower third, double-tap for the full-screen version#
A graphics button:
Single click: show the name lower third.
Double click: show the full-screen version of the same graphic.
Because both are configured, a quick tap waits up to 0.4 s to see whether a second tap follows before it shows the lower third. That short pause is the price of having both on one button. A press held 0.4 s or longer can't be the first half of a double-tap, so it shows the lower third straight away.
When the 0.4 s pause isn't acceptable, pair Double click with Press instead of Single click:
Press: put Camera 2 on Preview.
Double click: cut Camera 2 to Program.
Press has no delay, so one tap previews Camera 2 at once. A double-tap previews it twice (harmless) and then cuts it to air. This only works because the Press action is safe to repeat.
Example: double-tap only, for an action a stray tap mustn't fire#
A monitor-wall button that releases every route on the wall:
Double click: release the routes.
No other handlers.
A single tap does nothing. So do two taps more than 0.4 s apart, and a held press. Only a deliberate, quick double-tap releases the wall.
Add an ActionLogic the same way, from the ActionLogic button next to ActionGroup. It has three parts:
Condition: drop in any feedback, or the Internal Expression feedback to test a variable directly, such as $(time.hh) >= 12.
When true: actions that run only when the condition is true.
Else: actions that run when it isn't.
Select the condition to see its live state: a lit bulb when it's true, and for an Expression, the result under the expression, such as = true. This lets you confirm it evaluates the way you expect before relying on it. Unlike a button feedback, a condition has no Preview section or Test button, because a condition never styles the button. Stack more than one ActionLogic to test several conditions in the same step.
Add a While from the While button next to ActionLogic to repeat actions for as long as a condition holds. It has two parts:
Condition: drop in one or more feedbacks, the same way as for an ActionLogic. The condition is true only when every feedback in it is true.
While true: the actions to repeat. They run one after another, in order.
Buttons checks the condition, runs the While true actions if it's true, and checks again. The loop ends the first time the condition is false. If it's false at the start, the actions don't run at all.
Warning
Buttons doesn't pause between rounds. Give at least one action under While true a delay, or the loop repeats as fast as it can. A While also stops after 10,000 rounds, even if the condition is still true. An empty Condition counts as true, so it always runs to that limit.
For example, to fade a level down step by step:
Condition: an Internal Expression feedback testing the level, such as $(Mini.audio_input_1301_left_faderGain) > -40 for Mic 1 on an ATEM Mini.
While true: Fairlight Audio: Adjust fader gain on Mic 1 with a Delta of -1, and a Delay of 100 ms.
Each press lowers the fader 1 dB every 0.1 s until it reaches -40 dB, then stops. To stop a running While early, use the Internal Abort Button Actions action from another button.
When an action's own field is a dropdown of choices (such as an ATEM input selector), its ... menu offers Create Button Repeater from choices. This turns the button into a master, and generates one button per choice in the dropdown, each targeting a different value.
The Repeater tab (visible once a repeater exists) lists every Action Repeater or Feedback Repeater feeding the layout under Data Sources: a button can combine a repeated action with a repeated feedback, as long as both use the same option list, so the two stay aligned row for row.
Direction controls whether generated buttons lay out left-to-right or top-to-bottom.
Customize Data & Labels opens an editor with two views: Generated Buttons shows exactly what will be created and lets you hide entries you don't need or override a specific button's label, icon, or color; All Available Data is for aligning more than one data source by hand when their choices don't naturally correspond row for row. Sort sets the order of the generated buttons, and Default Label Source picks which data source names them.
Inside the repeated buttons' own text or actions, reference the position with:
$(self.repeatIndex): the button's position in the generated set, starting at 0.
$(self.repeatDataId): the underlying value of that button's choice.
$(self.repeatDataLabel): the display label of that button's choice.
A repeat index can also be substituted directly into another variable's own name using % as a placeholder, for example $(mixer.channel_name%) on the button repeated at index 3 reads as $(mixer.channel_name3). This is a repeater-specific substitution, separate from the general nested-variable mechanisms in Understand nested variables; use a literal \% if you need an actual percent sign in the same field.
Turn on the Encoder action handler to use a surface's encoder (such as a Stream Deck Studio or Stream Deck Plus) instead of, or alongside, Press and Release:
Initial, Min, and Max set the encoder's range; Current shows its live value once applied.
Assignment decides which physical encoder controls this button: Click Select (press the button to assign the nearest free encoder, the default), a specific location, or a specific encoder number.
Display shapes how the encoder's LED ring reflects the value: Single (one LED lit per step), Start/End (LEDs fill from one end), or Split (a pan/balance-style indicator).
Active Style controls how the assigned button itself looks while assigned: Highlight (a white outline, the default), Ignore (no change), or Value on white background (shows the live value and text on a white background).
To send the turned value to an action, select the encoder button next to a field that offers one: the field becomes Encoder Value. You can also reference the value as $(self.encoderValue), using the action field's expression mode. For example, an action expecting 0–255 from an encoder ranging 0–20 could use $(self.encoderValue) * 12.75.
When an encoder action's own field is a dropdown of choices, its ... menu also offers Create Encoder Selector from choices, turning the encoder into a direct selector across those choices, rather than a numeric range. Reference the selected choice with $(self.encoderSelectorValue) (the value) and $(self.encoderSelectorLabel) (the label).
Hold Shift and select a button in the editor to fire its actions directly: the same Execute Mode used elsewhere in the editor. You can also run a single action from inside its own settings, without touching the button at all.
