Hotkeys and OSC

One of the great things about QLab is that its capabilities can be extended beyond those included in the program. For instance, QLab 3 only allows you to turn looping on or off for one Audio cue at a time, using the checkbox in the Time and Loops tab of the inspector. But what if you frequently have large numbers of cues you want to set to loop? It is possible to create a cue that will can perform this action on all the cues that are selected. In QLab 2, this could be done with a Script cue. In QLab 3 and later, now you can also use OSC (Open Sound Control) which can be a bit easier to set up. Once you’ve created these cues, you can assign hotkeys to them which makes them behave almost like built-in functions just like copy (⌘C) and paste (⌘V).

QLab 4 and 5 allow some cue parameters to be edited on multiple cues simultaneously, and looping is indeed one of them, but the hotkey method is still useful because it can be invoked at any time, and you don’t have to be looking at the correct tab of the inspector to use them.

You can use similar OSC cues on hotkeys to control a huge range of parameters in QLab. The OSC dictionary for QLab found in the QLab manual:

• QLab 5 OSC Dictionary
• QLab 4 OSC Dictionary
• QLab 3 OSC Dictionary

You can create hotkeys to invoke any OSC command in the dictionary; this example will focus on looping.

How It Works

In QLab, OSC is often used to communicate with other pieces of equipment over a network, such as an ETC Ion or a Meyer Galaxy. But you can also send OSC messages from QLab to QLab itself. By default, QLab workspaces have OSC patch 1 set as a “loopback”, i.e the OSC is sent to the Mac QLab is running on, which has a special address, localhost, and to the port number which QLab listens for OSC on, port 53000.

In QLab 3, setting up that patch looks like this:

In QLab 5, the patch looks like this:

QLab 5 defaults to requiring a passcode for OSC messages, which you can configure here:

To set up a hotkey which will set the selected cue to loop, we do the following:

1. Create a Network cue (in QLab 3, it’s called an OSC cue.)
2. For QLab 3 or 4: in the Settings tab of the inspector, set the message type to “custom OSC message.” In QLab 5, the message type is defined by the patch.
3. In the text field, type /cue/selected/infiniteLoop 1 to switch the loop on or /cue/selected/infiniteLoop 0 to switch the loop off.

IMPORTANT: OSC is case-sensitive, so you must enter OSC with the capital letters in the correct place. If you are typing an OSC string from memory then the general rule is, all letters are lower case except the first letter of any words that are joined to another without a space, like ‘infiniteLoop’ where only the ‘L’ is capitalized.

Here’s a screen shot of our OSC cue that will set the selected cues to loops:

Of course, if we run this cue as it’s shown in the screen shot, nothing will happen, because the only cue selected is the Network cue (OSC cue) itself. So what we need to be able to do is trigger the cue while we have one or more other cues selected.

To do this, we assign a hotkey trigger to the Network cue (OSC cue.) This is done in the Basics tab of the inspector in QLab 3, or the Triggers tab of the inspector in QLab 4 or QLab 5.

L is generally already in use, as a shortcut for the built-in command “load”, so we might use ⇧L (shift-L). If you have a remote control device that sends MIDI notes, you could also set a MIDI trigger for the cue. The example workspace has a MIDI trigger listening for a note 60, note on with any velocity.

We can now select all the cues which we want to loop and hit ⇧L. The Network cue (OSC cue) will start, and the selected cue(s) will be set to loop.

The example workspace contains many useful OSC commands that will work in this way. You can copy and paste any cues you might find useful into your own workspaces. Generally, it’s best to keep all your hotkey cues together in a separate cue list so that they don’t get confused for cues that are part of your performance. Remember that batch commands are potentially dangerous, particularly when they can be triggered by simple key presses. If you put all your editing hotkey cues in a separate cue list, you can simply disarm that list when you are not programming.

Here’s whats included in the example workspace:

You can combine these in Group cues and give the Group cue a hotkey to build up more complex actions. For example, to set selected cues to not loop and hold on their last frame, you would put the OSC cues for these two functions into a Timeline Group cue (start-all Group cue,) then assign a hotkey or MIDI trigger to that Group. You may wish to remove the triggers for the cues inside the Group, or keep them in place. It all depends on how you plan to use them.

Comparison with AppleScript

If you are interested, here is the AppleScript solution for setting the selected cues to loop:

tell application id "com.figure53.qlab.5" to tell front workspace
  repeat with eachCue in (selected of front workspace as list)
    set infinite loop of eachCue to true
  end repeat
end tell

The OSC method is a lot simpler, and it has another advantage as well; if you send an OSC message to a cue that doesn’t understand it, then it just politely ignores the command without any drama. If you do the same with a Script cue, it has a nervous breakdown, cries in the corner, and decompiles itself. So you have to put even more code into the AppleScript version to test what sort of cue it is working with. Some proper programmers like this sort of thing, but it’s generally easier to use a Network cue (OSC cue) where it will achieve the same end!

OSC within QLab 3 is a bit of a one trick pony though, as a cue can’t modify its custom message depending on what’s going on in the rest of the program. In QLab 4 and QLab 5, Network cues can get values from other cues using OSC queries. This is discussed in detail in the final section of the chapter called Space Hijack.

Because of this, in QLab 3, Script cues are the best way of achieving anything more complex than setting one parameter to a fixed value. In QLab 4 and QLab 5, OSC has more flexibility, but Script cues are still very useful. For instance, (and as a reward for reading this far) if you didn’t know this already, here is the most useful AppleScript in the universe, based on original scripts by Chris Ashworth, Rich Walsh, and Jeremy Lee:

If you have an Audio cue, you will probably want to fade it out at some point. Put the following script into a Script cue with a hotkey like ⌃F (control-F), select your Audio cue, hit the hotkey, and a Fade cue will magically appear below it, targeted and set up to fade out.

set userDuration to 10 -- Edit Duration of Fade here

tell application id "com.figure53.qlab.5" to tell front workspace
  set originalCue to last item of (selected as list)
  set originalCueType to q type of originalCue
  if originalCueType is in {"Audio"} then
    make type "Fade"
    set newCue to last item of (selected as list)
    set cue target of newCue to originalCue
    set duration of newCue to userDuration
    newCue setLevel row 0 column 0 db -120
    set stop target when done of newCue to true
    set q name of newCue to "Fade out and Stop: " & q list name of originalCue
  end if
end tell