This tutorial is based on the original cookbook chapter about the Jazz Mutant Lemur and the Lemur app. With Lemur no longer available, this tutorial replicates some of the features from that chapter using TouchOSC from Hexler.

This chapter combines the advanced features of TouchOSC and QLab 5.3 to create a fader bank for remote control of QLab’s audio levels with the following features:

• A main slider and eight cue output sliders.
• Automatic updating of remote slider levels when a new cue is selected. (A limitation is that the playhead must be locked to the selection to achieve this)
• Control of sliders using hardware with continuous encoders or motorized faders with automatic updating when a new cue is selected.

Demo 1 - Fader Bank

This demo uses the FaderBank.qlab5 workspace in the downloadable example.

As each Audio cue is selected, the TouchOSC faders and the hardware MIDI encoders immediately update to the new levels, and the cue number and name are displayed in TouchOSC. The levels can be controlled with the TouchOSC faders or the hardware encoders.

TouchOSC setup

In TouchOSC, the network is configured by entering editor mode (by pressing the dot in the top right of the window) and then pressing the chain link icon to set up TouchOSC’s connections. In this example, we’re running TouchOSC on the same computer as QLab so we make a UDP connection to address 127.0.0.1 sending to port 53000 (the port that QLab uses to receive OSC) and receiving on port 8000.

Opening TouchOSC in kiosk mode

The first cue the QLab workspace is a Script cue that opens the relevant TouchOSC file. Normally, TouchOSC files open in editor mode, which is usually not what we want; this script automatically switches out of the editor as soon as the controller opens so that we can get right to level setting.

set theFileToOpen to "Fader Bank.tosc" --name of TouchOSC file in workspace folder.
--open a TouchOSC Layout in Kiosk Mode.
try
  tell application "Finder" to tell application "TouchOSC" to quit
end try
--open a TouchOSC Layout in Kiosk Mode.
tell application id "com.figure53.QLab.5" to tell front workspace to set workspacePath to path
tell application "System Events" to set sharedPath to ((path of container of file workspacePath) & theFileToOpen) as alias
tell application "TouchOSC"
  if application "TouchOSC" is not running then
    ignoring application responses
      activate
      delay 1
      open sharedPath
      repeat while application "TouchOSC" is not running
        delay 0.1
      end repeat
    end ignoring
    delay 0.5
    activate
    tell application "System Events" to keystroke "e" using command down
  end if
end tell

You may get an error message saying that osascript is not permitted to send keystrokes. The fix is to enable QLab 5 in System Preferences → Security & Privacy → Accessibility (in macOS versions before Ventura) or System Settings → Privacy & Security → Accessibility (in macOS versions Ventura or later.)

QLab show control broadcast

In order to automatically update TouchOSC when QLab’s selection changes (actually, when the playhead moves, but as we noted earlier this workspace will only function correctly when the selection is locked to the playhead,) we use an important and very useful new feature introduced in QLab 5.3: show control broadcast.

When this system is enabled, QLab will send OSC messages with information about its current activity. Before proceeding to the next section of the tutorial, it will be useful to read the section of QLab’s manual that introduces this feature.

How It Works

First, we need set up the QLab workspace to allow incoming OSC without a passcode. This is done in Workspace Settings → Network → OSC Access.

Main TouchOSC script

When the TouchOSC layout is opened, it runs this Lua script:

function init()
  sendOSC("/listen", { true })
  sendOSC ("/udpReplyPort",8000, { true })
  sendOSC("/forgetMeNot",1, { true })
end

This runs when the document is initialized and sends three OSC messages to QLab using Lua’s sendOSC command. First:

sendOSC("/listen", { true })

The sendOSC command takes two parameters. The first is the OSC message to be sent, and the second is a list of booleans, one for each configured connection, stating whether or not the message should be sent to that connection.

So, in this case, the script sends the message /listen. Since this TouchOSC layout has only one connection, the second parameter is a single-item list.

The next sendOSC command looks like this:

sendOSC ("/udpReplyPort",8000, { true })

This instructs QLab to send replies (and therefore show control broadcast messages) to port 8000, which is the port we selected when configuring the connection.

The third sendOSC command is:

sendOSC("/forgetMeNot",1, { true })

This tells QLab to maintain the connection and continue to broadcast the messages until /forgetMeNot,0 is received from TouchOSC or the workspace is closed.

When the playhead position (and therefore the selection) changes in QLab, it sends a series of show control broadcast OSC messages. This project uses the following three of them:

/qlab/event/workspace/playhead/number {cue number}
/qlab/event/workspace/playhead/name {cue name}
/qlab/event/workspace/playhead/uniqueID {cue ID}

The cue number and cue name messages will set the labels at the bottom of the TouchOSC layout. The most important parameter received is the cue ID, as this is the only data that is guaranteed to be both present and unique (cue numbers are optional and cue names are not necessarily unique.)

You can easily check that these messages are being received by TouchOSC by opening the OSC pane of the log window, accessed via the “hamburger” icon at the bottom of TouchOSC’s edit pane.

This screenshot shows the TouchOSC editing pane open at the root (document) level showing the document object’s script and the OSC log. The log is displaying the messages that TouchOSC received just after QLab’s playhead moved.

The automatic sync label

In the document tree, there is one hidden object, Label 25, indicated by a closed eye.

This is a label object which is set up to receive the text argument from the OSC message /qlab/event/workspace/playhead/uniqueID

This object also has a script:

function onValueChanged(key)
  sendOSC("/cue/FSYNC/start", { true })
end

Every time the playhead/selection moves in QLab, the text value of this label object changes to the cue ID of the newly selected cue. Every time the text value of this label object changes, this lua script runs and sends the OSC message /cue/FSYNC/start to QLab.

Cue FSYNC is a Timeline Group in QLab containing a set of nine Network cues, one each representing the main level slider and the first eight cue output sliders in an Audio cue. These cues each send OSC messages to TouchOSC.

Those Network cues each use an OSC query to set a TouchOSC Fader object to the current level of the matching cue output slider for the selected cue. For example, the first Network cue in the Group contains this OSC message:

/fader0 #/cue/selected/sliderLevel/0#

This messages sets TouchOSC’s fader0 to the level returned from the query between the hash marks, which is the level of the slider 0, i.e. the main level control.

The manual sync button

When pressed (x value rises), this button sends /cue/FSYNC/start to QLab.

This is the same message which is sent automatically by the script in the hidden label whenever QLab’s playhead moves.

The button is provided to re-sync the faders if they have been manually set in QLab after the playhead moved to the cue. It can also be used to sync the faders if show control broadcast is not in use, if you’re using a version of QLab prior to 5.3 and therefore cannot use show control broadcast.

The faders

Next are the nine fader objects which are named in the TouchOSC document tree as fader0 through fader8. The faders also have labels, but these are not interactive.

Fader0 is the main fader and is set up like this:

This fader sends the OSC message /cue/selected/sliderlevel/0 {x} to QLab, where x is the value for this fader, a floating point number between 0 and 1, scaled to a range -60 to 12.

The fader also receives the OSC message /fader0 {x} when the FSYNC cue runs in QLab. That sets the position of the fader to match the level of the selected cue in QLab.

The fader is also set up to both send and receive MIDI control change 11 on channel 11, which corresponds to encoder 1 on layer B of the Behringer X-Touch Mini used in the demo video. This allows the encoder indicator ring on the controller to follow the levels set by the TouchOSC fader and also to move the TouchOSC fader in response to movements of the encoder knob. To prevent the sending and receiving from interfering with each other, feedback in this parameter is set to OFF.

Using layer B fore the main fader is cumbersome, and later on in this chapter we’ll see how to set up the main level to be controlled from an encoder on layer A.

If you have a MIDI controller with nine encoders or motorized faders, you should instead arrange the MIDI settings of the nine faders in TouchOSC to match those. The demo uses Channel 11 and CC 1-8 because that’s what the Behringer X-Touch uses. It is a very cheap and readily available encoder-based control surface, but lacks a editor for macOS, so the demo uses its out-of-the-box defaults.

A LOCAL message sets the text of the label below the fader (Label 10) as an integer to a value between -60 and 12 to indicate the value of QLab’s corresponding slider level.

The eight other sliders are configured similarly. Here’s fader8, for example:

The outgoing OSC message is /cue/selected/sliderlevel/8 {x}

The incoming OSC Message is /fader8 {x}

The outgoing and incoming MIDI message is control change 8 on channel 11 which corresponds to encoder 8 on layer A of the Behringer X-Touch Mini .

The selected cue indicator

The two labels at the bottom of the TouchOSC layout receive text from the show broadcast messages:

/qlab/event/workspace/playhead/number {cue number}
/qlab/event/workspace/playhead/name {cue name}

to display the cue number and name of the cue currently at the playhead.

Demo 2 - Ganged Faders

This demo uses the FaderBankGanged.qlab5 workspace in the downloadable example.

The first cue in the workspace, cue TOSCG, closes the existing TouchOSC Layout and opens a new layout called “Fader Bank Ganged.tosc”

In this demo, the first eight cue outputs in QLab are ganged in pairs. The labels above each TouchOSC fader are changed to show this, and a second row of labels is added above to indicate which MIDI control change message is associated with each fader. This allows the main fader plus eleven cue outputs to all be controlled within a single bank of eight faders or encoders.

The script of the hidden label is changed to:

function onValueChanged(key)
  sendOSC("/cue/GFSYNC/start", { true })
end

This starts a Timeline Group in QLab with the following Network cues:

There is an OSC message for each TouchOSC fader, but for the ganged sliders only the odd-numbered level is sent.

The TouchOSC faders have their messages amended to take into account the above changes.

Demo 3 - Using TouchOSC on an iPhone or iPad

This demo uses the FaderBankGangedRemote.qlab5 workspace in the downloadable example.

Although it’s usually easier to edit a TouchOSC layout on the same computer as QLab, TouchOSC runs on virtually any computing device… Mac, Windows PC, Linux PC, Android device, or iOS (and iPadOS) device.

To transfer a TouchOSC layout from a Mac to another device, open TouchOSC on the Mac and click the Wi-Fi icon in the local editor. In the pane that opens, choose Server from the list on the left and then check the box labeled Enabled.

Next, make sure the other device is on the same Wi-Fi network as your Mac and then open TouchOSC. Enter edit mode if necessary by tapping/clicking the dot in the top right of the layout, then tap/click the Wi-Fi icon and choose Client from the list on the left. There, you should see the name of your Mac. Click the Connect button and the layout will transfer.

Save the layout locally by entering edit mode, opening the right hand sidebar, and clicking the save icon. Name the transferred layout “Fader Bank” and confirm.

Click the chain link to open Connections, go to the OSC Pane, and set Connection 1’s host to the IP address of the Mac running QLab. Enter port 53000 which is the port QLab uses by default to receive OSC. Set TouchOSC’s receive port to 8000.

Click Done and exit edit mode by clicking the play arrow button.

Over in QLab, go to Workspace Settings → Network and name patch 2 “TouchOSC (remote)“. Set its destination IP address to the IP address of your remote device, and set the port to 8000.

TouchOSC should now work from your remote device. MIDI control will no longer work, unless of course your MIDI controller is connected to the remote device as well.

To keep from getting confused, close TouchOSC on your QLab Mac.

Here is a demonstration of TouchOSC running on an iPad controlling ganged cue outputs in a QLab workspace.

TouchOSC by Hexler

Behringer is a trade mark of MUSIC TRIBE INNOVATION DK A/S

Scarborough Fair, traditional, arranged and recorded by Mic Pool © All Rights Reserved

Sound Effects from Freesound, public domain via the CC0 license.

Goldberg Variations by JS Bach, public domain, via The Open Goldberg Variations; a project by pianist Kimiko Ishizaka, and MuseScore.com, to create a public domain recording and score of J.S. Bach’s masterpiece, Die Goldberg Variationen (BWV 988).

Chapter Image adapted by Mic Pool from from an original photograph by Beyond My Ken. Licensed and distributed under a CC Attribution-Share Alike 4.0 International license.