QLab and MIDI Control

QLab can function well as a complete Show Controller for a variety of productions from simple to very complex. It achieves this is two main ways; Open Sound Control (OSC) or via the Musical Instrument Digital Interface (MIDI). The second, MIDI, was developed in the early 1980s and is a very common means to controlling various digital equipment.

This Wiki page serves as a primer for MIDI and more specifically how QLab handles it. There are not huge differences in version 2 and 3 of QLab regarding MIDI, so this one page looks at both.

Differences in MIDI between Version 2 and 3

Setting QLab Device IDs/Channels

Version 2: Set in Preferences under Remote Control.

Version 3: Set in Workspace Settings under MIDI Controls.

Output Patch

Version 2:

Version 3:

MIDI Triggers

Version 2: Set in the Triggers tab for each cue.

Version 3: Set in the Basics tab for each cue.


Version 2: Different cue types for Voice, MSC and SysEx

Version 3: One MIDI cue definable to any of the three types.

MIDI Time Code

Version 2: A separate MIDI Time Code (MTC) cue

Version 3: A Timecode cue that can be set to send either MTC or Linear Time Code

MIDI Message types

There are three main message types for MIDI:

General MIDI

Sometimes called Musical MIDI or MIDI Voice , this is a means to directly control musical instruments. It allows the specification of specific notes, the strength of the execution (velocity), changing programs in processing equipment, changing control values for MIDI equipment and other particulars. This lets one MIDI device to tell another to generate music.

MIDI Show Control (MSC)

This is a means to control equipment that is not necessarily musical, or even related to audio, in nature. It will allow a MIDI enabled device to control a large variety of equipment including lighting consoles, video and other projection equipment, mechanized fly systems, atmospheric devices, pyrotechnic controllers, and others as well.

MIDI System Exclusive (SysEx)

This is the base level of a MIDI message; the raw coded source that all MIDI messages use to specify the particulars of a command. It is generally a string of hexadecimal number pairs that detail the information of the message. And example of a SysEx message:

FO 7F 01 02 01 07 0C F7

This translates into System Exclusive message for Lighting Device address 01: Fire Macro 12 or Tell the Light Board to fire Macro 12. In this case, the controller being used was not able to define a MIDI Show Control message directly, so a SysEx message that does the same thing was used.

Connecting a MIDI Network

Classically, MIDI is connected through a dedicated set of wiring intended for that purpose only. It is possible, and sometimes preferable to use an Ethernet connection to transmit MIDI messages. However, not all equipment has that ability so here's how the original MIDI wiring scheme worked.

All connections on MIDI devices are female 5-Pin DIN connectors. Cables between the devices have male connectors. A device will have 2 or 3 connections:

IN - This is the connection a device receives information from another.

OUT - This connection a device sends information to another. It does not repeat any information received from an IN port.

THRU - This repeats the information from the IN connection to send it on to another device in the network. The THRU connection is not always present.

A QLab system, running on a Macintosh, will most likely not have such a MIDI connection built in, but one can be added easily. Many external Audio Interfaces have MIDI connections built into them. It is also possible to get a USB widget that gives MIDI connections to a Macintosh. The MOTU Fastlane is an example.

For more information regarding what devices to use on a QLab system, refer to the Tested Hardware Wiki.

It can take some thought to properly lay out a MIDI network. First of all, cable lengths are limited to 15 meters (about 50 feet). This may seem like plenty, but if your sound control is not in the same room as other equipment, such as in the house, you will discover how short 50 feet really is. This is length between powered devices, however, and so long as you can get to device in 50 feet, then you can get to the next.

In addition to cable length issues the basic idea of IN, OUT and THRU causes some limitations in how to arrange the network. For example, if you have 3 pieces of gear all with only MIDI IN and OUT then there is no way to connect these devices to so they can all talk to each other through MIDI. Here's an example of a simple network. The MIDI OUT from the audio interface from to the QLab system is connected to the IN of a lighting console. The OUT from the console is sent to the IN of an Effects processor:


This isn't a complete loss in control, it just makes things more complicated. QLab cannot tell the Effects processor to change to a different reverb program, it must tell the Lighting Console to do it. While the Lighting console is perfectly happy to oblige, it needs a second set of commands that must be programmed and possibly a delay in relaying the instruction that could make the show unworkable. This is where the THRU port becomes invaluable. If any of these devices had a THRU then the network may look more complicated, but you can do more and it gets simpler:


The OUT from QLab's interface is connected to the IN of the Effects Processor. From there the THRU is connected to the Lighting console. Also, the OUT from the Lighting Console is connected to the IN of QLAB.

Now QLab can send commands directly to either the Lighting Console or the effects processor. In addition, the Lighting Console can tell QLab what to do as well. The effects processor can't tell anyone anything, but they rarely care about that anyway.

When you're setting up your first few MIDI networks, it would be best to lay out all the equipment and make a list of who needs to talk to who and who has a THRU connection. Then you can puzzle your way through how to make the connections, go buy the cables you didn't realize you're missing and plug it all in.

Of note, there are devices that can make things a bit easier. A MIDI THRU box, is a breakout for MIDI: One line from an IN gives you many line to connect to OUTS. Using one of these gives you more possibilities in making the necessary connections.

Setting up MIDI Devices.

MIDI is an addressed network. This simply means that every piece of gear has an identifier that is used to make sure that a command from one device gets to the right place and is ignored by all who don't need to know. For MIDI Voice cues this ID is refferred to as a Channel and can be numbered from 1 through 16. Devices that listen for MIDI Show Control (MSC) use Device IDs which range from 0 through 126. ID 127 is a special ID number meaning All Call: Every device on the MIDI network needs to listen.

One thing to note is more than one one device on a MIDI network can have the same ID/Channel number. This means you can have one controller send a MIDI message to two separate listeners, such as a system set up with a redundant backup.

When defining your network, start by making a list of your devices and assigning IDs or Channels to each. It's not a bad idea to attach a label directly to the piece of gear that lists the number as a quick reference.

How to set the number for a device will be different for each. For instance, in an ETC Expression Series console, this setting is in the Setup -> System Settings menu. Refer to either your manual or an experienced friend to set the numbers on your devices.

Setting MIDI ID/Channel Numbers in QLab:

Version 2

Version 3

Now QLab will listen for MIDI messages as you have defined them. Triggers can be set for individual cues to respond to a particular MIDI Voice message. QLab will respond globally to MSC messages including GO, STOP, LOAD, RESUME, ALL_OFF, STANDBY +/-, RECEIVE +/- and RESET. In addition, you have the chance to define voice messages to execute a variety of global QLab commands in the same screen as you set up the Device ID. In the MIDI Voice section, there are a number of commands that can be defined, each with a drop down menu to select the particular type of message e. g. Note On, Control Change and so on. Next to that are two Byte fields that contain information specific to the command:

MIDI Command(s) Byte 1 Byte 2
Note On - Off Number Velocity
Program Change Program Number Not Used
Control Change Control Number Value

You can choose to set these manually, or by using a Capture. Once you have defined the appropriate message in the device that will trigger this command, simply click the 'Capture' button and have that device send the command. QLab will receive the command and set the particulars of the trigger accordingly.

Setting the MIDI Output Patch

A QLab system running on a Macintosh can have up to 12 MIDI output devices (8 on Version 3). Each of these devices represents a separate MIDI network, allowing quite a few possible devices. QLab needs to be told how to access each device before it can be used in a command cue. Each patch can be assigned to any device. In fact, more than one patch can be set to the same device allowing a very dynamic and easily reconfigurable system.

Version 2

V2 MIDI Patch.png

Version 3

V3 MIDI.png

Triggering a cue with a MIDI Voice Message.

Every cue in QLab has the capability to respond to one or more of three types of triggers: a Hot Key, the System Time, a received Time Code or a MIDI Voice message. In Version 2, this is done on the Triggers tab for each cue. In Version 3, the same settings have been built into the Basics tab.

You can set the MIDI trigger in one of two ways: Either manually, or by 'capturing' the value from another device. Capturing is simple. Once you have defined the appropriate message in the device that will trigger this cue, simply click the 'Capture' button and have that device send the command. QLab will receive the command and set the particulars of the trigger accordingly.

To define a Voice Message trigger manually, you enter the appropriate command/values for the intended MIDI message. Commands are in a pop-up menu for Note On, Note Off, Program Change, Control Change, Key Pressure and Channel Pressure. Each of these will allow for different values to be associated with them allowing for a huge number of possibilities in MIDI triggers.

The actual specifics of a message are up to you. QLab doesn't care if it is listening to a Program Change or a Note Off so long as it is tagged to a cue trigger. However, if you are adding this to an existing MIDI network, be careful you don't send/receive messages that will conflict with other devices in the network or else mayhem could easily ensue. It's always best to have a plan.

MIDI Voice Message Cues

This is where the biggest differences between QLab version 2 and 3 can be found. In version 2, the MIDI messages were broken into three separate cues for Voice, MSC and SysEx. You needed a different cue type for each message. In Version 3, these have been combined into one MIDI cue that can be set to be any of the three types. Other than that, the operation is identical.

Setting up a Voice Message cue

Version 2:

Version 3:

Once the cue is created, the next step is to select the particular MIDI output connection from the pop-up menu. This is called Output Patch in Version 2 and MIDI Destination in Version 3. To tell QLab how MIDI output devices are patched, refer to the Setting the Output Patch section of this page.

Next, select the specific MIDI Voice command from the pop-up menu. After that, set the Channel to send this command to as described in the Setting up MIDI Devices section of this page.

After that there are options that will change depending on the specific command you selected. Use the Command pop-up menu to select a MIDI command. For each a Channel number needs to be set to tell QLab which MIDI device receives the message.

MIDI Voice Commands

Note On/Off

Note Number:0-127

Velocity: 0-127

Both Note On and Off are intended to detail specific notes for a given MIDI instrument to play. The number is a code detailing the given note from 0 to 127. The velocity has to do with a digital representation of how hard the note is struck, like the difference between softly hitting a key on a piano and hitting it with a hammer. Whether or not the device receiving the Note command actually plays music is irrelevant to QLab. It is simply sending the message. Something to keep in mind, however, a velocity of '0' is as if the not was not actually struck and some devices will simply ignore commands set that way.

_ Program Change _

Program Number: 0-127

Many MIDI devices will allow for preset programs that may be selected from different banks such as effects processor that could have an Echo, a Chathedral Reverb, a Flange and so forth. The Program Change command is a way to select the desired effect.

_ Control Change _

Control Number: 0-127

Control Value: 0-127

Fade to Control Value: Checkbox

Final Value: 0-127

Fade Duration: Time in seconds

A Control change is a means of setting a dynamic control of a device, such as a slider on a control console, to a new value. In it's simplest form, a number would select which control to change and the Value would be what to set it to. However, there are more possibilities here. The first control value can be used as a beginning value and the command defined to have the control fade from that value to a new one over a specified time. To do this, click on the checkbox next to Fade to Control Value and enter a new value in the next box. Finally, a time in seconds may be specified in the Fade Duration box.

For example, QLab can send a command to boost the fader on an audio console from 20 to to 60 over 10 seconds. The Control Number would be set to the number of that fader as defined in the console. The Control Value would be at 20, Fade to Contol Value would be checked and 60 entered in that box. Finally, a value of 10 would be entered in the Fade duration box. How these values translate into actual decibel settings is something each console will define. Check your manual or experiment to determine how this works.

One thing to note on a timed control change is the control in question will start at the value set in the Control Value field. If that control is not currently at that value, it could jump to it immediately if the console responds in that way. This could lead to some undesirable results.

_ Key Pressure (Aftertouch) _

Note Number: 0-127

Pressure Value: 0-127

High end keyboard controllers often have the ability to sense how firmly a key is being sustained held down and react by either making the not from that note brighter (more present) for harder pressure or muffled (less present) for a lighter touch. The Key Pressure command acts to mimic this sense of manual control. A single note is specified for the adjustment.

_ Channel Pressure _

Pressure Value: 0-127

In the same way Key Pressure affects a particular note, Channel pressure will change the Aftertouch for all notes on a particular channel, sort of homogenizing the sound.

_ Pitch Bend Change _

Velocity: -8192 to 8191

Fade to Velocity: Checkbox

Final Value: -8192 to 8191

Fade Duration

Many keyboards and other MIDI instruments will allow for a dynamic control of a pitch being played, 'bending' that pitch to a new tone. On keyboards, this is often a lever that can be manipulated manually giving the musician more artistic possibilities. The Pitch Bend Change command is a way to sent such a change digitally. Because of the nature of sound, there needs to be a large range of values, in this case 16,384 possible values to send (it's a computer thing…) with 0 as the pure notes as played on the channel. Note that a changing the pitch affects all notes being played on a particular channel.

Similar to the Control Change command, PItch Bend Change will allow for a start and end value to be reached over a specified time. Put the starting value on the Velocity box and the ending value to in the Fade to Velocity box. Then specify the time it will take to make the change in the Fade Duration box.

How a particular device responds to a PItch Bend change will vary according to the device. Like anything else, refer to the manual or experiment to get the desired effect.

MIDI Show Control Cues (MSC)

Besides Audio equipment, there are many other devices that can be controlled by MIDI. Some will accept MIDI Voice commands, but others will only accept commands using another format such as MIDI Show Control. In QLab it is simple to define an MSC cue.

Building an MSC Cue

QLab versions 2 and 3 are very similar in how they work with MSC commands. The only real difference is in how ther are created.

Setting up an MSC cue

Version 2:

Create an MSC cue MSC Icon.png

Select the MIDI Show Control Message tab

Version 3:

Create a MIDI Cue Toolbox MIDI.png

Select the Settings tab

Set the Message Type pop-up menu to MIDI Show Control

The next step is to select the output patch from the pop-up menu. This is called Output Patch in Version 2 and MIDI Destination in Version 3. To tell QLab how MIDI output devices are patched, refer to the Setting the Output Patch section of this page.

Next select the Command Format. MSC will allow deferent formats depending on the type of device. For example, a Lighting Control console will need Lighting General. Select the format that best suits your device.

Next, select the command to send from the pop-up menu. Then set the Device ID from 0 to 127.

After that there are various parameters that will change depending on the specific command.

MSC Commands

Devices will accept different commands and some may interpret them differently. It's best to refer to the manual for your device to determine how MSC commands will be received. Here are some common ones:

_ GO _

Q Number

Q List

Q Path

Execute a cue on a target device. If no cue number is sent, generally, the next cue in sequence will be executed. Not all equipment will allow for Cue Lists of Cue Paths. Q List will become available when a Q Number is entered. Q Path will become available when a Q List is entered.

_ STOP _

Q Number

Q List

Q Path

Halt execution on one or all cues. If no cue number is sent, all executing cues will be halted. Cue list and path are as described in GO.


Q Number

Q List

Q Path

Allows a stopped cue to continue. If no cue number is sent, whatever stopped cues in the current list will be resumed.


Q Number

Q List

Q Path

Hours, Minutes, seconds, frames, subframes

Timecode format options

Executes a cue with a specified duration time. Selecting this command will open a series of fields that allow entering the time in a standard format. It will also provides buttons to select the timecode format in frames per second.

_ LOAD _

Q Number

Q List

Q Path

Readies a cue to be played. Often this isn't necessary, but for some type of cues, such as large video file playback, being able to tell a device to get it ready could help with clean execution. LOAD needs a cue number to be valid. List and Path are the same as described in the GO command.

_ SET _

Control Number

Control Value

Hours, Minutes, seconds, frames, subframes

Timecode format options

Send Time with Set checkbox

This command allows changing the value of a control on the other device, like a flying fader on a sound console. A duration time for the execution of the change can be selected if the device supports it.

_ FIRE _

Macro Number

Executes a macro selected by the number sent.


Functionally shuts down the device. All functions and outputs are turned off without changing any control settings. Like hitting the Blackout Button on a lighting console.


Restores from an ALL_OFF. All functions and settings return to where they were before the ALL_OFF was sent.


Clears the device and returns it to the state it's in when it's first powered up.


Moves the playback position to the next cue in a sequence.


Moves the playback position to the previous cue in a sequence.


Similar to STANDBY_+ this moves the playback position to the cue following the next automated sequence. For instance, if QLab has a series of cues that are set to automatically execute in a series using the Continue settings, then a Sequence_+ will move the playback to the cue following the cue that ends that sequence.


This is the logical opposite of SEQUENCE_+. The playback is set to the first cue of the previous automated sequence.

MIDI File Cues

A MIDI File is a series of MIDI Voice commands that can be sent to digital Instruments. MIDI files are less recorded sound and more like a digitized piece of sheet music. The destination instrument will interpret the instructions and create sound accordingly. There isn't much to be done with a MIDI file except send it out. QLab does this via a MIDI file cue. This is essentially the same in versions 2 and 3.

To send out a MIDI file, create a MIDI File Cue ( MIDI File Icon.png Version 2, Toolbox MIDI File.png Version 3). The target of that cue is the file to be played. When targeted, a graphic representation of the file with the various voices present is displayed. When executed, a playback 'head' will be seen tracking the progress of the file.

After that, it is possible to change the tempo of the song by changing the playback rate. A '1' is the normal rate, less than that is slower e.g..5 is half speed.

MIDI Information


Somascape Guide to the MIDI Specification

MIDI is the language of gods.

MSC Specifications

Hardware Information

MIDI Solutions