The Lighting Command Language

QLab 4 uses a textual light command language which you can use to control your lighting instruments. At its core, every light cue contains a plain block of text which is interpreted as this command language. The basic formats of lighting commands are as follows:

instrument = value
instrument.parameter = value
group = value
group.parameter = value

Note that spaces in a lighting command are always optional. 10=53 is the exact same thing as 10 = 53.

When a command omits a parameter, QLab fills in the default parameter as specified by the instrument’s definition. Typically, this default parameter is intensity but it can be any parameter. So, if instrument 20 uses an instrument definition that sets the default parameter to intensity, 20 = 75 is the exact same thing as 20.intensity = 75.

When a command refers to group.parameter, the value of that command is passed to all instruments within the group that have that parameter. So the command group.blue = 50 would set the blue parameter of any instruments in that group to 50. Instruments which do not have the given parameter are ignored.

Percentages, DMX values, and decimal numbers

QLab supports both percentage values and “raw” DMX values. Individual parameters of instruments can be set to use one or the other in their definitions. If a parameter uses percentage values, QLab will accept decimal numbers on the command line or when typing into the text field of sliders or tiles. QLab will round your entry to the nearest DMX level equivalent.

For example, if instrument 1 in your workspace is a conventional dimmer set to accept percentage values, and you enter 1 = 10.7, QLab will round down to 10.59, because 10.7% is mathematically closest to DMX level 25, and the exact representation of 25 in DMX is 10.59%.

Pass

An instrument or group can be set to the value pass to explicitly prevent them from being adjusted by the current cue. Consider a show with a group called backlight, and three instruments in the group called left, center, and right. If a cue consists of the following commands:

backlight = 75
center = pass

then instruments left and right would be set to 75, and center would be left un-adjusted.

Home

The command instrument = home or instrument.parameter = home sets the instrument or parameter to its home value, as specified in the instrument definition. For example, the included “dimmer” definition has a home value of 0, so setting an instrument that uses the dimmer definition to home turns it off. The included “DMX iris” definition has a home value of 100, so setting an instrument that uses the DMX iris definition to home opens the iris all the way.

Up arrow

The up arrow key scrolls through the history of the command line, providing an easy way to experiment with a level. For example:

1 = 80 |Enter|
|Up|
70 |Enter|
|Up|
75 |Enter|

Instrument 1 is set to 80, then 70, then 75, and reentering the 1= is not necessary.

Ranges

A lighting command can also refer to a range of instruments:

1 - 3 = 50
10, 12, 14 = 75

The range will be expanded to its constituent commands before being added to the cue, or applied to the Dashboard. Thus, the commands above would appear in a cue as:

1 = 50
2 = 50
3 = 50
10 = 75
12 = 75
14 = 75

Ad-hoc Groups

You can alternately define an “ad-hoc” group by enclosing a range in brackets:

[1 - 3] = 50
[10, 12, 14] = 50

Bracketed commands remain as single commands in the cue, and behave just like groups.

Pull From Cue

Starting with QLab 4.1, you can instruct a cue to “pull” a value from another cue when it’s run. Those familiar with the idea of palettes or presets on other lighting consoles will find this concept familiar.

To pull levels from one cue into another, enter cue and the number of the cue you want to pull as the level for a light command. For example:

10 = cue A

This command sets instrument 10 to whatever values it has in cue A. If instrument 10 is not recorded in cue A, then this command has no effect. If instrument 10 is a multi-parameter instrument, the above command will set all the parameters of instrument 10 to the values they’re set to in cue A. You can also be more precise, if you like:

10.zoom = cue A

This command sets only the zoom parameter of instrument 10 to the value stored in cue A. If cue A contains light groups, you can pull the whole group or only part of the group into the new cue by making use of the fact that QLab interprets light commands sequentially. Consider a workspace where group1 contains instruments 1, 2, 3, and 4.

group1 = cue A
3 = pass
4 = 75

This series of commands combines together to give you the following results:

1 = (whatever it is in cue A)
2 = (whatever it is in cue A)
3 = (left alone)
4 = 75

If cue A is updated, any cues which pull from it will receive the updated values the next time they run. In this way, you can think of a pull command as being “linked” to the cue that it pulls from. To “break” this link, and make the command stop pulling from the source cue, you can click the Expand button next to the light command in the inspector. This copies the pulled level into the current cue, and turns that command into a normal light command.

Proportional Pulls

Starting with QLab 4.5, you can scale pulled values using the asterisk (*) character:

10 = cue A * .5

This command sets instrument 10 to half of whatever values it has in cue A. This can be an easy way to mimic a look from an earlier cue, but make it a bit dimmer or a bit brighter.