Script actions

Please note that the syntax for actions is similar to events, with two crucial differences:

  • Actions are surrounded by curly brackets, while parentheses surround events.
  • Intervals cannot be defined for actions.
Action Syntax and description
Note On
{noteon:_channel_,_note_,_velocity_}
{noteon:1,47,120}
  • _channel_ is the Midi channel on which the command should be sent.
  • _note_ is the Midi note value in the range 0-127.
  • _velocity_ is the the velocity in the range 0-127.
  • To send the received value as velocity, use "#value#". See below.
Note Off
{noteoff:_channel_,_note_,_velocity_}
{noteoff:1,42,127}
  • _channel_ is the Midi channel on which the command should be sent.
  • _note_ is the Midi note value in the range 0-127.
  • _velocity_ is the the velocity in the range 0-127.
  • To send the received value as velocity, use "#value#". See below.
Control Change
{cc:_channel_,_cc_,_value_}
{cc:1,1,64}
  • _channel_ is the Midi channel on which the command should be sent.
  • _cc_ is the target control in the range 0-127.
  • _value_ is the the value for the control in the range 0-127.
  • To send the received value, use "#value#". See below.
Program Change
{pc:_channel_,_program_,_coarse_,_fine_}
{pc:2,35}
{pc:2,35,0,2}
  • _channel_ is the Midi channel on which the command should be sent.
  • _program_ is the program in the range 0-127.
  • _coarse_ is an optional Bank Select Coarse in the range 0-127.
  • _fine_ is an optional Bank Select Fine in the range 0-127.
Please note that there are two valid alternatives for the Program Change action; either you specify it without bank select (two parameters) or with both bank select values (four parameters).
Sysex
{sysex:_data_}
{sysex:F0 7F 01 06 02 F7}
  • _data_ is the sysex data in the same format as described for the Sysex button.
Image
{image:_path_}
{image:%plugin%\Extras\Icons\Generic.png}
  • _path_ is the path to an image to be displayed on the button. Image paths are preferably defined using replacement strings as follows:
    • All environment variables defined on the computer can be used, e.g. %appdata%
    • Use %trevligaspel% to get the path to the Trevliga Spel folder in your Documents folder
    • Use %documents% to get the path to your Documents folder
    • Use %music% to get the path to your Music folder
    • Use %plugin% to get the path to your plugin folder
  • To remove previous image without adding any new image, set "image:#none#".
  • You can use either slash or backslash in the path; the plugin will adapt the used path to the current platform (Windows or macOS).
  • You can use "#value#" anywhere in the path to have individual images for each value (in which case you, of course, must have image files for all possible values). See below.
Text
{text:_text_}
{text:Press me!}
  • _text_ is any text that should be displayed on the button.
  • To display text on multiple lines, use the code "\n" (without the quotes) where you want a line break (since regular line breaks in the script are ignored). Example: "Hello\nWorld"
  • To remove previous text without adding any new text, set "text:#none#".
  • To display the received value, set "text:#value#". See below.
State
{state:_state_}
{state:0}
  • _state_ is the state the button should be set to. Valid entries are "0", "1" and "#toggle#". Use this if you have defined images and/or labels for the two states in the Stream Deck editor.
Please note that Stream Deck will default toggle between states 0 and 1 every time you press the button, so you only need to define an explicit state if you want something else to happen. If you want to set the state when the button is used, I recommend setting it in a {release} event. Stream Deck will toggle the button state when the button is released, so if you set the state in the {press} event, it will be toggled when you release the button.

If you use the image and text actions to supply images and labels, you can ignore the button state; it has no impact on the plugin behavior.
Wait
{wait:_time_}
{wait:100}
  • _time_ is the number of milliseconds the plugin will do nothing before proceeding with the following action.
Next Press
{nextpress:_index_}
{nextpress:2}
The {nextpress} action gives you the option to change the order of press events. By default, the press events are executed sequentially from the first defined (press) event to the last and then starting over from the first one. With a {nextpress} action, you can specify which (press) event to execute the next time the button is pressed, regardless of which was the last executed (press) event.
  • _index_ is the index to the press event that should be triggered the next time the button is pressed. The first defined press event has index 1; the second has index 2, and so on. If a non-existing index is referenced, the first press event will be triggered next.

Value references

For Program Change, Control Change, Note On, Note Off, Text, and Image actions, the name #value# can be used to reference the event that triggered the action. The #value# tag can be used in the second and third parameters in the actions and references the corresponding second or third parameter in the event.

Program Change actions will refererence the second parameter, while Image and Text actions will reference the third parameter in the event.

Examples:



The contents between the # characters can be a simple reference to the received value or a math expression. Some examples:

  • "[(cc:1,1,0-127){noteon:1,27,#value#}]" will cause the sent Note On command to have the same velocity as the receive control value.
  • "[(cc:1,1,0-127){noteon:1,27,#value + 3#}]" will cause the sent Note On command to have a velocity 3 steps higher than the receive control value.
  • "[(cc:1,1,0-127){text:#value - 10#}]" will cause the displayed value to be 10 steps lower than the receive control value.
The text "value" (without the quotes) must be present between the # characters; otherwise, it will not be evaluated as a math expression. If the result is lower than 0, it will be set to 0. If the result is larger than 127, it will be set to 127.

Addition, subtraction, division, and multiplication can be used. Parentheses can be used, and #(value + 3)/2# is a perfectly valid expression.