# Build more capable button actions

> Run several steps per press, react to hold and click patterns, group, condition or repeat actions, generate repeater buttons, and use encoders.

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. Before you begin A button with at least one action added. See Create your first button . Run more than one action 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. Choose how the button reacts 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. Example: tap to preview, hold to take 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. Example: guard a destructive action 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. Mixing both kinds of Hold group 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. Fire an action on a single or double click 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. Example: instant preview, double-tap to cut 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. Group actions together Add an ActionGroup (from + Add Action... 's own ActionGroup button, alongside the recently-used-actions list) to run several actions as one unit: Mode : Concurrent runs every action in the group at once; Sequential runs them one after another. Group Delay : a delay applied to the whole group before it starts. Drop actions into the group's own Actions list, either from + Add Action... inside it or by dragging an existing action in. Run an action only when a condition is true 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. Repeat actions while a condition is true 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. Generate a row of buttons from one 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. Use an encoder's rotation as a value 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 . Let the encoder pick from a dropdown directly 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). Test without a surface 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. If you get stuck What you see What to try A repeated button's action targets the wrong choice. Confirm the Repeater's Data Sources entry actually points at the field you meant: a button can have more than one dropdown field. An encoder action doesn't respond to any physical encoder. Check Assignment : with Click Select , you need to press the button first to claim a free encoder before turning it. An ActionGroup's actions don't run in the order you expect. Check Mode : Concurrent runs them all at once; only Sequential guarantees order. A While seems to fire all at once, or stops early. Add a delay to an action under While true : without one, the loop doesn't pause between rounds and can reach its 10,000-round limit almost at once. A step's delay doesn't line up with the others. Check Relative Delays under the step cogwheel: when it's on, each delay counts from the previous action; when it's off, from the button press. Where to go next Add feedback so a button reflects real state , for the same set of ideas applied to feedback. Button Inspector reference , for every field on the Design and Repeater tabs. Understand nested variables .