Fading OSC

[Updated for QLab 4.1 13 JUL 17]

QLab 4 added the ability to fade OSC messages. This chapter is still useful as an introduction to using QLab with OSCULATOR by Wiidora.

The built-in tools in QLab 4 are documented here:

QLab 3 Using Osculator:

QLab 3 does not have this capability, but there is a workaround, using OSCULATOR. This utility can take a MIDI message as its input, and convert it to an OSC address. This means that you can use the MIDI cue in QLab in the usual way, including fades with curves, send the output via an internal MIDI bus to OSCULATOR, which will generate the stream of OSC messages required to communicate over a network with another device, in our example an OSC capable mixing console. (represented here by a set of TouchOSC faders running on an iPad)

Here it is in action:

How It Works:

Create a MIDI cue in QLab

Qlab cc cue

Set MIDI Destination to an internal MIDI bus to send to OSCULATOR. The example uses IAC bus 1

Select a Channel, MIDI controller number and starting Control Value (0-127)

Check ‘fade over duration’, set the duration of the fade, set the end value (0-127) and adjust the curve shape if required.

Setting up Osculator:

Open Osculator, create a new document, click the Parameters gearwheel and select I/O.

Osculator parameters

Make IAC Bus 1 (or whichever bus you are using) active.

Osculator parametersMIDI

Close the parameters pane.

Run the Midi Cue you created in QLab.

Quite magically, Osculator immediately translates any MIDI message it receives, on an Active MIDI input, to an OSC address, and puts it in the main window. In the case of our example:  /midi/cc50/1

Osculator cc50

We now need to translate this address to the OSC address we need to drive our fader.

In Event type select OSC message, In value select New…


The OSC routing menu will open

Osculator routing

Click the small gear icon in Target 1 and select the OSC server you want to send the OSC messages to. In our case, this is Touch OSC running on an iPad

Osculator ipad

If the OSC service you want is not listed you can manually enter it’s IP address and port number by double-clicking in the OSC URL column. (If there is a value already there clear it by selecting clear from  the small gear menu next to it.)

Osculator routing2

You will see that this is checked in the second column as the default and that the default routing is now in the Routes table. As it stands this would now route the OSC message (/midi/cc50/1) in the main window  to the default target (same address)

We now want to rewrite the address to the OSC address used by the faders on our mixing console. In our example ch1 fader has the address:


which means the fader1 on page 1 of the Touch OSC controller,  which is representing our mixing console.

Double-clicking in the Routes table  brings up the OSC routing editor:Osculator rewrite

We enter the address as we want it to be rewritten in the Rewrite address field.

We then close that pane and select this routing in the Value column of the main Osculator window. (It is usually there automatically)

OSCulatorfull route

The final step is to map the values from QLab’s MIDI cc message (0-127), to that required as the argument in our OSC message, to control the fader, in our example -60 to +12.

Select the scalings page from the View menu (or press cmd-f, or click the curl icon next to the Chan. column in the main Osculator window).

OSCulatorvalue map

Lock the routing (cmd-L, or from the Routing Menu) and save the OSCULATOR document.


If you look at the video again you will see that representing the entire fader movement from -60  to +12 as a MIDI cc range (0-127) gives a slightly steppy response, as there are only 127 possible fader positions represented. For faders, this may not matter too much. Many high-quality recording consoles of the 1960s had sets of resistors, operated by quadrant faders, rather than continuous fader tracks. Most had only 31 steps.

Consider, if you were using OSC to control a video server and were sending an address to pan an image across a 1920 pixel wide projector. Using a 7 bit MIDI controller we are restricted to 128 values, 0-127, (7^2). This would mean the image jumped 15 pixels for every 1 unit change in the MIDI cc value.

Luckily the MIDI pitch bend controller is a 14 bit controller which allows14^2 or 16,384 values which gives a resolution over 100 times greater,

Heres our fader being controlled by pitch bend:

As you can see the fader movement is much smoother, but towards the end it becomes jerky again. As well as increasing the resolution, we have also increased the number of messages from a 100 or so to around 15000. On a wired network connection, the bandwidth would be available to deal with this, but on the wifi connection, to TouchOSC on the iPad, the network is straining a bit. Some consideration needs to be given to the number of OSC messages generated and sent over the network.

Here’s a more complex example with 4 faders controlled by QLab Midi cues using 4 pitch bend messages on 4 different MIDi channels:

When using other applications with QLab it can be very beneficial to the operator if QLab opens these applications when it launches. This can be achieved by a script cue.

Here is an example:

How it Works:

QLab is set to automatically run the cue numbered OSCu when it opens. This is set up in settings/general

Autorun OSCu

The cue numbered OSCu is a script cue which runs this AppleScript, which is based on a script by Rich Walsh:

set thefilename to “Qlab MIDI to OSC control.oscd” –set filename of OSCULATOR file here
tell application id “com.figure53.qlab.3” to tell front workspace
— Establish the path to the current workspace
set workspacepath to path
if workspacepath is missing value then
display dialog “The current workspace has not yet been saved anywhere.” with title dialogTitle ¬
with icon 0 buttons {“OK”} default button “OK” giving up after 5
end if
— Get the path that should prefix all media file paths
tell application “System Events”
set sharedPath to path of container of file workspacepath
end tell
set filepath to quoted form of (POSIX path of sharedPath & thefilename)
set thecommand to “open ” & filepath
do shell script thecommand
end try
delay 0.1
end tell

This script expects the Osculator file (ext .oscd) to be in the same folder as the workspace. You set the name of the file in the top line of the script.

The script formats a command incorporating the path to the folder, and the file name, and runs the command using ‘do shell script’

You can download the QLab workspace, Osculator, and TouchOSC files   here

Other things to try:

If you explore OSCULATOR  you will find it can do so much more than mapping MIDI to OSC and vice versa.

It can take hardware inputs from Nintendo Wii remotes and balance boards which you can map to OSC addresses to control QLab.

It will allow OSC messages to be generated by input from a Wacom tablet. Details are in:


Chapter Author: Mic Pool

Chapter Image: bLpmusix at English Wikipedia.
Licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Creative Commons License