QLab 5Networking, MIDI, and Show ControlUsing OSC with QLab

Using OSC with 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 either already in place or easy to implement.

Understanding OSC

All software or devices which support OSC have their own dictionary of commands. You can use programs like Max, Medialon Manager, and TouchOSC, or hardware like ETC’s EOS family to send messages that exist in QLab 5’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 → Controls to capture your device’s OSC messages, and map them to several of QLab’s workspace-level commands like , 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 messages 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. You can find a list of workspace level OSC messages in the Workspace Messages section of QLab’s OSC dictionary.

If you are using a device or program which sends specific OSC messages that you want to associate with workspace level events such as and panic, you can do that in Workspace Settings → Controls → OSC.

There are also several application level messages which interact with QLab itself, “above” the workspace level. You can find a list of application level OSC messages in the Application Messages section of QLab’s OSC dictionary.

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; the command will be applied only to the cues which can accept it.
  • /cue/playhead - the command will target the cue that’s standing by in the current cue list.
  • /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. Cue ID is a unique identifier for each cue which never changes, even if you change the cue’s name and number. A cue’s ID can be discovered using the AppleScript property uniqueID

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. Also, sadly, OSC does not support unicode or emoji characters so cues with numbers like 繁 or 💃 are not addressable via OSC.

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, so if you’re on tour and a piece of your OSC infrastructure breaks, it may be relatively easy to find a replacement. 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; just 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 needs 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, and it’s not hard to imagine a curious individual doing a little recreational hacking during intermission.

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.

A small but frustrating technical detail is that OSC does not support use of the comma (,) as a decimal separator, only the period (or “full stop”.) This is important to keep in mind if your Mac, or other devices on your network, are configured to use comma decimal separators, as is common in many European nations.

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. While this is becoming more and more common on large shows, it’s still unfamiliar territory to many.

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.

Still have a question?

Our support team is always happy to help.

Business Hours
M-F 9am-7pm (ET)
Current time at our headquarters