QLab has an extensive API (application programming interface) for OSC which allows you to control QLab from any device or software which can broadcast OSC messages. What follows here is a complete dictionary of QLab 5’s OSC implementation. OSC messages are sorted more or less alphabetically in each section, which is to say they’re alphabetically sorted, but messages which are closely related to each other are sometimes grouped together even if they are not alphabetically adjacent if that makes it easier to understand their relationship.

Getting Started

The QLab OSC API can be used over both UDP and TCP transport layers. QLab listens for incoming OSC on port 53000. Individual workspaces can be configured to listen for incoming OSC on any port in the Network → OSC Access section of Workspace Settings, although it’s important to remember that QLab itself still listens on port 53000.

When a client talks to QLab via UDP, each OSC message corresponds to one UDP datagram. Replies to OSC messages sent via UDP are sent on port 53001 by default, but can be customized using /udpReplyPort; see below.

When a client talks to QLab via TCP, messages are framed using the double end SLIP protocol (RFC 1055) as required by the OSC 1.1 specification.

QLab also listens for plain text on UDP port 53535, and attempts to interpret it as OSC. For example, sending the text /cue/selected/start to QLab on UDP port 53535 will have the same result as sending the actual OSC command /cue/selected/start to port 53000. The plain text UDP port can also be customized on a per-workspace basis, just like the OSC port.

The OSC API behaves almost identically when using both UDP and TCP. Exceptions are noted below, such as cases where a reply may be larger than the maximum size of a UDP datagram.

Important: OSC messages which arrive on a given port will be received by every open workspace listening to that port. This is a change from QLab 4 in which only the front-most workspace received OSC messages. If you are using multiple workspaces simultaneously and wish to route OSC messages selectively, you can use different port numbers for each workspace, prefix messages with /workspace/{id}, or prefix messages with /workspace/{name} (discussed below.)

Three Ways To Use OSC With QLab

OSC can be used in essentially three ways with QLab: as a relatively simple “remote control” protocol in the spirit of MIDI, as a robust two-way protocol for tight integration with other systems, and (as of QLab 5.3) as a show control broadcast method.

Those readers interested in using OSC for simple remote control can skip ahead to the section titled “How To Read This Dictionary.” Those only interested in show control messaging should read the Show Control Broadcast section of this manual, although the OSC messages relating to show control broadcast are also listed on this page for completeness.

For those who are interested in using OSC to talk to QLab and getting answers back, and then doing things with those answers, read on here.

Getting status updates from QLab

When a client has requested status updates, that client will receive messages from QLab whenever the client needs to update its knowledge of a cue, cue list, or workspace.

Clients who have requested status updates might receive the following messages at any time:

• /update/workspace/{workspace_id} - the client needs to reload the cue lists for the workspace. This message is also sent whenever various other aspects of a workspace are updated.
• /update/workspace/{workspace_id}/cue_id/{cue_id} - the client needs to reload the state for the specified cue. If the cue is a Group cue or cue list, the client should also reload the children of that cue.
• /update/workspace/{workspace_id}/cueList/{cue_list_id}/playbackPosition {cue_id} - the playback position of cue_list_id has changed to cue_id. If there is no current playback position, there will be no cue_id argument.
• /update/workspace/{workspace_id}/disconnect - the client must disconnect from the given workspace (e.g. because it is closing.)

To receive status updates from QLab, send the following OSC command:

/updates 1

To stop receiving updates, send:

/updates 0

The /updates message can be used by clients with any level of access permission.

Replies from QLab

Most, but not all, OSC messages sent to QLab will result in a reply being sent back to the client who sent the message. This is separate from the idea of updates, as discussed above, which are sent proactively by QLab. Replies are only sent in response to incoming OSC messages.

Messages which perform discrete actions in QLab, like /go and /panic, do not generate replies by default, although you can request a reply for every message using the /alwaysReply command, discussed below.

Replies from QLab take the form:

/reply/{/invoked/osc/method} json_string

json_string takes the form:

{
    "workspace_id" : string,
    "address": "/osc/message/that/was/sent",
    "status": string,
    "data": value
}

workspace_id is optional, and only present if the reply is specifically from the given workspace, rather than from QLab as a whole.

status can be:

• ok - the OSC message was received and everything is good.
• error - the OSC message was malformed, invalid, or something else has gone wrong.
• denied - the client has not yet successfully connected to QLab and needs to do that before sending this OSC message, or the client is connected using a passcode that does not have suitable access privileges to send this OSC message.

data is the JSON-encoded result of the OSC message that was sent.

Show control broadcast messages are not sent using this reply format. They are sent as standard OSC messages, without any JSON encoding.

Example

Sending a workspace cueLists method:

/workspace/34200B51-835A-4918-A137-B6511784B6CA/cueLists

would cause QLab to respond with:

/reply/workspace/34200B51-835A-4918-A137-B6511784B6CA/cueLists {json_string}

where {json_string} would be a list of the cue lists in the workspace.

How To Read This Dictionary

Every OSC message that QLab will respond to is listed in this dictionary. Each definition starts with a horizontal separator followed by the OSC message itself written out like so:

/cue/{cue_number}/preWait {number}

The parts that are enclosed in {braces} are the parts which you have to fill in to make the message work, and the dictionary tries to give you clues about what sort of thing you’ll need to fill it with. For example, in the message above, you need to replace {cue_number} with the cue number of the cue you want to talk to, and you need to replace {number} with a number of some kind. This OSC message uses the number you fill in to set the pre-wait of the cue that you specify.

Next comes a table which looks like this:

View, Edit, Control

The first three columns in this table describe the degree of access to this message for clients with view, edit, and control permission.

• Read means that a client can send the message without arguments and get data back from QLab. For example, /cue/10/preWait will return the pre-wait of cue 10.
• Read/write means that a client can read data from QLab, and can also send data to QLab to make changes. For example, /cue/10/preWait 5 will set the pre-wait of cue 10 to 5 seconds.
• Read only means that this message can only be used to read; there is no “write” form.
• means that a client can send this message. This is used only for messages which are “actions” such as /go and /panic, which neither read nor write data.
• means that a client cannot send this message (well, it can send it, but QLab will ignore it.)

Query

The fourth column shows whether or not this message can be used by QLab’s internal OSC query mechanism.

+/-?

The fifth column is only present for OSC messages which are directed at cues, and it shows whether or not the message can be used with QLab’s increment/decrement syntax:

• /cue/1/property/+ {delta} adds {delta} to the current value.
• /cue/1/property/- {delta} subtracts {delta} from the current value.

For example, /cue/10/preWait/+ 1 increases the preWait of cue 10 by one second.

Live

The last column is only present for OSC messages which have a live form. “Live” messages are the same as their non-live counterparts but operate on the active, “live” value of a parameter rather than changing the saved initial state of the parameter. Sending these messages does not cause the document to have unsaved changes.

For example, /cue/1/rate 2 sets the playback rate of cue 1 to 2, but /cue/1/rate/live 2 sets the live playback rate of cue 1 to 2. When cue 1 (or the whole workspace) is reset, the live adjustment will vanish and cue 1 will revert to its saved rate.

To use the live form of an OSC message, add /live as the very last part of its address.

+/- and Live together

Live goes last, always.

• /cue/x/opacity/live/+ 10 - this will not work.
• /cue/x/opacity/+/live 10 - this will work.

After the table comes a description of the behavior of the OSC message, including separate explanations for read and write usage if applicable.

Finally, some OSC messages come with examples showing how to use them. Readers are heartily encouraged to request that specific additional examples be added by emailing the QLab support team.

OSC Booleans in QLab

Many OSC messages in QLab require an argument which sets a value to either true or false. QLab 5 allows several different data types for these arguments. All of the following are valid:

• Booleans. OSC 1.1 has a boolean data type, allowing you to send True or False as an argument.
• Integers or Floats. If QLab receives any number as an argument where it’s expecting a true or false value, 0 will be interpreted as false, and any other number (including, for example, 0.5) will be interpreted as true.
• Strings. If QLab receives a text string as an argument where it’s expecting a true or false value, any string which begins with N, n, F, f, or the digit 0 will be interpreted as false. Any string which begins with Y, y, T, t, or any digit 1 through 9 will be be interpreted as true.

Examples

The following messages will all flag cue 12:

• /cue/12/flagged Yes
• /cue/12/flagged yippee
• /cue/12/flagged "you betcha"
• /cue/12/flagged 1
• /cue/12/flagged 1.0
• /cue/12/flagged true

The following messages will all un-flag cue 12:

• /cue/12/flagged No
• /cue/12/flagged never
• /cue/12/flagged "forget it"
• /cue/12/flagged 0
• /cue/12/flagged 00
• /cue/12/flagged false

Starting with QLab 5.2, any OSC message in QLab’s dictionary that accepts a boolean argument can also accept the argument toggle or append /toggle to the end of their address. Doing this will toggle the current value.

Example

• /cue/12/flagged/toggle or /cue/12/flagged toggle will flag cue 12 if it is currently un-flagged, or un-flag it if it is currently flagged.

Application Messages

The following OSC messages pertain to QLab as a whole, not to a specific workspace. For security, however, if every open workspace requires a passcode, then a client must connect to at least one of those workspaces with the passcode before any application messages will be accepted.

There are two exceptions to this rule: /version and /workspaces will always be accepted, even without a passcode.

/alwaysReply {number}

By default, QLab will only reply to an incoming OSC message if that message generates a reply to send. For example, /go does not generate a reply.

Read: If number is not given, return the alwaysReply status for the sending client.

Write: If number is given and is not zero, send a reply for every OSC message received from the client. Messages that would not normally generate a reply will generate one with a JSON string argument that contains:

{
  "workspace_id" : {string},
  "address": "/osc/message/that/was/sent",
  "status": {"ok" or "error"}
}

If number is given and is 0, stop sending replies to messages that do not generate replies.

/disconnect

Disconnect from QLab. Clients should send this message when they will no longer be sending messages to QLab.

If you are communicating with QLab via UDP, QLab will automatically disconnect your client if it has not heard any messages from it in the last 61 seconds. Any message (e.g. /thump) will serve to keep the client connected, or you can send /forgetMeNot or /udpKeepAlive (see below) to override this 61-second timeout. If you are disconnected, you will need to reconnect before further commands will be accepted. If you are using a connection with a passcode, the passcode needs to be sent again, just as though you were connecting for the first time.

If you are communicating with QLab via TCP, QLab will not automatically disconnect your client, because TCP is nice like that. Clients will remain connected until they send /disconnect or until the TCP connection itself is disconnected.

/fontNames

Return an array of the names/PostScript names of all available fonts. For example:

[
  "AppleColorEmoji",
  "AppleSDGothicNeo-Bold",
  "AppleSDGothicNeo-ExtraBold",
  "AppleSDGothicNeo-Heavy",
  "AppleSDGothicNeo-Light",
  ...
]

/fontFamiliesAndStyles

Return a dictionary with each available font family name (e.g. “Helvetica”, “Courier New”) paired with an array of its available styles (e.g. “Regular”, “Light Oblique”). For example:

{
  "Apple Color Emoji" :
    [
      "Regular"
    ],
  "Apple SD Gothic Neo" :
    [
      "Regular",
      "Medium",
      "Light",
      "UltraLight",
      "Thin",
      "SemiBold",
      "Bold",
      "ExtraBold",
      "Heavy"
    ],
  ...
}

/forgetMeNot {boolean}

/udpKeepAlive {boolean}

Sending /forgetMeNot or /udpKeepAlive with a true argument will cause QLab to remember the client and all its settings (such as /alwaysReply) until QLab quits or until the client sends /forgetMeNot or /udpKeepAlive with a false argument. This allows a client to send a passcode, ask for specific replies, etc. only once at the beginning of a session, and not worry about being disconnected after 61 seconds of inactivity.

It is best practice to always send /forgetMeNot or /udpKeepAlive with a false argument when you’re done, to allow QLab to clear its record of the now-inactive client.

/overrides/dmxOutputEnabled {boolean}

Read: If no argument is given, return the current state of the DMX output override.

Write: Set the DMX output override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleDmxOutput

Enable or disable DMX output.

/overrides/midiInputEnabled {boolean}

Read: If no argument is given, return the current state of the MIDI input override.

Write: Set the MIDI input override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleMidiInput

Enable or disable MIDI input.

/overrides/midiOutputEnabled {boolean}

Read: If no argument is given, return the current state of the MIDI output override.

Write: Set the MIDI output override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleMidiOutput

Enable or disable MIDI output.

/overrides/mscInputEnabled {boolean}

Read: If no argument is given, return the current state of the MSC input override.

Write: Set the MSC input override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleMscInput

Enable or disable MSC input.

/overrides/mscOutputEnabled {boolean}

Read: If no argument is given, return the current state of the MSC output override.

Write: Set the MSC output override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleMscOutput

Enable or disable MSC output.

/overrides/sysexInputEnabled {boolean}

Read: If no argument is given, return the current state of the MIDI SysEx input override.

Write: Set the MIDI SysEx input override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleSysexInput

Enable or disable SysEx input.

/overrides/sysexOutputEnabled {boolean}

Read: If no argument is given, return the current state of the MIDI SysEx output override.

Write: Set the MIDI SysEx output override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleSysexOutput

Enable or disable SysEx output.

/overrides/networkExternalInputEnabled {boolean}

Read: If no argument is given, return the current state of the external network input override.

Write: Set the external network input override to true or false. See details on booleans at the beginning of this section.

The external network input override pertains to network messages that come from other devices on the network. It does not pertain to network messages from QLab itself, or from other software running on the same Mac as QLab.

/overrides/toggleNetworkExternalInput

Enable or disable external network input.

The external network input override pertains to network messages that come from other devices on the network. It does not pertain to network messages from QLab itself, or from other software running on the same Mac as QLab.

/overrides/networkExternalOutputEnabled {boolean}

Read: If no argument is given, return the current state of the external network output override.

Write: Set the external network output override to true or false. See details on booleans at the beginning of this section.

The external network output override pertains to network messages that QLab sends to other devices on the network. It does not pertain to network messages that QLab sends to itself or to other software running on the same Mac as QLab.

/overrides/toggleNetworkExternalOutput

Enable or disable external network output.

The external network output override pertains to network messages that QLab sends to other devices on the network. It does not pertain to network messages that QLab sends to itself or to other software running on the same Mac as QLab.

/overrides/networkLocalInputEnabled {boolean}

Read: If no argument is given, return the current state of the local network input override.

Write: Set the local network input override to true or false. See details on booleans at the beginning of this section.

The local network input override pertains to network messages that come from QLab itself or other software running on the same Mac as QLab. It does not pertain to network messages from other devices on the network.

/overrides/toggleNetworkLocalInput

Enable or disable local network input.

The local network input override pertains to network messages that come from QLab itself or other software running on the same Mac as QLab. It does not pertain to network messages from other devices on the network.

/overrides/networkLocalOutputEnabled {boolean}

Read: If no argument is given, return the current state of the local network output override.

Write: Set the local network output override to true or false. See details on booleans at the beginning of this section.

The local network output override pertains to network messages that QLab sends to itself or to other software running on the same Mac as QLab. It does not pertain to network messages sent to other devices on the network.

/overrides/toggleNetworkLocalOutput

Enable or disable local network output.

The local network output override pertains to network messages that QLab sends to itself or to other software running on the same Mac as QLab. It does not pertain to network messages sent to other devices on the network.

/overrides/timecodeInputEnabled {boolean}

Read: If no argument is given, return the current state of the timecode input override.

Write: Set the timecode input override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleTimecodeInput

Enable or disable timecode input.

/overrides/timecodeOutputEnabled {boolean}

Read: If no argument is given, return the current state of the timecode output override.

Write: Set the timecode output override to true or false. See details on booleans at the beginning of this section.

/overrides/toggleTimecodeOutput

Enable or disable timecode output.

/overrideWindow {boolean}

Read: If no argument is given, return the current visibility of the Override Window.

Write: Show or hide the Override Window. See details on booleans at the beginning of this section.

/toggleOverrideWindow

Show or hide the Override Window.

/replyFormat {format_string}

Set the format of QLab’s reply messages to suit your needs. format_string is a string containing your desired reply format. The string can optionally contain the following tokens that will be replaced when sending the reply:

• #workspace_id# - the workspace ID
• #address# - the OSC address of the reply
• #status# - ok / error
• #data# - the data of the reply

QLab will do its best to create a reply message with the format you specify.

Sending an empty string will reset QLab’s reply format to its default form.

Example

Let’s say you set QLab’s reply format with the following message:

/replyFormat “#data# #address#”

Then, if you sent /cue/1/colorName, you would get the reply:

green /cue/1/colorName

The #data# token resolves to green, assuming the color of cue 1 is in fact green, and the #address# token resolves to /cue/1/colorName, since that was the address portion of the OSC command that you sent.

/timecodeWindow {boolean}

Read: If no argument is given, return the current visibility of the Timecode Window.

Write: Show or hide the Timecode Window. See details on booleans at the beginning of this section.

/toggleTimecodeWindow

Show or hide the Timecode Window.

/udpReplyPort {number}

Read: If no argument is given, return the port number that QLab is using to send UDP messages to the sender.

Write: Set the port number on which the sender wants to receive UDP messages to number. number must be an integer from 0 to 65535. Sending 0 resets the port number to the default of 53001.

/updates {boolean}

Read: If no argument is given, return the current subscription status for this client.

Write: Subscribe or unsubscribe to updates from QLab. See details on booleans at the beginning of this section.

/version

Return QLab’s version number.

/workingDirectory {path}

Read: If no argument is given, return the current working directory, which is the directory that appears in Open or Save dialogue boxes.

Write: If path is provided, set the current working directory to path. You can provide two kinds of paths:

• Full paths, e.g. /a/full/path/to/some/directory/
• Paths beginning with a tilde, e.g. ~/a/path/to some/directory

Paths beginning with a tilde (~) will be expanded; the tilde signifies “relative to the user’s home directory.”

This message provides direct access to the macOS working directory command and therefore might seem to behave strangely to those who have not dealt with the inner workings of how macOS apps open and save things. If in doubt, you can consider this message to only really matter if you are opening or saving via OSC messages. If you are, you should try to set the working directory explicitly via OSC before trying to open or save via OSC.

/workspaces

Return an array of dictionaries for each open workspace. Each dictionary looks like this:

[
    {
        "uniqueID": string,
        "displayName": string,
        "port": number,
        "udpReplyPort": number,
        "version": string
    }
]

Workspace messages

Workspace OSC messages use the form /workspace/{id}/command, where {id} may be either the display name of the workspace, such as hamlet.qlab5, or the unique ID of the workspace, which can be found in the Info tab of the Workspace Status Window.

Note, however, that addressing by display name will work only if the display name is composed of characters allowed in OSC method names. This does NOT include spaces, unicode characters, diacriticals, or other “special” characters.

Addressing a workspace by its unique ID looks like this:

/workspace/1B11984A-3EBC-4A9C-A004-B9E3AA32DA6B/go

Addressing a workspace by its display name looks like this:

/workspace/hamlet/go

Note that the extension of the filename, the .qlab5 part, is omitted.

If you send a workspace message without the /workspace/{id} portion of the address, then the message will be sent to all open workspaces listening on the port to which the message is sent. So, if your hamlet.qlab5 workspace is the only open workspace, or the only workspace listening to a particular port, and you send QLab the OSC command /go to that port, then hamlet.qlab5 will GO. If both hamlet.qlab5 and twelfthnight.qlab5 are open and listening to the same port, sending the OSC command /go to that port will cause both workspaces to GO.

/workspace/{id}/alwaysAudition {boolean}

Read: If no argument is given, return true if the specified workspace is set to always audition or false if not.

Write: Turn always audition on or off for the specified workspace. See details on booleans at the beginning of this section.

/workspace/{id}/auditionMonitors {boolean}

Read: If no argument is given, return true if all audition monitor windows for the specified workspace are open or false if at least one audition monitor window is closed.

Write: Show or hide all audition monitor windows for the specified workspace. See details on booleans at the beginning of this section.

/workspace/{id}/toggleAuditionMonitors

Show or hide all audition monitor windows for the specified workspace.

/workspace/{id}/basePath

Return a string which is the path to the directory containing the QLab workspace. If the workspace is not yet saved, this will be an empty string.

/workspace/{id}/connect {passcode_string}

Connect to the specified workspace. {passcode_string} is optional; if it is not sent, the client will connect to the workspace with whatever permissions have been set for OSC connections without passcodes. If the workspace has no permissions enabled for passcode-less connections, then connecting without a passcode is not possible.

If connecting to a workspace using a passcode, you must supply it before any other OSC messages will be accepted by the workspace or the cues it contains.

Returns ok if the supplied passcode matches a passcode entry in the workspace.

Returns badpass if the passcode does not match any passcode entries in the workspace.

Returns error if the specified workspace does not exist or is not open.

Starting with QLab 5, repeatedly sending this message with incorrect passcodes will introduce a progressively longer delay until the next /connect message will be accepted. This helps to protect against unauthorized users attempting to guess the passcode.

/workspace/{id}/cueLists

/workspace/{id}/selectedCues

/workspace/{id}/runningCues

/workspace/{id}/runningOrPausedCues

Return an array of cue dictionaries listing the following information about all cues that fall within the scope of the message:

[
    {
        "uniqueID": string,
        "number": string
        "name": string
        "listName": string
        "type": string
        "colorName": string
        "colorName/live": string
        "flagged": number
        "armed": number
    }
]

The scope of each message is as follows:

• cueLists are all cue lists and carts which appear in the sidebar.
• selectedCues are all cues which are currently selected.
• runningCues are all cues which are currently running (visible in Active Cues, and with an elapsing duration.)
• runningOrPausedCues are all cues which are currently visible in Active Cues, whether or not their duration is elapsing.

If any of the included cues are Group cues, the dictionary will include an array of cue dictionaries for all children in the group:

[
    {
        "number": "{string}",
        "uniqueID": {string},
        "cues": [ {a cue dictionary}, {another dictionary}, {and another} ],
        "flagged": true|false,
        "listName": "{string}",
        "type": "{string}",
        "colorName": "{string}",
        "colorName/live": "{string}",
        "name": "{string}",
        "armed": true|false,
    }
]

Note: These messages may generate large replies, which can easily be larger than the maximum size supported by UDP datagrams. You should communicate with QLab via a TCP connection if you wish to use these messages.

Starting with QLab 4.4.3, versions of these commands are available which return smaller amounts of data.

The following messages are identical to the similar messages above, except they do not include any data for the children of Group cues:

/cueLists/shallow

/selectedCues/shallow

/runningCues/shallow

/runningOrPausedCues/shallow

The following messages return only the cue IDs of the cues in question, and not all the other information about them. Cue IDs of children of Group cues are included.

/cueLists/uniqueIDs

/selectedCues/uniqueIDs

/runningCues/uniqueIDs

/runningOrPausedCues/uniqueIDs

The following messages return only the cue IDs of the cues in question, and do not include children of Group cues.

/cueLists/uniqueIDs/shallow

/selectedCues/uniqueIDs/shallow

/runningCues/uniqueIDs/shallow

/runningOrPausedCues/uniqueIDs/shallow

/workspace/{id}/currentCueList {string}

Read: If no argument is provided, return the cue number of the current cue list or cart of the specified workspace.

Write: Set the current cue list or cart of the specified workspace to string. string must be the cue number of a cue list or cart in the workspace.

/workspace/{id}/currentCueListID {string}

Read: If no argument is provided, return the cue ID of the current cue list or cart of the specified workspace.

Write: Set the current cue list or cart of the specified workspace to string. string must be the cue ID of a cue list or cart in the workspace.

/workspace/{id}/dashboard/clear

Clear all modifications made in the Dashboard and set all parameters of all lights to their home value. Parked parameters are not affected. Please be aware that this generally causes a blackout. This message is the QLab equivalent of what many other consoles refer to as “Go To Cue out.”

/workspace/{id}/dashboard/mode {string}

Read: If no argument is provided, this message has no effect.

Write: Set the Dashboard’s view mode to string. Supported modes are sliders and tiles.

/workspace/{id}/dashboard/newCueWithAll

Record all current light levels into a new Light cue. Parameters which have no explicit level set will be recorded at their home value.

/workspace/{id}/dashboard/newCueWithChanges

Record all manually adjusted light levels in the Dashboard into a new Light cue. Parameters which have not been manually adjusted will not be recorded.

/workspace/{id}/dashboard/nextMode

Toggle between “sliders” and “tiles” view modes in the Dashboard.

/workspace/{id}/dashboard/recordAllToLatest

Record all manually adjusted light levels in the Dashboard into the latest-run Light cue, overwriting any levels already in that cue. If no levels have been manually adjusted, or Light cues have been run and no cue is displayed in the Dashboard as the latest Light cue, this message has no effect.

/workspace/{id}/dashboard/recordAllToSelected

Record all manually adjusted light levels in the Dashboard into the currently selected Light cue or cues, overwriting any levels already in those cues. If no levels have been adjusted, or there are no currently selected Light cues, this message has no effect.

/workspace/{id}/dashboard/redo

Redo the last un-done action taken in the Dashboard. If nothing has been un-done in the Dashboard, this message has no effect.

/workspace/{id}/dashboard/revert

Revert all manually adjusted light levels in the Dashboard to the levels that they held before they were adjusted. If no levels have been adjusted, this message has no effect.

/workspace/{id}/dashboard/setLight {string} {setting} {time}

/workspace/{id}/dashboard/setLight/{string} {setting} {time}

/workspace/{id}/dashboard/setLight/live {string} {setting} {time}

/workspace/{id}/dashboard/setLight/{string}/live {setting} {time}

Set instrument or light group string to level setting in the Dashboard. string may include a parameter name; if it does not, the default parameter for the specified instrument or light group will be addressed.

setting must be an acceptable value for the specified parameter of the specified instrument or group. If setting is a decimal number, the Light Dashboard may round it to the nearest equivalent DMX value.

time is an optional whole or decimal number. If provided, the parameter will be faded from its current value to level over that many seconds. If time is omitted, it will be assumed to be 0.0 seconds.

Examples

/dashboard/setLight frontlight 50 5 sets the default parameter of the light or group called “frontlight” to 50, fading from its current level over 5 seconds.

/dashboard/setLight myMover.cyan 75 sets the cyan parameter of the light or group called “myMover” to 75 immediately.

/dashboard/setLight/6 25 sets the default parameter of the light or group called “6” to 25 using the single-argument form of this OSC message.

/dashboard/setLight myMover.pantilt pantilt(20,30) sets the pantilt virtual parameter of the light or group called “myMover” to pan 20, tilt 30.

/workspace/{id}/dashboard/undo

Un-does the last action taken in the Dashboard. If nothing has been done in the Dashboard, this message has no effect.

/workspace/{id}/dashboard/updateLatestCue

Copy all manually adjusted light levels into the latest Light cue. If the adjusted levels belong to lights or groups that are already in the latest cue, QLab will overwrite those levels. If not, QLab will add them and leave everything else alone. If no Light cues have been run, and no cue is displayed to the left as the latest Light cue, this message has no effect.

/workspace/{id}/dashboard/updateOriginatingCues

Copy all manually adjusted light levels into the cue or cues which originated their current levels. Originating cues are discussed in detail in the page on Light Dashboard in the Lighting section of this documentation.

/workspace/{id}/dashboard/updateSelectedCues

Copy all manually adjusted light levels into the currently selected Light cue or cues. If the adjusted levels belong to lights or groups that are already in the selected cue or cues, QLab will overwrite those levels. If not, QLab will add them and leave everything else alone. If there are no currently selected Light cues, this message has no effect.

/workspace/{id}/delete/{cue_number}

/workspace/{id}/delete_id/{cue_id}

/workspace/{id}/delete/selected

Delete the specified cue(s).

/workspace/{id}/delete/active

Delete all cues that are currently running or paused.

/workspace/{id}/doubleGoWindowRemaining

When workspace “double go protection” is engaged, return the number of seconds that must elapse until the next GO is permitted. Returns 0 when a GO is currently allowed or if double go protection is not enabled.

/workspace/{id}/fullScreen {boolean}

Read: If no argument is provided, return the current full screen status of the workspace.

Write: Set the full screen mode status of the main workspace window. true will switch the main workspace window into macOS’ full screen mode; false will switch the main workspace window into regular window mode.

/workspace/{id}/toggleFullScreen

Turn full screen mode on or off for the main workspace window.

/workspace/{id}/go {cue_number}

If no cue_number is given, tell the current list of the given workspace to GO.

If cue_number is given and matches the cue number of a list in the given workspace, tell that list to GO.

If cue_number is given and matches the cue number of a cue in any list in the given workspace, jump the playhead to that cue and then GO.

If cue_number is given and either does not match the cue number of a cue in any list, or matches the cue number of a cue in a cart, this message has no effect. (Cue carts do not have a playback position, so GO means nothing to a cart. Use /start instead.)

cue_number is optional; if given, it must be a string and must match a cue number in the given workspace. QLab will jump to the specified cue and then GO. If no argument is provided, the current cue list in the given workspace will GO on whatever cue is currently standing by.

When handling this OSC message, QLab cannot use the same technique it uses in other places to turn numbers into strings when necessary. This is why cue_number, if given, must be a string. If you’re sending the message from QLab, the way to ensure that a number is sent as a string is to enclose the argument in quotation marks.

• Correct: /go
• Correct: /go "53"
• Incorrect: /go 53

Other OSC-sending devices or programs will have their own ways to specify an argument as a string.

/workspace/{id}/go/{cue_number}

This message is equivalent to the above /go command, except here cue_number is part of the address, not an argument, and is not optional. Since it’s part of the address, it should not include quotation marks as discussed above.

/workspace/{id}/auditionGo {cue_number}

/workspace/{id}/auditionGo/{cue_number}

These messages are equivalent to the above /go commands, except they trigger an audition GO instead of a regular GO. Audition GO causes the cue or cues which are started to play through their audition outputs, defined in Workspace Settings.

/workspace/{id}/hardStop

Stop all playback and cut all audio effects immediately.

/workspace/{id}/liveFadePreview {boolean}

Enable or disable live fade preview. See details on booleans at the beginning of this section. If no argument is given, return the current status of live fade preview.

/workspace/{id}/toggleLiveFadePreview

Enable or disable live fade preview.

/workspace/{id}/lightDashboard {boolean}

Read: If no argument is given, return the current visibility of the Dashboard.

Write: Show or hide the Light Dashboard. See details on booleans at the beginning of this section.

/workspace/{id}/toggleLightDashboard

If the Light Dashboard is closed, open it and place focus in the command line. If the Light Dashboard is open, but focus is not in the command line, place focus in the command line. If the Light Dashboard is open and focus is in the command line, move focus to the main workspace window.

/workspace/{id}/move/{cue_id} {new_index} {new_parent_cue_id}

new_parent_cue_id is optional, and must be a string.

If new_parent_cue_id is not provided, move the specified cue (cue_id) from its current position to the given new_index position within the cue’s current parent Group, Cart, or List. new_index is required and must be an integer.

If new_parent_cue_id is provided, move the specified cue from its current position to the given new_index position within the Group, Cart, or List whose unique ID is new_parent_cue_id.

If the move fails for any reason (i.e. a Group cue cannot be moved inside of another Group cue that it already contains), QLab will send an error reply.

If the move succeeds, QLab will reply with "status": "ok" and "data" containing a dictionary with 2 key/value pairs:

[
    {
        "parent_cue_id": string,
        "index": integer
    }
]

parent_cue_id is a string with the unique ID of the Group, Cart, or List that contains the cue that was moved. index is an integer with the index of the position of the moved cue in its new parent.

/workspace/{id}/new {cue_type}

Create a new cue. cue_type is a string stating the type of cue to create. Supported strings include: audio, mic, video, camera, text, light, fade, network, midi, midi file, timecode, group, start, stop, pause, load, reset, devamp, goto, target, arm, disarm, wait, memo, script, list, cuelist, cue list, cart, cuecart, or cue cart.

This method returns the unique ID of the new cue. The newly created cue will also be selected, so subsequent commands can address the new cue either using the unique ID or simply by addressing the currently selected cue.

This method has three optional additional arguments:

/workspace/{id}/new {cue_type} {cue_ID} {cart_row} {cart_column}

If {cue_ID} is supplied, the new cue will be created after that cue.

If {cue_ID} specifies a cart, the new cue will be created within the cart. You must then specify the position in the cart using {cart_row} and {cart_column}, which must be integers.

/workspace/{id}/panic

Tell the workspace to panic. A panic is a brief gradual fade out leading into a hard stop. Sending a second instruction to panic during that gradual fade out will cause an immediate hard stop.

/workspace/{id}/panicInTime {number}

Panic over the specified time, rather than over the panic time defined in the workspace. {number} can be any number 0 or greater, decimals allowed.

/workspace/{id}/pause

Pause all currently running cues in the workspace.

/workspace/{id}/playhead/{cue_number}

/workspace/{id}/playheadID/{cue_id}

/workspace/{id}/playbackPosition/{cue_number}

/workspace/{id}/playbackPositionID/{cue_id}

Set the playhead (also called the playback position) of the active cue list to the given cue. When using /playheadID or /playbackPositionID, sending the value none will unset the playhead.

/workspace/{id}/playhead/active

Move the playhead (also called the playback position) of the active cue list to the first active cue.

/workspace/{id}/playhead/next

/workspace/{id}/playbackPosition/next

Move the playhead (also called the playback position) of the active cue list to the next cue.

/workspace/{id}/playhead/previous

/workspace/{id}/playbackPosition/previous

Move the playhead (also called the playback position) of the active cue list to the previous cue.

/workspace/{id}/playhead/nextSequence

/workspace/{id}/playbackPosition/nextSequence

Move the playhead (also called the playback position) of the active cue list to the next cue sequence.

/workspace/{id}/playhead/previousSequence

/workspace/{id}/playbackPosition/previousSequence

Move the playhead (also called the playback position) of the active cue list to the previous cue sequence.

/workspace/{id}/playhead/selected

Move the playhead (also called the playback position) of the active cue list to the first selected cue.

/workspace/{id}/redo

Redo the last un-done action in the workspace. If nothing has been un-done in the workspace, this message has no effect.

/workspace/{id}/renumber {startNumber} {incrementNumber} {prefix} {suffix}

Renumber the selected cues, starting at startNumber and incrementing by incrementNumber. Both numbers must be a positive number, decimals allowed. prefix and suffix are both optional and can be any text.

/workspace/{id}/reset

Reset the workspace. Resetting stops all cues, returns the playhead to the top of the current cue list, and restores any temporary changes made to cues (such as retargeting via a Target cue or adjustments using a “live” OSC message.)

/workspace/{id}/resume

Un-pause all paused cues in the workspace.

/workspace/{id}/save

Tell the given workspace to save itself to disk.

/workspace/{id}/select/{cue_number}

/workspace/{id}/select_id/{id}

Select the specified cue(s).

/workspace/{id}/select/next

Move the selection down one cue.

/workspace/{id}/select/previous

Move the selection up one cue.

/workspace/{id}/showMode {boolean}

Read: If no argument is provided, return true if the workspace is currently in show mode, and false if the workspace is currently in edit mode.

Write: If boolean is true, set the workspace to show mode. If false, set the workspace to edit mode. See details on booleans at the beginning of this section.

/workspace/{id}/toggleEditShowMode

Switch between show mode and edit mode.

/workspace/{id}/stop

Stop playback but allow audio effects which decay over time (for example, reverbs) to continue rendering.

/workspace/{id}/thump

Returns a string thump. This is a simple “heartbeat” message (thump-thump, thump-thump) which you can use to verify a connection, keep a session active, etc.

/workspace/{id}/undo

Undo the most recent change in the workspace. If there is no valid action to undo, this message has no effect.

Workspace Settings messages

Workspace Settings OSC messages use the form /workspace/{id}/settings/command, where {id} may be either the display name of the workspace, such as hamlet.qlab5, or the unique ID of the workspace, which can be found in the Info tab of the Workspace Status Window.

Note, however, that addressing by display name will work only if the display name is composed of characters allowed in OSC method names. This does NOT include spaces, unicode characters, diacriticals, or other “special” characters.

Addressing a workspace by its unique ID looks like this:

/workspace/1B11984A-3EBC-4A9C-A004-B9E3AA32DA6B/settings/light/patch

Addressing a workspace by its display name looks like this:

/workspace/hamlet/settings/light/patch

Note that the extension of the filename, the .qlab5 part, is omitted.

If you send a workspace message without the /workspace/{id} portion of the address, then the message will be sent to all open workspaces listening on the port to which the message is sent. So, if your hamlet.qlab5 workspace is the only open workspace, or the only workspace listening to a particular port, and you send QLab the OSC command /light/patch to that port, then hamlet.qlab5 will receive that message and respond appropriately. If both hamlet.qlab5 and twelfthnight.qlab5 are open and listening to the same port, sending the OSC command /light/patch to that port will cause both workspaces to respond appropriately.

/settings/audio/cueOutputChannelCounts

Return a JSON dictionary of cue output counts for audio output patches:

[
  {
    "{patch uniqueID}":{number of cue outputs},
    "{another patch uniqueID}":{number of cue outputs},
    et cetera...
  }
]

The number of patches in a workspace varies, so the number of items in this dictionary will vary.

/settings/audio/maxVolume

/settings/audio/minVolume

Return the decibel value of the “Min:” and “Max:” levels from the Volume Limits section of Workspace Settings → Audio.

/settings/audio/outputChannelNames

/settings/mic/outputChannelNames

Return a JSON dictionary of output names for audio output patches:

[
  {
    "{patch uniqueID}" :
      {
        "{cue output number}": "{output name}",
        "{another cue output number}": "{another output name}",
        et cetera...
      }
  },
  { ... }
]

{ ... } represents a second audio patch; the number of patches in a workspace varies, so the number of items in this dictionary will vary.

If an audio output patch does not have customized output names, that patch will not be included in the dictionary. If no audio output patches have customized output names, the data returned will be an empty JSON object.

The /mic form of this message is deprecated in QLab 5.0. This message works in QLab 5, but will be removed in a future version of QLab. Use the /audio form instead.

/settings/audio/patch/{name}

/settings/audio/patchID/{id}

Return a JSON dictionary describing the specified audio output patch.

[
  {
    "name" : "{string}",
    "uniqueID" : "{string}",
    "routing" : [number,number,number,...]
  }
]

The numbers listed for routing are the device output numbers which have cue outputs routed to them. For example, if the patch is using a device with four outputs, and all four device outputs have cue outputs routed to them, the list will be [1,2,3,4]. If device output 3 has no cue outputs routed to it, the list will be [1,2,4].

/settings/audio/patch/{name}/cueOutputChannels {number}

/settings/audio/patchID/{id}/cueOutputChannels {number}

Read: If no argument is given, return the number of cue outputs of the specified patch.

Write: If number is given, set the number of cue outputs of the specified patch to number, which must be a whole number from 1 to 128.

/settings/audio/patch/{name}/level/{inChannel}/{outChannel} {decibel}

/settings/audio/patch/{name}/level/{inChannel}/{outChannel}/live {decibel}

/settings/audio/patchID/{id}/level/{inChannel}/{outChannel} {decibel}

/settings/audio/patchID/{id}/level/{inChannel}/{outChannel}/live {decibel}

Read: If no argument is given, return the volume level of the specified crosspoint.

Write: If decibel is given, set the specified crosspoint to decibel. decibel can be any number, decimals allowed, or a string such as -inf. If decibel is a string (any string, in fact) QLab will set the crosspoint to -inf.

/settings/audio/patch/{name}/mute {output} {boolean}

/settings/audio/patch/{name}/mute/{output} {boolean}

/settings/audio/patchID/{id}/mute {output} {boolean}

/settings/audio/patchID/{id}/mute/{output} {boolean}

Read: If no argument is given, return TRUE if the device output of the specified patch is muted, or FALSE if it is not.

Write: Mute or unmute the specified device output of the specified patch. See details on booleans at the beginning of this section.

/settings/audio/patch/{name}/mute/clear

/settings/audio/patchID/{id}/mute/clear

Un-mute all device outputs of the specified patch.

/settings/audio/patch/{name}/muteChannels

/settings/audio/patchID/{id}/muteChannels

Return an array of the numbers of device outputs that are muted.

/settings/audio/patch/{name}/name {string}

/settings/audio/patchID/{id}/name {string}

Set the name of the specified patch to string.

/settings/audio/patch/{name}/reset

/settings/audio/patchID/{id}/reset

Reset all faded parameters of the specified audio patch (cue output effects, routing, and device output effects) to their saved state.

/settings/audio/patch/{name}/routing

/settings/audio/patchID/{id}/routing

Return the device output numbers which have cue outputs routed to them. For example, if the patch is using a device with four outputs, and all four device outputs have cue outputs routed to them, the list will be [1,2,3,4]. If device output 3 has no cue outputs routed to it, the list will be [1,2,4].

/settings/audio/patch/{name}/routing/reset

/settings/audio/patchID/{id}/routing/reset

Reset faded audio levels of the specified audio patch to their saved state.

/settings/audio/patch/{name}/solo {output} {boolean}

/settings/audio/patch/{name}/solo/{output} {boolean}

/settings/audio/patchID/{id}/solo {output} {boolean}

/settings/audio/patchID/{id}/solo/{output} {boolean}

Read: If no argument is given, return TRUE if the device output of the specified patch is soloed, or FALSE if it is not.

Write: Solo or un-solo the specified device output of the specified patch. See details on booleans at the beginning of this section.

/settings/audio/patch/{name}/solo/clear

/settings/audio/patchID/{id}/solo/clear

Un-solo all device outputs of the specified patch.

/settings/audio/patch/{name}/soloChannels

/settings/audio/patchID/{id}/soloChannels

Return an array of the numbers of device outputs that are soloed.

/settings/audio/patch/{name}/uniqueID

/settings/audio/patchID/{id}/uniqueID

Return the unique ID of the specified audio output patch.

/settings/audio/patchList

Return a JSON dictionary describing all audio output patches defined in the workspace:

[
  {
    "name" : "{string}",
    "uniqueID" : "{string}", 
    "routing" : [number,number,number,...]
  },
  { ... }
]

The numbers listed for routing are the device output numbers which have cue outputs routed to them. For example, if the patch is using a device with four outputs, and all four device outputs have cue outputs routed to them, the list will be [1,2,3,4]. If device output 3 has no cue outputs routed to it, the list will be [1,2,4].

If an audio output patch does not have a name, QLab will use the name of the audio device assigned to that patch as its name.

/settings/audio/undo

Undo the most recent change in the Audio section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/audio/redo

Redo the most recent un-done change in the Audio section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/general/minGoTime {number}

Read: If number is not given, return the minimum time required between each GO (a.k.a. “double GO protection time” or “minimum GO time.“)

Write: Set the minimum time required between each GO to number seconds. number can be any number greater than or equal to 0, decimals allowed.

/settings/general/selectionIsPlayhead {boolean}

Read: If no argument is provided, return true if the selection is currently locked to the playhead, and false if it is not.

Write: If boolean is true, lock the selection and the playhead together. If boolean is false, unlock the selection from the playhead.

/settings/general/toggleSelectionIsPlayhead

Lock or unlock the selection to the playhead.

/settings/general/undo

Undo the most recent change in the General section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/general/redo

Redo the most recent un-done change in the General section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/light/patch

Return a (rather verbose) JSON dictionary describing the light patch for the workspace:

{
  "settingKeywords":[
    "home",
    "pass",
    "cue"
  ],
  "groups":[
    {
          "instruments":[
            {
              "conflicted":true|false,
              "patched":true|false,
              "name":"{instrument name}",
              "definition":{
                "isBroken":true|false,
                "manufacturer":"{manufacturer name}",
                "defaultParameter":{number of default parameter},
                "name":"{definition name}",
                "definitionVersion":{version of definition},
                "parameters":{
                  "{parameter number}":{
                    "isBroken":true|false,
                    "homeValue":{value},
                    "valueIsPercentage":true|false,
                    "name":"{parameter name}",
                    "type":"scalar"|"pantilt"|"rgbcolor"|"cmycolor"|"muxer",
                    "twoBytes":true|false
                  },
                  (more parameters as needed...)
                }
              },
              "parameters":[
                {
                  "valueIsPercentage":true|false,
                  "homeValueInDMX":{value},
                  "twoBytes":true|false,
                  "uniqueName":"{instrument name}.{parameter name}",
                  "definitionParameter":{
                    "isBroken":true|false,
                    "homeValue":{value},
                    "valueIsPercentage":true|false,
                    "name":"{parameter name}",
                    "type":"scalar"|"pantilt"|"rgbcolor"|"cmycolor"|"muxer",
                    "twoBytes":true|false
                  },
                  "instrumentName":"{instrument name}",
                  "homeValue":{value},
                  "name":"{parameter name}"
                },
                (more parameters as needed...)
              ]
            },
            (more instruments as needed...)
          ],
          "name":"{light group name}",
          "members":[
            {"name":"{instrument name"},
            (more instruments as needed...)
          ],
          "parameters":[
            {
              "isBroken":true|false,
              "homeValue":{value},
              "valueIsPercentage":true|false,
              "name":"{parameter name}",
              "type":"scalar"|"pantilt"|"rgbcolor"|"cmycolor"|"muxer",
              "twoBytes":true|false
            },
            (more parameters as needed...)
          ]
        },
    (more groups as needed...)
  ],
  "instruments":[
    {
          "conflicted":true|false,
          "patched":true|false,
          "name":"{instrument name}",
          "definition":{
            "isBroken":true|false,
            "manufacturer":"{manufacturer name}",
            "defaultParameter":{number of default parameter},
            "name":"{definition name}",
            "definitionVersion":{version of definition},
            "parameters":{
              "{parameter number}":{
                "isBroken":true|false,
                "homeValue":{value},
                "valueIsPercentage":true|false,
                "name":"{parameter name}",
                "type":"scalar"|"pantilt"|"rgbcolor"|"cmycolor"|"muxer",
                "twoBytes":true|false
              },
              (more parameters as needed...)
            }
          },
          "parameters":[
            {
              "valueIsPercentage":true|false,
              "homeValueInDMX":{value},
              "twoBytes":true|false,
              "uniqueName":"{instrument name}.{parameter name}",
              "definitionParameter":{
                "isBroken":true|false,
                "homeValue":{value},
                "valueIsPercentage":true|false,
                "name":"{parameter name}",
                "type":"scalar"|"pantilt"|"rgbcolor"|"cmycolor"|"muxer",
                "twoBytes":true|false
              },
              "instrumentName":"{instrument name}",
              "homeValue":{value},
              "name":"{parameter name}"
            },
            (more parameters as needed...)
          ]
        },
    (more instruments as needed...)
  ]
}

/settings/light/undo

Undo the most recent change in the Light section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/light/redo

Redo the most recent un-done change in the Light section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/mic/patchList

Return a JSON dictionary describing all audio input patches defined in the workspace:

[
  {
    "uniqueID" : "{string}", 
    "name" : "{string}",
  },
  { ... }
]

If an audio input patch does not have a name, QLab will use the name of the audio device assigned to that patch as its name.

NOTE: The /mic form of this message is changed in QLab 5.0 to list audio input patches. For output patches, use the /audio form instead.

/settings/mic/undo

Undo the most recent change in the Mic section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/mic/redo

Redo the most recent un-done change in the Mic section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/midi/patchList

Return a JSON dictionary describing all MIDI patches defined in the workspace:

[
  {
    "uniqueID" : string, 
    "name" : string
  },
  { ... }
]

{...} represents a second MIDI patch; the number of patches in a workspace varies, so the number of items in this dictionary will vary.

/settings/midi/undo

Undo the most recent change in the MIDI section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/midi/redo

Redo the most recent un-done change in the MIDI section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/network/patchList

Return a JSON dictionary describing all network patches defined in the workspace:

[
  {
    "uniqueID" : string, 
    "name" : string
  },
  { ... }
]

{...} represents a second network patch; the number of patches in a workspace varies, so the number of items in this dictionary will vary.

/settings/network/undo

Undo the most recent change in the Network section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/network/redo

Redo the most recent un-done change in the Network section of Workspace Settings. If there is no valid action to redo, this message has no effect.

/settings/video/inputPatchList

Return a JSON dictionary describing all video input patches defined in the workspace:

[
  {
    "uniqueID" : string, 
    "name" : string
  },
  { ... }
]

{...} represents a second video input patch; the number of patches in a workspace varies, so the number of items in this dictionary will vary.

/settings/video/routes

Return a JSON dictionary describing all video output routes defined in the workspace:

{
  "enableGuides":true|false,
  "destinationInfo":
  {
    "name":"Name of video device",
    "destinationType":
    "videoOutputKeyPath":"screen.screenID.1", -- macOS ID number of screen
    "videoOutputRasterSize":{"width":xxxx,"height":yyyy},
    "videoOutputRefreshRate":zzz -- frame rate in Hz
  },
  "rotationDegrees":0|90|180|270,
  "uniqueID":"some unique ID code",
  "scalingMode":0|1|2|3,
  "naturalSize":{"width":xxxx,"height":yyyy},
  "name":"Name of output route",
  "rear":true|false
},
{
  (more routes as needed...)
}

The contents of each destinationInfo dictionary will contain additional information which depends upon the type of output being described.

• Standard macOS-visible displays also have screenID and screenSerialNumber
• Blackmagic Designs devices also have deckLinkHandle, displayName, displayMode, displayModeInfo, and keyingMode
• NDI devices also have pixelSize, audioChannels, audioSampleRate, and audioBufferSize
• Syphon devices also have pixelSize

The displayModeInfo for Blackmagic Designs devices is itself a dictionary containing identifier, displayName, pixelDimensions, fpsDuration, fpsScale, and fieldDominance

/settings/video/route/{name}

/settings/video/routeIndex/{number}

/settings/video/routeID/{route_id}

Return a JSON dictionary describing the specified video output route.

Routes are zero-indexed, and the index order is the order in which the routes appear in Workspace Settings → Video → Output Routing.

/settings/video/route/{name}/enableGuides {boolean}

/settings/video/routeIndex/{number}/enableGuides {boolean}

/settings/video/routeID/{route_id}/enableGuides {boolean}

Read: If no argument is given, return the current visibility of the guides for the specified video output route.

Write: Set the visibility of the guides for the specified video output route to true or false. See details on booleans at the beginning of this section.

/settings/video/route/{name}/uniqueID

/settings/video/routeIndex/{number}/uniqueID

/settings/video/routeID/{route_id}/uniqueID

Return the unique ID of the specified video output route.

/settings/video/stages

Return a JSON dictionary describing all stages defined in the workspace:

{
  "uniqueID":"unique ID of stage",
  "name":"name of stage",
  "width":xxxx,
  "height":yyyy,
  "regions":[
    {
      "boundsOnStage":{"y":yyyy,"x":xxxx,"width":wwww,"height":hhhh},
      "meshWidth":number,
      "warpType":number,
      "uniqueID":"unique ID of region",
      "controlPoints":[
        {"x":xxx,"y":yyy},
        { mode control points as needed...}
      ],
      "name":"A",
      "meshHeight":number
    },
    { more regions as needed... }
  ]
},
{
  ( more stages as needed )
}

/settings/video/stage/{name}

/settings/video/stageID/{stage_id}

Return a JSON dictionary describing the specified stage.

/settings/video/stage/{current_name}/name {string}

/settings/video/stageID/{stage_id}/name {string}

Read: If no argument is given, return the name of the specified stage.

Write: If string is given, set the name of the specified stage to string.

/settings/video/stage/{name}/regions

/settings/video/stageID/{stage_id}/regions

Return a JSON dictionary describing the regions in the specified stage.

/settings/video/stage/{name}/size

/settings/video/stageID/{stage_id}/size

Return a JSON dictionary describing the size of the specified stage.

/settings/video/stage/{name}/size/height

/settings/video/stageID/{stage_id}/size/height

Return the height of the specified stage.

/settings/video/stage/{name}/size/width

/settings/video/stageID/{stage_id}/size/width

Return the width of the specified stage.

/settings/video/stage/{name}/uniqueID

/settings/video/stageID/{stage_id}/uniqueID

Return the unique ID of the specified stage.

/settings/video/stage/{name}/region/{name}

/settings/video/stage/{name}/regionID/{region_id}

/settings/video/stage/{name}/regionIndex/{index}

/settings/video/stageID/{stage_id}/region/{name}

/settings/video/stageID/{stage_id}/regionID/{region_id}

/settings/video/stageID/{stage_id}/regionIndex/{index}

Return a JSON dictionary describing the specified region.

/settings/video/stage/{name}/region/{name}/bounds {x} {y} {width} {height}

/settings/video/stage/{name}/region/{name}/bounds {string}

/settings/video/stage/{name}/regionID/{region_id}/bounds {x} {y} {width} {height}

/settings/video/stage/{name}/regionID/{region_id}/bounds {string}

/settings/video/stage/{name}/regionIndex/{index}/bounds {x} {y} {width} {height}

/settings/video/stage/{name}/regionIndex/{index}/bounds {string}

/settings/video/stageID/{stage_id}/region/{name}/bounds {x} {y} {width} {height}

/settings/video/stageID/{stage_id}/region/{name}/bounds {string}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds {x} {y} {width} {height}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds {string}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds {x} {y} {width} {height}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds {string}

Read: If no arguments are given, return a JSON dictionary describing the position, width, and height of the specified region.

Write: Set the position and size of the specified region. Arguments can be provided either as four separate numbers or as single string in the form "{{x,y}{width,height}}". In either case, all four numbers must be integers and must refer to a value within the bounds of the specified stage. x sets the horizontal position of the bottom left corner of the region, y sets the vertical position of the bottom left corner of the region, width sets the width of the region, and height sets the height of the region.

/settings/video/stage/{name}/region/{name}/bounds/origin {x} {y}

/settings/video/stage/{name}/region/{name}/bounds/origin {string}

/settings/video/stage/{name}/regionID/{region_id}/bounds/origin {x} {y}

/settings/video/stage/{name}/regionID/{region_id}/bounds/origin {string}

/settings/video/stage/{name}/regionIndex/{index}/bounds/origin {x} {y}

/settings/video/stage/{name}/regionIndex/{index}/bounds/origin {string}

/settings/video/stageID/{stage_id}/region/{name}/bounds/origin {x} {y}

/settings/video/stageID/{stage_id}/region/{name}/bounds/origin {string}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/origin {x} {y}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/origin {string}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/origin {x} {y}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/origin {string}

Read: If no arguments are given, return a JSON dictionary describing the position of the specified region.

Write: Set the position of the bottom left corner of the specified region. Arguments can be provided either as two separate numbers or as a single string in the form "{x,y}". In either case, both numbers must be integers and must refer to a value within the bounds of the specified stage. x sets the horizontal position of the bottom left corner of the region, and y sets the vertical position of the bottom left corner of the region.

/settings/video/stage/{name}/region/{name}/bounds/origin/x {number}

/settings/video/stage/{name}/regionID/{region_id}/bounds/origin/x {number}

/settings/video/stage/{name}/regionIndex/{regionIndex}/bounds/origin/x {number}

/settings/video/stageID/{stage_id}/region/{name}/bounds/origin/x {number}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/origin/x {number}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/origin/x {number}

Read: If no argument is given, return the horizontal position of the specified region.

Write: If number is given, set the horizontal position of the bottom left corner of the specified region to number. Number must be an integer and must refer to a value within the bounds of the specified stage.

/settings/video/stage/{name}/region/{name}/bounds/origin/y {number}

/settings/video/stage/{name}/regionID/{region_id}/bounds/origin/y {number}

/settings/video/stage/{name}/regionIndex/{regionIndex}/bounds/origin/y {number}

/settings/video/stageID/{stage_id}/region/{name}/bounds/origin/y {number}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/origin/y {number}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/origin/y {number}

Read: If no argument is given, return the vertical position of the specified region.

Write: If number is given, set the vertical position of the bottom left corner of the specified region to number. Number must be an integer and must refer to a value within the bounds of the specified stage.

/settings/video/stage/{name}/region/{name}/bounds/size {width} {height}

/settings/video/stage/{name}/region/{name}/bounds/size {string}

/settings/video/stage/{name}/regionID/{region_id}/bounds/size {width} {height}

/settings/video/stage/{name}/regionID/{region_id}/bounds/size {string}

/settings/video/stage/{name}/regionIndex/{index}/bounds/size {width} {height}

/settings/video/stage/{name}/regionIndex/{index}/bounds/size {string}

/settings/video/stageID/{stage_id}/region/{name}/bounds/size {width} {height}

/settings/video/stageID/{stage_id}/region/{name}/bounds/size {string}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/size {width} {height}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/size {string}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/size {width} {height}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/size {string}

Read: If no arguments are given, return a JSON dictionary describing the size of the specified region.

Write: Set the size of the specified region. Arguments can be provided either as two separate numbers or as a single string in the form "{width,height}". In either case, both numbers must be integers and must refer to a value within the bounds of the specified stage. width sets the width of the region, and y sets the height of the region.

/settings/video/stage/{name}/region/{name}/bounds/size/height {number}

/settings/video/stage/{name}/regionID/{region_id}/bounds/size/height {number}

/settings/video/stage/{name}/regionIndex/{index}/bounds/size/height {number}

/settings/video/stageID/{stage_id}/region/{name}/bounds/size/height {number}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/size/height {number}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/size/height {number}

Read: If no argument is given, return the height of the specified region.

Write: If number is given, set the height of the specified region to number. Number must be an integer and must refer to a value within the bounds of the specified stage.

/settings/video/stage/{name}/region/{name}/bounds/size/width {number}

/settings/video/stage/{name}/regionID/{region_id}/bounds/size/width {number}

/settings/video/stage/{name}/regionIndex/{index}/bounds/size/width {number}

/settings/video/stageID/{stage_id}/region/{name}/bounds/size/width {number}

/settings/video/stageID/{stage_id}/regionID/{region_id}/bounds/size/width {number}

/settings/video/stageID/{stage_id}/regionIndex/{index}/bounds/size/width {number}

Read: If no argument is given, return the width of the specified region.

Write: If number is given, set the width of the specified region to number. Number must be an integer and must refer to a value within the bounds of the specified stage.

/settings/video/stage/{name}/region/{name}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

/settings/video/stage/{name}/regionID/{region_id}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

/settings/video/stage/{name}/regionIndex/{index}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

/settings/video/stageID/{id}/region/{name}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

/settings/video/stageID/{id}/regionID/{region_id}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

/settings/video/stageID/{id}/regionIndex/{index}/subregionIndex/{index}/controlPointIndex/{index} {x} {y}

Read: If no arguments are given, return the coordinates of the specified control point.

Write: If x and y are given, set the coordinates of the specified control point to {x,y}. x and y must both be given together, must be integers, and must refer to a location within the bounds of the specified area.

/settings/video/stage/{name}/region/{name}/enableGrid {boolean}

/settings/video/stage/{name}/regionID/{region_id}/enableGrid {boolean}

/settings/video/stage/{name}/regionIndex/{index}/enableGrid {boolean}

/settings/video/stageID/{stage_id}/region/{name}/enableGrid {boolean}

/settings/video/stageID/{stage_id}/regionID/{region_id}/enableGrid {boolean}

/settings/video/stageID/{stage_id}/regionIndex/{index}/enableGrid {boolean}

Read: If no argument is given, return the current visibility of the grid for the specified region.

Write: Set the visibility of the grid for the specified region to true or false. See details on booleans at the beginning of this section.

/settings/video/stage/{name}/region/{name}/enableGuide {boolean}

/settings/video/stage/{name}/regionID/{region_id}/enableGuide {boolean}

/settings/video/stage/{name}/regionIndex/{index}/enableGuide {boolean}

/settings/video/stageID/{stage_id}/region/{name}/enableGuide {boolean}

/settings/video/stageID/{stage_id}/regionID/{region_id}/enableGuide {boolean}

/settings/video/stageID/{stage_id}/regionIndex/{index}/enableGuide {boolean}

Read: If no argument is given, return the current visibility of the guides for the specified region.

Write: Set the visibility of the guides for the specified region to true or false. See details on booleans at the beginning of this section.

/settings/video/stage/{name}/region/{name}/resetControlPoints

/settings/video/stage/{name}/regionID/{region_id}/resetControlPoints

/settings/video/stage/{name}/regionIndex/{index}/resetControlPoints

/settings/video/stageID/{stage_id}/region/{name}/resetControlPoints

/settings/video/stageID/{stage_id}/regionID/{region_id}/resetControlPoints

/settings/video/stageID/{stage_id}/regionIndex/{index}/resetControlPoints

Set all control points for the specified region to their default initial positions.

/settings/video/undo

Undo the most recent change in the Video section of Workspace Settings. If there is no valid action to undo, this message has no effect.

/settings/video/redo

Redo the most recent un-done change in the Video section of Workspace Settings. If there is no valid action to redo, this message has no effect.

Show Control Broadcast messages

Show control broadcast messages are sent by QLab in response to requests from clients. Clients request updates by sending a /listen message in one or more of the forms below. Every /listen message has a corresponding /ignore message which stops updates from being sent by QLab.

The format of these messages can be modified to suit individual needs using the /eventFormat message. You can read about this message and how to use it in the section on customizing OSC show control broadcast messages.

Show control broadcast messages require view access.

/listen

Requests all show control broadcast messages to be sent to the client.

/listen/auditionGo

Requests show control broadcast messages to be sent to the client for audition GO events only. Each audition GO event will result in four messages being sent:

• /qlab/event/workspace/auditionGo "{cue number}" "{cue name}" "{cue uniqueID}" "{cue type}"
• /qlab/event/workspace/auditionGo/number "{cue number}"
• /qlab/event/workspace/auditionGo/name "{cue name}"
• /qlab/event/workspace/auditionGo/uniqueID "{cue uniqueID}"

/listen/auditionGo/number

Requests show control broadcast messages to be sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue number}" form.

/listen/auditionGo/name

Requests show control broadcast messages to be sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue name}" form.

/listen/auditionGo/uniqueID

Requests show control broadcast messages to be sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue uniqueID}" form.

/listen/cue/start

Requests show control broadcast messages to be sent to the client for cue start events only. Each audition GO event will result in four messages being sent:

• /qlab/event/workspace/cue/start "{cue number}" "{cue name}" "{cue uniqueID}" "{cue type}"
• /qlab/event/workspace/cue/start/number "{cue number}"
• /qlab/event/workspace/cue/start/name "{cue name}"
• /qlab/event/workspace/cue/start/uniqueID "{cue uniqueID}"

/listen/cue/start/number

Requests show control broadcast messages to be sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/number "{cue number}" form.

/listen/cue/start/name

Requests show control broadcast messages to be sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/name "{cue name}" form.

/listen/cue/start/uniqueID

Requests show control broadcast messages to be sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/uniqueID "{cue uniqueID}" form.

/listen/cue/stop

Requests show control broadcast messages to be sent to the client for cue stop events only. Each audition GO event will result in four messages being sent:

• /qlab/event/workspace/cue/stop "{cue number}" "{cue name}" "{cue uniqueID}" "{cue type}"
• /qlab/event/workspace/cue/stop/number "{cue number}"
• /qlab/event/workspace/cue/stop/name "{cue name}"
• /qlab/event/workspace/cue/stop/uniqueID "{cue uniqueID}"

/listen/cue/stop/number

Requests show control broadcast messages to be sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/number "{cue number}" form.

/listen/cue/stop/name

Requests show control broadcast messages to be sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/name "{cue name}" form.

/listen/cue/stop/uniqueID

Requests show control broadcast messages to be sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/uniqueID "{cue uniqueID}" form.

/listen/go

Requests show control broadcast messages to be sent to the client for GO events only. Each GO event will result in four messages being sent:

• /qlab/event/workspace/go "{cue number}" "{cue name}" "{cue uniqueID}" "{cue type}"
• /qlab/event/workspace/go/number "{cue number}"
• /qlab/event/workspace/go/name "{cue name}"
• /qlab/event/workspace/go/uniqueID "{cue uniqueID}"

/listen/go/number

Requests show control broadcast messages to be sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue number}" form.

/listen/go/name

Requests show control broadcast messages to be sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue name}" form.

/listen/go/uniqueID

Requests show control broadcast messages to be sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue uniqueID}" form.

/listen/hardStopAll

Requests show control broadcast messages to be sent to the client for HardStop All events only.

/listen/panicAll

Requests show control broadcast messages to be sent to the client for Panic All events only.

/listen/pauseAll

Requests show control broadcast messages to be sent to the client for Pause All events only.

/listen/playhead

Requests show control broadcast messages to be sent to the client for playhead move events only. Each playhead move event will result in four messages being sent:

• /qlab/event/workspace/playhead "{cue number}" "{cue name}" "{cue uniqueID}" "{cue type}"
• /qlab/event/workspace/playhead/number "{cue number}"
• /qlab/event/workspace/playhead/name "{cue name}"
• /qlab/event/workspace/playhead/uniqueID "{cue uniqueID}"

/listen/playhead/number

Requests show control broadcast messages to be sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue number}" form.

/listen/playhead/name

Requests show control broadcast messages to be sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue name}" form.

/listen/playhead/uniqueID

Requests show control broadcast messages to be sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue uniqueID}" form.

/listen/resetAll

Requests show control broadcast messages to be sent to the client for Reset All events only.

/listen/resumeAll

Requests show control broadcast messages to be sent to the client for Resume All events only.

/listen/stopAll

Requests show control broadcast messages to be sent to the client for Stop All events only.

/ignore

Stops all show control broadcast messages from being sent to the client.

/ignore/auditionGo

Stops show control broadcast messages from being sent to the client for audition GO events only.

/ignore/auditionGo/number

Stops show control broadcast messages from being sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue number}" form.

/ignore/auditionGo/name

Stops show control broadcast messages from being sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue name}" form.

/ignore/auditionGo/uniqueID

Stops show control broadcast messages from being sent to the client for audition GO events only, and only in the /qlab/event/workspace/auditionGo/number "{cue uniqueID}" form.

/ignore/cue/start

Stops show control broadcast messages from being sent to the client for cue start events only.

/ignore/cue/start/number

Stops show control broadcast messages from being sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/number "{cue number}" form.

/ignore/cue/start/name

Stops show control broadcast messages from being sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/name "{cue name}" form.

/ignore/cue/start/uniqueID

Stops show control broadcast messages from being sent to the client for cue start events only, and only in the /qlab/event/workspace/cue/start/uniqueID "{cue uniqueID}" form.

/ignore/cue/stop

Stops show control broadcast messages from being sent to the client for cue stop events only.

/ignore/cue/stop/number

Stops show control broadcast messages from being sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/number "{cue number}" form.

/ignore/cue/stop/name

Stops show control broadcast messages from being sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/name "{cue name}" form.

/ignore/cue/stop/uniqueID

Stops show control broadcast messages from being sent to the client for cue stop events only, and only in the /qlab/event/workspace/cue/stop/uniqueID "{cue uniqueID}" form.

/ignore/go

Stops show control broadcast messages from being sent to the client for GO events only.

/ignore/go/number

Stops show control broadcast messages from being sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue number}" form.

/ignore/go/name

Stops show control broadcast messages from being sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue name}" form.

/ignore/go/uniqueID

Stops show control broadcast messages from being sent to the client for GO events only, and only in the /qlab/event/workspace/go/number "{cue uniqueID}" form.

/ignore/hardStopAll

Stops show control broadcast messages from being sent to the client for HardStop All events only.

/ignore/panicAll

Stops show control broadcast messages from being sent to the client for Panic All events only.

/ignore/pauseAll

Stops show control broadcast messages from being sent to the client for Pause All events only.

/ignore/playhead

Stops show control broadcast messages from being sent to the client for playhead move events only.

/ignore/playhead/number

Stops show control broadcast messages from being sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue number}" form.

/ignore/playhead/name

Stops show control broadcast messages from being sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue name}" form.

/ignore/playhead/uniqueID

Stops show control broadcast messages from being sent to the client for playhead move events only, and only in the /qlab/event/workspace/playhead/number "{cue uniqueID}" form.

/ignore/resetAll

Stops show control broadcast messages from being sent to the client for Reset All events only.

/ignore/resumeAll

Stops show control broadcast messages from being sent to the client for Resume All events only.

/ignore/stopAll

Stops show control broadcast messages from being sent to the client for Stop All events only.

Cue messages

Cue OSC messages use the form /workspace/{id}/cue/{cue_number}/command, where {id} may be either the display name of the workspace, such as hamlet.qlab5, or the unique ID of the workspace, which can be found in the Info tab of the Workspace Status Window.

Note, however, that addressing by display name will work only if the display name is composed of characters allowed in OSC method names. This does NOT include spaces, unicode characters, diacriticals, or other “special” characters.

Addressing a workspace by its unique ID looks like this:

/workspace/1B11984A-3EBC-4A9C-A004-B9E3AA32DA6B/cue/x/start

Addressing a workspace by its display name looks like this:

/workspace/hamlet/cue/x/start

Note that the extension of the filename, the .qlab5 part, is omitted.

If you send a cue message without the /workspace/{id} portion of the address, then the message will be sent to all open workspaces listening on the port to which the message is sent. So, if your hamlet.qlab5 workspace is the only open workspace, or the only workspace listening to a particular port, and you send QLab the OSC command /cue/x/start to that port, then cue x in the workspace called hamlet.qlab5 will start. If both hamlet.qlab5 and twelfthnight.qlab5 are open and listening to the same port, and both have a cue numbered x, then sending the OSC command /cue/x/start to that port will cause cue x in both workspaces to start.

Addressing Cues

Cues can be addressed either by their cue number or their unique ID. Cues always have a unique ID. They do not always have a number, but if it exists it will be unique within the workspace.

For all cue OSC messages, any instance of the address pattern /cue/{cue_number} can be replaced by the equivalent unique ID address pattern /cue_id/{id}.

Additionally, QLab supports a few special addresses for cues:

• /cue/selected addresses the currently selected cue or cues.
• /cue/playhead addresses the cue that’s currently standing by at the playhead.
• /cue/playbackPosition is the same as /cue/playhead.
• /cue/active addresses all active cues (currently playing or paused).

Finally, because QLab supports OSC address patterns, you may use an asterisk * and a question mark as wildcards within {cue_number} or {id}.

Examples

• /cue/*/armed 0 would disarm all cues in the workspace; * matches any character or characters.
• /cue/?/armed 0 would disarm all cues in the workspace with a single-character cue number; ? matches any single character.
• /cue/[*]/armed 0 would disarm only cues which have a cue number, and have no effect on cues which have no cue number.
• /cue/understudy-*/colorName green would set green as the display color for all cues that have a number that starts with the string “understudy-”.

Important: Spaces are not permitted inside OSC addresses, so cue numbers with spaces in them will not work properly with OSC. If you are using OSC to control your workspace, avoid using spaces in cue numbers.

/cue/{cue_number}/actionElapsed

Return the elapsed action (in seconds) of the specified cue.

/cue/{cue_number}/percentActionElapsed

Return the elapsed action (as a percentage of the total action) of the specified cue.

/cue/{cue_number}/allowsEditingDuration

Return true if the specified cue has an editable duration, such as an Audio, Video, or Fade cue. Otherwise, return false.

/cue/{cue_number}/armed {boolean}

Read: If no argument is given, return the armed state of the specified cue.

Write: If boolean is true, arm the specified cue. If false, disarm the specified cue. See details on booleans at the beginning of this section.

/cue/{cue_number}/auditionGo

Tell the specified cue to audition GO. Auditioning a cue starts it according to the audition behavior defined for its output type.

/cue/{cue_number}/auditionPreview

Audition preview the specified cue. Audition previewing a cue starts it according to the audition behavior defined for its output type, skipping over its pre-wait time, and does not advance the playhead. Also, if the cue has an auto-follow or auto-continue, the followed or continued cue is not started.

/cue/{cue_number}/autoLoad {boolean}

Read: If no argument is given, return the auto-load state of the specified cue.

Write: If boolean is true, set the specified cue to auto-load. If false, set the specified cue to not auto-load. See details on booleans at the beginning of this section.

/cue/{cue_number}/canHavePatchTargets

Return true if the specified cue can target a patch, such as a Fade or Reset cue. Otherwise, return false.

/cue/{cue_number}/captureTimecode

Set the timecode trigger time of the the specified cue to the currently incoming timecode. If there is no incoming timecode, this message has no effect.

/cue/{cue_number}/cartPosition/

Return an array with the row and column numbers for the specified cue’s position within a cart. A cue that is not contained within a cart will return [0,0].

/cue/{cue_number}/cartPosition/column

Return the column number for the specified cue’s position within a cart. A cue that is not contained within a cart will return 0.

/cue/{cue_number}/cartPosition/row

Return the row number for the specified cue’s position within a cart. A cue that is not contained within a cart will return 0.

/cue/{cue_number}/children/

If the specified cue is a list, cart, or Group cue, return an array of cue dictionaries listing the following information about all cues within the specified list, cart, or Group cue:

[
  {
    "number":"{string}",
    "uniqueID":"{string}",
    "cues":[ {a cue dictionary}, {another dictionary}, {and another} ],
    "flagged":true|false,
    "listName":"{string}",
    "type":"{string}",
    "colorName":"{string}",
    "colorName/live": "{string}",
    "name":"{string}",
    "armed":true|false
  },
  { ... }
]

The “cues” item is relevant only if the cue is a Group cue which contains other cues, in which case the “cues” item will contain cue dictionaries for each of the children of the enclosing Group cue. If any of those children are themselves Group cues, with their own children, then it’s Group turtles all the way down.

{…} represents a second cue dictionary; the number of cues within the specified list, cart, or Group cue will vary, so the number of items in this dictionary will vary.

If the specified cue is not a list, cart, or Group cue, this message will return an OSC reply containing an empty “data” field.

/cue/{cue_number}/children/shallow

This message behaves identically to the above message (/cue/{cue_number}/children) except that it omits the “cues” item, and therefore returns a smaller set of information. Nested Groups will not be queried, and so only the first “layer” of the cue hierarchy will be returned.

/cue/{cue_number}/children/uniqueIDs

If the specified cue is a list, cart, or Group cue, return an array of cue dictionaries listing the following information about all cues within the specified list, cart, or Group cue:

[
  {
    "uniqueID":"{string}",
    "cues":[ {a cue dictionary}, {another dictionary}, {and another} ]
  },
  { ... }
]

The “cues” item is relevant only if the cue is a Group cue which contains other cues, in which case the “cues” item will contain cue dictionaries which contain the uniqueID and cues for each of the children of the enclosing Group cue.

{…} represents a second cue dictionary; the number of cues within the specified list, cart, or Group cue will vary, so the number of items in this dictionary will vary.

/cue/{cue_number}/children/uniqueIDs/shallow

This message behaves identically to the above message (/cue/{cue_number}/children/uniqueIDs) except that it omits the “cues” item, and therefore returns a smaller set of information. Nested Groups will not be queried, and so only the first “layer” of the cue hierarchy will be returned.

/cue/{cue_number}/colorCondition {number}

Read: If no argument is given, return the color condition mode of the specified cue.

Write: If number is given, set the color condition mode of the specified cue to number. Valid color condition modes are:

0 - Always
1 - Before action
2 - After action

Removed in QLab 5.2. This message works in QLab 5.0.x and QLab 5.1.x only. In QLab 5.2 and later, use the /useSecondColor message instead.

/cue/{cue_number}/colorName {string}

/cue/{cue_number}/colorName/live {string}

Read: If no argument is given, return the color of the specified cue.

Write: If string is given, set the color of the specified cue to string. As of QLab 5.2, valid colors are:

berry
blue
crimson
cyan
forest
gray
green
hot pink
indigo
lavender
magenta
midnight
olive
orange
peach
plum
purple
red
sky blue
yellow

and

none

Certain other colors may also be valid…

/cue/{cue_number}/secondColorName {string}

/cue/{cue_number}/secondColorName/live {string}

Read: If no argument is given, return the second color of the specified cue.

Write: If string is given, set the second color of the specified cue to string.

/cue/{cue_number}/useSecondColor {boolean}

Read: If no argument is given, return the state of the Use second color lock button of the specified cue.

Write: Set the state of the Use second color lock button of the specified cue. See details on booleans at the beginning of this section.

/cue/{cue_number}/continueMode {number}

Read: If no argument is given, return the continue mode of the specified cue.

Write: If number is given, set the continue mode of the specified cue to number. Valid continue modes are:

0 - No continue
1 - Auto-continue
2 - Auto-follow

/cue/{cue_number}/cueTargetID {string}

Read: If no argument is given, return the cue ID of the target of the specified cue. Empty string ("") means that the cue has no cue target.

Write: If string is given, and if the specified cue can have cue targets, set the target of the specified cue to string. If string is "none" or empty (""), unset the cue target. If string is anything else, it must be a valid uniqueID of a cue in the workspace.

/cue/{cue_number}/cueTargetNumber {string}

Read: If no argument is given, return the cue number of the target of the specified cue. Empty string ("") means that the cue has no cue target.

Write: If string is given, and if the specified cue can have cue targets, set the target of the specified cue to string. string must be a valid cue number of a cue in the workspace.

/cue/{cue_number}/currentCueTarget

Return the cue ID of the current target of the specified cue. Empty string ("") means that the cue has no current target.

/cue/{cue_number}/tempCueTargetNumber {string}

Read: If no argument is given, and the specified cue has a temporary target, return the cue number of that temporary target. Empty string ("") means that the cue has no temporary target.

Write: If string is given, and if the specified cue can have cue targets, temporarily set the target of the specified cue to string. The specified cue will revert to its previous target if it is reset, if the workspace is reset, or if the workspace is closed and reopened. string must be a valid cue number of a cue in the workspace.

/cue/{cue_number}/tempCueTargetID {string}

This works exactly the same as /cueTargetID, but refers to the temporary target. See /tempCueTargetNumber for more detail about temporary targets.

/cue/{cue_number}/defaultName

Return the default name of the specified cue.

/cue/{cue_number}/displayName

Return the display name of the specified cue.

/cue/{cue_number}/duckLevel {number}

Read: If no argument is given, return the duck or boost level of the specified cue.

Write: If number is given, set the duck or boost level of the specified cue to number. If number is a negative number, it will set a duck level. If number is a positive number, it will set a boost level. number can be any number, decimals allowed, from -120 to 12.

NOTE: This message worked differently in QLab 4; it used a scaled range of 0 to 4, in which 0 = -120 dB, 1 = 0 dB, and 4 = +12 dB. In QLab 5, the message simply uses decibel values directly.

/cue/{cue_number}/duckOthers {boolean}

Read: If no argument is given, return the state of the Duck audio of other cues checkbox of the specified cue.

Write: Set the state of the Duck audio of other cues checkbox of the specified cue. See details on booleans at the beginning of this section.

/cue/{cue_number}/duckTime {number}

Read: If no argument is given, return the Duck audio of other cues time of the specified cue.

Write: If number is given, set the Duck audio of other cues time of the specified cue to number.

/cue/{cue_number}/duration {number}

Read: If no argument is given, return the duration of the specified cue.

Write: If number is given, and the selected cue has an editable duration, set the duration of the specified cue to number.

/cue/{cue_number}/currentDuration {number}

Return the current duration of the specified cue.

/cue/{cue_number}/tempDuration {number}

Read: If no argument is given, and if the specified cue has a temporary duration, return that temporary duration.

Write: If number is given, and if the specified cue has a duration, temporarily set the duration of the specified cue to number. The specified cue will revert to its previous duration if it is reset, if the workspace is reset, or if the workspace is closed and reopened.

/cue/{cue_number}/fadeAndStopOthers {number}

Read: If no argument is given, return the Fade and stop mode of the specified cue.

Write: If number is given, set the Fade and stop mode of the specified cue to number. Valid modes are:

0 - None
1 - Peers
2 - List or cart
3 - All

Mode 0 is equivalent to the Fade and stop checkbox being unchecked.

/cue/{cue_number}/fadeAndStopOthersTime {number}

Read: If no argument is given, return the Fade and stop others time of the specified cue.

Write: If number is given, set the Fade and stop others time of the specified cue to number.

/cue/{cue_number}/fileTarget {string}

Read: If no argument is given, return the target of the specified cue. Empty string ("") means that the cue has no file target.

Write: If string is given, and if the specified cue can have file targets, set the target of the specified cue to string. If string is "none" or empty (""), unset the file target. If string is anything else, string should be a file path and name in any of the following three forms:

• Full paths, e.g. /Volumes/MyDisk/path/to/some/file.wav
• Paths beginning with a tilde, e.g. ~/path/to some/file.mov
• Relative paths, e.g. this/is/a/relative/path.mid

Paths beginning with a tilde (~) will be expanded; the tilde signifies “relative to the user’s home directory”.

Relative paths will be interpreted according to the current working directory. Use the /workingDirectory application message to set or get the current working directory.

/cue/{cue_number}/flagged {boolean}

Read: If no argument is given, return the state of the Flagged checkbox of the specified cue.

Write: Set the flagged state of the specified cue. See details on booleans at the beginning of this section.

/cue/{cue_number}/go

If the specified cue is not a cue list, tell QLab to move the playhead to cue cue_number and then GO.

If the specified cue is a cue list, tell that cue list to GO. This GO respects the current playback position for that list, as well as double go protection for the workspace.

/cue/{cue_number}/hardPause

Pause the specified cue without allowing audio effects to decay naturally. If the specified cue is not playing, this message has no effect.

/cue/{cue_number}/hardStop

Stop the specified cue without allowing audio effects to decay naturally. If the specified cue is not playing, this message has no effect.

/cue/{cue_number}/hasCueTargets

Return true if the specified cue is able to target another cue. Examples of such a cue include Fade cues and Stop cues.

/cue/{cue_number}/hasFileTargets

Return true if the specified cue is able to target a file. Examples of such a cue are Audio, Video, and MIDI File cues.

/cue/{cue_number}/isActionRunning

Return true if the action of the specified cue (not the pre-wait or post-wait) is running.

/cue/{cue_number}/isAuditioning

Return true if the specified cue is auditioning.

/cue/{cue_number}/isBroken

Return true if the specified cue is broken.

/cue/{cue_number}/isCrossfadingOut

Return true if the specified cue is crossfading out. This only applies to cues inside Playlist Group cues.

/cue/{cue_number}/isLoaded

Return true if the specified cue is loaded.

/cue/{cue_number}/isOverridden