Script events

Available events are...

  • Button initialization
  • Button press
  • Button release
  • Received Control Change command
  • Received Program Change command
  • Received Note On command
  • Received Note Off command

Button initialization event

The button initialization event is triggered when the button is loaded, either when Stream Deck starts or when a profile/page/folder with the button is loaded. The primary purpose of the init event is to prepare an image and text on the button, but any action can be executed.

Incoming Midi events

For incoming Midi events, all commands triggered by the event are run. If an incoming midi event triggers multiple commands, they are executed in the order they appear in the script.

The plugin monitors both midi commands sent from you daw and commands sent from Stream Deck buttons.

Press/release events

For button events, multiple script commands can be defined, and if so, the plugin will cycle through them one by one and loop back to the first script command after executing the last defined command. Press and release events are treated as pairs since you can't press a button without eventually releasing it.

The order of button commands is important. When the button is pressed and released, the commands will be executed in the order they appear in the script.

The following example will mimic a Hold button that plays a note while the button is held.

[(press){noteon:1,42,127}]
[(release){noteoff:1,42,127}]
If an accompanying event is missing, no action will be taken for the event. The following example will mimic a Toggle button where a note starts with the first press and stops with a second press (no actions are taken on the release events).

[(press){noteon:1,42,127}]
[(press){noteoff:1,42,127}]

Please note that many events are treated differently when used in multi-event commands. This table describes the event logic used in single-event commands; please see the Multi-event commands page for the event logic in multi-event commands.
Event Syntax and description
Button initialization
(init)
The (init) event is triggered once for each button; when the button is loaded.
Button press
(press)
(press) events are triggered when the button is pressed. Multiple (press) events can be defined; if so, the plugin will cycle through them, one (press) event for each button press. When no more (press) events are defined, the plugin starts over with the first one.
Button release
(release)
(release) events are triggered when the button is released. Each (release) event is matched with the (press) event immediately before it in the script.
(release) events are optional; if no action is required when the button is released, you don't need to define a (release) event.
Control Change
(cc:_channel_,_cc_,_value_)
(cc:1,1,64-127)
(cc:1,1,<64<)
  • _channel_ is the Midi channel on which the command can be received. You can define an interval if the event should trigger if the command is received on one of multiple channels. An interval is defined with a hyphen: "2-6".
  • _cc_ is the control in the range 0-127. You can define an interval if the event should trigger for multiple CCs. An interval is defined with a hyphen: "25-64".
  • _value_ is the value for the control in the range 0-127.
    • You can define an interval if the event should trigger for multiple values. A range is defined as "25-64".
    • You can define a transiton value using the "<>" characters. The event (cc:1,1,<64<) will trigger when the previous received value for the control was above 64 and the current received value is 64 or below. The event (cc:1,1,>64>) will trigger when the previous received value for the control was below 64 and the current received value is 64 or above.
Program Change
(pc:_channel_,_program_)
{pc:2,35}
  • _channel_ is the Midi channel on which the command can be received. You can define an interval if the event should trigger if the command is received on one of multiple channels. An interval is defined with a hyphen: "2-6".
  • _program_ is the received program in the range 0-127. You can define an interval if the event should trigger for multiple programs. An interval is defined with a hyphen: "25-64".
Note On
(noteon:_channel_,_note_,_velocity_)
(noteon:1,47,120)
  • _channel_ is the Midi channel on which the command can be received. You can define an interval if the event should trigger if the command is received on one of multiple channels. An interval is defined with a hyphen: "2-6".
  • _note_ is the midi note number in the range 0-127. You can define an interval if the event should trigger for multiple notes. An interval is defined with a hyphen: "25-64".
  • _velocity_ is the velocity for the note in the range 0-127.
    • You can define an interval if the event should trigger for multiple velocities. An interval is defined with a hyphen: "25-64".
    • You can define a transiton velocity using the "<>" characters. The event (noteon:1,1,<64<) will trigger when the previous received velocity for the note was above 64 and the current received velocity is 64 or below. The event (noteon:1,1,>64>) will trigger when the previous received velocity for the note was below 64 and the current received velocity is 64 or above.
Note Off
(noteoff:_channel_,_note_,_velocity_)
(noteoff:1,42,127)
  • _channel_ is the Midi channel on which the command can be received. You can define an interval if the event should trigger if the command is received on one of multiple channels. An interval is defined with a hyphen: "2-6".
  • _note_ is the midi note number in the range 0-127. You can define an interval if the event should trigger for multiple notes. An interval is defined with a hyphen: "25-64".
  • _velocity_ is the velocity for the note in the range 0-127.
    • You can define an interval if the event should trigger for multiple velocities. An interval is defined with a hyphen: "25-64".
    • You can define a transiton velocity using the "<>" characters. The event (noteoff:1,1,<64<) will trigger when the previous received velocity for the note was above 64 and the current received velocity is 64 or below. The event (noteoff:1,1,>64>) will trigger when the previous received velocity for the note was below 64 and the current received velocity is 64 or above.
Time
(time)
The (time) event displays timing information in various ways. Please note that this is a display-only event; only {text} actions are executed, and other kinds of actions are ignored.

  • Song position can be displayed. For this to work, your daw must be configured to send Midi Timecode.
  • BPM can be displayed. For this to work, your daw must be configured to send Midi Clock.
{text} actions have a special syntax valid for the (time) event only:

  • #value# will display song position on two lines; the first line has hours and minutes, and the second has seconds and frames.
  • Individual parts of the time information can be formatted using key letters between the # characters.
    • H = hours
    • M = minutes
    • S = seconds
    • F = frames
    • R = frame rate
    • B = bpm
Individual parts can be mixed freely. The following two commands will produce the same results:
  • [(time){text:#value#}]
  • [(time){text:#H.M\nS.F#}]
Frame rate is displayed as one of the following strings: "24 fps", "25 fps", "30 fps(df)", or "30 fps".

BPM is a calculated number based on the frequency of Midi Clock commands received from the daw. Midi Clock timing isn't perfect, and to avoid having a BPM number that fluctuates if the timing is off, the plugin calculates a mean value over time. This gives a more stable BPM number but also means that it will take some second(s) to adjust when the BPM actually changes in the daw.