Using OSC To Control QLab

QLab has extensive support for the Open Sound Control protocol, a network communication standard for computers and multimedia devices. OSC is a great way to control QLab from other software and hardware because it’s relatively simple to set up, requires no specialized hardware, and uses networking infrastructure that is often already in place, or easy to implement if not.

Understanding OSC

All software or devices which support OSC have their own dictionary of commands. You can use programs like Max/MSP, Medialon Manager, and TouchOSC, or hardware like ETC’s EOS family to send messages that exist in QLab 4’s OSC dictionary.

Alternately, if your software or hardware does not allow you to program your own messages, you can use the OSC controls in Workspace Settings to capture your device’s OSC messages, and map them to several of QLab’s workspace-level commands like GO, Panic, Load, and so on.

Physical Requirements

QLab accepts incoming OSC messages via TCP and UDP over a local network. The sending device must be on the same network, and both the Mac running QLab and the other device must be configured correctly to share network traffic. A good, but rather dry, introduction to setting up devices on a network can be found here.

The long and short of it is that devices must be on the same network, on the same subnet, and use IP addresses that permit them to communicate with each other.

Controlling The Workspace

QLab accepts commands like /go, /panic, and /save, which are referred to as workspace level commands because they are directed at a workspace. When QLab receives these messages, it behaves exactly as though the corresponding button, menu item, or keyboard shortcut occurred within QLab. So sending /go to QLab from an external device will cause the exact same thing to happen as sitting down in front of QLab and clicking on the GO button with the mouse.

Controlling Individual Cues

There are also a variety of commands that can be directed at cues themselves. These commands have the structure /cue/{identifier}/{command}, where {identifier} is the piece of information that QLab uses to determine where to send the command. There are five identifiers available for OSC commands:

/cue/{x} - replace {x} with the cue number of the cue you want to target.

/cue/selected - the command will target all selected cues. If one or more of the selected cues can’t accept the command, they will be ignored.

/cue/playhead - the command will target the cue that’s currently standing by.

/cue/* - the * character is a wildcard. A command directed to /cue/* will target all cues in a workspace. You can combine the wildcard with other text, though, so a command directed to /cue/*1 will target all cues whose cue numbers end with 1, like cue 1, cue 11, cue 41, and cue alternate1. You can also use the wildcard in the middle or at the end of a cue number, so you can use ham* to target hamlet, hamster, and, of course, hamilton.

/cue_id/{id} - replace {id} with the cue ID of the cue you want to target.

Important: Spaces are not permitted in OSC addresses, so if you are using OSC to control your workspace, it’s a good idea to avoid spaces in cue numbers. For example, /cue/oh hello/start is an invalid command, since there’s a space between oh and hello.

The Benefits of OSC

OSC’s two main strengths are it’s infrastructure requirements and its flexibility. It runs over standard networking infrastructure, including WiFi, which is fairly cheap and very easy to obtain. You can buy network equipment pretty much anywhere, whereas MIDI cables and devices are a bit harder to come by if you’re not in a large city.

Complex networks of devices with bi-directional OSC control are fairly simple to set up: connect everything to a network switch and assign IP addresses in the same subnet range. MIDI, on the other hand, requires a more carefully designed and laid out infrastructure, with “in” and “out” cables for each device, careful management of power, and a mere 16 channels for separation of messages.

OSC is more flexible than MIDI, too, because each program or device defines its own set of OSC commands, rather than re-purposing MIDI messages such as Note On and Program Change. The set of commands that a given device can use is based on the exact need of that device.

The Perils of OSC

Despite these advantages, OSC is not without its drawbacks.

The more we use networks, the more important it is to secure them. If your show network includes WiFi, it’s important to follow best practices for securing your WiFi network. Audience members are more likely to have a cell phone in their pocket than a MIDI device, after all.

OSC is also, frankly, a little complicated when you’re trying to do complicated things. You have to know a good amount about networking in order to troubleshoot subtle problems, and it can be time consuming to gather and retain all the necessary information about which commands do what for each device or program.

Finally, there are some political implications of using OSC. Folks are typically pretty skeptical when approached by someone from a different department with the end of a network cable. Coordinating IP addresses and address schemes can be complicated, and someone has to do it, and everyone has to agree who that someone is.

Ultimately, though, we believe that the benefits of OSC far outweigh the drawbacks, and with a little careful planning, all the dangers can be overcome.