QLab 5VideoVideo Cues

Video Cues

Video cues allow you to play video and still images files with precise control over timing, opacity, scale, position on screen, and 3D rotation, and with a full suite of effects and blending tools. Video cues must have a file target, which is a video or image file on your computer, and must be assigned to a stage, which connects QLab to a video output destination such as a projector, screen, LED wall, or a virtual output device such as Syphon or NDI.

Video Files

Unlike audio files, video files have two attributes that determine whether they are compatible with QLab. The first attribute is the codec used by the file. Codec is short for either “compressor/decompressor” or “code/decode” and it describes the way that video data is encoded in the file. The second attribute is the container format used by the file. The container is like an envelope which contains the video, its audio tracks, and metadata about the media.

The following codecs are compatible with QLab 5 for moving images:

  • MPEG-1
  • MPEG-2
  • MPEG-4
  • H.263
  • H.264
  • H.265, also called HEVC
  • ProRes 422 Proxy
  • ProRes 422 LT
  • ProRes 422
  • ProRes 422 HQ
  • ProRes 4444
  • ProRes 4444 XQ
  • Photo-JPEG
  • DV/DVCPRO NTSC
  • DVCPRO50 NTSC
  • DV PAL
  • DVCPRO PAL
  • DVCPRO50 PAL
  • Hap Standard
  • Hap Alpha
  • Hap Q

While all those codecs technically work with the underlying video frameworks that power QLab 5, the following codecs give the best performance in QLab for moving images without transparency (listed in preferential order):

  1. ProRes 422 Proxy
  2. Hap Standard
  3. ProRes 422 LT
  4. Hap Q
  5. Photo-JPEG

For moving images with transparency, you must use one of the following codecs (listed in preferential order):

  1. ProRes 4444
  2. Hap Alpha

The following codecs provide higher picture quality at the cost of greater processing power:

  1. ProRes 422
  2. ProRes 422 HQ
  3. ProRes 4444 XQ

Of those three, only ProRes 4444 XQ can provide transparency.

The following codecs generally work well, but perform especially poorly when sped up, slowed down, or when scrubbing forward or back:

  1. H.265
  2. H.264

All other compatible formats are not recommended, even though they may work, or appear to work, with QLab 5.

The following containers are recommended for use with QLab 5 for moving images:

  • mov
  • mp4

Other container formats may work, but are not recommended because they are more likely to contain incompatible codecs or other data.

Still image formats

Most still image formats work with QLab 5, but we recommend PNG and JPG files. QLab 5 does not support PSD or PDF formats.

The Inspector for Video Cues

When a Video 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 video file and video output, and view details about them as well.

The I/O tab

File Target. If a target video 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.

Video Format displays the type of codec, pixel dimensions, and frame rate of the video in the target file.

Clock. This pop-up menu allows you to select the clock that will be used to set the timing for the playback of this cue.

  • Follow video clock prioritizes the timing and smoothness of video playback by using the display clock to control playback timing.1 This generally results in the best-looking playback, but can possibly reduce the accuracy with which this cue synchronizes with any other cues which don’t use the same display clock. Notably, if this cue has an audio track and uses the video clock for timing, it is not guaranteed that it will remain in sync with other cues using the same audio output patch.
  • Follow audio clock prioritizes the timing and smoothness of audio playback by using the clock of the audio device used by the audio output patch that the cue is using. This causes the cue to stay in perfect synchronization with other cues that use the same audio output patch, but can result in occasional visible timing imperfections which usually look like a single skipped or repeated frame.

Audio Format displays the codec, number of channels, and sample rate of the audio encoded within the first track of the video file.2

Video Output. This pop-up menu allows you to assign the cue to a stage, which is QLab’s video output mechanism. Every Video cue must be assigned to exactly one stage, and the way that the stage is configured defines how the imagery will ultimately be displayed. You can learn more about stages from the Video Output section of this manual. Clicking on the menu allows you to select one of the stages 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 Video Settings to edit stage list… to quickly get to Workspace Settings → Video → Video Outputs, or choose New stage with video route to quickly generate a new stage and select it for use.

The Monitor button opens the monitor window for the selected stage.

To the right of that button, QLab displays the pixel dimensions of the selected stage. QLab always displays the actual pixel dimensions, not the effective point size, so for Retina displays, these numbers may be considerably higher than the resolution reported in System Preferences.

To the right of that, the Edit… button opens the video stage editor for the currently selected stage.

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.

To the right of that menu, QLab displays the sample rate of the audio device associated with the audio output patch.

To the right of that, the Edit… button opens the audio output patch editor for the currently selected audio output patch.

The Geometry Tab

The Geometry tab lets you adjust the basic visible parameters of the cue. There are two forms the Geometry tab can take, depending upon the mode of the cue.

Fill Stage

The Geometry tab - Fill Stage

If the Mode pop-up menu is set to Fill Stage, the Geometry tab looks like this. Cues set to Fill Stage mode will be scaled as large as possible to fill the entire stage. If the Preserve Aspect Ratio box is checked, the cue will be scaled symmetrically in both directions and therefore may leave blank space to the sides or above and below. QLab does not fill this space with black pixels; if there is a cue on a lower layer that truly fills the stage, it will be seen in these empty spaces.

If the Preserve Aspect Ratio box is not checked, the cue will be scaled to match the full pixel dimensions of the stage and may be stretched in one direction or the other in order to fit.

Opacity sets the opacity of the cue on a scale of 0%, meaning fully transparent, to 100%, meaning fully opaque. Transparency in the target media is not altered by this control; if a cue’s target has transparent pixels, they remain transparent when the cue is set to 100% opacity. The button resets the cue’s opacity to its default value.

The Smooth checkbox determines whether the cue will be drawn using smooth anti-aliased scaling or nearest-neighbor scaling. Leaving the box checked will smooth out the jagged edges that can appear when images are scaled up. Unchecking the box will keep the sharp edges, which can sometimes be preferable depending upon your aesthetic goals.

Layer sets the stacking order of the cue relative to other cues assigned to the same stage.

QLab has 1001 layers: top is the layer closest to the viewer. Layer 999 is directly beneath, then layers continue downwards to 1, then bottom. Any cues assigned to the top layer will play on top of all other currently running cues. Any cues assigned to the bottom layer will play beneath all other currently running cues. Cues assigned to the same layer as each other will stack in the order in which they are started. So, for example, if you have three cues assigned to layer 10, whichever cue is started last will appear on top of the other two, but any cue assigned to layer 11 (or higher) will appear on top of all three cues on layer 10, regardless of the order in which those cues are started. Similarly, any cue on layer 9 (or lower) will appear beneath all three of the cues on layer 10.

Custom

The Geometry tab - Custom

If the Mode pop-up menu is set to Custom, the Geometry tab looks like this. Cues display at their natural pixel dimensions, and several more controls appear to allow you to customize the appearance of the cue. To the right, a thumbnail of the cue appears within a blue box. The blue box represents the stage that the cue is assigned to.

Crop. The four text fields of the crop parameter allow you to trim or shutter in from the four sides of the cue. Each text field represents one edge (top, bottom, left, right), and the number is the number of pixels to crop off counting from the edge towards the center of the cue. The button resets the cue’s crop to its default value.

Translation is the position of the cue on the stage, measured in pixels relative to the center of the surface. A translation of (0, 0) is centered, negative values are down and to the left, and positive values are up and to the right. You can also adjust the translation by clicking and dragging the thumbnail of the cue. The button resets the cue’s translation to its default value.

Scale is the size of the cue relative to its natural pixel dimensions, expressed as a multiplier. 1.0 represents the natural size, 0.5 is half the natural size, 2.0 is double, and so on. If the lock icon between the scale fields is closed, the aspect ratio of the video will be preserved while scaling. You can click the lock to unlock it and adjust the height and width independently. You can also adjust scale by vertically scrolling on the thumbnail of the cue using your mouse, trackpad, or other pointing device. The button resets the cue’s scale to its default value.

Rotation is the attitude of the cue in a virtual 3D space. You can click and drag on the (X), (Y), and (Z) buttons to manipulate the cue’s rotation around the desired axis, or click on each and type values into the text field that appears. The button resets the cue’s rotation to its default value.

A Word About Quaternions: QLab uses quaternion math to handle rotation of Video cues in 3D space. The advantage to quaternions is that when fading a cue from one position to another, QLab will always produce smooth, natural motion. The tradeoff is that there is no useful way to numerically display the current rotational position of a cue. Therefore, when you adjust the rotation of a cue, you’ll see numbers in the pop-up which represent the degrees of single-axis rotation since you started this particular adjustment, not any sort of absolute measure.

Anchor is the point around which a Video cue rotates, translates, and scales. The default anchor point is (0, 0), which is the center of the cue. Adjusting the anchor will change the way the cue moves when you adjust other geometry parameters. You can also adjust the anchor by clicking and dragging the light blue cross in the thumbnail of the cue. The button resets the cue’s anchor to its default value.

The Time & Loops Tab

The Time & Loops tab behaves the same as the Time & Loops tab for Audio cues.

The Levels Tab

The Levels tab only appears if the file target of the cue contains an audio track. If so, this tab behaves the same as the Levels tab for Audio cues.

The Trim Tab

The Trim tab only appears if the file target of the cue contains an audio track. If so, this tab behaves the same as the Trim tab for Audio cues.

The Audio FX Tab

The Audio FX tab only appears if the file target of the cue contains an audio track. If so, this tab behaves the same as the Audio FX tab for Audio cues.

The Video FX Tab

The Video FX tab lets you set the blend mode of the cue and add live video effects to the cue.

Blend Modes

The blend mode of a Video cue, selected using the Blend Mode pop-up menu, dictates the way that the cue interacts and combines with other Video cues that occupy the same space on the stage. Blend modes are best understood as a per-pixel mathematical operation which combines the values of each channel of a given pixel in the “foreground”, which is a cue on a higher layer, with the values from the pixel in the same position in the “background”, or a cue on a lower layer. In this context, channel values are represented on a scale from 0.0 to 1.0 in which 0.0 is off, and 1.0 is full brightness. A pure red pixel would be represented as (1.0, 0.0, 0,0). A pure white pixel would be (1.0, 1.0, 1.0).

The Blend Mode page of this manual contains descriptions and reference videos demonstrating the effects of the various blend modes available in QLab 5. The Blend Mode Demo tutorial is a downloadable, hands-on copy of the workspace which was used to create those reference videos.

Video Effects

The Add video effect… pop-up menu allows you to add a video effect to the cue. QLab 5 supports multiple video effects on a single cue, and effects are rendered in the order in which they appear in the list. Video effects are “live”, meaning that they are rendered on the spot, in realtime.

Please note that video effects can be extremely processor-intensive and can cause visible performance problems, sometimes even on powerful Macs. Please take time to experiment with video effects and learn their idiosyncrasies before using them in a production environment. That said, the underpinnings of the QLab 5 video system affords very good video effects performance, particularly on Apple Silicon-based Macs.

A Video effect

When a video effect is selected, it is highlighted with a light grey border and its controls become visible on the right side of the inspector. Each video effect has its own parameters which can be adjusted either by typing into their text fields or clicking and dragging their sliders. Some video effect parameters use color swatch selectors which require a click to start editing.

Clicking Set Default Parameters will reset the currently visible video effect to its default state. Other video effects will not be altered.

To remove a video effect from a cue, click the button next to its name.

A full list of available video effects and their parameters can be found in the Parameter Reference section of this manual.

Broken Video Cues

Video cues can become broken for the following reasons:

No video file selected

The cue has no target, and Video cues require a video or image file as a target. Select an appropriate file as the target of this cue to clear this warning.

Missing video 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 video output stage

The cue has no video output stage assigned. Assign the cue to a stage to clear this warning.

Incomplete video output

The cue is assigned to a stage, but the stage is incompletely configured. Visit the Video Stage Editor to complete the configuration of the stage and clear this warning.

No audio output patch

The file target has audio, but no audio output patch is assigned to the cue. 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

A video license is required to use custom geometry, blend modes, video effects, audio effects, or Timecode triggers. Install a video license or adjust the cue to avoid using licensed features to clear this warning.


  1. When a Video cue is assigned to a stage that goes to only one output, QLab will use the clock associated with that output. When a Video cue is assigned to a stage that goes to more than one output, QLab follows a slightly complex heuristic: if one output has a higher refresh rate than all the others, QLab will use that output’s clock. If two or more outputs are tied for highest refresh rate, QLab will prioritize clocks belonging to physical outputs (screens and projectors) over virtual outputs (NDI and Syphon.) If two or more outputs are still tied for best candidate, QLab picks one effectively at random.

  2. Video files can contain multiple audio tracks, each of which can contain up to sixteen channels. QLab can only access channels in a video file’s first track.

Still have a question?

Our support team is always happy to help.

Business Hours
M-F 9am-7pm (ET)
Current time at our headquarters