(init)
(init+)

The (init) event is triggered once when the script is loaded.

The (init+) event is likewise triggered when the script is loaded, but also whenever the additional event(s) in the command are triggered.

Example: Assume you want to display a text when a specific CC command is received and also want this text to be present when you switch to the page with the script. Using the (init) command, you would need to define two commands: one for the init phase and one for the running operation:

[(init)(cc:1,1,0){text:Super\nDuper}]
[(cc:1,1,0){text:Super\nDuper}]

If you use (init+), a single command handles both functions:

[(init+)(cc:1,1,0){text:Super\nDuper}]

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.
• _cc__ is the control in the range 0-127 for single byte commands and 128-160 for dual-byte commands, and can be defined as a single value, an interval, a transition, or as "all values".
• _value__ is the value in the range0-127 for single byte commands and 0-16383 for dual-byte commands, and can be defined as a single value, an interval, a transition, or as "all values".

Control Change events 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.

For the cc event, 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 event will be triggered when either of the two CC commands is received. The value referenced in the event and the event reference variable are the combined values of the latest received values for the two CC commands. The value range for a dual-byte CC command is 0-16383.

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.
• _nrpn__ is the control in the range 0-16.383, and can be defined as a single value, an interval, a transition, or as "all values".
• _value__ is the value in the range 0-16.383, and can be defined as a single value, an interval, a transition, or as "all values".

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.

• _program__ is the received program in the range 0-127, and can be defined as a single value, an interval, a transition, or as "all values".

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.

• _note_ is the midi note number in the range 0-127, and can be defined as a single value, an interval, a transition, or as "all values".

• _velocity_ is the velocity for the note in the range 0-127, and can be defined as a single value, an interval, a transition, or as "all values".

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.
• _note_ is the midi note number in the range 0-127, and can be defined as a single value, an interval, a transition, or as "all values".
• _velocity_ is the velocity for the note in the range 0-127, and can be defined as a single value, an interval, a transition, or as "all values".

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.
• _pressure_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

Special treatment is needed if you want to get the track volume as defined in the Mackie Control protocol. Getting the VU level is a bit tricky since bitwise operations are necessary to extract the VU level from the received data. The following script will display the VU level for track 1 (not to be confused with Midi channel 1).

[(cp:1,0-15){@l_vu:#BITAND(@e_cpvalue,15)#}{text:#MIN(@l_vu,12)#}]

To get track 2, you need to trigger on incoming values in the range 16-31, and so on.

• _channel_ is the Midi channel on which the command can be received, and can be defined as a single value, an interval, or as "all values". Transition cannot be used for channel.
• _value_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

• F0 is the standardized "sysex start" byte.
• F7 is the standardized "sysex end" byte.
• AA and BB are arbitrarily long sequences of bytes required for the script to trigger on that sysex command.
• XX is the flexible part of the command stored for later use.
  (It should be the string ”XX” in the event; the script engine searches for this string to determine which part of the sysex message is flexible.)
• Apart from the "XX" part, bytes shall be defined in hexadecimal representation and separated by space characters.

Examples:
(sysex:F0 01 14 XX 45 23 F7) This event will be fired by all sysex commands that start with "F0 01 14" and end with "45 23 F7". Everything in between (i.e., "xx") will be stored for potential use in actions.

(sysex:F0 02 XX F7) This event will be fired by all sysex commands that start with "F0 02" and end with "F7". Everything in between (i.e., "xx") will be stored for potential use in actions.

The sysex commands are real-time commands (as opposed to state commands). When a sysex command is received, the appropriate script commands are fired. Period. The sysex string isn't stored anywhere for later use. This means that if a sysex command is part of a multi-event command, the sysex command is the only command that can fire the multi-event command. Please see the Event Reference page for details on handling the received sysex information.

• The (time) event displays timing information in various ways. Please note: only {text} and {@variable} actions are executed, and other 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} and {@variable} 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 it will take some second(s) to adjust when the BPM changes in the daw.

According to the Stream Deck SDK documentation: "Deep-linking is the process of sending messages to local apps via custom URL scheme registered on the user's device, for example, a computer or mobile phone."

Deep links can be sent from, e.g., a web browser, using the following syntax:

streamdeck://plugins/message/se.trevligaspel.midi/hello?world#again
                                                 └─┬──┘ └─┬─┘ └─┬─┘
	                                            part1 part2  part3

part1, 2 and 3 keep the information that will reach the script.

• part1 must be prefixed with the "/" character.
• part2 must be prefixed with the "?" character.
• part3 must be prefixed with the "#" character.

All parts are optional, it is perfectly fine, e.g., to have a URL with only part2 present.

The content of each part is totally up to you, as is what you should do with it in the script. A suggestion could be to have part1 as a script target denominator if you have different scripts that should respond to different messages.

Script syntax:

_part1_, _part2_ and _part3_ will, of course, map to the corresponding part in the sent message (not including the prefix characters).

Each part in the event can be either an exact match (case sensitive) or a "*" to match any content.

Actions in a (deeplink) command will have the content of the three parts available in the environment variables @e_deeplinkpart1, @e_deeplinkpart2, and @e_deeplinkpart3.

If a (deeplink) event is present in a multi-event command, it must be tre triggering event. 

Please note: (deeplink) events are accessible for button and dial scripts at all times. However, technical limitations mean that (deeplink) events can only be utilized by background scripts if at least one Midi plugin button or dial is present in an active profile and page on any device. If no Midi plugin actions are loaded, background scripts will not have access to deep links.

For more information about deep linking, please see the deep linking page.

When a Stream Deck device is connected or disconnected, the script can be notified. 

Script syntax:

_devicename_ is the name of the device as displayed in the Stream Deck preferences (case sensitive) or a "*" if the command should be triggered for any device.

Please note 1: The plugin will initially get a list of all devices, but not the connection status. The plugin will presume that all devices are connected, but the real status is not known until a real connection status change is reported. If these events are present in a multi-event command that is triggered by another event, this semi-known state will be checked.

Please note 2: Device events are accessible for button and dial scripts at all times. However, technical limitations mean that device events can only be utilized by background scripts if at least one Midi plugin button or dial is present in an active profile and page on any device. If no Midi plugin actions are loaded, background scripts will not have access to device events.

Custom variables can be used as events in commands, and changing a custom variable will trigger script commands.

• _value_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

• String variables can only be tested for all values (*) or an exact match (surrounded by quotation marks, case insensitive!)

Timers can be used as events in commands, and when the timer reaches the defined millisecond count, it will trigger script commands. Example:

(@t_MyTimer:1000)
(@timer_MyTimer:2000)

Expiration time (in milliseconds) must be defined as a distinct value; you cannot use intervals, transitions or "*" in timer events. Unless the command executes a pause or reset action, the timer will continue counting after triggering the command.

(press) events are triggered when the button or dial 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. For dials, you may consider using (release) events instead since it is unclear at the press moment whether the intention is to press-rotate or press.

(release) events are triggered when the button or dial is released. The execution of (release) events depends on the press/release mode; see above. For dials, an optional parameter decides whether the release event should be triggered only when the dial has been rotated (release:r) or not rotated (release:n).

Please note that (press) and (release) events are triggered for the Generic Midi fader and V-pot buttons only when the speed is set to 0. If speed is set to 1-100, the (fader) and (vpot) events are triggered instead.

• _value_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

When using the Generic Midi button as a fader, it can trigger either a (press) event or (fader) events, all depending on the current speed setting for the button.

Speed = 0

If the fader speed is 0, it operates in "button mode", and (press) events will be triggered. In "button mode", the fader does not move and the (press) event will be triggered once.

Sequence of events when speed is 0:

1. You press the button.
2. The (press) event is triggered.
3. You release the button
4. The (release) event is triggered.

Speed = 1-100

If the fader speed is in the range of 1-100, fader events will be triggered as follows:

1. You press the button.
2. The plugin moves the fader.
3. The (fader:nnn) event is triggered, where "nnn" is the current position of the fader (within the min/max range defined in the editor)
4. Steps 2-3 are repeated as long as the button is pressed or until the fader reaches the endpoint.

• _value_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

When using the Generic Midi button as a V-Pot, it can trigger either a (press) event or (vpot) events, all depending on the current speed setting for the button.

Speed = 0

If the V-Pot speed is 0, it operates in "button mode", and (press) events will be triggered. In "button mode", the V-Pot does not move and the (press) event will be triggered once.

Sequence of events when speed is 0:

1. You press the button.
2. The (press) event is triggered.
3. You release the button
4. The (release) event is triggered.

Speed = 1-100

If the V-Pot speed is in the range of 1-100, fader events will be triggered as follows:

1. You press the button.
2. The plugin moves the V-Pot.
3. The (vpot:nnn) event is triggered, where "nnn" is the current position of the V-Pot (within the min/max range defined in the editor)
4. Steps 2-3 are repeated as long as the button is pressed or until the V-Pot reaches the endpoint.

The (rotate) event is triggered when the dial is rotated. The fader/vpot/bar will move according to the step setting, and then the event will be triggered with the value for the current position. If the step size is set to 0, no automatic movement is performed, but the event will be triggered for each step the dial is rotated.

• (rotate) without options will trigger regardless of whether the dial is rotated left or right or if the dial is pressed or not.
• The lrpn options can be used to restrict the instances when the event is triggered. 
  • l = trigger when rotated left (counterclockwise). r = trigger when rotated right (clockwise). If neither l nor r is used, or if both are used, the event will trigger regardless of the direction. 
    
  • p = trigger when the dial is pressed during the rotation. n = trigger when the dial is not pressed during the rotation. If neither p nor n is used, or if both are used, the event will trigger regardless of the pressed state.
    
• _value_ is the value for the control in the range defined by the min/max properties, and can be defined as a single value, an interval, a transition, or as "all values".

Internally, the Stream Deck software reports the dial movements in "tics", where one tic equals the physical step that can be felt when the dial is rotated slowly; clockwise movements are positive and counterclockwise movements are negative tics. For a single event, tic values are approximately in the range +/- 20 (the max value for extremely fast dial movements varies for unknown reasons but usually is about 20); tic value 0 is never used. This tic value cannot be referenced in the event but can be accessed by actions using the @e_tics reference variable.

A (tap) event is triggered when you tap the dial screen. 

• (tap) triggers across the complete screen space (for the dial).
• (tap:l) triggers when the left half of the screen is tapped.
• (tap:r) triggers when the right half of the screen is tapped.
• (tap:x,y,w,h) triggers when the screen is tapped within the assigned coordinates.  
  x,y = top left corner of the tap area within the 200x100 screen space.
  w,h = width and height of the tap area.

When an item in a list is selected, the selectedfromlist event is triggered. 

• If item references are set to be item text (see the listoptions action), the parameter for the event can be "*", or a distinct item text, case-sensitive.
• If item references are set to be item index, the parameter for the event can be "*", a distinct item index or an interval.

The event reference variable @e_selectedindex will keep the index of the selected item. The first item has index 1. If the list is configured to show an exit item, this has an index of 0, so the first "real item always has an index of 1.

The event reference variable @e_selectedtext will keep the text of the selected item.

The (config) command is used to set configuration parameters for the script in which it is defined (not globally). It doesn't matter where the command is defined in the script; the configuration parameters are set when the script is parsed.

Available configuration parameters are:

• TriggerOnLocalMidiEvents
• TriggerOnUnchangedVariables
• FirstMidiChannel

Please note that a script can only have a single (config) command. If you need to set multiple configuration parameters, they must all be defined in the same config command.

The default behavior is always to trigger Midi events regardless of whether the Midi commands are received from the daw or sent from the same script, another script or another Stream Deck button. You can set this parameter if you don't want the script to trigger on Midi commands sent from Stream Deck.

[ (config) {TriggerOnLocalMidiEvents:No} ]

If the {TriggerOnLocalMidiEvents} action is missing or has the parameter "Yes", "True", or "1", Midi commands sent from Stream Deck will trigger commands in the script. If the parameter is "No", "False", or "0", the script will ignore Midi commands sent from Stream Deck and only be triggered by Midi commands sent from the daw.

When you have an action that stores a value in a custom variable, the default behavior is to trigger commands where the variable is referenced in an event. This behavior is the same regardless of whether or not the variable value is changed. Consider the following script:

[ (press) {@MyVariable:1} ]
[ (@MyVariable:0-64) {@MyCounter:#@MyCounter+1#} ]

When the button is pressed and the variable MyVariable is set to 1, the second command will be triggered, and the counter will be incremented even if the value in MyVariable is unchanged. If you want commands to be triggered only when the variable value is changed, you can add the following action to the (config) command:

[ (config) {TriggerOnUnchangedVariables:No} ]

If the {TriggerOnUnchangedVariables} action is missing or has the parameter "Yes", "True", or "1", an action that stores a value in a variable will trigger commands in the script even if the value is unchanged. If the parameter is "No", "False", or "0", the script will avoid triggering commands if the content of a variable is unchanged.

In the Midi protocol, the channel is always defined from 0-15. For humans, it is more natural to start counting at 1, and many (all?) daws and VSTs show the Midi channel in the range 1-16 even though the range 0-15 is still used on the protocol level.

The Midi plugin adapts to this "human" numbering of midi channels and uses the range 1-16, and when specifying a channel in the script, you should use the range 1-16. However, if you find yourself in a situation where the "true" channel numbering (0-15) makes more sense, you can change the behavior of the script by adding the following declaration to your script:

[ (config) {FirstMidiChannel:0} ]

The plugin will always use the range 0-15 when sending or receiving midi commands since that's how the midi protocol works. This configuration only changes how you specify channels in your script, using the range 0-15 or 1-16.