• _channel_ is the Midi channel on which the command should be sent.
• _cc_ is the target control in the range 0-127, or 128-160 for dual-byte commands.
• _value_ is the value for the control in the range 0-127, or 0-16383 for dual-byte commands.
• To send the received value, use #@e_ccvalue#.

Control Change actions can be defined for both single-byte ( standard) and dual-byte (14-bit) CC commands. A standard CC command has a control number ranging from 0 to 127 and a value range from 0 to 127.

A 14-bit CC command consists of two standard CC commands. The control numbers from 0 to 31 are designated to have a corresponding second command positioned 32 steps higher (from 32 to 63). These command pairs are represented as [0][32], [1][33], and so forth in plugin actions that can use dual-byte commands.  The value range for a dual-byte CC  command is 0-16383.

For the CC action, the dual-byte commands are assigned the numbers 128 to 160, with 128 representing the pair [0][32], 129 representing the pair [1][33], and so forth.

A dual-byte CC action will sequentially send both CC commands, and the value in the CC action (within the range of 0-16383) will be divided into the two commands in accordance with the MIDI standard.

• _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 #@e_nrpnvalue#

• _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.
• _fin_ is an optional Bank Select Fine in the range 0-127.
• To send the received value, use #@e_pc#

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).

• _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 use #@e_note#

• _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 use #@e_note#

• _channel_ is the Midi channel on which the command should be sent.
• _pressure_ is the pressure value in the range 0-127.
• To send the received value use #@e_cpvalue#

• _channel_ is the Midi channel on which the command should be sent.
• _value_ is the pitchbend value in the range 0-16.383.
• To send the received value use #@e_pbvalue#

• _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.

• _time_ is the number of milliseconds the plugin will do nothing before proceeding with the following action.

Please note: Using the wait action will effectively block further execution until the wait period is over. For shorter periods (like < 100ms), this is probably not a problem, but longer wait periods are better solved using timers. Consider the following case where two scripts interact:

Script1: 
[(cc:1,1,*){@ccReceived:#@e_ccvalue#}{text:#@e_ccvalue#}{value:#@e_ccvalue#}]

Script 2:
[(@ccReceived:*){wait:1000}{text:#@ccReceived#}]

When a CC message is received, script 1 will set the variable @ccReceived. This will immediately trigger the command in script 2. Script 2 will wait for 1 second before displaying the text, whereafter, the control is returned to script 1. 

The text and value updates in script 1 will be delayed by the wait command in script 2. To avoid this, you can use timers instead:

Script1: 
[(cc:1,1,*){@ccReceived:#@e_ccvalue#}{text:#@e_ccvalue#}{value:#@e_ccvalue#}]

Script 2:
[(@ccReceived:*){@t_ccReceived:restart}]
[(@t_ccReceived:1000){@t_ccReceived:pause}{text:#@ccReceived#}]

In this case, control is returned to script 1 as soon as the timer is started, so script 1 will not be affected by the delay in script 2.

 A timer can be controlled using four distinct actions:

• {@t_mytimer:run} will start a timer. If it has been running before and not being reset, it will continue to count from where it was paused. If it has not been run before or has been reset, it will start counting from zero.

• {@t_mytimer:pause} will stop/pause a timer at its current time value.

• {@t_mytimer:restart} will reset a timer and start counting from zero. A restart action can be the first action for a timer; it doesn't need to have been run before in order to be restarted.

• {@t_mytimer:reset} will stop/pause a timer and reset the time to zero.

An integer variable can store any value (...in the range -2,147,483,648 to 2,147,483,647).
Enclose the value with quotation marks to store a string in a variable.

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).

The {launch} action launches an app or a file. If a file is launched, it will be opened with the default app according to the OS settings.

{launch:_app_}  

• When an app is launched without parameters, an existing window (if any) will be opened and put into focus. If no window exists for the app, a new window is loaded.
• The app path should be enclosed in quotation marks.
• In macOS, the app must be defined with the ".app" extension. The app name can be defined with a full path or only by the name.
  Example: {launch:"Safari.app"}
• In Windows, the full path must be defined; otherwise, the plugin cannot determine if the app is already running.
  Example: {launch:"C:\Program Files\Mozilla Firefox\firefox.exe"}

{launch:_app_ , _parameters_}

• When an app is launched with parameters, a new window is always loaded.
• Example: {launch:"Safari.app" , "https://trevligaspel.se/streamdeck/midi/index.php"}
• Whether the parameters should be enclosed with quotation marks depends on the app and probably the OS since macOS and Windows behave slightly differently. 
• I recommend always enclosing the parameters with quotation marks; if it fails, try removing them.

Tip: If you want to ensure the plugin starts a new window instead of opening an existing one, include an empty parameter.

• Example: {launch:"Safari.app" , ""}.
• Since the presence of a parameter in the command instructs the plugin to open a new instance, that is what it will do. The empty parameter will not be passed to the app.
• Please note that an empty parameter is one without any characters within quotation marks; a space character " " is not considered "empty" by the plugin and will be passed to the app. 

{launch:_file_}

• When a file is launched, it's basically the same thing as opening the file from the Finder/Explorer; based on the file extension, the default app for the extension will be launched with the file.
• A new window will always be created when a file is opened this way since the plugin cannot determine if any window exists for that file.
• The file path should be enclosed in quotation marks.

The {input} action will open a web page in a browser, allowing real-time input to the plugin. The information entered on the web page will be sent to the plugin via a deep link.

• _id_ is returned as part1 in the deeplink. This can be utilized in the deeplink event to establish a one-to-one relationship between the input action and the deeplink event. This parameter is not displayed on the web page; the _id_ parameter is merely returned as part1 in the deeplink message.
• _part2Label_ and _part3Label_ are the labels that should be shown for the input fields of part2 and part3 in the returned deeplink message. If you only require an input field for part2, the _part3Label_ parameter should be omitted. If, for any reason, you only need an input field for part3, the _part2Label_ parameter must be set to "".

Example:

When you press the button/dial, this web page will be displayed in a browser:

For information about how to receive the information, please see the (deeplink) event and the deep linking page.

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.

• _position_ is the visible position where the fader, vpot or bar should be positioned within the value range defined by the min/max values in the editor. No Midi commands are sent; this is only the positioning of the visible fader, vpot or bar.
• To set the value for the secondary "while pressed" bar (Dials only), use the {value:p,_value} action, where the "p," indicates that it is the secondary bar that is the target. The "p," is only available for the value action, not the fader and vpot actions.
• "fader", "vpot" and "value" are equivalent; any word can be used for both fader, vpot and the main bar. For the "while pressed" bar, the "value" action must be used.

• _text_ is any text that should be displayed.
• For buttons
  • use the "text" action for single buttons or the lower button in a pair.
  • use the "textupper" action for the upper button. When using paired buttons, the script is defined only for the lower button, and to address the upper button text, you use the "textupper" action.
• For  scripted dials two text fields are available: a "title" field and a "value" field.
  • To access the "title" field, you use the {title} action. When used, the text will replace the title in the editor's Title field and be displayed on the screen according to the "Title/value position" setting.
  • To access the "value" field, you use the {text} action. The "Value display" dropdown must be set to "Controlled by script" for this text to be displayed, and it is displayed on the screen according to the "Title/value position" setting.
• 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#" or "title:#none#"

• _path_ is the full path to the XML file that defines the design.
• _name_ is the display name for the design that is visible in the design dropdown (case-sensitive).
  A name reference requires that the design name is available in the design dropdown. Built-in designs can always be referenced by name; custom designs can be referenced by name if they have been referenced with the full path earlier (and hence are available in the design dropdown menu).
  The easiest way to get the correct name is to select the option in the dropdown and then right-click the dropdown to copy the name to the clipboard.

• _level_ is the visible level for the VU meter in the range 0-127.

The "VU scale" setting in the editor may modify the visible level. Daws may report the VU level in a non-linear fashion, in which case the VU scale option can be used to get a more linear response on the VU meter. Cubase, e.g., for some reason, reports the VU level using an exponential curve, and if the sent midi value were used for the visible VU level, you would get something that isn't even close to what Cubase shows in the mixer.

To get a similar view on Stream Deck, the script can use the raw Midi value in the vu action and have the plugin use the Cubase VU scale to calculate a more reasonable visual level for the VU meter. It will not be exact, especially not in the lower ranges, but it will be closer to what Cubase shows. Currently, no other VU scale than Cubase/Nuendo is available.

Set the selected option in the "VU Scale" dropdown.

The "name_" is the option name as it appears in the dropdown (case-sensitive). The easiest way to get the correct name is to select the option in the dropdown and then right-click the dropdown to copy the name to the clipboard.

With the {minmax} action, you set the value span for the dial. The values can be defines as "0,127" or "0-127".

• _min_ is the min value.
• _max_ is the max value. 
• The "p," tag indicates that the min and max values for the "Rotate while pressed" section will be set. Without the "p,", the min and max values for the "Rotate " section are set.

• The "_name_" is the option name as it appears in the "Active span indication" dropdown (case-sensitive). The easiest way to get the correct name is to select the option in the dropdown and then right-click the dropdown to copy the name to the clipboard.

Set the selected option in the "Value display" dropdown.

The "_name_" is the option name as it appears in the dropdown (case-sensitive). The leading "*" must be included for a personalized dB file. The easiest way to get the correct name is to select the option in the dropdown and then right-click the dropdown to copy the name to the clipboard.

The optional "u," tag indicates that the value display dropdown for the upper button should be set (buttons only).

The optional "p," tag indicates that the value display dropdown for the secondary "while pressed" control should be set (dials only).

• _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.

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.

• _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.

The "icon..." actions are used for single fader buttons or the lower button in a pair.
The "iconupper..." actions are used for the upper button in a pair and are ignored for single fader buttons and the lower button in a pair. 
When using paired fader buttons, the script is defined only for the lower button, and to address the upper fader state icon, you use the "iconupper..." actions.

• _path_ is the full path to the icon image file.
• _size_ is the size, in pixels, of the state icon. The max size is 144, which will fill the entire button.
• _x,_y_ are the coordinates for the upper left corner of the icon in the buttons 144x144 pixel space. The upper left corner of the button is 0,0.
• To remove an icon, use #none# or none.

• _value_ is the speed the button uses, in the range 0-100.

  A scripted speed change will change the speed slider in the editor, thus causing the speed change to be "permanent" (until the following change...)

Set the selected option in the "Title/value position" dropdown.

The "_name_" is the option name as it appears in the dropdown (case-sensitive).

•  _path_ is the full path to the icon image file.
• To remove an icon, use #none# or none.

The display action sets the dial display to one of the display types listed in the display dropdowns.

• The "_name_" is the option name as it appears in the dropdown (case-sensitive).
• The "p," tag indicates that the display for the "Rotate while pressed" section will be set. Without the "p,", the display for the "Rotate " section is set.

 _on_or_off_ is controlling if large icons should used. 

• To use large icons, _on_or_off_ should be set to "on", "yes", "true", or "1" (without quotation marks).
• To use small icons, _on_or_off_ should be set to "off", "no", "false", or "0" (without quotation marks).
• To switch between sizes, _on_or_off_ should be set to "toggle".

The {step} action sets the step type and, optionally, the step size.

• _type_ is the step type and the target control.
  • "s" is for slow step size
  • "v" is for variable step size,
  • "q" is for quick step size
  • "u" is for ultrafast step size
  • "f" is for fixed step size
  • "p" indicates that the stepsize for the secondary (while pressed) bar is set. Without the "p", the step size for the main control is set.
• _size_ is the step size. 

The existing step size is left unchanged when using the action without specifying a step size.

Examples:

{step:f,10}
{step:pf,10}
{step:v}
{step:pv}

_size_ is controlling the Vpot size. 

• To use full Vpot,  _size_ should be set to "full" (without quotation marks).
• To use half Vpot,  _size_ should be set to "half" (without quotation marks).
• To switch between sizes, __size_ should be set to "toggle" (without quotation marks).

 _on_or_off_ is controlling if the Vpot is endless. 

• To use an endless Vpot, _on_or_off_ should be set to "on", "yes", "true", or "1" (without quotation marks).
• To use a ranged Vpot, _on_or_off_ should be set to "off", "no", "false", or "0" (without quotation marks).
• To switch between types, _on_or_off_ should be set to "toggle" (without quotation marks).

• The "_name_" is the option name as it appears in the "Active span indication" dropdown (case-sensitive). The easiest way to get the correct name is to select the option in the dropdown and then right-click the dropdown to copy the name to the clipboard.

With list options, you control how a dial selection list should be displayed and how it responds to dial press and release. 

The list options are active "from now on" when a listoptions action is executed; if all lists in a script have the same list options, you can have the listoptions action in an (init) command. All option groups have default values used unless you change them with a listoptions action. You only need to specify the option you want to change; the other options are left as is. Options are defined in separate groups where only one option in the group can be active at a time.

The default options are: {listoptions:paddedlist,usetext,hideexit,press}

List-display options

The list can be displayed as a...

• a loop, wrapping from the last to the first item and vice versa.
• a list, stopping at the first and last item.
• a paddedlist, stopping at the first and last item and displaying an empty line above the first item and below the last item.

The selected item in a list is displayed with white text on a blue background, while the other items are a bit dimmed on a gray background.

For the looped and padded lists, the selected item is always in the center of the display. The unpadded list moves the selection indication to the first and last position at the list endpoints.

Item reference type

Item references for focusing and when a selection is made can be made using the item text or index.

• usetext. Item references are made using the item text. References must be exactly as defined in the list, and they are case-sensitive.
• useindex. Item references are made using the item index, starting with the number 1 for the first item. If an exit item is shown as the first item in the list, it has the number 0, so the first "real" item in the list is always index 1.

Exit option

The plugin can show an extra option, "Exit (no change)", which will close the list without notifying the script if selected. The options to control this feature are:

• showexit, which will show the "Exit (no change)" as the first item in the list.
• hideexit, which will not show the item. With hideexit active, you must select an item in the list to have the list closed.

Press/release options

With these options, you can control whether a list selection will be made on dial press, dial release, or both. Please note that when a list is displayed, the script will NOT get press or release events triggered. Instead, a selectedfromlist event will be triggered when a selection is made.

• press, The selection will be made the first time the dial is pressed after the list is displayed; a dial release will be ignored.
• release, The selection will be made the first time the dial is released after the list is displayed; a dial press will be ignored.
• pressrelease, The selection will be made the first time the dial is pressed or released after the list is displayed. A dial release will make the selection if the dial is pressed when the list is displayed. A dial press will make the selection if the dial is not pressed when the list is displayed. 

Set the selected option in the "Avoid handle/text collisions" dropdown.

The "_name_" is the option name as it appears in the dropdown (case-sensitive).

The showlist action will show a dial selection list.

The showlist action can have an optional list of list items and an optional definition of which item should be focused on when the list is displayed. Four variations of the action are available:

• {showlist}. Without parameters, the showlist action will show the last used list again, with the last selected item focused.
• {showlist:item1,item2, item3...}. To define a list, you enter a comma-separated list of items. The entire list can be held in one variable, individual items can be held in variables or combinations thereof. Since the list is comma-separated, an item cannot contain a comma.
• {showlist:focus=...} To focus on a specific item when the list is displayed, add a "focus=..." item as the last item. In this special case, the last item is also the first item, in which case the last used list is displayed again, this time with the assigned item focused. The focused item must be referenced with a name or index (optionally in a variable), depending on the item reference type.
• {showlist:item1,item2, item3...,focus=...}  The full action is a combination of the above. If the very last item starts with "focus=", it is treated as a focus item; if not, it is treated as an ordinary list item.

The list is automatically closed when a selection is made, and the normal display is restored. If you need to close the list for other reasons, you can use the {hidelist} action.

The recommended way to set focus to an item is to do it in the {showlist} action. The focuslist action serves the same purpose as the "focus=..." item in the {showlist} action but is used to change the focus on an already displayed list. Please note that this action can only be used when a list is displayed; it cannot be used in preparation for a list display.

As for the focus item in the {showlist} action, the focused item in this action must be referenced with a name or index, depending on the item reference type.