In this section, 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 for emphasis, to highlight keyboard shortcuts (like ⌘S), and for indicating a menu name (such as the File menu.)

A cue is the most basic unit of action in QLab. A single cue causes a single event to occur when it is started, and the type of event which occurs is dependent upon the type of cue.

Here is a cue numbered 1 and named “Preshow announcement,” which is selected (highlighted with the blue bar.) The color of the selection highlight may be different on different Macs; it can be configured in System Preferences → General.

The white triangle on the left edge of the cue list is called the playhead and it indicates that cue 1 is standing by. When the button is pressed, the cue that is standing by will be started, and the playhead will advance down the cue list, in this case to cue 2, named “Opening song”.

Making Cues

There are several ways to make a cue in QLab:

1. Click on one of the cue type icons in the toolbar.
2. Drag a cue type icon from the toolbar into the cue list.
3. Double-click on a cue type in the toolbox.
4. Drag a cue type from the toolbar into the cue list.
5. Select a cue type from the Cues menu.
6. Use one of the ⌘-number keyboard shortcuts for the first ten cue types.
7. Drag a compatible audio or video file from the Finder into the cue list.
8. Hold down the option key while dragging a cue in the cue list to make a copy of it.

There are also ways to make cues using OSC and AppleScript, which you can learn more about in the OSC Dictionary and AppleScript Dictionary sections of this manual.

Setting File Targets, Cue Targets, and Patch Targets

An important basic rule of QLab is that some kinds of cues require a target, which is the thing that the cue acts upon. Some cues target media files on your computer, some cues target other cues, some cues target other cues or patches, and some cues have no target. Cues which require targets will not work unless one has been assigned, and they can only ever have one target at a time.

Audio, Video, and MIDI File cues - file targets

Audio, Video, and MIDI File cues require a file target which is a file on your Mac containing audio (for Audio cues,) video (for Video cues,) or MIDI data (for MIDI File cues.) There are several ways to assign a file target to cue:

1. Click the button for the cue in the Target column of the cue list.
2. Select the cue and type the keyboard shortcut for Edit target, which is T by default.
3. Double-click in the target field in the Basics tab of the inspector.
4. Drag and drop a file from the Finder onto the cue in the cue list.
5. Drag and drop a file from the Finder into the target field in the Basics tab of the inspector.

If a cue’s file target is deleted or moved to the trash, the cue will break.

Other cues - cue targets

Cues which require a cue target, which is another cue, include Fade, Start, Stop, Pause, Load, Reset, Devamp, GoTo, Target, Arm, and Disarm. There are several ways to assign a cue target to a cue:

1. Double-click in the target column in the cue list and enter the cue number of the intended target.
2. Select the cue and type the keyboard shortcut for Edit target, which is T by default, then enter the cue number of the intended target.
3. Double-click in the target field in the Basics tab of the inspector and enter the cue number of the intended target.
4. Drag and drop the intended target cue onto the cue in the cue list.
5. Drag and drop the cue onto its intended target cue in the cue list.

Additionally, QLab has special behavior when you create a new cue that requires cue targets using the toolbar, toolbox, Cues menu, or ⌘-number keyboard shortcut:

1. If no cues are selected, then the new cue is created without a target.
2. If one cue is selected, then the new cue is created targeting the selected cue.
3. If more than one cue is selected, QLab asks you whether you want to create multiple targeted cues, one after each selected cue; multiple targeted cues all after the last selected cue, or only one single new cue.

You can choose which behavior you want by clicking on the appropriate button, or pressing the corresponding number key on your keyboard. You can also hit the enter or return key on your keyboard to select the default choice, which is the highlighted button, or the escape key to dismiss the question and create no cues.

Whichever option you select will become the default option the next time QLab presents this question.

Fade cues and Reset cues - patch targets

Fade cues and Reset cues have the additional ability to target patches as well as cues. When cue targets a patch, it adjusts parameters of that patch, which can have an effect on every cue which uses that patch. To assign a patch target:

1. Select the cue and navigate to the Basics tab in the inspector.
2. Click the pop-up menu labeled Target and choose Patch.
3. Another pop-up menu will appear immediately to the right. Use that menu to select the attribute you want the cue to adjust.

Types of Cues

Group cues contain other cues, and have several different modes which cause different behaviors. Group cues have different icons for their different modes, all of which have the same basic shape. You can read more about Group cues here.

Audio cues play pre-recorded audio using your Mac’s built-in speakers, headphone jack, or another audio device. They require a target which must be a compatible audio file. You can read more about Audio cues here.

Mic cues route live audio through QLab. You can read more about Mic cues here.

Video cues play pre-recorded moving or still images on one or more projectors, displays, or screens connected to your Mac. They require a target which must be a compatible video or image file. You can read more about Video cues here.

Camera cues route live video through QLab, using the same outputs as Video cues. You can read more about Camera cues here.

Text cues display formatted text using the same outputs as Video cues. You can read more about Text cues here.

Light cues control lights and other DMX-controllable equipment connected to your Mac using Art-net or a USB-DMX device. You can read more about Light cues here.

Fade cues adjust one or more parameters of another cue in your workspace. They require a target, which must be an Audio, Mic, Video, Camera, or Text cue. Fade cues have different icons for absolute mode and relative mode. You can read more about Fade cues which target Audio and Mic cues here. You can read more about Fade cues which target Video, Camera, and Text cues here.

Network cues send OSC messages and some other types of messages using your Mac’s network connection. You can read more about Network cues here.

MIDI cues send MIDI Voice, MIDI Show Control, or MIDI System Exclusive (SysEx) messages using a MIDI device connected to your Mac. You can read more about MIDI cues here.

MIDI File cues play pre-recorded MIDI files using a MIDI device connected to your Mac. They require a target which must be a MIDI file. You can read more about MIDI File cues here.

Timecode cues either generate Linear Timecode (LTC) and play it using an audio device connected to your Mac, or generate MIDI Timecode (MTC) and play it using a MIDI device connected to your Mac. You can read more about Timecode cues here.

Start cues tell another cue to start playing. They require another cue as a target. You can read more about Start cues here.

Stop cues tell another cue to stop playing. They require a target which can be any cue. You can read more about Stop cues here.

Pause cues tell another cue to pause. They require a target which can be any cue. You can read more about Start cues here.

Load cues tell another cue to load. They require a target which can be any cue. You can read more about Load cues here.

Reset cues tell another cue to reset. They require a target which can be any cue. You can read more about Reset cues here.

Devamp cues tell a cue which is looping to get to the end of the current loop, and then exit the loop. They require an Audio or Video cue as a target. You can read more about Devamp cues here.

Go To cues move the playhead to their target. They require a target which can be any cue. You can read more about Go To cues here.

Target cues tell another cue to change its target. They require any cue which can accept targets as their target. You can read more about Target cues here.

Arm cues arm their target cue. They require a target which can be any cue. You can read more about Arm cues here.

Disarm cues disarm their target cue. They require a target which can be any cue. You can read more about Disarm cues here.

Wait cues do nothing by themselves, but can be useful as part of a cue sequence. You can read more about cue sequences here.

Memo cues are placeholders which have no effect when played. They can be used to provide in-line notes to the person operating QLab or any similar reason.

Script cues execute AppleScript. You can read more about Script cues here.

Rules for cues

Once started, cues continue to play until they reach the end of their programmed action, or until they’re told to stop. For an Audio or Video cue, a cue’s action is the duration of the media file which it targets unless you program it otherwise. For example, an Audio cue that targets a one minute long audio file will play that whole file and therefore last for one minute, but the cue can be programmed to play only a portion of the file and thus last for less than one minute, or to repeat some or all of the file and thus last for more than one minute. For a Fade cue, the default duration is five seconds, although you can change that default in Workspace Settings → Templates → Cue Templates → Fade.

By default, cues which are running will ignore additional commands for them to start. You can alter this behavior on a cue-by-cue basis in the Triggers tab of the inspector.

When you start a cue, the playhead will advance down the cue list. On the next press of the button or its keyboard shortcut (space by default), the next cue will start. If you’re accustomed to using a non-theatrical playback program such as Apple Music or Spotify, this behavior can be disorienting at first. Fear not, for this is how QLab is meant to work.

Batch editing cues

When more than one cue is selected, QLab allows you to simultaneously edit properties that the selected cues all have in common. Not all properties of cues are batch-editable, but you can expect future releases of QLab to expand the list of batch-editable properties.

Whenever multiple cues are selected, the inspector shows only tabs which contain batch-editable properties. When the selected cues are of mixed types, only the Basics and Trigger tabs will be shown since those are the only tabs that all cues have in common.

You can set a batch-editable property in all selected cues to the same value by using the contextual menu (right-click, control-click, or two-finger-click), the inspector, or the keyboard shortcut for editing that property.

You can set a batch-editable property of an individual cue within the selected set by using the mouse in the cue list to edit the property. The other selected cues will not be edited.

It’s important to remember that batch editing a property sets that property to the same value in all selected cue. For example, if you have selected two Audio cues whose main audio levels are set to different values, batch editing the main audio level will set both cues to that same new level.