QLab

What it's for — CueSync drives QLab 5 over OSC. A Theatre cue, a Cue Pad, a Look or the panic can GO a QLab cue by number, start it, stop it, move the playhead, or change a cue's level, rate, opacity, pre-wait and duration. It can also build your QLab cue list from a Part (section 7); it never deletes or changes a cue that is already there. QLab keeps the audio and video; CueSync says when.

What has been checked. CueSync has been tested against QLab 5 on both transports. Some verbs are built from QLab's documented OSC addresses and have not been confirmed one by one; see What has been checked. QLab 4 has not been checked.

1 · Set up QLab

Do this once on the QLab machine, with the workspace open. Most mistakes here look like success in CueSync: the cue reports sent and QLab does nothing.

1. Open the workspace and leave QLab running. CueSync's own hint says a workspace must be open and QLab in the foreground.
2. Open Workspace Settings > Network > OSC Access. QLab 5 ships this panel with two rows: a No Passcode row that grants nothing, and a QLab-generated four-digit passcode row that grants View, Edit and Control. Pick one way in: either tick View, Edit and Control on the No Passcode row, or keep the passcode and type it into the CueSync output (OSC passcode, section 2).
3. Leave the OSC port at 53000. CueSync uses 53000 for both TCP and UDP.
4. Keep one workspace open, or read the two-workspace rule below.
5. Make sure the QLab machine's firewall accepts inbound TCP and UDP on 53000.

Two workspaces open is the dangerous case. QLab then discards the /cue/<number> part of an unscoped address and runs what is left as a workspace-level command. A GO fires whatever sits at the playhead and advances it. A stop aimed at one cue stops them all. Both are answered ok. The property setters (rate, level, opacity, preWait, duration) have no workspace-level form and answer error. With one workspace open, the unscoped form was correct in every case tested. So: one workspace, the Workspace ID field is optional; two, it is required.

Cue numbers are matched across the whole workspace. Give every cue a unique number, in every cue list.

2 · Connect CueSync

1. Network → Outputs → Add Output. Set Category to Audio, then Protocol to QLab (TCP).
2. Give it a Name. Enter the QLab machine in Host / IP Address. Port fills in as 53000.
3. Workspace ID (optional): leave empty on a one-workspace rig. Fill it in whenever a second workspace is open (a show and its backup). CueSync's hint says it logs every open workspace's ID and name when it connects. QLab does not show the ID beside the OSC settings.
4. OSC passcode: the code from QLab's OSC Access panel, or blank if you ticked the No Passcode row. The field starts empty on an existing output and says leave blank to keep the stored code. CueSync keeps the passcode securely on this Mac; it is not written to the show file or a settings export. The passcode belongs to the address you typed it for. If an output's passcode was saved before that, or the output has since been moved to another address, the output connects without it and a notice asks Send the passcode to <address>? with a Send passcode button; your answer is remembered for that address.
5. Timing (optional): Pre-fire (ms) and Latency comp (ms), 0–500 each. See section 5.
6. Test Connection, then Add Output. The output connects immediately.

TCP or UDP. Both go to port 53000 and carry the same addresses. They differ in what CueSync can learn back.

Use TCP unless you need a Fade ramp or timetag scheduling.

Do not add both transports for one machine. CueSync fires every QLab action down every QLab transport it has. A machine with a TCP and a UDP output receives each GO twice, and the second one fires the next cue. The Add Output dialog warns "Every cue would reach this device twice". A venue profile or an imported output list can add outputs without that warning, so check the list afterwards. If you need both on one machine, pin each action to one output: pick that output first in Add Action (section 3), and only that output receives it.

What "connected" means. Read the green dot for what it proves.

On a TCP connect CueSync sends your passcode (if you set one), reads the workspace list and subscribes to QLab's running-cue updates, which is what lets a Look turn LIVE.

A refusal is easy to miss over UDP. CueSync reads QLab's denied on TCP, records it in its log and as the output's last error, and reports the cue as failed with the wording "QLab refused the connection — set the output's QLab passcode". UDP carries no reply, so nothing is read back there. On a new rig, fire one harmless cue and watch QLab. A QLab Look that never turns LIVE while QLab visibly runs the cue is the other symptom, because refusals do not count as feedback.

3 · What a QLab action can send

Add the action from a cue's Actions list (Show Editor Inspector → Actions tab, or the Cue Editor) with Add Action. Pick your QLab output under Your outputs, then QLab. That pins the action to that one output. Or search for QLab; the entry sits under Show Control. A new QLab action starts with GO ticked.

The fields, and what goes on the wire

With a Workspace ID set, every address above is prefixed /workspace/<id>. A TCP output and a UDP output send the same address for each verb.

⚠ The Cue List box changes nothing on the wire. QLab has no OSC address that scopes a GO to one cue list. CueSync logs the list name and sends /cue/<n>/go, which QLab resolves across the whole workspace. Two cue lists with the same cue number are a trap.

Which verb wins

An action does one transport verb, chosen in this order: panic, stop, pause, resume, reset, select cue, select next, select previous, playhead, start, GO. The first one that is set fires and the rest are dropped. Property setters (rate, level, opacity, pre-wait, duration) are separate: each one that has a value is sent alongside the verb, after it, provided a Cue Number is set.

Three consequences that catch people:

• GO is ticked by default, and it loses to everything above it. Type a Select Cue and leave GO ticked, and CueSync sends the select and drops the GO. If you want select, then GO, use two actions.
• A property-only action needs GO unticked. Cue Number 12 plus Audio Level (dB) −12 with GO still ticked sends /cue/12/go and then the level. The cue starts, and the level arrives after it.
• Properties go out after the verb. If a level must be in place before a cue starts, put it in an earlier action.

What is refused, and what fails visibly

Rate and level take any number: CueSync does not range-check them. QLab's level is in dB, and QLab documents a rate range of 0.03 to 33 (from QLab's documentation), so a rate outside it is QLab's to clamp or ignore.

Fade (OSC ramp)

Add Action → Fade (OSC ramp), target QLab cue level, ramps a cue's level from From dB to To dB over Duration (beats) or or ms, on a curve (Linear, In, Out, S-Curve, Exp). It sends /cue/<n>/level/0/0 repeatedly, so it needs the QLab (UDP) output. The dB boxes are limited to −60 to +12. Panic, show-stop and a disconnect cancel it.

4 · How QLab is reached from Looks, pads, intents and panic

Panic is one-way for QLab. Releasing the panic (Cmd+Shift+B again, or Resume) restores nothing in QLab. /panic ends in a hard stop; QLab fades briefly into it, and CueSync has no /hardStop verb for an instant cut. Start the audio again with a cue. In Run Mode a manual GO still reaches QLab while a blackout is latched, and the GO button reads INTO BLACKOUT.

Timecode does not stream to QLab. QLab reads MTC or LTC itself. CueSync's timecode output routing deliberately excludes it. See Timecode.

5 · Timing

• Pre-fire and Latency comp shift when a beat-driven cue's QLab message is sent, per output, up to 500 ms each. A Theatre GO is sent when you press it.
• Schedule on the console's clock (QLab UDP only) sends pre-fired cues as timetagged bundles. It needs Pre-fire or Latency comp above 0 and both machines on one clock. It is untested against a real QLab.
• A QLab (TCP) output shows a measured latency in its editor with a one-tap Use for Latency comp.

6 · Use cases

A · Theatre: GO a sound cue by number

You have a Theatre show and QLab 5 running the sound design. Cue 5 of the show should start QLab cue 3.

1. In QLab: Workspace Settings > Network > OSC Access, tick View, Edit and Control on the No Passcode row. Confirm cue 3 exists and is the only cue numbered 3.
2. In CueSync: Network → Outputs → Add Output, Audio, QLab (TCP), host = the QLab machine, Test Connection, Add Output. Expect a green output.
3. In the Show Editor, open Output Routing… for the lane that carries sound cues (lane header ⋯ menu, or right-click the lane chip). Tick only the QLab output and Save.
4. Select cue 5. In the Inspector's Triggers tab set the mode to Manual.
5. Actions tab → Add Action → your QLab output → QLab. Expand the row. Set Cue Number to 3. Leave GO ticked and Cue List blank.
6. The row's summary reads Go 3. Set the rehearsal selector to DRY first and step through the show to check sequencing without sending anything. Then switch to SHOW.
7. Open Run Mode, press P to play, and press Space at the cue.

You should see: QLab starts cue 3. Run Mode's activity log records the cue as fired. If it fails, the log names the output and the reason.

Give QLab its own lane. Every action in a lane is tried against every output the lane routes to. An output of a different protocol refuses it by name: "Cue routed to '<name>' (…) but this action needs QLAB — fix the lane/track output routing". The QLab leg still fires; the cue then reports one failed output.

B · Hybrid night: QLab as the audio half, with a panic

A DJ set with stingers and spoken cues played from QLab, and one gesture that stops everything.

1. Add the QLab (TCP) output as above. Put its passcode in OSC passcode if you used one.
2. Open Cue Pads. Add three pads from the QLab templates: Go, Stop and Panic. Set the Go pad's action to GO with a Cue Number if you want one stinger per pad, since a bare GO fires whatever the playhead holds.
3. Test-fire each pad with a harmless cue at the playhead (right-click → Test Fire).
4. During the set, fire the stingers from the pads.
5. To stop everything, press Cmd+Shift+B, or Transport → Panic → Blackout.

You should see: QLab stops every cue at once (a brief fade into a hard stop, QLab's own panic), and the lighting outputs go dark with it. If the QLab output was down, CueSync raises a sticky Blackout incomplete banner naming it. Release the panic when you are ready, then start audio again with a cue. See Hybrid Night workflow.

C · Ramp a music bed down

1. On the QLab machine's output, use QLab (UDP) only (a Fade needs it), or keep a UDP output beside the TCP one and pin your GO actions to the TCP output.
2. In a cue: Add Action → Fade (OSC ramp). Choose QLab cue level. Set Cue # to the music cue, From dB 0, To dB -60, Duration (beats) blank, or ms 4000.

You should see: the cue's level in QLab move over four seconds. The level/0/0 address is QLab's documented form, so watch the level move on a rehearsal before you trust it.

7 · Send a cue list to QLab

File → Sync, Import & Export → Send Cue List to QLab… (Theatre and Production; also in ⌘K) creates one QLab cue for each cue of a Part, in the workspace of a QLab output, so the sound department does not retype the cue list.

1. Pick the QLab output (when there are several), the Part, and optionally one Lane (your SFX lane, say). Choose Memo (a placeholder) or Group (a container you drop the audio cues into; firing the group fires them).
2. Read the plan. Every row shows the show's cue number, the QLab number it becomes, the name and, for a Timecode cue, its trigger time. A cue with a QLab GO or Start action becomes a QLab cue with that number, the number CueSync already fires. A cue without one keeps its own number and is marked the show does not fire it. Skipped, each with its reason: a disabled cue, no number, a number used twice, a number QLab cannot be sent over OSC (a space, /, *, ?, #, ,, [ ] { }), and a number QLab already holds.
3. Read QLab asks the workspace which of those numbers it already has. Those cues are left exactly as they are, so sending again after a partial send creates only what is missing.
4. Send N cues…, then Create N cues. CueSync reads QLab again, then creates each cue after the previous one (the first after the cue selected in QLab), with its number, name, notes and timecode trigger time, and reads each one back. It stops at the first thing QLab refuses and reports what it had made and what QLab said.

Timecode triggers. With Write timecode trigger times on, a Timecode cue gets its trigger set to the time CueSync fires it, on the house clock (venue origin and trigger offsets included). QLab's OSC dictionary can set that time but has no command to switch a cue's timecode trigger on, or to make a cue list follow timecode, and setting the time does not switch it on (the trigger reads disabled with the time filled in). Do both in QLab: tick Timecode in the cues' Triggers tab and set the list's timecode input at the show's rate. GO, standby and follow cues get no trigger time.

What it needs from QLab. One workspace open, or the output's Workspace ID set; with two open and no ID, the send refuses, because QLab sends an unscoped message to every workspace. Edit access: the output's passcode, or Edit ticked on the No Passcode row. A send is refused while the show is live.

What was checked. The messages are QLab 5's documented ones (see What has been checked).

Tips & gotchas

• Factory workspace, no passcode, no ticked row: every command is denied. The number-one first-day problem. See section 1.
• One workspace, or set the ID. With two workspaces open and no ID, a GO fires the playhead cue and a stop stops everything, and QLab answers ok.
• Same cue number in two lists. The Cue List box does not disambiguate. Renumber.
• GO is ticked by default. A select, stop, pause or panic in the same action wins over it. A property-only action needs GO unticked.
• A cue-less Stop is /stop. It stops every running cue in the workspace, including the music bed and ambience CueSync did not start.
• UDP cannot tell you anything. Not a wrong passcode, not a refusal, not a closed workspace. Prefer TCP.
• Two transports, one machine, double GO. Keep one, or pin.
• The panic does not undo itself. Restart audio with a cue.
• Lane routing. Give QLab a lane of its own, or every routed non-QLab output reports a mismatch.
• Rehearse in DRY. DRY steps through cues and sends nothing to hardware.

What has been checked

CueSync has been tested against QLab 5 on both transports. Some verbs are built from QLab's documented OSC addresses and have not been confirmed one by one, and QLab 4 has not been checked. Do one dry run on your own QLab before you rely on a verb, and try Send Cue List on a scratch workspace first. A checklist is on Desk Verification.

Related

• Network Outputs — Adding, testing and monitoring outputs
• Palette — Building Looks, QLab cues included
• Cues — Adding actions to cues
• Cue Pads — Putting QLab actions on pads
• Show Editor — Lanes, Parts and Output Routing
• Timecode — Why QLab follows MTC or LTC itself
• Diagnostics — Flight Check depth labels and the connection log
• Desk Verification — A checklist for proving your own setup
• What Each Action Can Send — The verb list for every action
• MIDI and MIDI Show Control — The theatre-desk lane
• Theatre show workflow — Building a whole show
• Hybrid night workflow — A DJ half and a theatre half in one night
• GrandMA3 — The console playbook this page follows