Script actions
Please note that the syntax for actions is similar to events, with two crucial differences:
Curly brackets surround actions, while parentheses surround events.
Intervals cannot be defined for actions.
{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 value for the control in the range 0-127.
-
To send the received value, use "#value#". See below.
{nrpn:_channel_,_nrpn_,_value_}
{nrpn:1,1,64}
-
channel is the Midi channel on which the command should be sent.
-
nrpn is the target control in the range 0-16.383.
-
value is the value for the control in the range 0-16.383.
-
To send the received value, use "#value#". See below.
{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).
{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 velocity in the range 0-127.
-
To send the received value as velocity, use "#value#". See below.
{noteoff:_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 velocity in the range 0-127.
-
To send the received value as velocity, use "#value#". See below.
{cp:1,64}
{cc:1,1,64}
-
channel is the Midi channel on which the command should be sent.
-
pressure is the pressure value in the range 0-127.
{pb:_channel_,_value_}
{pb:1,64}
-
channel is the Midi channel on which the command should be sent.
-
value is the pitchbend value in the range 0-16.383.
{sysex:_data_}
{sysex:F0 7F 01 06 02 F7}
-
data is the sysex data in the same format as described for the Sysex button.
-
The action can have variable references and math expressions. The result of a math expression will be limited to the range 0-127 and injected into the string as a hexadecimal value.
Example: "{sysex:F0 7F 01 #@l_v + 5# 02 F7}" will be translated to "{sysex:F0 7F 01 0F 02 F7}", assuming @l_v=10 (0F is the hexadecimal value for the decimal value 15 that is the result of the expression). If you use expressions that inject text (not mathematical values), you need to inject hexadecimal values in the range 00-7F.
{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 the 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.
- Images must be .png or .jpg.
{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: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 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 it is released, so if you set the state in the {press} event, it will be toggled when you release it.
If you use the image and text actions to supply images and labels, you can ignore the button state; it does not impact the plugin's behavior.
{wait:_time_}
{wait:100}
-
_time_ is the number of milliseconds the plugin will do nothing before proceeding with the following action.
{nextpress:_index_}
{nextpress:2}
The {nextpress} action allows you 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 starting over from the first. 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.
{key:_text_}
{key:shift+a}
The {key} action will send keystrokes to the active window. The text can be of any length and may contain references to modifiers and special characters, as described below. For Mac users, only characters available on a US keyboard are available, while Windows users can use any character. The script ignores the case used when typing the characters; if capital letters should be sent, please use the shift tag described below.
-
Modifier keys can be defined using "shift", "ctrl", "alt", "altgr", "opt", or "cmd".
-
Use the + sign to separate parts of the string, e.g. "shift+a" to send a capital A.
-
Modifiers are active up to the next + sign or the end of the string: "shift+art" => ART. "shift+a+rt" => Art.
-
Use tag words for special characters: "f1"-"f24", "num0"-"num9", "numplus", "num-", "num/", "num*", "num,", "numenter", "up", "down", "left", "right", "space", "insert", "delete", "home", "end", "enter", "escape", "pagedown", "pageup", "tab", "plus", "backspace".
-
Spaces are ignored; use "space" to send a space character.
-
Use "plus" if you want to send a plus character.
-
You cannot use the brackets used to define the script parts. ({[]}).
-
Variable references and math expressions can be used: "a+#@l_v + 5#" will send a15 (assuming @l_v is 10).