Advanced scripting - Multi-event commands

As the name suggests, a multi-event command is a command with multiple events that can trigger the command. Any number of events can be included in the command. The basic principle is that one of the events will trigger the command, at which time the plugin checks if the states of the other events are met.

By definition, two events cannot happen at the same time. Even if you have multiple midi events that happen within the same millisecond, they don't happen at the same time. For every event that happens, that event alone is the event that triggers the command, and all the other events in that command are states rather than events.

If all events are fulfilled, the actions in the command are executed. An example:

[ (press)(cc:1,1,127) {text:Yeah} ]

For the text action to be executed, both events (press) and (cc) must be met, which will happen in the following two situations:

  • When the button is pressed, and the latest received value for CC1 is 127.

  • When CC1 value 127 is received while the button is pressed.

If either of those situations occurs, the text action will be executed.

If any of the events fail, the actions are not executed; this will be the case:

  • When the button is pressed, and the latest received value for CC1 is unknown or something other than 127.

  • When CC1 value 127 is received while the button is not pressed.

Script execution rules

One script command can trigger other commands in the same or other scripts. Several rules control how script commands interact to get an expected behavior and avoid script loops. To do this, the plugin keeps track of the "command chain" (i.e., the chain of commands triggering each other) and makes decisions based on the contents of the command chain.

  • A script command can only execute once (in a command chain). When a command is triggered, the plugin checks the command chain to see if that very same command has already been executed, and if so, ignores the command. This is done to avoid command loops.

  • If a (press) event has started the command chain, no other commands containing (press) events will be executed. This is done to avoid illogical behavior; you probably expect a single (press) command to be executed when you press the button.

  • Commands containing an (init) event are only executed when the button is loaded (i.e., when the profile/page is loaded or when the Stream Deck software is starting). Other events in the (init) command are evaluated when the button is loaded, but they will not trigger a command execution by themselves.

Events in multi-event commands

In a multi-event command, some events work differently than those in a single-event command. The following list outlines the rules for using events in a multi-event command.

(init)

(init) events can be used in multi-event commands, and the (init) event is the only event that can trigger the command.

You can have multiple (init) commands combined with various midi events or custom value events, but please note that the (init) commands are only executed when the button is loaded. If you have midi events in a multi-event command with (init), the states of those midi controls are checked when the button is loaded, but the command is not triggered when those midi commands are received.

(time), (press) and (release) events are ignored if used in a multi-event command with (init).

When midi controls and custom variables have not yet received any values (e.g., when the profile is loaded as a part of the Stream Deck start-up), the value 0 is returned.

#value# references in multi-event commands

If actions in a multi-event command reference #value# or time values, they will always reference the first defined event in the command, regardless of which event triggered the command. This gives the following guidelines:

  • A (time) event must always be the first event in a multi-event command; otherwise, references to received time values will not work.

  • (press) and (release) events must not be the first event if they are present in multi-event commands with value references since they have no values.

Event value references in multi-event commands

If actions in a multi-event command reference event values (e.g., @event_ccvalue, @event_notevelocity), they will always reference the first defined event of the referenced type (CC or NoteOn/NoteOff in the example) in the command, regardless of which event triggered the command.