Introduction to Lighting in QLab

A note on style

On this page, every time a new tool, interface item, or concept that we feel is particularly essential is mentioned, it will appear in bold text. This is meant to help you notice that you’re being introduced to a new idea. Thereafter, and throughout the rest of this documentation, bold text will be used in the traditional manner, as well as to indicate a menu name (such as the File menu.)

How QLab Communicates With Lights

QLab 4 communicates with lighting equipment in two ways. The first is by using the Art-Net protocol, which uses an ethernet or WiFi network to transmit data. QLab sends Art-Net messages into the network, and those messages are received by other devices on the network which can interpret Art-Net messages.

While some lighting instruments and dimmers are able to receive and directly interpret Art-Net messages, most lighting equipment must be controlled using the DMX control protocol. To connect to DMX-controlled lighting equipment, you’ll need an Art-Net interface, often called a node, which is a device that receives Art-Net messages from a network and outputs DMX messages over a traditional DMX connection. QLab is compatible with any Art-net interface that uses ethernet or WiFi.

The second way QLab can communicate with lighting equipment is by using any of the following compatible USB-DMX interfaces:

  • Enttec DMX USB Pro
  • Enttec DMX USB Pro Mk2
  • DMXking ultraDMX Micro
  • DMXking ultraDMX RDM Pro
  • DMXking ultraDMX2 Pro
  • Yarilo DMX PRO

These devices connect directly to your Mac over USB, and output DMX using a traditional XLR-3 or XLR-5 DMX connection.

A Very Brief Introduction To DMX

DMX, which is short for Digital MultipleX, is a venerable, reliable digital communication standard for lighting equipment. DMX is generally transmitted using five-pin XLR cables, with one cable carrying a single universe of DMX. One universe contains 512 channels, and each channel is simply an address paired with a value. The status of the entire group of 512 channels is broadcast every 23 milliseconds or so; that’s called one frame of data. You can imagine a frame of DMX like this:

Address Level
1 50
2 75
3 08
512 00

(The … represents the rows for addresses 4 through 511.)

In this frame, address 1 is set to 50, address 2 is set to 75, address 3 is set to 8, and address 512 is set to 0. If the cable that carries this DMX data is plugged into, say, a rack of dimmers that are addressed as 1 through 24, then that frame of DMX will set dimmer 1 to 50, dimmer 2 to 75, dimmer 3 to 8 and so on up to 24. The dimmer will ignore the data for the rest of the DMX universe.

Levels in DMX range from 0 to 255, although most equipment represents that range on a percentage scale of 0 to 100.

You will sometimes encounter DMX-controlled devices which use RJ-45 connectors, which are the type of connector used for ethernet. It’s important to keep in mind that while the connector is physically identical, the language being “spoken” is not ethernet or Art-Net. You cannot plug such a device straight into an ethernet network and expect anything to happen.

The Light Patch

Before you can use lights in Light cues, you need to tell your workspace which lights it will be controlling, and what DMX addresses those lights are using. You do this for each QLab workspace in the Light section of Workspace Settings. There, you create instruments in the workspace and map them to the Art-Net/DMX addresses of real lights or dimmers in the physical world. You can also define light groups which behave as shorthand for collections of instruments.


In QLab, an instrument represents a single physical DMX-controlled object in the world. Your workspace will therefore need one instrument for every lighting fixture, DMX-controlled accessory, and dimmer in your plot. Each instrument has one or more parameters. Conventional lights, controlled by dimmers, have a single parameter: intensity. QLab also supports instruments with more than one parameter. This could include any kind of fixture that uses more than a single DMX address, such as lights which can pan, tilt, zoom, change color, etc.

Light Definitions

The parameters available for each instrument are specified by a light definition. QLab comes with a variety of light definitions for a range of lighting fixtures and dimmers, which you can find in the Light Library. You can copy and edit these definitions to suit your needs, and you can create new light definitions for any fixtures you’ll be using which are not already in QLab’s library. Any light definition you use in a workspace will be saved both in QLab’s master library, as well as a library within the workspace, so that the workspace may be safely moved from computer to computer.

If you do not wish to create your own definitions, please contact and tell us the exact model name of the fixtures you want to use, and we will be happy to create definitions for you.

Light Groups

In QLab, a light group is a collection of instruments or other light groups. For example, you might create a light group that contains all the front light in your plot, to allow you to quickly set them all to a given level. Instruments within a group can still be controlled individually at any time; the group is just a quick way to control several instruments at once.

Instruments and lighting groups may be given any name you like using letters, numbers, and spaces. By default, instruments are given numeric names, but they are not limited to numbers. For example, if you have an instrument that lights a particular location on the stage, such as a specific chair, you could name that instrument “chair” and refer to it as such. Similarly, you can name groups to reflect their function, such as “front light” or “warms”.

To add an instrument to a group, select the instrument and click the button labeled Add to Group…

Once you have created instruments (and, optionally, groups) for all of your lights, you are ready to start building cues.

Light Cues in QLab

In many respects, Light cues in QLab work just like cues in any other lighting console: they fade some number of instruments to specific levels over a given amount of time. An important difference, however, between QLab and most other lighting consoles is that in QLab, any instrument that is not included in a cue is given no level, rather than an assumed 0. Consider a show with six conventional lights in it:

Cue 1 2 3 4 5 6
0 0 0 0 0 0 0

(Here, each row is a cue, and each column is an instrument.)

Now, let’s add cue 1 which brings all the lights to full:

Cue 1 2 3 4 5 6
0 0 0 0 0 0 0
1 100 100 100 100 100 100

Let’s say that the next scene is on one half of the stage, so for cue 2 we want to turn the other half of the stage down very low. In QLab, that might look like this:

Cue 1 2 3 4 5 6
0 0 0 0 0 0 0
1 100 100 100 100 100 100
2 15 15 15  

For instruments 4, 5, and 6, the levels from cue 1 persist since cue 2 does not assign any levels to those instruments. When you launch QLab and then run cue 1 followed by cue 2, the real-world levels look like this:

Cue 1 2 3 4 5 6
0 0 0 0 0 0 0
1 100 100 100 100 100 100
2 15 15 15 100 100 100

The italicized levels in cue 2 are actually levels from cue 1 which have persisted. Cue 1 is the originating cue for the levels of instruments 4, 5, and 6. Cue 2 is the originating cue for the levels of instruments 1, 2, and 3.

If you open your workspace, starting with all lights off, and then run only cue 2, you’ll get this:

Cue 1 2 3 4 5 6
2 15 15 15 0 0 0

Lights 1, 2, and 3 will come on to 15%, and lights 4, 5, and 6 will remain off. Put another way, the order in which you run Light cue matters to QLab.

QLab provides a few tools which help you make use of this difference without letting it get in your way. You’ll learn more about those tools in the rest of the Lighting section of this documentation.

Still have a question?

Our support team is always happy to help.

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