QLab Collaboration allows multiple people using multiple Macs to collaborate on a single QLab 5 workspace over a local network.

Terminology

The Mac that hosts the QLab workspace which others will connect to is called the primary Mac. The workspace on that Mac, therefore, is called the primary workspace.

A Mac which connects to the primary is called a remote client, or sometimes either a remote or a client. The workspace as it appears on a remote mac is called a remote workspace.

The types of access that a remote has while collaborating are called the remote’s access permissions. There are three types of permissions:

• Connect & View access, also called just view access, allows the remote to connect and view the primary workspace but does not allow starting, stopping, pausing, or resuming cues; moving the playhead; or editing anything in the workspace other than flagging or un-flagging cues and editing cue notes. A remote without view access will not be allowed to connect to the primary.
• Edit access allows the remote to edit all parameters of all cues and workspace settings, but does not allow starting, stopping, pausing, or resuming cues or moving the playhead.
• Control access allows the remote to start, stop, pause, and resume cues and set the position of the playhead, but does not allow editing cues or settings.

Requirements

Any Mac that can run QLab 5 can be a collaboration primary. The license or licenses installed on the Mac dictate the available behavior.

With no license installed on the primary Mac:

• Any number of Macs with licensed copies of QLab can connect with any level of access. While connected, they behave as though they have no license installed.
• Any number of Macs with un-licensed copies of QLab can connect with connect & view access only.

When one or more licenses installed on the primary Mac:

• Each license installed on the primary allows one Mac with an un-licensed copy of QLab to connect with any level of access.
• Any number of Macs with licensed copies of QLab can connect with any level of access.
• Any number of Macs with un-licensed copies of QLab can connect with connect & view access only.

Collaboration sessions are always subject to the license installed on the primary. Every Mac collaborating on a workspace will behave according to the license or licenses installed on the primary Mac.

Example

The primary Mac, a Mac Studio in the tech booth, has an audio license and a video license installed. This means:

• Two Macs with un-licensed copies of QLab can both connect with any level of access permission. Both of them will behave as though they have audio and video licenses installed while they are connected to the primary.
• Additional Macs can also connect with any level of access permission as long as those Macs have at least one license of any kind installed. No matter what license they have, though, they will behave as though they have audio and video licenses installed while they are connected to the primary.
• Additional Macs with un-licensed copies of QLab can connect with view-only access. This makes it easy for a stage manager or backstage crew members to follow along with QLab visually as long as they already have access to a Mac.

Physically, all Macs involved in collaboration must be connected to the same local area network via ethernet or WiFi, and must use compatible IP addressing schemes. Collaboration also works over virtual private networks (VPNs) so with a little careful planning, an off-site Mac can be included in your collaboration setup. In short, if two Macs are able to connect via file sharing or screen sharing, they will be able to connect via QLab Collaboration as well.

The Basic Computer Networking for the Theater tutorial provides an overview of the basics of setting up a network geared towards theater practitioners. If all this networking stuff is making your head spin a little, this tutorial can help!

QLab Collaboration uses Bonjour to make connections between Macs, which means less configuration work for you.

Setting Up A Primary

This topic is covered in the Workspace Settings → Collaboration section of this manual.

Connecting As A Remote

There are three ways to connect as a remote to a primary Mac:

• From the Launcher Window, click the Connect to Workspace button
• Choose Connect to Workspace… from the File menu
• Use the keyboard shortcut ⇧⌘K

Any of these three options will open a window listing the QLab workspaces available to connect to.

If the primary is set to ask before allowing new collaborators to connect, and this client has never connected to this primary before, attempting to connect will display a permission request on the primary:

Clicking the blue button or pressing the return or enter key will allow the connection and assign the default access permissions set in Workspace Settings → Collaboration. Clicking any of the other “accept” buttons will allow the connection and assign the access permissions indicated by the button. Clicking Reject connection will, of course, reject the connection and not add the remote to the list of collaborators.

After a remote connects and is accepted, future re-connections will happen without approval.

Remotes can have their access permissions changed and can be removed from the list of approved collaborators in Workspace Settings → Collaboration.

Using A Remote

A remote workspace is visually distinct from a normal, local workspace in several ways:

• The title bar is drawn in purple, and the word “Remote” appears before the workspace name.
• The button is drawn with a purple border.
• The footer displays the collaboration icon with the current access permissions listed beside it. You can click on the icon to display the IP address and other details of the primary.

Both remote and primary workspaces (while collaborating) display an additional column on the right side of the cue list view; the collaboration column. A colored dot here indicates a cue that is currently selected by a collaborator on another Mac. If multiple collaborators are connected, one dot appears for each collaborator.

When two or more collaborators have the same cue selected, the inspector shows a colored indicator on the inspector tab that each other collaborator is viewing.

By default, the selection on all remote workspaces is unlocked from the playhead, so each collaborator can independently select separate cues. The playhead position, meanwhile, is necessarily a state shared across all collaborators, because it is a property of each cue list on the primary. Any collaborator that has control permission can move the playhead to a cue by clicking in the status column for that cue. Any collaborator with control permissions can also quickly jump the playhead to their locally selected cue by pressing the keyboard shortcut for load, which is L by default.

Additionally, you can optionally set any collaboration remote with control permission to lock the playhead to its selection by visiting Workspace Settings → Collaboration on that remote.

If this box is checked, the playhead will be locked to the selection on this remote. If multiple collaborators have this box checked, they will all be able to move the playhead by moving their selection. This can make some workflows much simpler, but can complicate others.

Working With Cues

All edits made while collaborating follow a last-edit-wins policy. Because of network latency, however, it can sometimes be surprising which edit was in fact last. For this reason, collaborators are encouraged to devise their own person to person guidelines about how to work together smoothly without confusing each other.

Undo and Redo

Each collaborator maintains their own, unique undo history for edits made in cue lists and carts. This allows you to focus on your own work, and not worry about keeping track of what your collaborators are doing.

The Light Dashboard has a single undo history shared across all collaborators.

Each settings area (General, Controls, Audition, etc…) has its own single undo history shared across all collaborators.

Creating, Deleting, and Moving Cues

While collaborating, creating a cue, deleting a cue, and moving a cue cannot be undone. This blocking of undo allows QLab to avoid having more complex rules which you need to follow while collaborating, and prevents the workspace from entering an un-synchronizable state. Because this is different from how QLab normally behaves, QLab will display an explanatory message when you add, delete, or move a cue while collaborating.

Assigning File Targets

When assigning file targets on a remote, QLab displays a collaboration-specific file browser which shows files available in the folder within which the workspace is saved on the primary. This means that the primary must be saved at least once on the primary before a remote can assign file targets to cues. It also means that remotes can only “see” files in the same folder as the primary workspace, or in folders within that folder.

QLab only shows folders which contain files that are valid targets for the selected type of cue. In the screen shot above, an Audio cue is selected. The “video” folder on the primary is not visible because it does not contain any files which are valid targets for an Audio cue.

Running Cues

Cues always run on the primary. When a remote with control permission tells a cue to or preview, the same thing happens as though the primary told that cue to or preview.

Collaboration Error Messages

The following error messages may appear on a remote while collaborating.

Access Denied

If a new remote attempts to connect to the primary, and the person at the primary clicks Reject connection, the remote will see this message. If the rejection was made in error, simply try to connect again. If the rejection was deliberate, please understand that many people read for this part and we thank you for your time.

Action Rejected

If a remote does not have control permission, this error message will appear if the remote attempts to move the playhead, or start, stop, pause, or resume a cue.

Change Rejected

If a remote does not have edit permission, this error message will appear if the remote attempts to make any edit other than flagging or unflagging a cue, or editing the notes of a cue.

Connection Rejected

If a remote attempts to connect to a primary which has been configured to refuse access, this error message appears.

View Permission Disabled

If a remote attempts to connect to a primary that has that remote in its collaborators list, but the Connect & view checkbox is unchecked, this error message appears.