OSC Queries

OSC querying is a powerful capability of the Network cue which allows you to capture the current, live value of nearly any property that can be accessed via OSC and include that value as a part of an OSC message. This is one of those concepts that is easiest to understand through examples.

Imagine a show which is using QLab and some other device on a network. The other device needs to be given a cue number via OSC, so in QLab we make a Network cue and build this message:

/device/standby 53

Sending that message sends the value 53 to the address /device/standby, and in our imaginary situation, that’s the address that the receiving devices wants.

That’s all well and good if we only need to send this one value, or maybe just a few, but if we want the device to simply follow QLab, and we have lots and lots of cues, it could get arduous to program. What we’d really like is for the device to just always know which cue is selected in QLab.

Enter OSC queries. By replacing the 53 with a query, we can build a single OSC message which inserts a value at the moment the message is sent. All we need to do is choose the right query, which in this case is:

#/cue/selected/number#

The query, which is enclosed in hashmarks¹, asks QLab for the cue number of the currently selected cue. When an OSC message including this query is actually sent by QLab, the query is replaced with the result of that query. The message, therefore, is built like this:

/device/standby #/cue/selected/number#

Which you can think of as:

/device/standby [the number of the selected cue in QLab]

So if cue 53 is selected when the OSC message is sent, it becomes:

/device/standby 53

But if cue 101 is selected when the OSC message is sent, it becomes:

/device/standby 101

Continuously Updating Queries

The above example works fine when you just need to extract a piece of information from QLab at a given moment, but you can also use queries to send a continuously updating value. When you use an OSC query in a Network cue, and you give that cue a duration, the query is continuously updated as long as the cue is running.

So, if you set a duration for the Network cue that sends the message:

/device/standby #/cue/selected/number#

then the output of that cue would dynamically update its query for as long as it was running, and therefore keep our mystery device updated about the currently selected cue.

Using Queries With Localhost

QLab’s ability to route OSC to itself via the network address localhost allows you to use OSC queries to dynamically change QLab’s behavior based on what’s currently happening in your workspace. For example, you might like to use the loudness of an actor’s voice to control the brightness of a lighting instrument. If you put a microphone in front of that actor and route it through a Mic cue, you can capture the level of the Mic using liveAverageLevel. Imagine a workspace with a lighting instrument called “myLight” and a Mic cue with the cue number 10. You could create a Network cue with the OSC message:

/dashboard/setLight myLight #/cue/10/liveAverageLevel/1 0 100#

Let’s pull that apart into its individual pieces:

/dashboard/setLight myLight {x} is an OSC command to set myLight to level x. In this case, though, we replace x with a query which will return a numeric value:

#/cue/10/liveAverageLevel/1 0 100#

The hashmarks denote the query, and this particular message says “talk to cue 10, get the live average audio level of output 1, and re-scale it to a range of 0 to 100.”

If you wanted the loudness of the Mic to only vary the brightness of the light from 50% to 100%, you could change the message to:

/dashboard/setLight myLight #/cue/10/liveAverageLevel/1 50 100#

To make the most use of this, you’d probably also want to give the Network cue a duration so that it stays “alive” for as long as you need it to.

Reading the OSC Dictionary

OSC messages which can be queried are indicated in the QLab 5 OSC Dictionary with a checkmark under the heading “query”, like so:

query