Using MIDI To Control QLab

QLab can be controlled from another program or device using MIDI. MIDI, which stands for Musical Instrument Digital Interface, is a digital protocol created for allowing electronic musical instruments, computers, and other related equipment to connect and communicate with each other. While not originally designed for show control, MIDI has been adopted (and adapted) for use in theaters, theme parks, concerts, and all manner of live entertainment venues.

Workspace MIDI control

QLab allows you to map incoming MIDI voice messages to controls at the workspace level, such as GO, Pause All, Panic, and so forth, so that you can use a MIDI device as a remote control for running QLab. This could be as simple as a single physical GO button, or as complex as a full MIDI surface with a button for each MIDI-mappable control in QLab. Any device capable of sending MIDI voice messages can be used, including keyboards, drum pads, purpose-built remote devices, or the user-defined keys on many popular digital audio consoles.

To configure QLab to respond to MIDI Voice Messages, open the Workspace Settings window by clicking the gear icon in the lower right corner of the workspace, or by using the keyboard shortcut ⌘, (that's command-comma) and then select MIDI Controls from the list on the left.

MIDI Controls

At the top of the window, you can select which of the 16 MIDI channels QLab will listen to. You can also select Any to allow QLab to respond to incoming messages on any channel. QLab will listen on the selected channel for incoming MIDI messages from all MIDI devices connected to the computer.

The next section of MIDI Controls pertains to MIDI Show Control, which is disussed below.

Checking the box labeled Use "Musical" MIDI Controls will enable incoming MIDI controls for the workspace. You can then enter the MIDI message that you want to assign to each workspace control. Workspace controls can respond to four types of MIDI messages: Note On, Note Off, Program Change, and Control Change. Choose the message type from the dropdown menu, and then enter the two bytes of data for the message. For Note On and Note Off messages, byte 1 is the note number, and byte 2 is the velocity. For Control Change messages, byte 1 is the control number, and byte 2 is the control value. For Program Change messages, byte 1 is the program number, and byte 2 is ignored.

You can use greater-than (>) or less-than (<) signs in the byte fields. So, for example, if you want to use a Note On message to trigger GO, and you're using a velocity-sensitive keyboard, you may wish to enter >0 for byte 2, so that no matter the velocity of the keypress, the GO is triggered.

You can also use the word any in the byte fields. It is recommended that you proceed with caution, though, especially when using any in conjunction with Note On messages. Many MIDI devices don't actually use Note Off, and instead send a Note On message with a velocity of 0 to indicate a Note Off. If your MIDI device does that, and you're using a Note On message with any as byte 2, you will get double triggers: one when the key is pressed, and another when it's released.

Instead of manually entering each MIDI message, you can also click the Capture button next to the workspace control that you wish to use. Once you click it, you'll see "Waiting..." in yellow text appear in the two byte fields. QLab will listen for the next compatible incoming MIDI message, and assign it to that control. To cancel listening for a new message without capturing one, just click the "Capture..." button a second time.

Workspace MSC control

MSC stands for MIDI Show Control, and it was created to help simply the process of using MIDI for show control purposes. Rather than arbitrarily assigning Note On or Program Change messages to show control commands like "go" and "stop", MSC has a set of commands designed for a show control environment.

Checking the box labeled Use MIDI Show Control, will allow QLab to respond to a selection of incoming MSC messages associated with common tasks, without requiring you to manually set up connections between MIDI voice messages and controls or triggers in QLab. The MSC specification includes a wide variety of categories for devices that can be addressed by MSC; QLab will respond to messages sent as Audio (General), Lighting (General), and Video (General).

With that box checked, you need to set QLab's MSC Device ID, which is a number between 0 and 126. Every device on an MSC network must have a Device ID number, and must respond to incoming messages within their own categories if the messages are addressed to that Device ID. Also, all devices must respond to messages sent to Device ID 127.

Once you've set the Device ID, there's nothing else to configure in QLab. QLab will respond to the following MSC commands:

  • ALL_OFF. Fade out and stop all currently playing cues.
  • STANDBY+/-. Move the playhead to the next or previous cue.
  • SEQUENCE+/-. Move the playhead to the next or previous cue sequence.
  • RESET. If RESET is sent without a cue number, reset the workspace to the state it would be in when it is first opened. If RESET is sent with a cue number, stop that cue if it's playing, and revert any temporary changes made to it, such as with a Target cue.
  • GO. If GO is sent without a cue number, start the standing by cue and advance the playhead to the next cue or cue sequence, just as though the on-screen GO button was pressed. If GO is sent with a cue number, start that cue.
  • STOP. If STOP is sent without a cue number, stop the currently selected cue(s). If STOP is sent with a cue number, stop that cue.
  • RESUME. If RESUME is sent without a cue number, resume all currently paused cues. If RESUME is sent with a cue number, resume that cue.
  • LOAD. If LOAD is sent without a cue number, load the currently selected cue(s). If LOAD is sent with a cue number, load that cue.

One extremely important thing to remember when using MSC is that cue numbers in MSC, and in QLab, are strings not actual numbers. What that means is that you need to be sure to match the cue numbers exactly on both ends. 1, 01, 1.0, 1.00 are all the same number, but they're all different cue numbers!

MIDI triggers

You can also set MIDI voice messages to trigger individual cues in your workspace. You can learn more about that in the Triggers Tab section of the page on the Inspector.

The Benefits of MIDI

MIDI can be a great choice for controlling QLab because it's a simple and reliable protocol with a long-proven track record, and it's spoken by thousands of devices and programs all over the world. Lighting consoles, video mixers, musical instruments... you can find MIDI in use in almost all of them.

MIDI is quick to set up, often only requiring a single cable if you only need control in one direction, and doesn't usually require a ton of programming knowledge to configure.

It's also extremely easy to send from place to place in a theater, since it can be sent over long distances on regular XLR cable using a simple, inexpensive adapter. A common misconception is that MIDI can't be sent farther than 50 feet (about 15 meters) without using an active amplifier, but this usually isn't the case. In fact, MIDI amplifiers often cause more trouble than they solve. For more details, see this guide to MIDI cable length by Richmond Sound Design.

The Perils of MIDI

Its advantages notwithstanding, using MIDI to control QLab, or any other aspect of a show for that matter, isn't without it's downsides.

Getting MIDI in and out of a computer requires a MIDI interface. There are hundreds of different brands of MIDI interfaces out there at all price points, and unfortunately the vast majority of them are unsuitable for show-critical use. This is because the amount of MIDI data generated by, say, a keyboard controller is comparatively low, and even a world class pianist can't play faster than the MIDI interface can follow. But a computer generating MIDI, MSC, or MIDI timecode sends a lot more data, and sends it a lot faster than a typical musical performance. This higher load can outstrip the capacity of lower end MIDI interfaces, causing them to either skip or corrupt messages. Needless to say, that's problematic.

For this reason, the only MIDI interfaces we currently recommend are those manufactured by iConnectivity or ESI. We've experienced problems with nearly every other brand of MIDI interface we've encountered in the field. Naturally, your mileage may vary, and you may have perfect success with other interfaces. By and large, though, if your show depends on MIDI control, we strongly encourage sticking with one of these proven brands.

Another reason to be cautious of MIDI has to do with what MSC calls "controlled devices" and "controllers." Most lighting consoles are designed as "controlled devices," which means the level of control you have over the MSC messages they send out is limited. In ETC consoles, for example, MSC can only be enabled on a per-list basis. Once enabled on a cue list, the console will send an MSC GO with the cue number of every cue that it triggers in that cue list. While this is very convenient if it's what you need, it can also create quite a challenge if that's not what you need. Since the lighting console sends an MSC GO for every single cue, any cue in QLab with a matching cue number will be triggered. The only way to ensure that certain cues trigger over MSC and others don't is to use matching cue numbers for the trigger cues, and make sure that no other cues in QLab have the same cue number as any cue on the lighting console. More advanced ETC consoles also let you work around this with a complicated arrangement of multiple cue lists and macros. You can also solve the problem by using QLab to send MSC triggers to the lighting console, since QLab only sends triggers when you tell it to. But there are any number of reasons why that might not be practical, which leaves you with the hassle described here.

Our intention is not to discourage the use of MIDI and MSC, only to try to point out potential issues, hopefully before you encounter them. With a little care, MIDI can be a very powerful and useful tool in a show control environment.