Welcome to the workspace

When you first open QLab, you’re presented with a new, fresh document. QLab documents are referred to as workspaces. A workspace contains one or more cue lists which contain cues.

Detailed descriptions of the various cue types and cue lists can be found in other sections of the documentation; for now we will focus on what you see when you look at a workspace.

download video ↓

A note on style

• On this page only, 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.)

The GO Button

Prominently located in the top left corner of the workspace, the GO button starts, or triggers, the cue which is currently standing by at the playback position. The playback position then advances to the next cue, which will then be standing by, displayed in the standby indicator and ready to GO. The default keyboard shortcut for the GO button is the space bar. You can change this shortcut in Settings.

The Standby Indicator

Located at the very top of the workspace across most of the width of the window, the standby indicator displays the cue number and cue name of the cue in the playback position. In other words, it tells you what cue will play the next time the cue list is triggered. When a cue is in standby, it will also appear highlighted in the cue list, with a small indicator arrow against the left edge of the workspace.

Beneath the standby indicator is the Notes field which displays notes associated with the currently standing-by cue.

The Notes Field

Beneath the standby indicator and to the right of the GO button is the Notes field. Text entered in this field is connected to the currently standing by cue, and is visible whenever that cue is standing by, so it is the perfect place for notes or special instructions to your operator. Text in the Notes field is searchable using the find feature.

Flagged Cues

Next to the Notes field is the Flagged checkbox. Flagging a cue is a way of marking it for later. You might, for example, flag cues during a run through of your show as a way of notating which ones need to be reviewed after the run through.

The Toolbar

The toolbar, found underneath the Notes field, is a ribbon of icons for each of the different cue types available in QLab. Clicking any of these icons will create a new cue of that type. Explanations of the different cue types can be found later in this documentation.

The Cue List

Beneath the toolbar is the cue list. It is composed of eight columns that provide information about each cue.

Playback Position

Along the left edge of the cue list is the playback position indicator (a right-facing grey pointer) which shows you which cue is on standby.

Cue Status

The left-most column displays the status of the cue:

• A green triangle means the cue is active.
• A yellow circle means the cue is loaded and is ready to be triggered.
• A red X means the cue is broken and cannot be played.
• A grey triangle outline means the cue has been stopped, but has an effect that must finish rendering before the cue can be started again.

This column also displays an icon depicting the cue’s type; these icons match the cue icons in the toolbar.

Cue Number

A cue number may be any text string, or may be empty. All cue numbers in a given workspace must be unique. Cue numbers do not need to be consecutive, nor do they need to be digits. Acceptable cue numbers could be “1,” “1.5,” “A,” “AA,” “A.5,” “Preshow Music,” or “Fred.” Change the number of a cue by double clicking in the cue’s number column, or by selecting the cue and using the keyboard shortcut N.

It’s important to realize that since cue numbers are text strings, “1”, “1.0”, and “1.00” count as three different unique cue numbers in QLab.

Renumbering Selected Cues

Select Renumber Selected Cues in the Tools menu, or use the keyboard shortcut ⌘R, to automatically assign new numbers to each currently selected cue in the workspace. Note that since cue numbers must be unique within the workspace, the renumber tool will skip numbers that already exist.

Cue Name

A cue name may be any text string, or may be empty. The name of a cue will default to reflect the name of its target; for Audio and Video cues, that is the name of the target file. For Fade cues, it will be the word “fade” plus the name of the cue that the Fade targets. Other types of cues have their own, hopefully logical, default names. You can change the name of a cue by double clicking in the cue’s name column, or by selecting the cue and using the keyboard shortcut Q. Unlike cue numbers, cue names do not have to be unique.

Note that changing the name of a cue will also change the name of any cues that target it (for example, Fade cues), if those cues are using their default names.

Target

A key concept in QLab is that some types of cues have a target which is the recipient of the action of that cue. So, Audio and Video cues have targets, which are media files. When an Audio cue is triggered, the target file is played. Fade cues have targets, which are other cues which have fade-able parameters, such as audio levels or video display geometry. When a Fade cue is triggered, the parameters of the target cue are faded. For cues that require a target, they must have one and only one target.

Thus, the target column shows different information for different types of cues.

For Audio and Video cues, the Target column displays a round button that looks like an upwards-pointing arrow inside a circle. Clicking this arrow will open a Finder window in which you can select the file you wish to target. You can also set the target of an Audio or Video cue by dragging and dropping an appropriate file onto the cue from the Finder.

Cues which target other cues, such as Fade cues and Stop cues, will display the cue number of their target cue. If the target cue has no number, the cue name will be displayed instead. If the cue lacks a target, the target column will display a question mark. You can assign a target to these sorts of cues by typing a cue number into the Target column, by dragging and dropping the cue onto its intended target, or by dragging and dropping the intended target cue onto the cue.

The default keyboard shortcut for changing the selected cue’s target is T.

Cues which do not require a target will show nothing in this column.

Pre-wait

Pre-wait is the amount of time that QLab waits between receiving a trigger for a cue and starting the action of that cue. For example, an Audio cue with a pre-wait of 3 would start playing sound three seconds after being triggered.

The pre-wait of a cue can be edited by double clicking and typing in the pre-wait column, or by using the keyboard shortcut E.

Action

The action of a cue tells you how long it takes for the cue to complete, not counting pre-wait. Action is often used interchangeably with “duration” conversationally. They are one and the same. The action of some cues cannot be edited directly, but for those that can, they can be edited by double clicking and typing in the action column, or by using the keyboard shortcut D.

Post-wait

The post-wait of a cue is meaningful only in combination with an as-yet-un-discussed feature: auto-continue. When a cue is set to auto-continue, then it triggers the next cue in the cue list when it is itself triggered. If the first cue has a post-wait time, then, once the first cue is triggered, QLab waits for the post-wait to elapse and then triggers the second cue.

The post-wait of a cue can be edited by double clicking and typing in the post-wait column, or by using the keyboard shortcut W.

Notes about pre-wait, action, and post-wait.

The pre-wait, action, and post-wait columns display seconds with two decimal places, but QLab is accurate to three decimal places.

When a cue is not playing, these columns will always display the total duration of the cue or its wait. When a cue is playing, you can toggle between seeing how far into a cue (or wait) you are and how far from the end of a cue (or wait) you are by clicking the arrows in the column headers.

It’s also important to remember that in the interest of keeping QLab’s interface from using too much processing power, QLab sometimes updates times as little as once per second, which means that the times displayed may appear to be wrong by as much as one second. This does not indicate that the actual behavior of QLab is off by a second, only the display. A paused cue will always display exact times.

Auto-follow and Auto-continue

The final column, labeled with a downwards-pointing arrow in the column header, displays icons indicating whether a cue has been set to auto-continue or auto-follow.

If a cue is set to auto-continue, as soon as the cue is triggered the next cue in the cue list will trigger as well. If the cue has a post-wait as well as an auto-continue, the post-wait will be honored before the next cue is triggered.

If a cue is set to auto-follow, then the next cue will be triggered as soon as the first cue completes. When you set a cue to auto-follow, QLab will automatically show a post-wait time equal to the action of the cue. This cannot be edited, and serves as a visual reminder of the auto-follow.

The Inspector

The inspector is located beneath the cue list, and can be shown or hidden by selecting Inspector from the View menu or using the keyboard shortcut ⌘I. The inspector is a tabbed interface. The Basics tab is the same for all cues and is a convenient place to adjust cue parameters such as number, name, and target. Other tabs vary based on what type of cue is selected, and will be explained later in this documentation.

The settings on the left side of the Basics tab refer to basic properties of the cue. Many of the properties shown in the Basics tab are also editable from the Cue list.

• Number. Discussed above.
• Color. The cue can be given a background color to make it stand out in the cue list. There are five colors to choose from; the X sets the background to no color. The color doesn’t alter the cue in any way, so feel free to adapt color coding in whatever way is most useful to you.
• Name. Discussed above.
• Target. This field, only relevant when the selected cue has a target, shows either the name of the target cue, or the full path to the target file depending on what type of cue is selected. Clicking the arrow button next to the target field will show you the target, either by jumping the cue list to the target cue, or opening a Finder window to show the target file.
• Pre Wait. Discussed above.
• Post Wait. Discussed above.
• Continue. Discussed above.
• Auto-load. If this box is checked, this cue will automatically be loaded after the previous cue is played. A global setting is available to set all new cues to auto-load by default.
• Armed. Cues are armed by default. When disarmed, cues will not execute their action, but an auto-continue or auto-follow will be triggered if present. Disarming a cue is useful, for example, for temporarily silencing a cue while allowing the surrounding cues to operate as-is.

download video ↓

The settings on the right side of the tab refer to four ways to trigger a cue directly. You can use these triggers in any combination.

• MIDI Trigger. Individual cues can be triggered with external hardware or software using MIDI voice messages here. Check the box to enable the trigger, and then either program in the message manually, or click the Capture button to record an incoming message. MIDI trigger values can include > and < operators, or be set to “any”. This is particularly helpful for MIDI Note On messages, where a specific note velocity won’t necessarily be achieved with each press of the MIDI controller. Set the velocity (byte 2) to “any”, and the note will be the specific part of the message, rather than being limited to a particular velocity along with the note. Then, no matter how hard you press the piano key (as an example), the cue will start.
• Hotkey Trigger. The spacebar is the default keyboard command to start the cue in the playback position (the GO button), but most keys on the keyboard can become a trigger for a given cue regardless of its playback position. Note that some keys are reserved by QLab, such as Esc (panic/stop all), and keys that have already been assigned functions in Key Map Settings. Hotkey triggers behave just like regular keyboard shortcuts for menu items; for example, by assigning the Hotkey “J” to cue 49, any time you press J on the keyboard, cue 49 will start even if it is not currently on standby. Hotkeys may include modifier keys (option, control, function, and shift). Hotkeys are particularly useful for triggering scripts that act on selected cues. Click the X to clear the hotkey assignment.
• Wall Clock Trigger. This will trigger a cue at a specific time of day and, optionally, only on certain days of the week. Please note that computer clocks will drift if left to their own devices, so if your show computer is offline or if you’ve disabled online clock setting, be sure to check your clock’s accuracy from time to time.
• Timecode Trigger. Cues can be triggered from incoming LTC or MTC timecode, but only if timecode has been enabled for the enclosing cue list. You can enable timecode for a Cue List in the Sync tab of the inspector when the cue list is selected. The dropdown menu lets you choose to enter the timecode trigger using either the timecode format of hours:minutes:seconds:frames or the real-time format of hours:minutes:seconds:decimals.

download video ↓

Workspace Footer

Edit Mode and Show Mode

On the left side of the workspace window footer, two buttons allow you to toggle between Edit mode and Show mode. When a workspace is in show mode, the following functions of QLab are disabled:

• The inspector
• The toolbar
• Load-to-time
• Find
• Adding, deleting, or reordering cues
• Editing any cue properties (name, number, target, times, etc.)
• Copy and paste levels
• Copy and paste geometry
• Copy and paste fade shape

Just as important is the list of things which are not disabled in show mode:

• The Audition window
• Opening, closing, and saving workspaces
• Use of the ESC key
• Showing or hiding the Cue lists & active cues display
• Viewing and changing workspace settings

Show mode is a safety mechanism designed to prevent accidental changes to a workspace, not a security mechanism to prevent deliberate changes.

Cue and Cue List Count

The center of the footer displays the number of cues in the workspace and the number of cue lists into which they are divided.

Broken Cues and Warnings

The Broken Cues icon will appear in the bottom right corner of the workspace window when (and only when) the workspace contains broken cues. Clicking this icon displays a list of all broken cues, explains why they’re broken and provides instructions for how they can be fixed. Learn more about this in the Workflow Tools section.

Sidebar

Click the Sidebar button in the bottom right corner of the workspace window to show or hide the sidebar. Learn more about this in the Workflow Tools section.

Settings

The gear in the bottom right corner of the workspace allows you to access its settings. Learn more about this in the Settings section.

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.

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 documentation.

Targeting Audio and Video cues

Audio and Video cues require a target which is a file containing the relevant type of media. There are several ways to assign a target to an Audio or Video cue:

1. Click the target button for the cue in the cue list.
2. Select the cue and type the target hotkey, 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.

Targeting other cues

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

1. Double-click in the target column in the cue list.
2. Select the cue and type the target hotkey, T by default.
3. Double-click in the target field in the Basics tab of the inspector.
4. Drag and drop the intended target cue onto the cue in the cue list.

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 a Fade cue, the default duration is five seconds.

When you start a cue, the playback position will advance to the next cue. On the next press of the GO button or space bar, the next cue will start. If you’re accustomed to using a non-theatrical playback program such as iTunes, this behavior can be disorienting at first. Fear not, for this is how QLab is meant to work.

Rules for control

QLab can be told to GO, which is to say, to trigger the cue or cue sequence that is currently standing by, and advance the playback position to the next cue or cue sequence, in a number of ways. You can:

1. Click on the GO button with the mouse.
2. Press space (or whichever keyboard shortcut you assigned to GO.)
3. Send an OSC “/go” command to QLab from another program or an external device.
4. Send another OSC command that you assigned to “GO” in OSC Controls.
5. Send an MSC “Go” command to QLab from another program or an external device.
6. Send a MIDI message that you assigned to “GO” in MIDI Controls.
7. Run an AppleScript which sends the “go” command to QLab.

There are similar options for other commands such as stop, panic, pause, and so forth. The purpose of this plurality is to accommodate the myriad situations and possibilities that QLab might encounter in the world, and make it easier for you to use QLab in the way that suits your needs or your style.