Show control broadcast is QLab’s name for a set of MIDI Show Control (MSC) and Open Sound Control (OSC) messages which report on the status of a workspace while in performance. These messages can be used to monitor QLab’s status, for example by a stage manager or director of production who wants to be kept informed about “where we are” in the show, or used to remote-control another device by having that device start cues of its own whenever a matching cue in QLab starts.

Show control broadcast can be switched on and off per workspace, and is entirely optional.

Show Control Broadcast With MSC

MSC show control broadcast uses the same MIDI output patches that MIDI cues and MIDI File cues use. To configure MIDI output patches, visit Workspace Settings → MIDI → MIDI Outputs.

Once you have at least one MIDI output patch configured, go to the MSC Broadcast tab.

The upper left corner has a checkbox which allows you to enable or disable MSC broadcast messages for the entire workspace. To add an MSC broadcast output, click on the New Destination button or use the keyboard shortcut ⌘N while this tab of this window has focus.

Each destination is an individually configurable output for MSC broadcast messages, which requires three settings:

• A MIDI Patch, which the MIDI output patch that will receive the messages. The MIDI output patch, in turn, connects the workspace to a MIDI device (or virtual device, such as an IAC bus or RTP-MIDI session.)
• Under the Message heading is a pop-up menu which lets you set the command format for the destination. Command format is an MSC term for the category of device or software that will be receiving the messages. The MSC spec defines a number of specific categories and each device or software must self-identify as belonging to one or more category. QLab itself, for example, responds to messages in the Sound (General), Video (General), and Lighting (General) categories. Refer to the documentation of the device that you’re sending messages to in order to learn which category to use.
• Also under the Message heading is a field to enter the Device ID of the device that will be receiving the messages. Device ID 127 is the “all-call” ID, so if you set a destination to use, say, the Lighting (General) format and device ID 127, then all devices which are physically connected to that MIDI output patch and which self-identify as Lighting (General) will receive the messages.

To remove a destination, click the button at the right edge of that destination in the list.

Example

In the screen shot above, there are three MSC broadcast destinations.

The first one sends MSC messages to “All Types” via an IAC bus. Since IAC busses are internal to the Mac, any other programs running on the same Mac which are using device ID 9 will receive these messages.

The second one sends MSC messages to “Lasers” via a different IAC bus. Any laser-specific software running on the same Mac which uses device ID 2 will receive these messages.

The third one sends MSC messages to “Robots” via an RTP-MIDI session. Any robots out there listening to the same RTP-MIDI session and using device ID 53 will receive these messages.

MSC Show Control Messages

Action in QLab	Corresponding MSC message
GO	MSC GO {cue number of the cue which ran}
Panic All	MSC ALL_OFF
Stop All	MSC ALL_OFF
HardStop All	MSC ALL_OFF
Reset All	MSC RESET

Show Control Broadcast With OSC

OSC show control broadcast consists of a set of OSC messages which another program or device can send to QLab which will cause QLab to keep that other program or device informed about show control status. If the QLab workspace is closed and reopened, the remote program or device will need to re-send the message to continue receiving updates.

Messages To QLab

The highest-level commands are /listen and /ignore which start and stop the flow of all show control messages.

Message sent to QLab	Result
/listen	Client will receive all show control messages.
/ignore	Client will stop receiving all show control message.

Once a client requests updates, QLab can send show control messages in three basic forms.

Workspace Event messages with arguments

The first form of OSC show control broadcast message is a workspace event message with arguments, which looks like this:

/qlab/event/workspace/{event} {cue number} {cue name} {cue uniqueID} {cue type}

Action in QLab	Corresponding {event}
GO	go
Audition Go	auditionGo
Stop	cue/stop
Start	cue/start
Playhead move	playhead

When any of those events occur in the workspace, the corresponding message will be sent with arguments filled in based on the cue that was related to the event. For example, consider this screen shot:

If someone pressed at this moment, QLab would send this show control broadcast message:

/qlab/event/workspace/go "24" "intro music" "F8CD48F4-B06B-4992-ACD6-5753D0224" "Audio"

QLab also sends four individual messages containing each of those four arguments individually:

• /qlab/event/workspace/go/number 24
• /qlab/event/workspace/go/name "intro music"
• /qlab/event/workspace/go/uniqueID F8CD48F4-B06B-4992-ACD6-5753D0224
• /qlab/event/workspace/go/type Audio

GO and Start

Whenever a cue starts for a reason other than a , that is considered a “start.” So, if cue 1 is a Start cue which targets cue 2, and you select cue 1 and press , QLab would report a /qlab/event/workspace/go message for cue 1, and a /qlab/event/workspace/cue/start message for cue 2.

As far as show control broadcast is concerned, “previewing” a cue is the same as “starting” it.

Stop

Whenever a cue stops, whether it’s stopped manually or as a result of a Stop cue or because it simply runs out, QLab reports a /qlab/event/workspace/cue/stop message for that cue.

Playhead Move

Whenever the playhead in the current cue list moves for any reason, QLab reports a /qlab/event/workspace/playhead message for the cue that the playhead moves to.

Workspace Event messages without arguments

The second form of OSC show control broadcast message is a workspace event message without arguments, which looks like this:

/qlab/event/workspace/{event}

Action in QLab	Corresponding {event}
Pause All	pauseAll
Resume All	resumeAll
Panic All	panicAll
Stop All	stopAll
HardStop All	hardStopAll
Reset All	resetAll

Whenever any of those events occurs in the workspace, the corresponding message is sent.

Setting scope

While a comprehensive set of show control messages is hardly overwhelming, it still may be desirable to receive only a subset of these messages instead of every single one.

To that end, the /listen and /ignore messages have a set of extended forms which allow you to receive or stop receiving exactly the show control messages you want. The extended forms look like this:

/{command}/{event}/{optional detail}

• {command} can be either listen or ignore
• {event} can be any event listed above, such as go, playhead, cue/start, or stopAll.

You can stop there with messages like /listen/go or /listen/resumeAll, or add any of the following optional details:

• number
• name
• uniqueID
• type

Adding those details further reduces the variety of messages which get sent.

Example

If a client sends QLab only this message:

/listen/go

It will only receive /qlab/event/workspace/go messages, including all forms of that message with all arguments.

If a client sends QLab only these messages:

/listen/go/number, /listen/panicAll

It will receive one /qlab/event/workspace/go {number} message with every with only that single argument. It will also receive a /qlab/event/workspace/panicAll message whenever the workspace panics.

By using the extended forms of /listen and /ignore messages in combination, you can subscribe to the exact set of messages you want, with nothing extraneous.

Customizing outgoing OSC show control broadcast messages

Sometimes, you may need to send show control broadcast messages from QLab which are formatted differently than the default messages listed above. For example, you may be using a device which can only respond to OSC messages formatted in a specific way.

You can set your own format by sending the OSC message /eventFormat to QLab from the client that wants the custom-formatted messages. This message accepts one argument which is a text string containing the desired message format. The string can contain any or all of the following tokens which will be replaced with live data when the message is sent:

• #workspace_id# - the workspace ID.
• #address# - the address of show control broadcast message.
• #status# - this token returns “error” if either the incoming or outgoing message is malformed or in any other way problematic, or “ok” if everything is ok.
• #data# - the argument of the show control broadcast message.

When you use /eventFormat, QLab will only send single-argument show control broadcast messages. The multi-argument message will not be sent.

At present, you are only able to use a single /eventFormat at a time (per client) which will format all OSC show control broadcast messages for the given client. This means it’s possible to create a format which will generate invalid messages. For this reason, it’s probably best to /listen to specific events which are compatible with your chosen format.

To find out the current format, send /eventFormat without any arguments. QLab will reply with the current format.

To reset to the default format, send /eventFormat "" (an empty string argument.)

Examples

• The default format can be re-created using /eventFormat "#address# #data"
• To format a message which starts cues in another copy of QLab on another Mac, you could use this format: /eventFormat "/cue/#data#/start. Then send /listen/go/number and optionally also /listen/start/number
• To send the message expected by an ETC Eos family console, use /eventFormat "/eos/cue/#data#/fire. Then send /listen/go/number and optionally also /listen/start/number