Using an Elgato Stream Deck to control QLab

This is a living document, being constantly updated - email me if you think I’ve missed anything out! - last updated 7th June 2022. If you’ve got anything that should usefully be on here, please email me.

Don’t use keyboard triggers

I’ve recently designed an exhibition using an Elgato Stream Deck as a control panel. I’d googled various ways other people use a Stream Deck, but they are mostly focused at programming and editing rather than running a show. Most of those techniques use Stream Deck’s ability to emulate a QWERTY keyboard, and then trigger cues in QLab by using the built in keyboard commands (Space, Escape, etc) or by assigning keyboard triggers to cues. This can work fine in a programming situation, when QLab is the foreground application, but on a computer that is running 24/7 there are a bunch of things that can steal focus and prevent the keyboard triggers from working. These include software update dialogue boxes, WiFi log-in pages, users knocking the mouse and keyboard, etc. Of course, there’s lots we can do to eradicate some of these - some of these are documented here, and some here, but it’s difficult to anticipate every possibility, so I prefer other methods to trigger QLab as they are typically more reliable in the long run.

Method 1: Applescript

Setup

  • Open Stream Deck’s Store

  • Search for “OSA” and install the OSA Script plug-in

  • You will now find “Run OSA Script” in the Custom section of the list of actions on the right hand side of Stream Deck (if you can’t find it, quit and restart Stream Deck)

  • Drag a Run OSA Script from the right side to an empty button

  • In the script window you can add AppleScript. See below for examples

  • The first time you trigger a cue, MacOS will ask you for permission to let QLab be controlled by AppleScript. Click OK. You won’t be asked in the future.

Bug: There is currently a bug with the OSA plug-in, and every time you add a button, or make any change to the AppleScript, you need to quit Stream Deck and restart it

Handy Tip: Use the Script Editor application (on your hard drive in Applications > Utilities) to test your script works

QLab responds to AppleScript in lots of ways. Here’s a list of all the commands QLab will accept: QLab v4 AppleScript dictionary

tell application "QLab" to tell front workspace
start cue "SQ1" -- this will trigger the cue with the cue number SQ1 regardless of which cue is currently selected
end tell

tell application "QLab" to tell front workspace
go -- this is the equivalent of pressing the Go button
end tell

tell application "QLab" to tell front workspace
stop -- this is the equivalent of pressing escape
end tell

tell application "QLab" to tell front workspace
stop -- this is the equivalent of pressing escape
delay 2 -- wait 2 seconds
start cue "SQ1" -- this will trigger the cue with the cue number SQ1 regardless of which cue is currently selected
end tell

 
 

Method 2: OSC

Setup

  • Open Stream Deck’s Store

  • Search for “OSC Remote” and install the OSC Remote plug-in

  • You will now find “OSC Remote” in the list of actions on the right hand side of Stream Deck (if you can’t find it, quit and restart Stream Deck)

  • Drag a Push action from the right side to an empty button

  • Ensure the client address is set to 127.0.0.1 (which basically sends OSC commands to any compatible applications on the same computer as Stream Deck)

  • Set Client port to 53000 — QLab v4 listens to port 53000.

  • In Adress [sic], you can enter single OSC commands. See below for examples

  • Open up QLab and check in Workspace Settings that “Use OSC Controls” is ticked.

Handy tip: If you need to send multiple OSC commands, you can add a Multi-Action command from the Stream Deck section in the list of actions on the right hand side of Stream Deck

QLab responds to OSC in lots of ways. Here’s a list of all the commands QLab will accept: QLab v4 OSC dictionary

Note, in my casual tests there is a 0.15second delay when using OSC to trigger QLab as a go button. For some applications that won’t be a big deal. For others where millisecond timing is critical you’ll be better off using a dedicated go button like these from That Little Box

/go - this is the equivalent of pressing the Go button
/stop - this is the equivalent of pressing the Escape key
/cue/SQ1/start — this will trigger the cue with the cue number SQ1 regardless of which cue is currently selected

QLab v4: Ensure OSC Commands are enabled

Icons for your buttons

Search in the Stream Deck store for QLab, and you’ll find some nice icons to use

Using a StreamDeck with a Dual Redundant system

It’s slightly tricky to use a Stream Deck with two computers, having any button you press control both computers simultaneously.

I’ve not tried this, but I know of one show who are successfully using the following setup.

The Stream Deck is plugged into a Raspberry Pi computer. The Pi is running the Linux version of Bitfocus Companion software.

Bitfocus is programmed so that each button press sends an OSC command to the main and backup computers.