Running scripts

Scripts let you perform a task on one or many machines at once — restarting an app, clearing a cache, launching software, and so on. ShowTrak Server keeps a library of scripts and sends the right one to each machine based on its operating system.

What a script is

A script is a folder containing a small settings file called Script.json plus the actual command files it runs. Because a single script can include separate files for Windows, macOS, and Linux, one script in your library works across all your machines — the Server automatically sends each machine the version made for its operating system.

Where scripts live

Scripts are stored in the Scripts folder inside the Server's data directory:

Windows: %APPDATA%\ShowTrakServer\Scripts
macOS:   ~/Library/Application Support/ShowTrakServer/Scripts
Linux:   ~/.local/share/ShowTrakServer/Scripts

The quickest way to get there is Settings (gear) → Open Scripts Directory.

Creating a script

Open Settings (gear) → Script Manager. From there you can:

  • Start from a template — click New from template to browse ShowTrak's official sample scripts and create a ready‑made one you can customise.
  • Start blank — click the + button to create an empty script, then fill in the details and add your command files.

You can also build a script by hand: make a new folder under Scripts, add a Script.json, and add your command file(s).

Example layout

Scripts/
  RestartPlayback/
    Script.json
    restart-windows.bat
    restart-mac.sh

Script.json reference

{
  "Name": "Restart Playback",
  "Description": "Restarts the playback application",
  "Colour": 3,
  "Weight": 10,
  "Confirmation": true,
  "Enabled": true,
  "Timeout": 20000,
  "Platforms": {
    "Windows": "restart-windows.bat",
    "macOS": "restart-mac.sh",
    "Linux": "restart-mac.sh"
  },
  "Arguments": {
    "Windows": "",
    "macOS": "",
    "Linux": ""
  }
}
Field Meaning
Name The name shown in the menu when you run scripts.
Description A short note about what the script does.
Colour A colour for the script's label, chosen as a number 0–7 (red, orange, yellow, green, blue, purple, light grey, dark grey).
Weight Sort order in the list — lower numbers appear first.
Confirmation If true, you're asked to confirm before the script runs. Good for anything disruptive.
Enabled If false, the script is greyed out and can't be run (see Disabling below).
Timeout How long, in milliseconds, to wait before giving up (minimum 5000 = 5 seconds).
Platforms Which command file to run on each operating system. Leave one out if you don't support that OS.
Arguments Optional extra arguments passed to the command on each operating system.

You don't have to remember all of this — the Script Manager gives you fields, toggles, and a colour picker for everything above, and it repairs or fills in anything that's missing when you save.

Command files by operating system

  • Windows: .bat, .cmd, .ps1 (PowerShell), .exe
  • macOS: .sh, .bash, .zsh, .command
  • Linux: .sh, .bash, .zsh

Cross‑platform setup

To make one script work everywhere, add a command file for each operating system you use and point the matching Platforms entry at it. The same file can serve more than one platform — for example a single .sh file used for both macOS and Linux, as in the example above. When you run the script, each machine only ever receives and runs the file meant for its operating system.

In the Script Manager, each script shows a small badge per operating system so you can see at a glance which platforms it supports.

Running a script

  1. Select one or more clients (or target a group).
  2. Right‑click and choose the script from the menu.
  3. If the script has confirmation turned on, confirm when prompted.
  4. Watch progress in the execution area — each run shows as Pending, then Running, then Success or Failed with any error.

You can also run scripts remotely over OSC or the HTTP API — see the OSC / API reference.

Disabling vs deleting

  • Disable — turn off Enabled in the Script Manager. The script stays in your library but is greyed out and can't be run. Use this to temporarily retire a script without losing it.
  • Delete — open the script in the Script Manager and click the trash icon, then confirm. This permanently removes the script's folder from disk.

Tips

  • Test a new script on a single machine before running it everywhere.
  • Keep scripts small and self‑contained so they transfer quickly.
  • Prefer scripts that are safe to run more than once.