(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}]

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.

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.

• 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?streamdeck=hidden
└─┬──┘ └─┬─┘ └─┬─┘└────────┬───────┘
part1 part2 part3       optional

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.

Sending a deep-link message will, by default, bring the Stream Deck editor window to the front and focus it. If you do not want that to happen, you can add the parameter "?streamdeck=hidden" to the URL.

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.

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 gets notified. 

Please note: Device events are always available for button and dial scripts. However, technical limitations mean that background scripts can only access device events if at least one Midi plugin button or dial exists in an active profile and page on any device. If no Midi plugin actions are loaded, background scripts will not be able to access device events.

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

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

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.

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.

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 = The top left corner of the tap area within the 200x100 screen space. The top-left corner of the screen space has coordinates (0,0).
  w,h = The width and height of the tap area.

When an item in a list is selected, the selectedfromlist event is triggered. The list selection detection depends on the item reference type set (optionally) with the listoptions action. 

• useText: The _item_ is assumed to be a text that matches the text of the selected item (case sensitive).
• useIndex: The _item_ is assumed to be an integer or an interval that matches the index of the selected item.
• useAuto (default): If _item_ is explicitly defined as an integer or an interval, it is assumed to match the index of the selected item. If it cannot be deciphered as an integer or interval, it is assumed to be a text that matches the text of the selected item. If you need to match a text that can be deciphered as an integer or interval, enclose the value in quotation marks to force it to be a string.

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.