Prepare, Execute, Troubleshoot

A Computer Prepares

Before even opening QLab, there are a few things to consider at the system level to keep your show running smoothly. Mac OS X is wonderfully powerful and flexible, but its general-purpose nature means there are some processes that can get in the way of show playback, and should be disabled.

This section presupposes a basic understanding of the Mac OS and at least a passing familiarity with the Terminal.

  1. Disable Spotlight. Spotlight periodically updates its index of all files on all attached disks, and this updating can cause the disk to be momentarily unavailable to QLab. This can cause late cues or stuttering in playback. To prevent Spotlight from updating its index, open a Terminal window and enter this command:
    sudo mdutil -a -i off
  2. Disable Display Sleep, Disk Spindown, and System Sleep. Obviously we don't want our computer going to sleep during a show. The Mac OS has independent sleep intervals for the display, the hard disk, and the whole system. To prevent all three kinds of sleeping, open a Terminal window and enter this command:
    sudo pmset -a displaysleep 0 disksleep 0 sleep 0
  3. Disable Screen Saver. Likewise, we don't want the screensaver coming up, particularly if QLab is running video. To prevent that from happening, open a Terminal window and enter this command:
    defaults -currentHost write idleTime 0
  4. Disable Time Machine. Backups are wonderful. You should back up everything, all the time. But on a computer used for your show, backups should only be done manually. Time Machine, much like Spotlight, uses indexing and background processes which can take hold of the disk at inopportune moments. To shut off Time Machine, open a Terminal window and enter this command:
    sudo tmutil disable
  5. Disable Software Update. You don’t want your computer trying to update software in the middle of a run, let alone in the middle of a performance. To disable Software Update, open a Terminal window and enter this command:
    sudo softwareupdate --schedule off
  6. Disable Dashboard. Dashboard, largely neglected by Apple these days, is a pernicious little vampire of CPU time and network access. Also, if accidentally invoked, it takes over the screen of your Mac entirely, which can be surprising and confusing and lead to missed cues. To disable Dashboard entirely, open a Terminal window and enter this command:
    defaults write mcx-disabled -boolean YES
  7. Stay Off The Internet. Many individual applications, including QLab, have their own internal scheme to check for updates. You can turn them off manually, and we recommend that. But the best way to guarantee that automatic software updates or any other network traffic won’t bother your show is to disconnect the show computer from the Internet. We strongly encourage this. If you use a network to connect your QLab computer to other hardware, and your show doesn't require Internet access, make sure that network is a closed LAN (local area network) and has no path to the Internet.
  8. Disable Hot Corners. Perhaps a lesser danger to a smooth running show, hot corners are nevertheless potentially problematic and we like to disable them, particularly when using screen sharing or VNC. To disable all four hot corners, open a Terminal window and enter these four commands, one at a time:
    defaults write wvous-tl-corner -int 1
    defaults write wvous-bl-corner -int 1
    defaults write wvous-tr-corner -int 1
    defaults write wvous-br-corner -int 1
  9. Disable Notification Center. Depending on the way that you're using QLab, the iOS-style notifications system in Mac OS 10.8 and newer can be anything between a minor nuisance to a seriously embarrasing accidental component of your projection design. To prevent those charming little pop-up bubbles in the top right corner of your screen, open a Terminal window and enter this command:
    launchctl unload -w /System/Library/LaunchAgents/
  10. Disable Mission Control. Mission Control is the feature that shows you all the open windows of all the open applications on your Mac, and makes it easy to move between them. On most laptops, the keyboard shortcut for this is F3, which is marked with three little rectangles. Needless to say, accidentally invoking Mission Control, particularly in a show with projections, can be a problem. To keep your own control of your theatrical mission, open a Terminal window and enter this command:
    defaults write mcx-expose-disabled -bool TRUE
  11. Restart the Dock. Oddly, the Dock is in control of several of the system components that we just adjusted. Restarting the Dock allows these changes to take effect. Open a Terminal window and enter this command:
    killall Dock

If you're using QLab for video, there are two more critical settings:

  1. Disable "Mirror Displays." When you have more than one display connected to a Mac (including the built-in display on a laptop or iMac), you can either have the displays mirroring each other, showing the same thing, or turn off mirroring, which lets each displauy show its own image. That's how you want it set for QLab, so that you can see QLab on your display, and the audince sees your cues on the other display or displays. Amazingly, there is no Terminal command for this! To turn off display mirroring:
    Open System Preferences; choose Displays; choose "Arrangement"; uncheck "Mirror Displays."
  2. Disable "Displays have separate Spaces." Spaces is Apple's name for virtual Desktops (if you don't know what this means, don't worry about it.) If your displays are set to have separate spaces, the Menu bar also appears on all Displays, and that is visible to your audience when no cues are playing through QLab. To set your displays to share Spaces, and thus keep the menu bar out of your picture, open a Terminal window and enter this command:
    defaults write spans-displays -bool TRUE
    Important: you'll need to log out, then back in again for this to take effect.

Marshal Your Content

Among QLab’s virtues is its relative agnosticism towards file formats and locations. You can use AIFF, WAV, MOV, and M4A files scattered all over your disk (or over multiple disks) and QLab doesn’t really care. However, that’s not to say there aren’t some advantages to taking a more organized approach.

For Audio:

  1. Compressed audio file formats like MP3 or AAC save disk space, but take more CPU power to play back because the computer has to decode them on the fly. Using AIFF or WAV will reduce the load on your CPU, although at the expense of increasing the amount of data that must be read from the disk. We generally recommend trying AIFF or WAV first. They're usually best.
  2. QLab automatically resamples all audio to match the sample rate of the selected audio hardware, which likewise increases processor load during playback. If you need every last drop of performance, it can't hurt to pre-process your files to convert your audio to the same sample rate that you’ve selected for your interface.
  3. Consolidating your files into a single folder, or a collection of subfolders within one master folder, has no bearing on performance but can be a real timesaver in tech rehearsal when you’re searching for files in use.
  4. If you find yourself playing a number of mono or stereo sound files together to simulate a single multitrack file, consider combining those files together to create an actual multitrack file; QLab 3 supports files with up to 24 tracks (with a Pro Audio or Pro Bundle license). Playing back one multitrack file is more efficient than playing back the same number of tracks in separate files. Your DAW software may be able produce a multitrack file, or you can use a tool such as SoundFilesMerger to combine your mono and/or stereo source files.

For Video:

  1. QLab 3 can use any of the following video codecs:
    ProRes 422
    ProRes 422 HQ
    ProRes 422 LT
    ProRes 422 Proxy
    ProRes 4444
    In practice, we’ve found that the best formats are ProRes 422 Proxy, ProRes 422 LT, PhotoJPG, and H.264 for videos without transparency, and ProRes 4444 for videos with transparency. Meanwhile, we do not recommend using MPEG-1, MPEG-2, H.263, or any of the DV codecs even though they are technically compatible.
  2. ProRes 422 Proxy and ProRes 422 LT produce very large files but is less taxing on the CPU and GPU of your computer. H.264 and PhotoJPG produce smaller files, but are more taxing on the CPU and GPU. We recommend that you experiment with different formats to determine the sweet spot for your particular hardware configuration and playback needs.
  3. Like with Audio, consolidating your files into a single folder, or a collection of subfolders within one master folder, has no bearing on performance but can save time in tech rehearsal when you’re searching around for files in use.

Programming Clearly

Programming cues in QLab can be approached in a number of ways, none of which is “right” or “wrong.” However, no matter your approach, a useful guideline is to imagine yourself being suddenly unable to make it to the final tech rehearsal and instead calling in a substitute who is QLab literate, but who has never worked with you or seen your workspace before.

Consider, for example, the use of auto-continues and auto-follows versus Group cues in the following two examples:

auto-continued cues

grouped cues

Both sequences of cues sound exactly the same, but the first example uses post-wait times and auto-continues while the second example uses a Group cue set to Start all children simultaneously and pre-wait times. Reasonable people may differ about which is clearest, but it can be valuable to consider that while the functionality is exactly the same, the two versions read very differently.

Loads, Auto Loads, and Statistics

QLab 3 handles loading cues differently from QLab 1 and 2, and understanding that difference can give you more fine-grained control of how your show operates. Before we dive in, however, let’s understand what loading really is. This section is a little wordier than the earlier stuff, but hang in there.

In QLab, a sound or video cue that is loaded has a portion of the audio or video content that it targets placed into RAM. Other cue types likewise have information about them prepped or initialized. You can tell that a cue is loaded because a yellow disc appears in the status column on the left side of the cue list. A cue sequence that is triggered without being loaded will exhibit a variable amount of latency, depending on the complexity of the sequence and the other things going on with the computer at that moment. In most cases, the difference between playing a cue that is loaded versus one that is unloaded will only be noticeable for sound and video cues.

In QLab 1 and 2, whenever a cue was triggered by either the mouse or the space bar, the next cue sequence would automatically be loaded. Thinking about how a show normally runs, that makes a lot of sense. The one thing QLab can safely assume is that the next thing that will happen after a cue plays is the next cue will play at some point. The problem with this logic became evident as people started designing more complex shows: sometimes the work required to load a cue sequence was substantial enough that it would cause the computer to choke on the currently playing cue. Usually this came in the form of overtaxing the hard drive, which was happily serving up the data for the currently running cue and then suddenly had to also serve up the data required to preload the next cue. For those folks out there in search of a hobby, you could easily see the difference in performance of 5400 RPM drives, 7200 RPM drives, and SSDs by running the same QLab 2 workspace on each and noting the degree of choppiness of playback while loading.

Now, QLab 3’s playback engine is dramatically more efficient than that of QLab 1 or 2, so there are many instances in which loading is not necessary; data just makes it off the disk and out the door faster that it used to, even on identical hardware. Therefore, by default QLab 3 does not automatically load cues the way QLab 1 and 2 did, so as not to create a playback choking situation. If your show is relatively simple, which is to say that you’re not playing more than a few sound or video cues at the same time, or if you’re using an SSD, you might discover that you never need to think about loading. However, if you find that some cues or cue sequences are showing latency, you’ll probably want to load those cues. But how? There are several ways.

You can use a Load cue to load another cue at a strategically selected moment. For example, you could add a called cue during a quiet moment in the show, or you could add a Load cue to an earlier sequence with a load pre-wait so that the Load fired after the previous cue completed.

In QLab 3, you can individually set cues to auto-load with the correspondingly named checkbox in the Basics tab of the inspector. If you have a complex sequence following a simple one, this will probably work quite well.

If you find that loading isn’t causing hiccups with playback, you can have QLab enable auto-load by default in general settings (under the gear icon in the lower right corner of the workspace.)

When Houston Has The Problem

Troubleshooting a QLab problem actually doesn’t differ all that much from troubleshooting a physical problem with your system. The essential steps are these:

  1. Can the problem be clearly defined? That is to say, can you easily explain what the problem is, or is the problem vague and difficult to quantify? Very specific problems, such as “all my cues are about 10 db quieter than expected,” are the easiest to troubleshoot. Less specific problems like “it… sounds weird,” are much more difficult.
  2. Can the problem be reliably replicated? Once you’ve defined the problem, can you list a specific set of actions that you can take in order to make the problem appear again?
  3. Follow the path. Just as you troubleshoot a mysteriously silent speaker by starting at the speaker and moving backwards along the signal path, so too can you follow a pathway within QLab to find a problem. For example, if your problem has to do with levels, there are several places that the level of a cue can be changed: in the cue list, there’s the Devices & Levels tab in the inspector, the Trim tab in the inspector, and any number of Fade cues that target the cue in question. In the audio settings for the workspace, there are the three tabs in the Edit Device window: Cue Outputs, which can have Audio Units which affect level; Device Routing, which is nothing but level controls; and Device Outputs, which can also have Audio Units. Then there’s likely some sort of software control panel for your audio interface. Tracing the path through these steps can often be all that’s required to solve a level problem.
  4. Even though it’s software, it really might be a cable. Strange things can happen with flaky USB or FireWire cables. Swap those out. If your problem is with video, try swapping VGA or DVI cables too.
  5. Ask the group. Our user group (found here:!forum/qlab) is full of brainy people who are out there doing really cool things with QLab, and chances are good that someone has seen the problem you’re seeing.
  6. Email! We’re here to help. The questions we’re likely to ask you right off the bat are:
    • What version of QLab are you running?
    • What version of Mac OS are you running?
    • What kind of Mac are you using, and what are the details pertaining to the CPU, GPU, RAM, and hard disk?

What Have I Done?

With a little preparation, and a little careful structured thinking, you can easily preempt the most common sources of show-stopping system problems. There is no way to predict every problem, of course, which is why we take support so seriously. It is our hope that this post can serve as a starting point, rather than a definitive mandate, for healthy QLab Kung-Fu.

Updates to this article:

  • April 2, 2015: removed a section on XProtect which is only relevant to Mac OS 10.8. Added a section on disabling Dashboard. Added a section on video-specific Displays settings.
  • September 29, 2014: added a section on disabling Mission Control.
  • November 5, 2013: added a section on disabling Notification Center.

Sam Kusnetz is a Sound and Projections Designer and a Field Operative for Figure 53