Script setup


The Script Button allows multiple actions to be performed when a button is pressed (and released), when a midi command is received or when a custom variable is changed.

The script button is meant to fill gaps between the other button types. It is not as good as the other buttons for keeping state, and it is not as good at automatically synchronizing incoming midi messages with sent messages. What it is good at is being very flexible in what actions to take when you press a button and when receiving midi commands from the input midi port.

Please note that you are on your own here; the Script button does not assume anything and does nothing by default. It reacts to the events you specify with the actions you specify. Period.

I have tried to make it flexible while keeping the syntax reasonably simple. More complex actions would require a full-fledged programming language, which I have no desire to implement. If you require more complex actions than what the plugin can handle, I think it's a better solution to incorporate some middleware (e.g., Bome MIDI Translator) that has such scripting capabilities built-in.

The script can be entered in the Script field or loaded from a file. Since the plugin area in the Stream Deck editor is quite limited, it may be more convenient to edit the script in an external editor.

Please note that the option to load the script from a file does not load it into the editor's script field; it loads the script from the file instead of using the Script field.

Predefined scripts

The Predefined Scripts dropdown enables easy access to scripts that perform predefined functions. If you select a script from the dropdown, that script will be copied to the Script field, replacing whatever script was present. This is a "copy/paste" operation; once done, you can edit the Script field in any way you like.

If you have scripts that you think may interest others, please email them to me or publish them in the Scripts subforum in my forum. The dropdown is partially populated from the website, so I can add scripts to the dropdown without publishing new plugin versions.

If you want to add your own scripts to the dropdown, do as follows:

  1. Create the folder Documents/Trevliga Spel/PredefinedScripts.

  2. Copy the file PredefinedScriptTemplate.xml from the plugin folder to the PredefinedScripts folder and rename it to something useful (but keep the .xml extension). Don't edit the file in the plugin folder; that file is a template only and is never accessed by the plugin.

  3. Change the Category name to something useful, like <Category name="My scripts">

  4. Copy/paste the Script section as many times as you have scripts you want to add.

  5. For each Script section, set a name to be displayed in the dropdown and the script itself.

You can have multiple XML files in the PredefinedScripts folder; the plugin will merge the contents from all of them.

Script syntax

Each script command consists of an event, followed by several actions to be taken when the event is triggered. An unlimited number of commands can be defined for a single button.

A command is surrounded by square brackets, and within the command, the event is surrounded by parentheses, and the actions are surrounded by curly brackets. An unlimited number of actions can be defined for a single event.

The plugin ignores text outside the parentheses and curly brackets, so you can format the script in any way that makes sense to you as long as you avoid using the bracket characters. Everything can be written on one line or divided into multiple lines. You can add text between brackets if it helps to visualize the script; you could, e.g., do something like this to visualize that an event leads to actions:

[(press){noteon:1,42,127}] And here you can add whatever comment you want.

Please remember the following syntax rules:

  • Commands are enclosed in square brackets. [ ]

  • Events are enclosed in parentheses. ( )

  • Actions are enclosed in curly brackets. { }

Real-time syntax check

The plugin will perform a syntax check on the script and display a message in case anything is wrong with the script.

If you load the script from a file, the syntax check will be performed immediately when a script change is saved. If you enter the script in the Script field, the plugin will try to avoid interfering with the editing by only checking the script when you have not made any changes for three seconds.

If you make a pause longer than three seconds while entering/editing your script, the plugin will check the syntax and display potential "error" messages. If you know you are not finished, you can ignore whatever messages the plugin displays. This delay also means that if you correct an error, the error message will not be removed until three seconds after you have stopped typing.

The real-time syntax check is built to capture the most apparent syntax problems, such as missing brackets or parameters and misspelled event and action names. More complex problems, e.g., using actions in a command where they are not allowed, may not be detected. If the plugin displays a message, there is a problem in the script; if the plugin doesn't display a message, the script might be OK. ๐Ÿ˜

Midi channel configuration

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 button by adding the following declaration to your script:

[ (config) {firstmidichannel:0} ]

You can add this declaration anywhere in the script; it doesn't need to be first or last. With that declaration in the script, the plugin expects you to specify midi channels in the range 0-15 and will use the channel number without any changes.

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.

The Script button in a Multi Action

The Script button works the same in a Multi Action as it does stand-alone. Please note that incoming midi commands trigger script commands only within the Script button itself; the other actions in the Multi Action are not run.

Loop detection

Creating loops when defining script commands for incoming Midi events is theoretically possible. The plugin has a loop detection where it stops responding if the same midi message is received more than ten times within one second.

Example: Even though I strongly suggest not to ๐Ÿ˜• , it is, e.g., possible to:

  • create a script command triggered by an incoming Play command and respond by sending a Stop command.

  • create another script command triggered by an incoming Stop command and respond by sending a Play command.

Depending on the response from the daw, you may end up in a loop of Play/Stop commands, and in such cases, the loop detection will activate and break the loop.

Script editing

Even if you choose to have the script in the Stream Deck editor (as opposed to loading it from a file), it may be more convenient to use an external editor and copy/paste the script.

Since I am a Windows guy, I have minimal experience with editors on macOS; sorry about that.๐Ÿ™

If you are on Windows, I recommend using Notepad++, a free editor far superior to the standard Notepad editor. One nice feature of Notepad++ is the option to select language, and I have created a language file that helps color-code the different script sections.

  • Square brackets (surrounding the command) are in red.

  • Events are in blue.

  • Actions are in green.

To install the language file:

  • Open the User Defined Language Folder in Notepad++: go to menu Language => User Defined Language => Open User Defined Language Folder...

  • Download this file and unzip it to the Notepad++ User Defined Language Folder.

  • Restart Notepad++

To use the language file:

  • Open the script file (or create a new one).

  • If you set the file's extension to ".midiScript", Notepad++ will automatically apply the correct language file. (The plugin does not care about the extension, so you can set whatever extension you like)

  • If the file has another extension, please select the language Midi Script in the bottom section of the Language menu.

The colors applied by the language file are only visual and are not saved with the file. A final tip if you are using Notepad++ is to enable auto-completion for the brackets: