Background scripts


You can use a script button to translate midi commands in various ways to achieve something the plugin does not natively support, e.g., having latch groups to control articulation using Program Change instead of Note commands. The "problem" with script buttons is that they must be visible on an active page to work, and it may feel like a waste to reserve a button for translation purposes.

This is where background scripts come into play; a service in the plugin controls them, and they do not require a script button to be active. There is a "Background scripts" action you can load on a button to configure the background scripts, but this action does NOT need to be loaded for the scripts to be active. You can load this action when you need to configure background scripts and remove it when you're done.

The scripts are run in the background, and the primary usage is to have translation scripts that receive commands from buttons or dials, translate them to other commands and send them to the daw (and vice versa).


Since the scripts run in the background, they have no direct contact with buttons or dials. They cannot react on (press) or (release) events, and they cannot execute {image}, {text} or {state} actions.

Configuration action

Up to four background scripts can be run in parallel. For a script instance to be active, a script file must be defined, and the active flag must be set.

Sections with inactive scripts are automatically compressed when you open the action in the editor, but you can expand them by clicking on the header.

Script communication

Background scripts will receive commands on the input port, do their magic and send the result on the output port. If you need bidirectional translation, you need two background scripts: one to translate commands from your buttons and dials and send the result to your daw, and a second script to translate commands from your daw and send the result to your buttons and dials.

Communication between buttons/dials and background scripts is preferably done using plugin-internal midi ports. These ports are not visible outside the plugin, and commands sent on these ports will not inadvertently interfere with external devices. By default, no plugin-internal ports are available; if required, use the field in the Background Scripts action to set the number of ports required. There is no limit to the number of internal ports you can use, but please be aware that a large number of ports will make the port dropdown lists very long.

Script execution

Scripts with a valid file path and the active flag set are started when the plugin is loaded, usually when the Stream Deck software is started (or when the first profile with a Midi button or dial is loaded). Scripts are active until the plugin is unloaded, usually when the Stream Deck software stops.

(init) commands are run when the script is loaded. For preconfigured scripts, this means when the plugin is loaded (see above). For new scripts (i.e., when you configure a new script in the editor or set it active), the (init) commands are run immediately when configuring the script as active.

The background service automatically detects changes to an active script file's content; you do not need to open the background script action for such changes to be active.

Configuration storage

Background script information is not stored in the Stream Deck profile because the scripts do not belong to a specific profile or page. Instead, the information is stored in what is called "global storage". As the name suggests, global storage is global to the plugin; this information is stored somewhere other than the profiles.

This means that the background script configuration will not be part of an exported/imported profile.