Audio cues allow you to play sound files with precise control over timing, levels, and routing. Audio cues must have a file target, which is a sound file on your computer, and an audio output patch, which connects QLab to a sound output destination such as your computers’ speakers or headphone jack, an audio interface, or a network-based output such as Dante, AVB, or NDI.

Audio Files

Audio cues may target any file type supported by Core Audio (Apple’s audio framework), but we recommend the following types:

• AIFF - the Audio Interchange File Format
• WAV - the Waveform Audio File format
• CAF - Core Audio Format
• AAC - Advanced Audio Coding format
• MP4 - MPEG-4 part 14 container format (which is usually just an AAC audio file wearing a different set of clothes.)
• M4A - MPEG-4 Audio container format (which is also just AAC.)

QLab also supports MP3 files, by their very design they incur a variable and unpredictable delay when decoding and playback begins. This makes exact timing impossible when using MP3 files. For this reason, and also because they usually don’t sound very good, we do not recommend using them unless you are certain that their limitations are not relevant to your show.

Audio cues can also target any file type supported by Video cues; the audio portion of the file will be used and the video portion of the file will be ignored.

Without getting too far into the technical weeds, AIFF, WAV, and CAF files will give you the best audio quality and the least technical trouble and those are the formats that we recommend most highly.

Audio File Details

QLab can target multichannel audio files and will recognize the first 24 channels in an audio file².

QLab supports audio file targets at any sample rate from 8 kHz up to 192 kHz, and any bit depth from 8-bit up to 32-bit³.

Through the low-level audio frameworks built into macOS, QLab automatically and seamlessly performs any necessary sample rate and bit depth conversion on the fly to match the requirements of the audio output patch. This means that you do not need to choose a single sample rate and bit depth to work with; workspaces can target audio files of various rates and depths, and you can use audio outputs with various rates and depths.

This on-the-fly conversion is a very efficient process and in most situations you will not need to concern yourself with the matter. If you are trying to squeeze every available drop of performance out of your system, you can convert all your audio to the same sample rate and bit depth as your output hardware is using.

The Inspector for Audio Cues

When an Audio cue is selected, the inspector shows the Basics tab and Triggers tab, used by all cues, as well as the following tabs:

The I/O Tab

The I/O tab lets you assign a target audio file and audio output patch, and view details about them as well.

File Target. If a target audio file is assigned, this field shows the path to that file. You can double-click on the field to select a file target, or you can drag and drop a file in from the Finder.

Clicking the button removes the target file from the cue (though it does not delete the file itself, of course.)

Clicking the button reveals the target file in the Finder.

These controls are also visible in the Basics tab; you can use either one or both interchangeably.

Format displays some technical details of the target audio file, including the type of file and codec in use, number of channels, and sample rate.

Audio Output. This pop-up menu allows you to select an audio output patch for the cue to use. Clicking on the menu allows you to select one of the audio output patches already configured in the workspace, or (unpatched) if you want to ensure that the cue does not play when started. You can also choose Open Audio Settings to edit patch list… to quickly get to Workspace Settings → Audio → Audio Outputs, or choose New patch with audio device to quickly generate a new audio output patch and select it for use.

The Edit… button opens the audio output patch editor for the currently selected audio output patch, for quick access.

Format displays the number of channels and sample rate of the audio device used by the selected audio output patch. Note that for virtual audio devices such as Existential Audio’s BlackHole or the venerable Soundflower, the sample rate may not display accurately at all times, or even at all. Virtual devices are not always able to provide this information; it’s not necessarily a sign of a problem.

The Time & Loops Tab

The Time & Loops tab lets you adjust time-based behaviors of the cue and view a waveform representation of the target audio file.

Start Time and End Time

Start time defaults to 00:00.000 and represents the timestamp in the target audio file at which QLab will start playing the file. You can change the start time of the cue in three ways:

1. You can type a new value into the text field.
2. You can drag the start time marker, which is the downwards-pointing grey triangular handle at the top left side of the waveform view.
3. You can click anywhere in the waveform view, or preview the cue and then pause it, then use the keyboard shortcut ⇧I (“I for in”) to set the start time to the current playback time.

End time defaults to the end of the target audio file, and so displays the timestamp of the final sample of audio in the target file. You can change the end time of the cue in three ways:

1. You can type a new value into the text field.
2. You can drag the end time marker, which is the downwards-pointing grey triangular handle at the top right side of the waveform view.
3. You can click anywhere in the waveform view, or preview the cue and then pause it, then use the keyboard shortcut ⇧O (“O for out”) to set the end time to the current playback time.

If you click and drag within the waveform view to select a section of the file, you can use both ⇧I and ⇧O one right after the other to quickly crop the cue to the selected region.

Play count and infinite loops

Play count defaults to 1 and is the number of times that the target audio file will be played when the cue is run. You can enter any whole number in the text field to loop the target audio file that number of times, or select Infinite loop below to loop the target audio file indefinitely.

Waveform contextual menu

Right-clicking (or two-finger-clicking, or clicking while holding down the option [⌥] key) within the waveform view brings up a contextual menu which lets you open the target audio file in an external audio editor or select which channel of audio you wish to view. By default, QLab displays a sum of all channels. The channel names in this menu reflect names set in the Levels tab.

Slices

The play count and infinite loop options allow you to loop the entire target audio file, but QLab allows you to loop specific sections of the file as well. To this, you create slices within the cue, and set each slice to loop as needed.

To create a slice, click in the waveform view and then click the Add Slice button to the left of the waveform, or use the keyboard shortcut M. A green marker, called a slice marker, will appear in the waveform at the spot where you clicked. A section of the cue between two slice markers, or between a marker and the start or end of the cue, is a slice.

The green numbers which appear along the bottom of the waveform view are play counts for each slice. The play count will default to 1, but you can easily edit the count of an individual slice by double-clicking the number at the bottom of the slice and entering a value. To loop a slice infinitely, type any letter. To seamlessly skip a slice, type 0. The slice will receive a darkened tint, and QLab will skip over that slice while playing the cue. At least one slice of a cue must have a play count greater than zero.

You can click the green handle at the top of a slice marker and slide it left and right along the waveform to adjust its position, or click on the handle and then enter a value manually in the text field that appears on the left side of the waveform view. Slice markers cannot be closer together than .05 seconds.

If you click and drag within the waveform to select a section of the file, the Add Slice button (and the M shortcut) will create slice markers on both sides of the selected section.

If the target audio file is an AIFF or WAV file which contains markers, those markers will automatically appear in QLab as slice markers. Markers closer together than .05 seconds will be discarded by QLab, though the markers in your file will remain untouched.

To delete a selected slice, select it and hit ⌫ (delete) on the keyboard, or drag its slice handle upwards out of the waveform view.

ProTools users will find that markers from ProTools projects are not included in bounced files, which makes QLab’s automatic marker importing somewhat less useful. Fortunately, there is a workaround as long as you have a two-track editor that allows importing markers (such as TwistedWave):

1. Bounce or export your audio as usual.
2. In ProTools, choose Export… from the File menu and export your session info as text.
3. Open your audio file in your two-track editor and import the text file you created from ProTools. Et voila!

The Delete All button deletes all slices from the cue. Markers in the target audio file are not deleted.

Vamping and devamping

Looping and slicing cues starts to get really interesting when used in combination with the Devamp cue, which allows you to dynamically exit loops while cues are playing. You can learn more about this from the section on Devamp cues in this manual.

Rate and pitch

You can adjust the playback rate of the Audio cue by typing a value in the Rate text field to the right of the waveform, or by clicking in that field and dragging up or down. By default, adjusting the rate will adjust pitch as well in a manner similar to changing the playback speed of analogue tape. If you check the Preserve pitch box, however, the pitch will not be changed along with the rate.

Rate 1 = 100% (normal speed) - no pitch shift Rate .5 = 50% (half speed) - pitched down one octave Rate 2 = 200% (double speed) - pitched up one octave The minimum rate is 0.03, and the maximum rate is 33.

It is worth noting that checking the Preserve pitch box requires slightly more processor power than leaving the box unchecked.

The Integrated fade envelope

The integrated fade envelope allows you to adjust the overall volume of the cue graphically over its duration. This can be useful for evening out dramatic volume differences, or modulating volume for creative effect.

To use the integrated fade envelope, check the box underneath the waveform view labeled Integrated fade. A yellow line will appear along the top of the waveform view, and you can click and drag along the line to create control points.

The pop-up menu next to the Integrated fade checkbox allows you choose between Custom Curve, which makes the integrated fade envelope curve smoothly between and around control points, or Linear Curve, which creates sharp angles precisely at each control point.

The pop-up menu also gives you the option to Lock fade to start/end, which automatically stretches the integrated fade curve to fit within the start and end time of the cue. With this option not set, the integrated fade curve will remain locked to the natural start and end time of the target audio file, regardless of the start and end times set in the cue.

Note that if you edit the envelope while the cue is playing, you won’t hear your changes until you stop and restart the cue.

You can edit and navigate between control points using the arrow keys:

Command	Key
Select previous control point	←
Select next control point	→
Move selected control point up	⌥↑
Move selected control point down	⌥↓
Move selected control point left	⌥←
Move selected control point right	⌥→
Move selected control point up a small amount	⇧⌥↑
Move selected control point down a small amount	⇧⌥↓
Move selected control point left a small amount	⇧⌥←
Move selected control point right a small amount	⇧⌥→

Preview, Reset, and Zoom

You can use the and buttons to zoom in and out on the waveform. If you’re using a trackpad, you can zoom in and out by placing the cursor over the waveform view and pinching in and out, or by holding down the ⌥ (option) key and scrolling vertically. If you’re using a mouse or trackball with a scroll wheel, you can zoom in and out by placing your mouse cursor over the waveform view and scrolling.

The button resets the cue, stopping it and resetting all temporary properties such as conditional cue colors.

The button starts playing the cue without advancing the playhead or triggering any auto-follow or auto-continue. The default keyboard shortcut for previewing a cue is V. While the cue is playing, this button changes to a pause button.

The Levels Tab

The Levels Tab lets you adjust volume levels for the cue.

Controls

Set Default Levels. This button sets all levels of the cue to match the levels in the Audio cue template, which can be found and adjusted to suit your needs in Workspace Settings → Templates → Cue Templates.

Set all silent. This button does exactly what it seems: it sets all levels for the current Audio cue to -inf.

Inputs. Clicking this button allows you to assign names to each input (row) in the cue.

Input names are unique for each cue, so they can reflect the specific details of that cue.

Gangs. When you click this button, all audio levels will be hidden and the mixer will switch to gang assignment mode. In this mode, you can type anything (for example, a single letter) into any level field. All fields which receive the same text will become part of the same gang, or level group.

When you click Assign Gangs again, the mixer will switch back to its regular view, and ganged fields will be shown with matching colored backgrounds so you can tell at a glance which fields are ganged. Then, you can simply click and drag one control to adjust every level in that gang by the same amount.

If you gang levels together while they’re at different starting points and start moving them up or down, one level might reach its maximum or minimum level before another. Then and only then will the levels be adjusted disproportionately with one movement. Once the levels catch up to each other at their maximum or minimum, they will all move together.

The Edit Audio Patch button opens the Audio Output Patch Editor for the audio output patch in use by the cue.

The Cue Matrix Mixer

The cue matrix mixer is a grid made of rows and columns, like a spreadsheet. The main output level for the cue is in the top left, the cue outputs are the column headers, and channels in the audio file are the rows. The number of rows in the mixer is dictated by the number of channels in the target audio file.

Cue outputs which are assigned to device outputs have a yellow fader handle. Cue outputs which are not assigned to device outputs, and which therefore cannot be heard, have a grey fader handle.

Crosspoints are the level controls for routing a given input (row) to a given output (column).

Levels can be typed into each control, or you can click in a field and drag up or down. QLab won’t allow you to drag above 0 dB as a safety measure, but you can type a level above 0 manually, limited by the maximum level set in Workspace Settings → Audio. Since the majority of levels set are below 0 db, QLab will interpret a number entered without a + or - sign as a negative number.

A level control showing no value can be assumed to be set at -inf (silent).

Adjustments made in the Levels tab take effect live and in realtime, so you can start the cue and then adjust levels by ear. Please be careful at the beginning of a project, since a very small movement of the mouse can cause a very large adjustment in level.

The Trim Tab

The Trim tab provides a set of “post-fader” overall level adjustment controls for the main output and the cue outputs of a cue.

These controls are not adjustable using Fade cues, MIDI, OSC, or any other automation; their purpose is specifically to exist outside the realm of automation and other sources of control so that they are guaranteed to stay the way you set them.

If you make a cue sequence with a bunch of fades and lots of intricate level movement, and then afterwards you decide that one output is too loud throughout the whole sequence, you can adjust the trim in the audio cue instead of adjusting that output in each and every fade cue; just one adjustment and you’re done.

If you build a cue sequence with a set of audio files and then need to replace those audio files with new versions, but accidentally normalize the new versions differently so the new versions are all 3 dB hotter than the old versions, you can correct for that using the Trim tab.

The Audio FX Tab

With an Audio license installed, QLab can use AudioUnit effects installed on your Mac to process sound dynamically in realtime. For an AudioUnit to work in QLab, it must be compatible with the version of macOS that you’re using, must be defined as an effect (i.e. MIDI synthesizers won’t be available in QLab because they are generators, not effects), and must report a “tail time” (for example, a reverb’s decay time.)

Additionally, the number of channels in the target audio file must match the number of channels supported by the AudioUnit. Different AudioUnits behave differently if there is a mismatch in channel count. Some will pass the audio straight through as though no effect is in use, some won’t pass any audio at all, and some may have other unpredictable consequences. A good example of this behavior is exhibited by Apple’s AUMatrixReverb, which requires a two-channel (stereo) source. If you use AUMatrixReverb on a mono audio track, the audio will pass through the AudioUnit unchanged.

To use an audio effect, select it from the pop-up menu labeled Add Audio Effect… When you select an effect, it will appear in the list to the right of the menu, and an AudioUnit editor window will open automatically. You may close the window and access it again easily anytime by clicking the Edit button next to the name of the effect in the list. The editor window looks different for each AudioUnit because each effect requires different controls. QLab uses the built-in interface created by the designer of the AudioUnit, which means the look and feel (as well as quality and usability) of AudioUnits can vary widely.

You can bypass an audio effect by unchecking the box to the left side of the effect, and you can remove an audio effect from the cue by clicking the button to the right side. If the AudioUnit editor window is open, you can also turn the effect on or off by using the checkbox labeled Enabled in the top right corner of the effect window.

Audio effects will be applied to the cue in the order in which they appear in the effects list. To change this order, simply click on an effect and drag it up or down within the list.

You can also insert AudioUnits on cue outputs and device outputs. You can find out more about using AudioUnits on outputs in the Audio Output Patch Editor section of this manual.

Broken Audio Cues

Audio cues can become broken for the following reasons:

No audio file selected

The cue has no target, and Audio cues require an audio file as a target. Select an audio file as the target of this cue to clear this warning.

Missing audio file

The cue had a target file assigned, but that file is missing. Perhaps the file was on a removable drive or network drive which is not currently connected. Re-locate the target file, or assign a new target file to clear this warning.

File target in Trash

The cue’s target file is in the Trash, and files in the Trash cannot be used. Either move the target file out of the Trash, or assign a new target file to clear this warning.

File target lacks read permissions

This is a bit of a bizarre error that is technically possible, but very unusual. If the target file lacks read permissions, it cannot be used. Since it cannot be used, though, it probably could not have been selected as a target in the first place. Despite this seeming paradox, it still is technically possible that this could happen, and so QLab tries to handle it. Fix the target file’s permissions, or assign a new target file to clear this warning.

No audio output patch

The cue has no audio output patch assigned. Assign an audio output patch to clear this warning.

Issue with audio output patch

The cue has an audio output patch assigned, but something is wrong with it. The audio output patch will have warnings of its own, listed in the Warnings tab of the Workspace Status window, which you can use to figure out what’s wrong with it. Either fix the audio output patch or select a new audio output patch to clear this warning.

Missing cue audio effect

The cue has an audio effect assigned, but that AudioUnit is not installed. Either remove the audio effect from the cue or install the missing AudioUnit to clear this warning.

Invalid slice play counts

The cue is sliced, and all slices have a play count of 0. This means that no part of the target file will be played, which means the cue effectively does nothing. Either set at least one slice to a play count greater than zero, or delete this cue that does nothing anyway to clear this warning.

License required

An audio license is required to use more than the first two cue outputs, audio effects, or Timecode triggers. Install an audio license or adjust the cue to avoid using licensed features to clear this warning.