5.4 QLab control for ASM and Viewer sync (Beta)

What this beta workflow does

This workflow keeps SurtitleLive as the script, translation, deployment, live-console, and audience-phone system. QLab becomes the show-control surface for subtitle cues during the performance.

• QLab displays the imported subtitle Text cues locally, so the projection computer has a QLab-native subtitle backup.
• When armed, each SurtitleLive subtitle Group can also tell SurtitleLive Cloud to jump to the matching deployed cue.
• The already-open SurtitleLive live console then publishes the normal cue state to Viewer links and audience phones.
• This is not a separate deployment path. It uses the existing deployed show, existing ASM link, and existing Viewer links.

Prepare subtitles on SurtitleLive

1. Finish script editing, translation, and subtitle review in the Editor.
2. Use Simulation to confirm cue order and languages.
3. Deploy the show through Go Live.
4. Open the deployed show in Deployment Cockpit.

Enable QLab Cloud Sync and download the pack

1. In Deployment Cockpit, find the QLab Cloud Sync panel after Front-of-House Materials.
2. Turn on Enable QLab control in the SurtitleLive console. This does not change the ASM link, QR code, Copy, or Open action.
3. Download the QLab Projection Pack for the deployed show.
4. In the QLab options dialog, choose projection outputs before download: language, caption position, same-screen or separate-screen routing, QLab screen/stage name when needed, character-name display, and stage-direction handling.
5. The beta defaults remain theatre-safe: character names hidden and stage directions skipped unless you deliberately include them.
6. Download a fresh QLab Projection Pack after Update Live or redeploy so QLab and ASM use the same deployed subtitle source.
7. Download the pack on the Mac that will run QLab. Cloud Sync uses QLab Script cues, which require a QLab license of any kind. Node.js (version 18 or newer) must also be installed on this Mac to run the bridge helper.

Set up the downloaded pack in three steps

1. Unzip the pack, open your QLab 5 workspace, then read and follow 1 - START HERE.txt. It is the short operator guide for this pack.
2. Run 2a - Import into QLab.applescript, then choose 2b - QLab Cue Data.json.
3. Double-click 3 - Start Local Bridge.command and keep Terminal open. Open and unlock the normal ASM Console, click QLab enabled at the bottom-right, click Connect local bridge, allow local-network access if asked, wait for Viewer sync ready, then click Allow QLab control.

The Support Files folder is for checking or troubleshooting only. You do not need to open it during normal setup.

Imported pack structure & rules

• The deployed-show pack imports SurtitleLive subtitles as QLab Groups. Each Group contains one or more Text child cues for local projection and one Script child cue that sends non-secret cue identity to the local bridge.
• If you choose multiple languages or screens, keep them inside the same SurtitleLive Group. They are the same subtitle cue, not separate cue moments. Same-screen languages should remain separate Text child cues at different top/middle/bottom positions.
• If you include stage directions as Text cues, they are imported as normal SurtitleLive Groups too. They can project locally and sync to audience phones, which is useful for accessibility captions. Memos do not support sync.
• If you import a revised pack later, matching SurtitleLive subtitle Groups are updated by stable cue key. SurtitleLive output children omitted by the latest pack are disabled and cleared; your sound, light, video, standby, and other QLab cues are untouched.
• Move whole SurtitleLive subtitle Groups into your main QLab show list. Do not copy them: duplicate stable cue keys are rejected before re-import changes captions.
• Add sound, light, video, standby, wait, pause, or other QLab cues before, after, or between SurtitleLive subtitle Groups.
• Keep each SurtitleLive Group intact. Do not split Text child cues from the Script child cue unless you intentionally want that subtitle to stop syncing audience phones.

Bridge checks and troubleshooting

• Double-click 3 - Start Local Bridge.command. It opens Terminal automatically. The bridge requires Node.js 18 or newer, must run on the same Mac as QLab, and its Terminal window must stay open during the show.
• If file 3 does not open, open Terminal from Applications → Utilities, then follow the short fallback in 1 - START HERE.txt: run bash "./3 - Start Local Bridge.command" from the unzipped pack folder.
• If port 37621 is busy, do not change the port in QLab. If a SurtitleLive bridge is already running, keep it open and connect ASM to it. Do not start another bridge.
• If another app owns the port, open Terminal from Applications → Utilities, run lsof -nP -iTCP:37621 -sTCP:LISTEN, close the app shown, then run bash "./3 - Start Local Bridge.command" again. If you cannot identify or close it, disconnect QLab control and continue with normal ASM controls.
• Confirm the SurtitleLive live console shows Bridge helper connected and Viewer sync ready.
• After Allow QLab control, ASM switches mobile Viewer and Projection output to cue-to-cue replacement, so the previous subtitle disappears when the next QLab subtitle cue fires.
• While QLab control is allowed, ASM locks its mobile-subtitle display toggles. If your QLab pack includes stage directions as Text cues, QLab-triggered stage-direction cues still project and sync to audience phones.
• Run one QLab subtitle cue to verify QLab cue input reaches ASM.

Rehearse before showtime

• Run one early subtitle from QLab and confirm QLab projection, SurtitleLive live-console current cue, and Viewer subtitles all match.
• Confirm the previous subtitle disappears when the next QLab subtitle cue appears.
• Run one middle subtitle directly from QLab, not only the next cue.
• Jump to a wrong subtitle, then correct it from QLab, and confirm ASM and Viewer follow the corrected cue.
• If your show uses QLab blackout, pause, wait, or standby cues, test those as your own QLab cues. The SurtitleLive beta pack does not add extra blackout, standby, test-card, memo, or final-clear cues.
• If any check fails, click Stop QLab control and use SurtitleLive live-console manual controls or QLab projection-only as the fallback.

If subtitles change after export

• Make the subtitle change in SurtitleLive and save the Editor.
• Use Update Live Subtitles or redeploy, depending on your live workflow.
• Download a fresh QLab Projection Pack from the updated deployment.
• Run the importer again. Text edits to the same SurtitleLive cue update the matching QLab Group and its output Text children in place.
• New SurtitleLive cues receive new cue keys and are inserted after the previous SurtitleLive Group when possible. Removed subtitles are marked as removed rather than deleted.
• If cue order, line IDs, cue numbers, or cue types changed, the active ASM source identity may change. Old QLab Projection Packs are intentionally rejected until the latest pack is imported.
• After re-importing, check any surrounding sound, light, video, wait, or standby cues before performance.

Safety boundaries

• The QLab Projection Pack does not contain SurtitleLive passwords, runtime tokens, or admin credentials.
• QLab local projection can continue if the network drops, because the Text cues live in the QLab workspace.
• Mobile Viewer sync still needs ASM, the local bridge, and SurtitleLive runtime control to be connected.
• The local bridge only relays allowed cue jumps from QLab to ASM on the show Mac. It listens on loopback localhost, not a public network interface.
• The local bridge is the only QLab-to-ASM control path. If it is unavailable, disconnect QLab control and continue with manual ASM.
• ASM prepares the QLab sync timeline only after QLab control is enabled in Deployment Cockpit and the operator connects and allows QLab control in ASM.
• QLab connected status is not proof that audience phones are receiving subtitles. Always test a real Viewer link before performance.