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 QLab document is called a workspace. Workspaces contain one or more cue lists and/or cue carts, which each contain cues. Workspaces also contain settings and configuration details which govern how QLab behaves when that workspace is in use.

A QLab workspace can have multiple windows that belong to it. Most of those are optional, or only necessary to use from time to time, and you’ll learn about them throughout this manual.

The main workspace window is what you’ll see when you create a new QLab workspace or when you first open an existing one.

The Title Bar

Most windows have a title bar, and QLab workspace windows are no exception.

The “traffic light” buttons on the left control the visibility of the window: clicking the red button closes the window, clicking yellow minimizes the window into the Dock, and clicking green zooms the window into fullscreen mode.

If the workspace has unsaved changes, a dark dot will appear inside the red button. If you try to close a workspace with unsaved changes, you’ll be asked if you want to save those changes or not before closing.

The title bar also displays the name of the workspace followed by the name of the currently visible list or cart. In the screen shot above, the workspace is named Welcome to QLab 5.qlab5 and the current cue list is called Main Cue List.

The Masthead

The top section of the workspace window is called the Masthead, borrowing a journalistic term for the top section of the front page of a newspaper.

The four elements of the masthead are the button, the standby display, the notes field and the toolbar.

The GO button

The GO Button tutorial is a hands-on exploration of the topics discussed in this section.

Clicking the button starts the cue which is listed in the standby display. QLab then advances the playhead to the next cue, which will then be standing by and ready to .

The appearance of the button changes based on context:

• A green border appears around the button when a cue is standing by and QLab is ready to play that cue. In essence, the green border means that GOing will do something.
• A red border appears around the button to indicate that GOing is temporarily disabled due to double-GO protection.
• When a Cart is active, the button becomes a “Preview” button. You can learn more about what that means and why it happens in the Cue Carts section of this manual.
• When the workspace is set to always audition, the button becomes an “Audition” button. You can learn more about auditioning in the Auditioning Cues section of this manual.

The default keyboard shortcut for the button is space. You can change this shortcut in Workspace Settings. This keyboard shortcut always operates the button, whether it’s currently labeled GO, Preview, or Audition.

The Standby display

The cue that is standing by is listed here, to the right of the button. If the cue has a cue number, the cue number is shown first, separated from the cue name with a bullet (•). The cue that is standing by is also identified in the cue list below using the playhead, which is a light-colored, right-pointing triangular indicator.

Each cue list in a workspace has its own playhead, and therefore its own idea of which cue is standing by. The button and its keyboard shortcut only apply to the active list.

The Notes field

Beneath the standby display, also to the right of the button, is the Notes field. Text entered here is connected to the cue that is standing by, and is visible whenever that cue is standing by. This makes it the perfect place for any notes or special instructions to your operator which pertain to that cue.

Text in the Notes field is searchable using the Find tool. It can be styled and formatted, and can include emoji and images.

You can edit a cue’s notes here in this field, or in the Basics tab of the inspector. You can also select a cue and use the keyboard shortcut to edit notes, which is O by default.

The Toolbar

The toolbar, found underneath the Notes field, is a row of buttons for each of the different cue types available in QLab. Clicking any of these icons will create a new cue of that type in the current cue list. Explanations of the different cue types can be found in the Cues section of this Manual.

This space can also be used by the Find tool and the Load To Time tool.

The masthead can be resized by clicking and dragging on the horizontal divider that separates it from the cue list. Dragging all the way up will collapse and hide the masthead completely, and dragging back down from the top will restore it. When the cursor is hovering over the divider, the pointer will turn into a horizontal line with arrows.

The masthead can also be shown and hidden by choosing GO Button / Standby Display / Toolbar from the View menu, or by clicking the button in the footer.

The Cue List

The middle section of the workspace window shows the current active cue list or cart. Newly created workspaces generally default to showing a cue list, although you can make workspaces that contain only carts and no lists. When a cue list is active, it looks like this:

The cue list is a table with one row for each cue, listed in the order that they will play from top to bottom. Each column shows a different essential piece of information about each cue.

Status

The status column shows icons indicating the current status of the cue.

The Playhead

If the cue is standing by, the playhead appears on the absolute left edge. The playhead is a very light grey triangular pointer. If a cue is not standing by, clicking in the status column moves the playhead to that cue, thus making that cue stand by.

Cues might also display any of the following icons:

• A green triangle means the cue is active.
• A pair of yellow bars means the cue is paused.
• A yellow disc means the cue is loaded. Loaded cues are ready to be started with a minimum of latency, although loading cues before starting them is usually unnecessary.
• A yellow slope means the cue has been stopped, but has an effect that is tailing out. This icon remains visible as long as the cue’s effects are still producing audio, such as an echo, a reverberation, or a distortion effect. The length of this “tail” can be adjusted within the audio effect itself, although QLab also leaves the audio pathway open for some additional time afterwards, just to be completely sure that no effect gets cut off prematurely.
• A red X means the cue is broken and cannot be played. Hovering the mouse over the red X will show a tool tip with a brief explanation of the problem. You can also see a list all the broken cues in the workspace in the Warnings tab of the Workspace Status window.
• A yellow triangle with an ellipsis inside is a non-breaking warning, meaning there’s something wrong with cue, but not in a way that is likely to interfere with a show. Cues with non-breaking warnings are also listed in the Warnings tab of the Workspace Status window.
• A red circle with a slash through it means that an override is suppressing the cue’s output. You can learn more about overrides in the Override Controls section of this manual.
• A yellow flag means the cue has been flagged.
• A yellow double-slope icon means the cue is currently crossfading with another cue. It’s only used in conjunction with a Group cue in playlist mode.
• A hollow green play triangle in parentheses means the cue is being auditioned.

Cue Type

To the right of the status icon is an icon depicting the type of the cue. For Group cues and Fade cues, which each have more than one mode, the icon varies depending upon the mode of the cue. These icons match the icons used in the Toolbar and the Toolbox.

Cue Number

A cue number may be any text, or may be empty. All cue numbers in a workspace must be unique. Cue numbers do not need to be consecutive, nor do they need to be digits. Some examples of acceptable cue numbers are: 1, 1.5, A, AA, A.5, Steve, or .

While QLab allows you to use digits, letters, punctuation, and emoji in cue numbers, you need to stick to only digits if you plan to use MIDI or MSC to remote-control cues, and only ASCII characters¹ if you plan to use OSC.

You can 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 for editing cue numbers which is N by default. Changing a cue’s number will not affect any cues that target it, or really anything else in fact.

It’s important to understand that since cue numbers are text strings, 1, 1.0, and 1.00 are technically three different unique cue numbers in QLab. If you’re using MIDI, MSC, or OSC for show-control and relying on matching cue numbers across different systems, be sure to match numbers character-by-character, not just semantically.

Reordering cues in the list does not automatically renumber them, and QLab does not care about “out of order” cue numbers.

Renumbering Selected Cues

You can automatically assign new cue number to each currently selected cue by selecting Renumber Selected Cues from the Tools menu, or using the keyboard shortcut ⌘R.

The cue renumbering tool allows you to select a starting number, an increment value, an optional prefix, and an optional suffix. The tool will use the starting number for the first selected cue and then add the increment value to the starting number for each subsequent cue. If you provide a prefix and/or suffix, those will be prepended or appended to every renumbered cue accordingly.

Since cue numbers must be unique within the workspace, the renumber tool will automatically skip over numbers that already exist within the workspace.

Cue Name

A cue name may be any text, or may be empty. For many cue types, QLab fills in a default name which reflects an essential attribute about the cue.

Cue type	Default name
Audio	The file name of the target audio file.
Video	The file name of the target video or image file.
Text	The text entered in the Text tab of the inspector.
Light	If the Light cue contains a single light command, the default name will be that full command. If the Light cue contains more than one command, the default name will be “fade x lights” where x is the number of instruments that have commands in the cue.
Fade	“fade” plus the name of the cue being faded. If the fade is set to stop target when done, the default name is “fade and stop” plus the name of the cue being faded.
Network	The network command sent by the cue.
MIDI	The type of MIDI message sent by the cue.
MIDI File	The file name of the target MIDI file.
Timecode	The starting frame of timecode sent by the cue.
Start, Stop, Pause, Load, Reset, Go To, Arm, Disarm	The type of cue plus the name of the target cue.
Wait	“wait” plus the duration of the cue.

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 for editing cue names which is Q by default. Unlike cue numbers, cue names do not have to be unique.

Changing the name of a cue will also change the name of any cues that target it, if those cues are using their default names.

Deleting the name of a cue will reset it to its default name, if that type of cue has one, or to empty if not.

Target

Some types of cues require a target which is the recipient of the cue’s action.

Cue type	Target type	Acceptable targets
Group, Mic, Camera, Text, Light, Network, MIDI, Timecode, Wait, Memo, Script	None	—
Audio	File target	Any core-audio-compatible audio file (AIFF, WAV, CAF, MP3, MP4, M4A, AAC, etc.), except for files which are subject to digital rights management.
Video	File target	Any AVFoundation-compatible video file (MOV, MP4, M4V, etc.) containing video in an AVFoundation-compatible format (ProRes, PhotoJPG, H.264, H.265, Hap, and others.)
Fade	Cue target	Group, Audio, Mic, Video, Camera, and Text cues.
Start, Stop, Pause, Load, Reset, Devamp, Go To, Target, Arm, Disarm	Cue target	Any cue. Some cue targets may not have much of an effect (e.g. a Pause cue can target a Memo cue, but since a Memo cue doesn’t have a duration, there’s nothing to pause.)

Since different types of cues have different types of targets, the target column can show different types of information for different cues.

For cues which accept file targets, namely Audio, Video, and MIDI file cues, the Target column displays a round button with this icon: . Clicking this button will display a window in which you can select the file you wish to target. You can also set a cue’s file target by dragging and dropping an appropriate file onto the cue’s Target column from the Finder.

Cues which accept cue targets, such as Fade cues and Stop cues, will display the cue number of their target cue. If the target cue has no number, the target cue’s 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 the Target column of its intended target, or by dragging and dropping the intended target cue onto the Target column of 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 an optional delay that transpires before the cue starts. For example, when you start an Audio cue with a pre-wait of 3, that cue will allow three seconds to elapse, counting down its pre-wait, and then the audio will begin playing.

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 for editing pre-wait which is E by default.

Duration

The duration of a cue is the length of time it takes for the cue to complete, not counting its pre-wait. The duration of some cues cannot be edited directly, but for those that can, they can be edited by double clicking and typing in the duration column, or by using the keyboard shortcut for editing durations which is D by default.

Cues which have an instantaneous action, such as a Pause cue or a MIDI cue that sends a single Note On message, have no listed duration.

Post-Wait

The post-wait of a cue is meaningful only in combination with an as-yet-un-discussed feature of cues: auto-continue. When a cue is set to auto-continue, it starts the next cue in the cue list when it is itself started. If the first cue has a post-wait time, QLab waits for the post-wait to elapse and then starts 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 for editing post-wait which is W by default.

Continue Mode

The final column, labeled with this icon: , displays the continue mode of the cue. Cues have one of three continue modes:

If a cue is set to auto-continue ( ), starting that cue will start the following cue as well. If the first cue has a post-wait, the post-wait will be honored before the next cue is started.

If a cue is set to auto-follow ( ), then the next cue will be started 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 duration of the cue. This cannot be edited, and serves as a visual reminder of the auto-follow.

When you connect two or more cues with auto-follows and/or auto-continues, that’s called a cue sequence, which you can learn more about from the cue sequences section of this manual.

The continue mode of a cue can be editing by clicking in the cue’s continue mode column and using the pop-up menu which appears, or by using the keyboard shortcut for editing continue mode which is C by default.

The Inspector

Below the cue list is the inspector, which lets you view and edit the parameters of the selected cue or cues.

The tabs that appear in the inspector, and the contents of those tabs, will vary based upon the type and number of cues that are selected. The inspector always shows at least the Basics tab, shown in the screen shot above, and the Triggers tab.

The inspector can be resized by clicking and dragging on the horizontal divider that separates it from the cue list. Dragging all the way down will collapse and hide the inspector completely, and dragging back up from the bottom will restore it. The inspector can also be shown and hidden by choosing Inspector from the View menu, by using the keyboard shortcut ⌘I, or by clicking on the button in the footer.

You can learn more about the inspector and how to use it in the Inspector section of this manual.

The Footer

At the very bottom of the workspace window is the window footer.

The Edit/Show mode buttons let you switch the workspace between edit mode, which is the default mode, and show mode. When a workspace is in show mode, the following tools and functions of QLab are disabled:

• The inspector
• The toolbar
• The toolbox
• Load to Time
• Find
• Adding, deleting, and moving cues
• Editing, copying, and pasting any cue properties using the mouse or keyboard

Equally important are the things which are not disabled by when in Show mode:

• Quitting QLab
• Opening, closing, and saving workspaces
• Using the escape key
• Editing cue properties using AppleScript and OSC
• Viewing and changing workspace settings

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

When a workspace is in show mode, QLab will ask for confirmation before closing the workspace or quitting.

Next to the Edit/Show buttons are two icons:

• Click here to open or close the Toolbox.
• Click here to open or close the Masthead.

The cue count in the center of the footer displays the number of cues in your workspace and the number of cue lists and carts in which those cues reside. This is useful for confirming which copy of a workspace has the most recent work, and it’s also pretty useful for bragging about your show.

The center of the footer also sometimes displays other informational text about the overall status of the workspace. This text can pertain to workspaces in Demo mode, workspaces set to always audition, and Override Controls.

The right side of the footer shows three or four icons:

• Always visible. Click here to open the Workspace Settings window.
• Always visible. Click here to open or close the Sidebar.
• Always visible. Click here to open or close the Inspector.
• Visible only when the workspace contains a broken cue or a warning. Click here to open the Warnings tab of the Workspace Status window and see details about the problem.

The Sidebar

The sidebar is an optional display on the right side of the workspace window. It has a set of controls at the top, and a two-tabbed section below. You can open and close the sidebar by clicking on the button in the footer, by choosing Lists / Carts & Active Cues from the View menu, or by using the keyboard shortcut ⌘L.

Sidebar Controls

The four buttons at the top of the sidebar have an effect on all cues in all lists and carts in the workspace.

• The reset button hard stops all running cues, resets all temporary properties² of all cues, returns the playhead for each cue list to the first cue in that list, and loads the first cue in every list. In effect, clicking the reset button makes the workspace behave as though it was just opened. If the workspace has a workspace open cue, however, that cue will not automatically run when the workspace is reset.
• The pause all button pauses all currently running cues in the workspace. This button is yellow when cues are running, and thus pause-able.
• The resume all button resumes all currently paused cues in the workspace. This button is green when cues are paused, and thus resume-able.
• The panic button panics all running cues. In QLab, panic means to fade and stop all cues using the panic duration, which is set in Workspace Settings → General.

Lists and Carts

The left tab in the sidebar displays the lists and carts in the workspace. The label of the tab will change to reflect the number of list and/or carts in the workspace.

By default, a workspaces will contain one list named “Main Cue List.” You can change this name as you prefer. You can add lists and carts using the New List and New Cart buttons at the bottom of the sidebar. To delete a cue list or cart (and all the cues in it!), select the list or cart and choose Delete from the Edit menu or use the keyboard shortcut ⌘⌫ (delete).

To open a list or cart in a new window, select that list or cart and click Open in New Window, or by right-clicking (or control-clicking, or two-finger-clicking) on the list or cart and using the contextual menu. Windows opened in this way are called secondary windows, and they have some behavior that is different from the main workspace window:

• They have no toolbar
• They have no inspector
• They have a different footer which contains only a menu to choose which list or cart they show
• When the workspace is in show mode, they display the words SHOW MODE in their footer.

Although secondary windows appear to always be in show mode, as long as the workspace is in edit mode you can edit cues in secondary windows using the basic editing keyboard shortcuts found in Workspace Settings → Controls → Keyboard or by right-clicking (or control-clicking, or two-finger-clicking) and using the contextual menu.

For more information about cue lists and cue carts, check out the cue list section of this manual and the cue carts section of this manual.

Active Cues

The right tab in the sidebar shows all cues in the workspace which are currently playing or paused.

Each active cue is displayed in its own row showing the cue’s number and name with the elapsed and remaining time just below. If the cue has a cue color, that color is shown on the left edge of the row.

On the left side of each row is a pause/resume button, on the right side is a panic button, and throughout the whole row is a progress bar, colored green when the cue is playing and yellow when the cue is paused, which gives a visual indication of the progress of the cue.

If you hover your mouse over an active cue, the leading edge of the progress bar will show a thick yellow line, which can be dragged left or right to scrub the cue backward or forward.

Active cues are listed in the order in which they were started. By default, each cue that’s started gets added to the bottom of the list, so the most recent cue is always at the bottom. You can reverse this order, putting the most recent cue at the top, in Workspace settings → General → Display.

The Toolbox

The toolbox is an optional miniature sidebar on the left side of the workspace window. You can open or close the toolbox by selecting Toolbox from the View menu, by using the keyboard shortcut ⌘K, or by clicking the button in the footer.

The toolbox provides an alternative view of the toolbar; the two are very nearly identical. However, you can re-order cues in the toolbox. This lets you keep the cue types that you use most often close at hand. If you re-order the cues, notice that the ⌘-number keyboard shortcuts remain assigned to the first ten cues. In this way, you can assign ⌘-number keyboard shortcuts to the cues you prefer.

Reordering cues in the toolbox will reorder them in the Cues menu, but not in the toolbar.