This chapter requires Bitfocus Companion 3.5 or newer, which has some significant new features of which this tutorial makes use.

The QLab with feedback Companion module, which is included in Companion, is not developed or maintained by Figure 53. Support and documentation for the module are only available via its Github page.

Readers who are not familiar with the Elgato Stream Deck or Bitfocus Companion are advised to read two earlier chapter in the QLab Cookbook, Button Button, Who’s Got The Button which looks at controlling QLab from Companion using generic OSC, and Companion for Musical Directors which covers using Companion with the included qlabfb module to provide comprehensive remote controls that do not require a display monitor. It also discusses using a Stream Deck on a local network via a second computer or an inexpensive Raspberry Pi.

This chapter explores some more advanced features in Companion with the qlabfb module, specifically the use of variables and triggers. It explores creating a volume control remote that provides feedback about the main level of the currently selected cue in QLab, together with buttons for increasing or decreasing this level in 1dB and 5dB increments.

Here it is in action

When any cue with audio is selected, the level of that cue is displayed on a Stream Deck button.

If the cue has no audio, then the button displays the cue type and the words “NO AUDIO”.

The main level can be adjusted in 1dB or 5dB increments using the four buttons adjacent to the level indicator button.

The cue number and cue name are displayed on two Stream Deck buttons.

The Stream Deck also has buttons for preview selected cue, stop selected cue, select next cue, and select previous cue.

How it Works

Setting up the QLab Workspace

We are also going to use a passcode for OSC access. The example uses 9999 but of course you can use any passcode you like. OSC passcodes are set in Workspace Settings → Network →OSC Access.

Setting up Companion

This tutorial assumes you have installed Companion on the same computer as QLab and that it is running. From the Companion menu, select Show Window.

The Companion Window will open.

You can launch the Companion GUI from the Companion menu or from the Companion window.

From the Import/Export tab of the Companion GUI, import the config file included in the example download, More Advanced Companion.companionconfig

The most important feature this chapter demonstrates is Companion’s ability to obtain information that the qlabfb module does not request from QLab directly, in this case, the main level of a cue.

The qlabfb module knows the unique ID for the workspace, the current cue list, the cue currently at the playhead, and the currently selected cue(s). It can also request /valuesForKeys when needed. Here is the valueForKeys message sent from Companion:

2024-12-23 13:32:24 (4365.142): OSC received from TCP 192.168.1.57:50868: /workspace/8BA539C0-9041-4E6B-BBF5-775F46B61F5F/cue_id/CF6A4F10-9B92-4359-BF1B-CD30081ACF6B/valuesForKeys "["number","uniqueID","listName","type","mode","isPaused","duration","actionElapsed","parent","flagged","notes","autoLoad","colorName","isRunning","isAuditioning","isLoaded","armed","isBroken","continueMode","percentActionElapsed","cartPosition","infiniteLoop","holdLastFrame"]"

As you can see, the information requested does not include anything about levels.

To get around this, we can set up a Companion Event, which is triggered when QLab’s playhead moved. This is done in the Triggers tab of Companion.

qlabfb keeps track of the selected cue with the variable qlabfb:s_id, so when the value of that variable changes, that means the selection in QLab has changed.

The Events section tells companion to watch for a change in that variable, and when it changes do whatever is listed under Actions below.

The Actions section includes a press and release action which simulates a press of the Stream Deck button that displays the current level of the selected cue, which is at Page 1, Row 2, Column 2. (Rows and columns in Companion are zero-indexed.)

Here is the set-up for that button:

When the button is pressed (either physically or by the Companion trigger event,) Companion sends an OSC message to QLab to start Cue SLEVEL. This is a Script cue which sets its own name to match the main audio level of the selected cue, or to “NO AUDIO” if the selected cue has no audio. Here’s the script:

tell application id "com.figure53.QLab.5" to tell front workspace
	try --tests for a selection
		set theCue to last item of (selected as list)
		try --tests for an audio main level
			set theLevel to (getLevel theCue row 0 column 0)
			--Format to 1 decimal place and add a + sign if a positive dB Level
			set theLevel to (theLevel * 10 as integer) / 10
			if theLevel > 0 then set theLevel to "+" & theLevel
			set q name of cue "SLEVEL" to theLevel
		on error
			set the q name of cue "SLEVEL" to q type of theCue & " NO AUDIO"
		end try
	on error
		set the q name of cue "SLEVEL" to "No Cue Select"
	end try
end tell

Note the use of the nested try blocks, which detect if no cue is selected or if there is no audio in the selected cue. Also note the formatting of the audio level with one decimal place and a ”+” sign for positive values.

Once the script runs, the name of cue SLEVEL will display the main audio level of the selected cue. The qlabfb module in Companion has a variable, $(qlabfb:q_SLEVEL_name), which automatically obtains the name of cue SLEVEL from QLab when it is updated.

The text on the button is set using that variable.

The +5dB level change button is programmed as follows:

The button is labelled with text “+5dB”

When the button is pressed, the following OSC message is sent to QLab:

/cue/selected/level/0/0/+ 5

As the level has changed, but the cue hasn’t, we also need this button to start cue SLEVEL in order to update its name, which will in turn update the level display on the Stream Deck.

The other level change buttons are programmed similarly with the only changes being the button text, the plus or minus sign at the end of the OSC address, and the argument of the OSC message (1 or 5).

The up and down navigation arrows send OSC messages /select/previous:

and /select/next

The Stop Preview button displays a white square plus the word “Preveiw” as its label. To get the word to appear on a second line, use the code ‘\n’. When this button is pressed, it stops the selected cue with qlabfb’s Stop Selected action.

The Play Preview button displays the text “◼︎ \n Preview” as its label and, when pressed, previews the Selected Cue using qlabfb’s Start Cue (Cue ID) action.

The cue number button displays the cue number with this expression in its Button text expression field:

This expression uses two functions which we haven’t discussed before.

concat() joins two text strings together. The two strings are each enclosed in single quotation marks and separated with a comma. parseVariables() enables the value of a variable to be inserted into another variable. In this case, we inster the ID of the selected cue, $(qlabfb:s_id), into the number of a cue identified by its ID: $(qlabfb:id_$_num).

The cue name button uses a similar expression using the parseVariable() function, to insert the ID of the selected cue, $(qlabfb:s_id), into the variable name of a cue identified by its ID: $(qlabfb:id_$_name).

This Companion set-up can be used with any QLab 5 workspace by copying cue SLEVEL from this demo and pasting it anywhere into the new workspace.

Bitfocus Companion is an open-source product from Bitfocus AS.

The qlabfb module is included as a module in Companion. It is maintained on github.com.

Stream Deck is a product of Elgato.

Music in the demo workspace by Kevin MacLeod. Licensed under Creative Commons: By Attribution 3.0

Sound Effects from Freesound; CC0.