QLab's OSC Dictionary

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 query +/-? Live
read read/write read only edit, control

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}

view edit control query
read/write read/write read/write

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

view edit control query

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

view edit control query
read only read only read only

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

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

/fontFamiliesAndStyles

view edit control query
read only read only read only

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}

view edit control query
read/write read/write read/write

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}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable DMX output.


/overrides/midiInputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable MIDI input.


/overrides/midiOutputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable MIDI output.


/overrides/mscInputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable MSC input.


/overrides/mscOutputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable MSC output.


/overrides/sysexInputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable SysEx input.


/overrides/sysexOutputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable SysEx output.


/overrides/networkExternalInputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

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}

view edit control query
read read/write read/write

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

view edit control query

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}

view edit control query
read read/write read/write

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

view edit control query

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}

view edit control query
read read/write read/write

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

view edit control query

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}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable timecode input.


/overrides/timecodeOutputEnabled {boolean}

view edit control query
read read/write read/write

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

view edit control query

Enable or disable timecode output.


/overrideWindow {boolean}

view edit control query
read read/write read/write

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

view edit control query

Show or hide the Override Window.


/replyFormat {format_string}

view edit control query
read/write read/write read/write

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}

view edit control query
read read/write read/write

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

view edit control query

Show or hide the Timecode Window.

/udpReplyPort {number}

view edit control query
read/write read/write read/write

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}

view edit control query
read/write read/write read/write

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

view edit control query

Return QLab’s version number.


/workingDirectory {path}

view edit control query
read read/write read

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

view edit control query
read only read only read only

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}

view edit control query
read read/write read

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}

view edit control query
read read/write read

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

view edit control query

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


/workspace/{id}/basePath

view edit control query
read only read only read only

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}

view edit control query

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

view edit control query
read only read only read only

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}

view edit control query
read read read/write

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}

view edit control query
read read read/write

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

view edit control query

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}

view edit control query
read read/write read/write

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

view edit control query

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

view edit control query

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

view edit control query

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


/workspace/{id}/dashboard/recordAllToLatest

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

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}

view edit control query live
control

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

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

Delete the specified cue(s).


/workspace/{id}/delete/active

view edit control query

Delete all cues that are currently running or paused.


/workspace/{id}/doubleGoWindowRemaining

view edit control query
read only read only read only

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}

view edit control query
read read/write read

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

view edit control query

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


/workspace/{id}/go {cue_number}

view edit control query

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}

view edit control query

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}

view edit control query

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

view edit control query

Stop all playback and cut all audio effects immediately.


/workspace/{id}/liveFadePreview {boolean}

view edit control query
read read/write read

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

view edit control query
read/write

Enable or disable live fade preview.


/workspace/{id}/lightDashboard {boolean}

view edit control query
read read/write read

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

view edit control query

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}

view edit control query

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}

view edit control query

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

view edit control query

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}

view edit control query

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

view edit control query

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}

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

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

view edit control query

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


/workspace/{id}/playhead/selected

view edit control query

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


/workspace/{id}/redo

view edit control query

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}

view edit control query

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

view edit control query

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

view edit control query

Un-pause all paused cues in the workspace.


/workspace/{id}/save

view edit control query

Tell the given workspace to save itself to disk.


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

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

view edit control query

Select the specified cue(s).


/workspace/{id}/select/next

view edit control query

Move the selection down one cue.


/workspace/{id}/select/previous

view edit control query

Move the selection up one cue.


/workspace/{id}/showMode {boolean}

view edit control query
read read/write read

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

view edit control query

Switch between show mode and edit mode.


/workspace/{id}/stop

view edit control query

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


/workspace/{id}/thump

view edit control query
read only read only read only

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query
read only read only read only

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

view edit control query
read only read only read only

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}

view edit control query
read only read only read only

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}

view edit control query +/-?
read read/write

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}

view edit control query +/-? live
read read/write control

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?
read/write

Un-mute all device outputs of the specified patch.


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

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

view edit control query +/-?
read only read only read only

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


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

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

view edit control query +/-?

Set the name of the specified patch to string.


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

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

view edit control query +/-?

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

view edit control query +/-?
read only read only

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

view edit control query +/-?

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?
read/write

Un-solo all device outputs of the specified patch.


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

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

view edit control query +/-?
read only read only read only

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


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

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

view edit control query
read only read only read only

Return the unique ID of the specified audio output patch.


/settings/audio/patchList

view edit control query
read only read only read only

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

view edit control query

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

view edit control query

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}

view edit control query
read read/write read

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}

view edit control query
read read/write read/write

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

view edit control query

Lock or unlock the selection to the playhead.


/settings/general/undo

view edit control query

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query

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

view edit control query

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

view edit control query
read only read only read only

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

view edit control query
read only read only read only

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}

view edit control query
read only read only read only

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}

view edit control query +/-?
read read/write read

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

view edit control query
read only read only read only

Return the unique ID of the specified video output route.


/settings/video/stages

view edit control query
read only read only read only

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}

view edit control query
read only read only read only

Return a JSON dictionary describing the specified stage.


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

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

view edit control query +/-?
read read/write read

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

view edit control query
read only read only read only

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


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

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

view edit control query
read only read only read only

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


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

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

view edit control query
read only read only read only

Return the height of the specified stage.


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

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

view edit control query
read only read only read only

Return the width of the specified stage.


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

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

view edit control query
read only read only read only

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}

view edit control query
read only read only read only

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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

view edit control query

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


/settings/video/undo

view edit control query

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

view edit control query

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

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/percentActionElapsed

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/allowsEditingDuration

view edit control query +/-?
read only read only read only

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?

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

view edit control query +/-?

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/captureTimecode

view edit control query +/-?

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/

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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/

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-? live
read read/write read control

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}

view edit control query +/-? live
read read/write read control

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?
read only read only read only

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?
read only read only read only

Return the default name of the specified cue.


/cue/{cue_number}/displayName

view edit control query +/-?
read only read only read only

Return the display name of the specified cue.


/cue/{cue_number}/duckLevel {number}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read only read only read only

Return the current duration of the specified cue.


/cue/{cue_number}/tempDuration {number}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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}

view edit control query +/-?
read read/write read

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

view edit control query +/-?

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

view edit control query +/-?

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

view edit control query +/-?

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

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/isAuditioning

view edit control query +/-?
read only read only read only

Return true if the specified cue is auditioning.


/cue/{cue_number}/isBroken

view edit control query +/-?
read only read only read only

Return true if the specified cue is broken.


/cue/{cue_number}/isCrossfadingOut

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/isLoaded

view edit control query +/-?
read only read only read only

Return true if the specified cue is loaded.


/cue/{cue_number}/isOverridden

view edit control query +/-?
read only read only read only

Return true if the specified cue’s output is currently suppressed by an override control.


/cue/{cue_number}/isPanicking

view edit control query +/-?
read only read only read only

Return true if the specified cue is panicking.


/cue/{cue_number}/isPaused

view edit control query +/-?
read only read only read only

Return true if the specified cue is paused.


/cue/{cue_number}/isRunning

view edit control query +/-?
read only read only read only

Return true if the specified cue is running.


/cue/{cue_number}/isTailingOut

view edit control query +/-?
read only read only read only

Return true if the specified cue has an audio effect which is decaying.


/cue/{cue_number}/isWarning

view edit control query +/-?
read only read only read only

Return true if the specified cue has a non-breaking warning.


/cue/{cue_number}/listName

view edit control query +/-?
read only read only read only

Return the list name of the specified cue. The list name is the name that is displayed in the cue list, which can be either the default name, a manually set display name, or nothing.


/cue/{cue_number}/load

view edit control query +/-?

Load the specified cue.


/cue/{cue_number}/loadAt {number}

/cue/{cue_number}/loadAt {hours} {minutes} {seconds}

view edit control query +/-?

If a single argument, number, is given and is a positive number, load the specified cue to number seconds. If number is a negative number, load the specified cue to number seconds before the end of the cue. If the cue has a pre-wait, that time is counted as part of the load time.

If three arguments are given, and each are positive numbers, load the specified cue to hours:minutes:seconds. Negative numbers are not accepted. If the cue has a pre-wait, that time is counted as part of the load time.

If no argument is given, this command is equivalent to load.

Examples:

  • /cue/10/loadAt 15 loads cue 10 to 15 seconds.
  • /cue/20/loadAt -30 loads cue 20 to 30 seconds before the end (so that, for example, you can rehearse the last 30 seconds of a dance number.)
  • /cue/30/loadAt 0 4 6.5 load cue 30 to 4:06.5 (four minutes, six point five seconds.)

/cue/{cue_number}/loadActionAt {number}

/cue/{cue_number}/loadActionAt {hours} {minutes} {seconds}

view edit control query +/-?

If a single argument, number, is given and is a positive number, load the specified cue to number seconds. If number is a negative number, load the specified cue to number seconds before the end of the cue. QLab will automatically add the pre-wait of the specified cue so that the cue is loaded to the given time as though it has no pre-wait.

If three arguments are given, and each are positive numbers, load the specified cue to hours:minutes:seconds. Negative numbers are not accepted. QLab will automatically add the pre-wait of the specified cue so that the cue is loaded to the given time as though it has no pre-wait.

If no argument is given, this command is equivalent to load.


/cue/{cue_number}/loadFileAt {number}

/cue/{cue_number}/loadFileAt {hours} {minutes} {seconds}

view edit control query +/-?

If a single argument, number, is given and is a positive number, load the specified cue to number seconds ignoring any slice loop counts. If number is a negative number, load the specified cue to number seconds before the end of the cue. QLab will automatically add the pre-wait of the specified cue so that the cue is loaded to the given time as though it has no pre-wait.

If three arguments are given, and each are positive numbers, load the specified cue to hours:minutes:seconds ignoring any slice loop counts. Negative numbers are not accepted. QLab will automatically add the pre-wait of the specified cue so that the cue is loaded to the given time as though it has no pre-wait.

If no argument is given, this command is equivalent to load, but ignores slice loop counts.


/cue/{cue_number}/loadAndSetPlayhead

view edit control query +/-?

Move the playhead to the specified cue and load that cue.


/cue/{cue_number}/maxTimeInCueSequence

view edit control query +/-?
read only read only read only

Return the maximum time required to complete the cue sequence starting at the specified cue, as used e.g. for the “load to time” slider. Any infinite loops within the sequence are only counted once.


/cue/{cue_number}/name {string}

view edit control query +/-?
read read/write read

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

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


/cue/{cue_number}/notes {string}

view edit control query +/-?
read/write read/write read/write

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

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


/cue/{cue_number}/number {string}

view edit control query +/-?
read read/write read

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

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


/cue/{cue_number}/panic

view edit control query +/-?

Panic the specified cue. Panicked cues fade out and stop over the panic duration specified in the General section of Workspace Settings.


/cue/{cue_number}/panicInTime {number}

view edit control query +/-?

Panic the specified cue, using number for the panic duration instead of the panic duration specified in Workspace Settings.


/cue/{cue_number}/parent

view edit control query +/-?
read only read only read only

Return the cue ID of the parent of the specified cue. If the specified cue is inside a Group, then the Group is the parent. Otherwise, the cue list or cue cart that contains the cue is the parent.


/cue/{cue_number}/patchTargetID {id}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the ID of the patch that is targeted by the specified cue.

Write: If id is given, set the target of the specified cue to the patch with ID id.


/cue/{cue_number}/pause

view edit control query +/-?

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


/cue/{cue_number}/togglePause

view edit control query +/-?

If the specified cue is playing, pause it. If the specified cue is paused, resume it. If the specified cue is not playing and not paused, this message has no effect.


/cue/{cue_number}/postWait {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the post-wait of the specified cue.

Write: If number is given, set the post-wait of the specified cue to number.


/cue/{cue_number}/postWaitElapsed

view edit control query +/-?
read only read only read only

Return the elapsed post-wait time (in seconds) of the specified cue.


/cue/{cue_number}/percentPostWaitElapsed

view edit control query +/-?
read only read only read only

Return the elapsed post-wait time (as a percentage of the total post-wait time) of the specified cue.


/cue/{cue_number}/preview

view edit control query +/-?

Preview the specified cue. Previewing a cue starts it, 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}/preWait {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the pre-wait of the specified cue.

Write: If number is given, set the pre-wait of the specified cue to number.


/cue/{cue_number}/preWaitElapsed

view edit control query +/-?
read only read only read only

Return the elapsed pre-wait time (in seconds) of the specified cue.


/cue/{cue_number}/percentPreWaitElapsed

view edit control query +/-?
read only read only read only

Return the elapsed pre-wait time (as a percentage of the total pre-wait time) of the specified cue.


/cue/{cue_number}/reset

view edit control query +/-?

Reset the specified cue. Resetting a cue returns any temporary changes (such as those caused by a “live” OSC method) to be reverted.


/cue/{cue_number}/resume

view edit control query +/-?

Resume the specified cue. If the specified cue is not paused, this message has no effect.


/cue/{cue_number}/secondTriggerAction {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the second trigger action of the specified cue to number. Valid actions are:

0 - Do nothing
1 - Panic
2 - Stop
3 - Hard stop
4 - Hard stop & restart
5 - Devamp
6 - Playlist Next
7 - Playlist Previous

Options 6 and 7 are only valid when sent to a Playlist Group cue.


/cue/{cue_number}/secondTriggerOnRelease {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the state of the Second trigger on release checkbox of the specified cue.

Write: Set the state of the Second trigger on release checkbox of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/soloCueInTime {number}

view edit control query +/-?

Fade and stop all other cues in the same cue list as the specified cue over number seconds. number is required, and can be any number greater than or equal to zero, decimals allowed.


/cue/{cue_number}/start

/cue/start {cue_number}

/cue_id/start {cue_id}

view edit control query +/-?

Start the specified cue. This does not move the playhead.


/cue/{cue_number}/startAndAutoloadNext

view edit control query +/-?

Start the specified cue and load the following cue or cue sequence if that cue or cue sequence is set to auto-load. This does not move the playhead.


/cue/{cue_number}/stop

view edit control query +/-?

Stop the specified cue. If the specified cue is not playing, this message has no effect.


/cue/{cue_number}/targetMode {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return 0 if the specified cue targets a cue or 1 if the specified cue targets a patch.

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

0 - Cue target
1 - Patch target

/cue/{cue_number}/timecodeTrigger

view edit control query +/-?
read only read only read only

Return the timecode time of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/hours {number}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the “hours” portion of the specified cue’s timecode trigger.

Write: If number is given, set the “hours” portion of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/minutes {number}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the “minutes” portion of the specified cue’s timecode trigger.

Write: If number is given, set the “minutes” portion of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/seconds {number}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the “seconds” portion of the specified cue’s timecode trigger.

Write: If number is given, set the “seconds” portion of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/frames {number}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the “frames” portion of the specified cue’s timecode trigger.

Write: If number is given, set the “frames” portion of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/bits {number}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the “bits” portion of the specified cue’s timecode trigger.

Write: If number is given, set the “bits” portion of the specified cue’s timecode trigger.


/cue/{cue_number}/timecodeTrigger/text {string}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the specified cue’s timecode trigger as a text string.

Write: If string is given, set the specified cue’s timecode trigger to string. string must be in the form of a valid timecode entry.


/cue/{cue_number}/type

view edit control query +/-?
read only read only read only

Return the type (Audio, Video, Fade, etc.) of the specified cue.


/cue/{cue_number}/uniqueID

view edit control query +/-?
read only read only read only

Return the uniqueID of the specified cue.


/cue/{cue_number}/valuesForKeys {json_string}

view edit control query +/-?

This special method can be used to request a custom collection of state information about the specified cue. json_string must be a JSON-formatted string representing an array of keys you wish to query.

Example:

/cue/2/valuesForKeys "[\"opacity\",\"surfaceSize\"]"

would return the values for the “opacity” and “surfaceSize” properties of cue 2, assuming cue 2 is a Video, Camera, or Text cue.

Invalid use of this message has no effect.


/cue/{cue_number}/valuesForKeysWithArguments {json_string}

view edit control query +/-?

This special method can be used to request a custom collection of state information about the given cue. json_string must be a JSON-formatted string representing a dictionary of keys and arguments you wish to query.

Example:

/cue/2/valuesForKeysWithArguments "{\"level\":[0,0]}"

would return a dictionary that contains the value of the main volume level of cue 2, assuming cue 2 has audio levels. Note that this method is limited to returning one value per key, even if you send multiple keys with different arguments.


Group cue/List/Cart messages

Messages specific to Group cues, cue lists, and cue carts (which are really also Group cues.)


/cue/{cue_number}/cartColumns

/cue/{cue_number}/cartRows

view edit control query +/-?
read only read only read only

If the specified cue is a cart, these messages return the number of rows or columns in the cart. If the specified cue is not a cart, these messages have no effect.


/cue/{cue_number}/collapse

view edit control query

If the specified Group cue is expanded, displaying its children, collapse it.


/cue/{cue_number}/expand

view edit control query

If the specified Group cue is collapsed, not displaying its children, expand it.


/cue/{cue_number}/currentTimecode

/cue/{cue_number}/currentTimecode/hours

/cue/{cue_number}/currentTimecode/minutes

/cue/{cue_number}/currentTimecode/seconds

/cue/{cue_number}/currentTimecode/frames

/cue/{cue_number}/currentTimecode/bits

/cue/{cue_number}/currentTimecode/text

view edit control query +/-?
read only read only read only

If the specified cue is a cue list or cart which is set to receive timecode, these messages return the all or part of the current incoming timecode, either as a number or as a string.


/cue/{cue_number}/isChildAuditioning

view edit control query +/-?
read only read only read only

If the specified cue is a list, cart, or Group cue, return true if there is at least one currently auditioning cue amongst the children of the specified cue. If there are none, return false.

If the specified cue is not a list, cart, or Group cue, this message has no effect.


/cue/{cue_number}/isChildFlagged

view edit control query +/-?
read only read only read only

If the specified cue is a list, cart, or Group cue, return true if there is at least one flagged cue amongst the children of the specified cue. If there are none, return false.

If the specified cue is not a list, cart, or Group cue, this message has no effect.


/cue/{cue_number}/mode {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the mode of the specified Group cue, list, or cart.

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

0 - List
1 - Start first and enter
2 - Start first
3 - Timeline
4 - Start random
5 - Cart
6 - Playlist

Modes 0 and 5 are read-only; a cue list will return mode 0, but mode cannot be set to 0, and a cue cart will return mode 5, but mode cannot be set to 5.


/cue/{cue_number}/moveCartCue/{child} {row} {column}

view edit control query +/-?

If the specified cue is a cart, then move child cue child to position row, column within the cart.

child can be the cue number or cue ID of the child cue. row and column must be valid for the specified cart cue.

If the specified cue is not a cart, this message has no effect.


/cue/{cue_number}/playhead {string}

/cue/{cue_number}/playhead/{string}

/cue/{cue_number}/playbackPosition {string}

view edit control query +/-?
read read read/write

Read: If no argument is given, return the cue number of the standing-by cue, or “none” if there is no cue standing by.

Write: If the specified cue is a cue list, set the playhead (playback position) to the cue whose cue number matches string. If string is none, unset the playhead.


/cue/{cue_number}/playheadID {string}

/cue/{cue_number}/playheadID/{string}

/cue/{cue_number}/playbackPositionID {string}

view edit control query +/-?
read read read/write

Read: If no argument is given, return the cue ID of the standing-by cue, or “none” if there is no cue standing by.

Write: If the specified cue is a cue list, set the playhead (playback position) to the cue whose uniqueID is string. If string is none, unset the playhead.


/cue/{cue_number}/playhead next

/cue/{cue_number}/playhead/next

view edit control query +/-?

If the specified cue is a cue list, set the playhead in that cue list to the next cue.


/cue/{cue_number}/playhead previous

/cue/{cue_number}/playhead/previous

view edit control query +/-?

If the specified cue is a cue list, set the playhead in that cue list to the previous cue.


/cue/{cue_number}/playhead/nextSequence

view edit control query +/-?

If the specified cue is a cue list, set the playhead in that cue list to the next cue sequence.


/cue/{cue_number}/playhead/previousSequence

view edit control query +/-?

If the specified cue is a cue list, set the playhead in that cue list to the previous cue sequence.


/cue/{cue_number}/playlist/doCrossfade {boolean}

view edit control query +/-?

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

Write: Enable or disable crossfading on the specified Playlist Group cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.


/cue/{cue_number}/playlist/doLoop {boolean}

view edit control query +/-?

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

Write: Enable or disable looping on the specified Playlist Group cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.


/cue/{cue_number}/playlist/doShuffle {boolean}

view edit control query +/-?

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

Write: Enable or disable shuffle on the specified Playlist Group cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.


/cue/{cue_number}/playlist/next

view edit control query +/-?

If the specified cue is a Playlist Group cue, start the next cue in that playlist.


/cue/{cue_number}/playlist/previous

view edit control query +/-?

If the specified cue is a Playlist Group cue, start the previous cue in that playlist.


/cue/{cue_number}/playlist/crossfade/duration {number}

/cue/{cue_number}/playlistCrossfadeDuration {number}

view edit control query +/-?

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

Write: If number is given, set the crossfade time of the specified Playlist Group cue to number seconds. number can be any whole or decimal number greater than or equal to zero.

If the specified cue is not a Playlist Group cue, this message has no effect.

playlistCrossfadeDuration is deprecated in QLab 5.0.4. This message works but will be removed in a future version of QLab. Use /playlist/crossfade/duration instead.


/cue/{cue_number}/playlistCrossfade {boolean}

view edit control query +/-?

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

Write: Enable or disable crossfading on the specified cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.

Deprecated in QLab 5.0.4. This message works but will be removed in a future version of QLab. Use /playlist/doCrossfade instead.


/cue/{cue_number}/playlistLoop {boolean}

view edit control query +/-?

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

Write: Enable or disable looping on the specified cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.

Deprecated in QLab 5.0.4. This message works but will be removed in a future version of QLab. Use /playlist/doLoop instead.


/cue/{cue_number}/playlistShuffle {boolean}

view edit control query +/-?

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

Write: Enable or disable shuffle on the specified cue. See details on booleans at the beginning of this section.

If the specified cue is not a Playlist Group cue, this message has no effect.

Deprecated in QLab 5.0.4. This message works but will be removed in a future version of QLab. Use /playlist/doShuffle instead.


/cue/{cue_number}/shuffle

view edit control query +/-?

If the specified cue is a Playlist Group cue, shuffle the contents of the specified cue.


/cue/{cue_number}/timecodeFreewheelTime

view edit control query +/-?
read read/write read

Read: If number is not given, return the timecode freewheel time of the specified list or cart.

Write: Set the timecode freewheel time of the specified list or cart to number seconds. number can be any number from 0 to 2, decimals allowed.

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


/cue/{cue_number}/timecodeLookbackTime {number}

view edit control query +/-?
read read/write read

Read: If number is not given, return the timecode lookback time of the specified list or cart.

Write: Set the timecode lookback time of the specified list or cart to number seconds. number can be any number greater than or equal to 0, decimals allowed.

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


/cue/{cue_number}/timecodeSMPTEFormat {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the SMPTE format of the specified list or cart.

Write: If number is given, set the SMPTE format of the list or cart. Valid formats are:

0  - 24 fps
1  - 25 fps
2  - 30 fps drop-frame
3  - 30 fps
4  - 29.97 fps
5  - 29.97 fps drop-frame
6  - 60 fps
7  - 59.94 fps
8  - 60 fps drop-frame
9  - 59.94 fps drop-frame
10 - 50 fps
11 - 23.98 fps

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


/cue/{cue_number}/timecodeStartBehavior {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the timecode start behavior of the specified list or cart.

Write: If number is given, set the timecode start behavior of the list or cart. Valid behaviors are:

0 - do not start cues whose triggers precede the incoming timecode
1 - start cues whose triggers fall within the most recent minute of timecode
2 - start cues whose triggers fall within the most recent hour of timecode
3 - start cues whose triggers fall within the lookback time
4 - start all cues which precede the timecode

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


/cue/{cue_number}/timecodeStopBehavior {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the timecode stop behavior of the specified list or cart.

Write: If number is given, set the timecode stop behavior of the list or cart. Valid behaviors are:

0 - do nothing
1 - pause timecode triggered cues
2 - stop timecode triggered cues

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


/cue/{cue_number}/timecodeSyncMode {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the timecode sync mode of the specified list or cart.

Write: If number is given, set the timecode sync mode of the list or cart. Valid timecode sync modes are:

0 - MTC (MIDI timecode)
1 - LTC (Linear timecode)

If the specified cue is not a list or cart, this message has no effect. Also, note that this setting is separate from the question of whether the list or cart is set to sync to timecode at all.


Audio cue messages

Messages specific to Audio cues. Most of these messages work with Mic cues, Video cues, and Camera cues, as well.


/cue/{cue_number}/addSliceMarker {time} {play_count}

view edit control query +/-?

Add a slice marker to the specified cue. If time is given, add the marker at that time. If not, add the marker at the current time of the cue. time can be any positive whole or decimal number.

If play_count is given, set the play count of the new slice (the slice preceding the new marker) to play_count. If play_count is not given, the play count will be 1. play_count can be any positive whole number, or -1 to set the slice to infinite loop.

Slice markers are zero-indexed, meaning the first marker of a cue is marker 0.


/cue/{cue_number}/audioOutputPatch

view edit control query
read only read only read only

Return a JSON dictionary describing the specified audio output patch currently in use by the specified cue.

[
  {
    "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].


/cue/{cue_number}/audioOutputPatch/cueOutputChannels {number}

/cue/{cue_number}/audioOutputPatch/cueOutputChannels {number}

view edit control query +/-?
read read/write

Read: If no argument is given, return the number of cue outputs of the audio output patch currently in use by the specified cue.

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


/cue/{cue_number}/audioOutputPatch/level/{inChannel}/{outChannel} {decibel}

/cue/{cue_number}/audioOutputPatch/level/{inChannel}/{outChannel}/live {decibel}

view edit control query +/-? live
read read/write control

Read: If no argument is given, return the volume level of the specified crosspoint of the audio output patch currently in use by the specified cue.

Write: If decibel is given, set the specified crosspoint of the audio output patch currently in use by the specified cue 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.


/cue/{cue_number}/audioOutputPatch/mute {output} {boolean}

/cue/{cue_number}/audioOutputPatch/mute/{output} {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return TRUE if the device output of the audio output patch currently in use by the specified cue is muted, or FALSE if it is not.

Write: Mute or unmute the specified device output of the audio output patch currently in use by the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/audioOutputPatch/mute/clear

view edit control query +/-?
read/write

Un-mute all device outputs of the specified cue.


/cue/{cue_number}/audioOutputPatch/muteChannels

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/audioOutputPatch/name {string}

view edit control query +/-?

Set the name of the specified patch to string.


/cue/{cue_number}/audioOutputPatch/reset

view edit control query +/-?

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


/cue/{cue_number}/audioOutputPatch/routing

view edit control query +/-?
read only read only

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].


/cue/{cue_number}/audioOutputPatch/routing/reset

view edit control query +/-?

Reset faded audio levels of the audio output patch currently in use by the specified cue to their saved state.


/cue/{cue_number}/audioOutputPatch/solo {output} {boolean}

/cue/{cue_number}/audioOutputPatch/solo/{output} {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return TRUE if the device output of the audio output patch currently in use by the specified cue is soloed, or FALSE if it is not.

Write: Solo or un-solo the specified device output of the audio output patch currently in use by the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/audioOutputPatch/solo/clear

view edit control query +/-?
read/write

Un-solo all device outputs of the specified cue.


/cue/{cue_number}/audioOutputPatch/soloChannels

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/audioOutputPatch/uniqueID

view edit control query
read only read only read only

Return the unique ID of the audio output patch currently in use by the specified cue.


/cue/{cue_number}/audioOutputPatchName {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the name of the audio output patch currently in use by the specified cue. String "none" means that the cue is un-patched.

Write: If string is given and matches the name of an audio output patch in the workspace, set the audio output patch of the specified cue to that patch. If string is "none" or empty (""), un-patch the specified cue. If string is anything else, this message has no effect.


/cue/{cue_number}/audioOutputPatchNumber {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the index of the audio output patch currently in use by the specified cue. Index 0 means that the cue is un-patched, index 1 means the first patch in the audio output patch list in Workspace Settings, 2 means the second patch, and so on.

Write: If number is given, set the audio output patch of the specified cue to that patch. If number is 0, un-patch the specified cue. If number is greater than the number of audio output patches in the workspace, this message has no effect. number must be a whole number.


/cue/{cue_number}/audioOutputPatchID {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the patch ID of the audio output patch currently in use by the specified cue. Empty string ("") means that the cue is un-patched.

Write: If string is given and matches the patch ID of an audio output patch in the workspace, set the audio output patch of the specified cue to that patch. If string is "none" or empty (""), un-patch the specified cue. For Video and Camera cues which use an NDI device for output, string may also be "ndi-output". If string is anything else, this message has no effect.


/cue/{cue_number}/audioTrackFormats

view edit control query +/-?
read only read only read only

Return a JSON dictionary containing any available metadata about the file target of the specified cue. The exact form and contents of the dictionary varies depending upon the type of file, but generally includes things like channel count, sample rate, and file format.

This message may be most helpful when used with Video cues.


/cue/{cue_number}/audioTrackID

view edit control query +/-?
read only read only read only

Return the ID of the track currently in use by the specified cue. This is only relevant if the file target of the specified cue is a video file which contains multiple audio tracks.

This message may be most helpful when used with Video cues.


/cue/{cue_number}/currentFileTime

view edit control query +/-?
read only read only read only

If the specified cue has a file target, return the current playback time of the target file in seconds.

Examples

  • If the cue is not running, the playback time is 0.
  • If the cue has been playing for ten seconds, and the playback rate of the cue is 1.0, then the playback time is 10.
  • If the cue has been playing for fifteen seconds, and the playback rate of the cue is 0.5 , then the playback time is 7.5.

/cue/{cue_number}/deleteSliceMarker {index}

/cue/{cue_number}/deleteSliceMarker/{index}

view edit control query +/-?

Delete slice marker index of the specified cue. index can be zero or any positive whole number.


/cue/{cue_number}/deleteSliceMarkers

view edit control query +/-?

Delete all slice markers of the specified cue.


/cue/{cue_number}/doFade {boolean}

view edit control query +/-?
read read/write read

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

Write: Enable or disable the integrated fade curve of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/endTime {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the end time of the specified cue to number seconds. number can be any whole or decimal number greater than or equal to zero.


/cue/{cue_number}/gang {inChannel} {outChannel} {gang}

/cue/{cue_number}/gang/{inChannel}/{outChannel} {gang}

view edit control query +/-?
read read/write read

inChannel is required and must be an integer from 0 to 24. 0 is the main column.

outChannel is required and must be either an integer from 0 to 128, or a string that is the name of a cue output. 0 is the main row.

Read: If no gang is given, return the gang of the specified crosspoint.

Write: If gang is given, set the gang of the specified crosspoint. gang must be a string. While it’s not technically necessary, in practice at least two crosspoints must have exactly matching gang strings for it to really do anything.


/cue/{cue_number}/infiniteLoop {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the specified cue is set to loop infinitely, and false if it is not.

Write: Set the infinite loop of the specified cue to true or false. See details on booleans at the beginning of this section.

/cue/{cue_number}/inputChannelName/{number} {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the name of audio input number of the specified cue. Inputs are numbered starting at 1.

Write: Set the name of input number to string.


/cue/{cue_number}/lastSliceInfiniteLoop {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the last slice of the specified cue is set to loop infinitely, and false if it is not.

Write: Set the infinite loop of the last slice of the specified cue to true or false. See details on booleans at the beginning of this section.


/cue/{cue_number}/lastSlicePlayCount {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the play count of the last slice of the specified cue.

Write: If number is given, set the play count of the last slice of the specified cue to number. number can be any positive whole number, or -1 to set the slice to infinite loop.


/cue/{cue_number}/level {inChannel} {outChannel} {decibel}

/cue/{cue_number}/level/{inChannel}/{outChannel} {decibel}

view edit control query +/-?
read read/write read

inChannel is required and must be an integer from 0 to 24. 0 is the main column.

outChannel is required and must be either an integer from 0 to 128, or a string that is the name of a cue output. 0 is the main row.

Read: If no decibel 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,


/cue/{cue_number}/levels

view edit control query +/-?
read only read only read only

Return all the audio levels currently available in the specified cue’s inspector. The levels are returned as an array of arrays, like so:

[
  [ main level, output 1 level, output 2 level, ...],
  [ input 1 main level, input 1/output 1 level, input 1/output 2 level, ...],
  [ ... ]
]

[ ... ] represents a second row in the crosspoint matrix, which is present if and only if the specified cue has at least two audio input channels. There could be as many as 24 rows.

Row 0 of /levels is equivalent to the results of the /sliderLevels method.


/cue/{cue_number}/liveAverageLevel/{outputChannel} {low} {high}

/cue/{cue_number}/liveAverageLevel/{outputChannel}/{low}/{high}

view edit control query +/-?
read only read only read only

Return the RMS level of outputChannel. outputChannel can be either the number or name of a cue output.

low and high are optional numerical values. If they are present, they will cause QLab to re-scale the output of this message to a range of values from low to high.

Examples:

  • /cue/1/liveAverageLevel/1 0 100 will return the level of cue output 1 of cue 1 on a scale of 0 (silent) to 100 (as loud as possible).
  • /cue/10/liveAverageLevel/center/-20/20 will return the level of the cue output named “center” of cue 10 on a scale of -20 (silent) to 20 (as loud as possible).

/cue/{cue_number}/lockFadeToCue {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the state of the Lock fade to start/end checkbox of the specified cue.

Write: Set the state of the Lock fade to start/end checkbox of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/mute {output} {boolean}

/cue/{cue_number}/mute/{output} {boolean}

view edit control query +/-?
read read/write read

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

Write: Mute or unmute the specified cue output of the specified cue. See details on booleans at the beginning of this section. You can refer to the cue output by its number or its name, if it has one.


/cue/{cue_number}/mute/clear

view edit control query +/-?
read/write

Un-mute all cue outputs of the specified cue.


/cue/{cue_number}/muteChannels

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/numChannelsIn

view edit control query +/-?
read only read only read only

Return the number of input channels in the specified cue.


/cue/{cue_number}/patch {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the patch of the specified cue. number must be a positive whole number.

Deprecated in QLab 5.0. This message works in QLab 5, but incompletely, and will be removed in a future version of QLab. Use /audioOutputPatchNumber or /audioOutputPatchID instead.


/cue/{cue_number}/patchList

view edit control query +/-?
read only read only read only

Deprecated in QLab 5.0. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /settings/audio/patchList.


/cue/{cue_number}/playCount {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the play count (number of times to loop) of the specified cue to number. number can be any whole number greater than zero.


/cue/{cue_number}/preservePitch {boolean}

view edit control query +/-?
read read/write read

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

Write: Enable or disable the Preserve pitch checkbox of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/rate {number}

/cue/{cue_number}/rate/live {number}

view edit control query +/-? live
read read/write read control

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

Write: If number is given, set the rate of the specified cue to number. number can be any positive whole or decimal number from 0.03 to 33.0.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/setDefaultLevels

view edit control query +/-?

Set the audio levels of the specified cue to the default levels set in the cue template for the specified cue’s type.


/cue/{cue_number}/setSilentLevels

view edit control query +/-?

Set the audio levels of the specified cue to silent.


/cue/{cue_number}/sliceMarker {index} {time} {play_count}

/cue/{cue_number}/sliceMarker/{index} {time} {play_count}

view edit control query +/-?
read read/write read

index is required and can be zero or any positive whole number.

Read: If time and play_count are not given, return a JSON dictionary listing the time and play count of slice index, like so:

[
  {
    "time":(time in seconds),
    "playCount":(whole number or -1 for infinite loop)
  }
]

Write: For the specified cue, set the time of slice marker index to time, and the play count of slice index to play_count. time can be any positive whole or decimal number. play_count can be any positive whole number, or -1 to set the slice to infinite loop.

time and play_count must both be given if either one is.


/cue/{cue_number}/sliceMarker/{index}/time {time}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the time of slice marker index of the specified cue.

Write: If time is given, set the time of slice marker index of the specified cue to time. time can be any positive whole or decimal number.


/cue/{cue_number}/sliceMarker/{index}/playCount {play_count}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the play count of slice index of the specified cue.

Write: If play_count is given, set the play count of slice index of the specified cue to play_count. play_count can be any positive whole number, or -1 to set the slice to infinite loop.


/cue/{cue_number}/sliceMarkers

view edit control query +/-?
read read/write read

Read: Return a JSON dictionary listing the marker time and play count of all slices of the specified cue:

[
  {
    "time": number,
    "playCount": number
  },
  { ... }
]

{ ... } represents a second slice; the number of slices in a cue varies, so the number of items in this dictionary will vary.

Slices end with slice markers. Therefore, time corresponds to the end time of the slice whose playCount is being reported.

Write: The “write” form of this message is only available via the increment/decrement syntax discussed above.

Examples:

  • /cue/10/sliceMarkers/+ 5 would shift all slice markers in cue 10 to be five seconds later.
  • /cue/10/sliceMarkers 5 would be invalid, and have no effect.

/cue/{cue_number}/sliderLevel {channel} {decibel}

/cue/{cue_number}/sliderLevel/{channel} {decibel}

view edit control query +/-?
read read/write read

Get or set a single cue output slider volume level.

outChannel is required and must be either an integer from 0 to 128, or a string that is the name of a cue output. 0 is the main row.

Read: If no decibel is given, return the volume level of the specified cue output.

Write: If decibel is given, set the volume level of channel 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.


/cue/{cue_number}/sliderLevels

view edit control query +/-?
read only read only read only

Return an array of the output levels of the specified cue, including the cue main. The array is therefore 65 numbers.


/cue/{cue_number}/solo {output} {boolean}

/cue/{cue_number}/solo/{output} {boolean}

view edit control query +/-?
read read/write read

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

Write: Solo or un-solo the specified cue output of the specified cue. See details on booleans at the beginning of this section. You can refer to the cue output by its number or its name, if it has one.


/cue/{cue_number}/solo/clear

view edit control query +/-?
read/write

Un-solo all cue outputs of the specified cue.


/cue/{cue_number}/soloChannels

view edit control query +/-?
read only read only read only

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


/cue/{cue_number}/startTime {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the start time of the specified cue to number seconds. number can be any whole or decimal number greater than or equal to zero.


Mic cue messages

Messages specific to Mic cues. Mic cues also respond to any Audio cue messages that pertain to the I/O or Levels tabs of the inspector.


/cue/{cue_number}/audioInputPatchName {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the name of the audio input patch currently in use by the specified cue. String "none" means that the cue is un-patched.

Write: If string is given and matches the name of an audio input patch in the workspace, set the audio input patch of the specified cue to that patch. If string is "none" or empty (""), un-patch the specified cue. If string is anything else, this message has no effect.


/cue/{cue_number}/audioInputPatchNumber {number}

view edit control query +/-?
read only read/write read

Read: If no argument is given, return the index of the audio input patch currently in use by the specified cue. Index 0 means that the cue is un-patched, index 1 means the first patch in the audio input patch list in Workspace Settings, 2 means the second patch, and so on.

Write: If number is given, set the audio input patch of the specified cue to that patch. If number is 0, un-patch the specified cue. If number is greater than the number of audio input patches in the workspace, this message has no effect. number must be a whole number.


/cue/{cue_number}/audioInputPatchID {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the patch ID of the audio input patch currently in use by the specified cue. Empty string ("") means that the cue is un-patched.

Write: If string is given and matches the patch ID of an audio input patch in the workspace, set the audio input patch of the specified cue to that patch. If string is "none" or empty (""), un-patch the specified cue. If string is anything else, this message has no effect.


/cue/{cue_number}/channelOffset {number}

view edit control query +/-?
read only read/write read

Read: If no argument is given, return the input channel offset of the specified cue, as set in the I/O tab of the inspector.

Write: If number is given, set the input channel offset of the specified cue to number. number can be any whole number, zero or greater.


/cue/{cue_number}/channels {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the number of input channels used by the specified cue.

Write: If number is given, set the number of input channels used by the specified cue to number. number can be any positive whole number.


/cue/{cue_number}/duration {number}

/cue/{cue_number}/tempDuration {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the duration (or temporary duration) of the specified cue to number. number can be any number greater than zero.


Video cue messages

Messages specific to Video cues. Most of these messages will also work with Camera and Text cues as well.

Video cues will also respond to Audio cue messages, although some Audio cue messages will have no effect if the target video file does not have an audio track.


/cue/{cue_number}/anchor {x} {y}

/cue/{cue_number}/anchor/live {x} {y}

view edit control query +/-? live
read read/write read control

Read: If no arguments are given, return the anchor point of the specified cue.

Write: Set the anchor point of the specified cue to (x,y). x and y can be any decimal numbers.


/cue/{cue_number}/anchor/x {number}

/cue/{cue_number}/anchor/x/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the X-axis anchor point of the specified cue.

Write: If number is given, set the X-axis anchor point of the specified cue to number. number can be any decimal number.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/anchor/y {number}

/cue/{cue_number}/anchor/y/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the Y-axis anchor point of the specified cue.

Write: If number is given, set the Y-axis anchor point of the specified cue to number. number can be any decimal number.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/blendMode {string}

view edit control query +/-?
read only read/write read only

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

Write: If string is given, set the blend mode of the specified cue to string. string must be the name of a blend mode, a list of which can be found in the Parameter Reference page of this manual.


/cue/{cue_number}/clockType {string}

view edit control query +/-?
read only read/write read only

Read: If no argument is given, return the clock type used by the specified cue (either audio or video.)

Write: If string is given, set the clock type of the specified cue to string. string can be either “audio” or “video”.

NOTE: There are two alternate forms of this message: /cue/{cue_number}/clockType/audio and /cue/{cue_number}/clockType/video which allow you to set the clock type of a cue without needing an argument. This form may be easier to use with some OSC-sending clients.


/cue/{cue_number}/crop {top} {bottom} {left} {right}

/cue/{cue_number}/crop/live {top} {bottom} {left} {right}

view edit control query +/-? live
read only read/write read only edit, control

Read: If no arguments are given, return the current crop for the specified cue. Crop values are expressed in terms of numbers of pixels counting inwards from each edge of the cue. So 0,0,0,0 is a cue that isn’t cropped at all, and 10,20,30,40 is a cue that is cropped 10 pixels in from the top, 20 pixels in from the bottom, 30 pixels in from the left side, and 40 pixels in from the right side.

Write: If top, bottom, left, and right are given, set the crop of the specified cue to those values. Each value must be a number, and all four values must be given.


/cue/{cue_number}/cropTop {number}

/cue/{cue_number}/cropTop/live {number}

view edit control query +/-? live
read only read/write read only edit, control

Read: If no argument is given, return the current crop for the top edge of specified cue. Crop values are expressed in terms of numbers of pixels counting inwards from each edge of the cue, so a cropTop of 10 means that the top ten pixels of the cue are cropped out.

Write: If number is given, set the top crop of the specified cue to number. number can be any number.


/cue/{cue_number}/cropBottom {number}

/cue/{cue_number}/cropBottom/live {number}

view edit control query +/-? live
read only read/write read only edit, control

Read: If no argument is given, return the current crop for the bottom edge of specified cue. Crop values are expressed in terms of numbers of pixels counting inwards from each edge of the cue, so a cropBottom of 10 means that the bottom ten pixels of the cue are cropped out.

Write: If number is given, set the bottom crop of the specified cue to number. number can be any number.


/cue/{cue_number}/cropLeft {number}

/cue/{cue_number}/cropLeft/live {number}

view edit control query +/-? live
read only read/write read only edit, control

Read: If no argument is given, return the current crop for the left edge of specified cue. Crop values are expressed in terms of numbers of pixels counting inwards from each edge of the cue, so a cropLeft of 10 means that the left ten pixels of the cue are cropped out.

Write: If number is given, set the left crop of the specified cue to number. number can be any number.


/cue/{cue_number}/cropRight {number}

/cue/{cue_number}/cropRight/live {number}

view edit control query +/-? live
read only read/write read only edit, control

Read: If no argument is given, return the current crop for the right edge of specified cue. Crop values are expressed in terms of numbers of pixels counting inwards from each edge of the cue, so a cropRight of 10 means that the right ten pixels of the cue are cropped out.

Write: If number is given, set the right crop of the specified cue to number. number can be any number.


/cue/{cue_number}/cueSize

view edit control query +/-?
read only read only read only

Return the natural size of the cue’s video frame:

{
    "width": number,
    "height": number
}

/cue/{cue_number}/cueSize/height

/cue/{cue_number}/cueSize/height/live

view edit control query +/-? live
read only read only read only control

Return the height of the natural size of the cue’s video frame.


/cue/{cue_number}/cueSize/width

/cue/{cue_number}/cueSize/width/live

view edit control query +/-? live
read only read only read only control

Return the width of the natural size of the cue’s video frame.


/cue/{cue_number}/fillStage {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the specified cue is set to play in full-stage mode, or false if it is not.

Write: Set the full-stage mode of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/fillStyle {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the fill style mode of the specified cue. Valid styles are:

0 - Fit
1 - Fill
2 - Stretch

/cue/{cue_number}/holdLastFrame {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the specified cue is set to hold last frame, or false if it is not.

Write: Set the state of the Hold last frame checkbox of the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/layer {number}

view edit control query +/-?
read read/write read

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

Write: If number is given, set the layer of the specified cue to number. number can be any whole number from 0 to 1000. Layer 0 is the “bottom” layer and layer 1000 is the “top” layer.


/cue/{cue_number}/opacity {number}

/cue/{cue_number}/opacity/live {number}

view edit control query +/-? live
read read/write read control

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

Write: If number is given, set the opacity of the specified cue to number. number can be any decimal number from 0 to 1, where 0 represents 0% opacity and 1 represents 100% opacity.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/origin {x} {y}

/cue/{cue_number}/origin/live {x} {y}

view edit control query +/-? live
read read/write read control

Read: If no arguments are given, return the anchor point of the specified cue.

Write: Set the anchor point of the specified cue to (x,y). x and y can be any decimal numbers.

Deprecated in QLab 5.0.2. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/anchor.


/cue/{cue_number}/origin/x {number}

/cue/{cue_number}/origin/x/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the X-axis anchor point of the specified cue.

Write: If number is given, set the X-axis anchor point of the specified cue to number. number can be any decimal number.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.

Deprecated in QLab 5.0.2. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/anchor/x.


/cue/{cue_number}/origin/y {number}

/cue/{cue_number}/origin/y/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the Y-axis anchor point of the specified cue.

Write: If number is given, set the Y-axis anchor point of the specified cue to number. number can be any decimal number.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.

Deprecated in QLab 5.0.2. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/anchor/y.


/cue/{cue_number}/preserveAspectRatio {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the state of the scale ratio lock of the specified cue.

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


/cue/{cue_number}/quaternion {a} {b} {c} {d}

view edit control query +/-?
read read/write read

Read: If no arguments are given, return an array of four numbers representing the cue’s rotation as a quaternion.

Write: If four numbers are given (a, b, c, and d), set the rotation of the specified cue. Each number can be any number, decimals allowed.

Caution: you need to understand quaternion math to make any meaningful use of this message. Quaternion math is really hard. Good luck!


/cue/{cue_number}/resetRotation

view edit control query +/-?

Reset the rotation of the specified cue.


/cue/{cue_number}/rotate/x {number}

/cue/{cue_number}/rotate/y {number}

/cue/{cue_number}/rotate/z {number}

/cue/{cue_number}/rotate/x/live {number}

/cue/{cue_number}/rotate/y/live {number}

/cue/{cue_number}/rotate/z/live {number}

view edit control query +/-? live
control

Add number to the current quaternion rotation of the specified cue. number can be any decimal number.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/scale {x} {y}

/cue/{cue_number}/scale/live {x} {y}

view edit control query +/-? live
read read/write read control

Read: If no arguments are given, return the scale of the specified cue.

Write: If x and y are given, set the scale of the specified cue to (x,y). x and y can be any number, decimals allowed.


/cue/{cue_number}/scale/x {number}

/cue/{cue_number}/scale/x/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the X-axis scale of the specified cue.

Write: If number is given, set the X-axis scale of the specified cue to number. number can be any number, decimals allowed.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/scale/y {number}

/cue/{cue_number}/scale/y/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the Y-axis scale of the specified cue.

Write: If number is given, set the Y-axis scale of the specified cue to number. number can be any number, decimals allowed.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/smooth {boolean}

view edit control query +/-?
read read/write read

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

Write: If boolean is given, enable or disable the Smooth checkbox on the specified cue. See details on booleans at the beginning of this section.


/cue/{cue_number}/stage

view edit control query
read only read only read only

Return a JSON dictionary containing all available information of the stage that the specified cue is assigned to. The exact contents of this dictionary can vary widely, but generally includes information such as the name, size, and warping details for all regions, the size and gamma of edge blend zones, control point positions and link information, and so on.


/cue/{cue_number}/stage/name {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the name of the video stage currently in use by the specified cue. String "none" means that the cue is un-patched.

Write: If string is given and the specified cue is patched to a stage, set the name of that stage to string. If the specified cue is not currently patched to a stage, this message has no effect.


/cue/{cue_number}/stageName {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the name of the video stage currently in use by the specified cue. String "none" means that the cue is un-patched.

Write: If string is given and matches the name of a video stage in the workspace, set the video stage of the specified cue to that stage. If string is "none" or empty (""), un-patch the specified cue. If string is anything else, this message has no effect.


/cue/{cue_number}/stage/size

view edit control query
read only read only read only

Return a JSON dictionary describing the size of stage in use by the specified cue.


/cue/{cue_number}/stage/size/height

view edit control query
read only read only read only

Return the height of stage in use by the specified cue.


/cue/{cue_number}/stage/size/width

view edit control query
read only read only read only

Return the width of stage in use by the specified cue.


/cue/{cue_number}/stageNumber {number}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the index of the video stage currently in use by the specified cue. Index 0 means that the cue is un-patched, index 1 means the first stage in the video stage list in Workspace Settings, 2 means the second stage, and so on.

Write: If number is given, set the video stage of the specified cue to that stage. If number is 0, un-patch the specified cue. If number is greater than the number of video stages in the workspace, this message has no effect. number must be a whole number.


/cue/{cue_number}/stage/uniqueID

view edit control query
read only read only read only

Return the unique ID of the stage in use by the specified cue.


/cue/{cue_number}/stageID {string}

view edit control query +/-?
read read/write read

Read: If no argument is given, return the stage ID of the video stage currently in use by the specified cue. Empty string ("") means that the cue is un-patched.

Write: If string is given and matches the stage ID of a video stage in the workspace, set the video stage of the specified cue to that stage. If string is "none" or empty (""), un-patch the specified cue. If string is anything else, this message has no effect.


/cue/{cue_number}/surfaceID

view edit control query +/-?
read read/write read

Deprecated in QLab 5.0. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/stageID.


/cue/{cue_number}/surfaceList

view edit control query +/-?
read only read only read only

Deprecated in QLab 5.0. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /settings/video/stages.


/cue/{cue_number}/surfaceName {string}

view edit control query +/-?
read read/write read

Deprecated in QLab 5.0. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/stageName.


/cue/{cue_number}/surfaceSize

view edit control query +/-?
read only read only read only

Deprecated in QLab 5.0. This command is present for backwards compatibility and will be removed in a future version of QLab. For now, it is a synonym of /cue/{cue_number}/stage/size.


/cue/{cue_number}/translation {x} {y}

/cue/{cue_number}/translation/live {x} {y}

view edit control query +/-? live
read read/write read control

Read: If no arguments are given, return the translation of the specified cue.

Write: If x and y are given, set the translation of the specified cue to (x,y). x and y can be any numbers, decimals allowed.


/cue/{cue_number}/translation/x {number}

/cue/{cue_number}/translation/x/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the X-axis translation of the specified cue.

Write: If number is given, set the X-axis translation of the specified cue to number. number can be any number, decimals allowed.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/translation/y {number}

/cue/{cue_number}/translation/y/live {number}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the Y-axis translation of the specified cue.

Write: If number is given, set the Y-axis translation of the specified cue to number. number can be any number, decimals allowed.

Note: If using both increment/decrement and live at the same time, the /live part of the address must come last, after the /+ or /- part.


/cue/{cue_number}/videoEffects

/cue/{cue_number}/videoEffects/live

view edit control query +/-? live
read only read only read only control

Return a list of the video effects in use by the specified cue.

Video effects have OSC-compatible names which can be discovered by hovering your mouse over a video effect currently in use in the Video FX tab of the inspector, or in the video effects section of the Parameter Reference page of this manual.


/cue/{number}/videoEffects/add {name}

view edit control query +/-?

Add a video effect, specified by name, to the specified cue. If the cue already has one or more video effects in use, the new video effect will be added as the last video effect. name must be the OSC name of a video effect in QLab, a list of which can be found in the video effects section of the Parameter Reference page of this manual.


/cue/{number}/videoEffects/insert {name} {index}

view edit control query +/-?

Add a video effect, specified by name, to the specified cue at position index. Video effects are zero-indexed; the first video effect on a cue is at position 0. If there is already a video effect at position index, that effect and any effects after it will be pushed down by one, and the new effect will occupy position index. If index is greater than one plus the number of video effects currently in use by the cue, the new effect will be added as the last video effect. name must be the OSC name of a video effect in QLab and index must be a whole number, 0 or higher.


/cue/{number}/videoEffect/{name}/delete

view edit control query +/-?

Remote the video effect named name from the specified cue. If there is no video effect of the specified name in use by the cue, this message has no effect. If there is more that one video effect with the same name in use by the cue, this command addresses the first instance of the video effect.


/cue/{number}/videoEffectIndex/{index}/delete

view edit control query +/-?

Remote the video effect at position index from the specified cue. Video effects are zero indexed; the first video effect on a cue is at position 0. If there is no video effect at position index, this message has no effect. index must be a whole number, 0 or higher.


/cue/{number}/videoEffect/{name}/enabled {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the specified video effect on the specified cue is enabled, and false if it is not. The video effect is specified by name which is the OSC name of the video effect.

Write: If boolean is given, enable or disable the specified video effect on the specified cue. See details on booleans at the beginning of this section.


/cue/{number}/videoEffectIndex/{index}/enabled {boolean}

view edit control query +/-?
read read/write read

Read: If no argument is given, return true if the specified video effect on the specified cue is enabled, and false if it is not. The video effect is specified by index which is a zero-indexed count of the video effects in use by the cue.

Write: If boolean is given, enable or disable the specified video effect on the specified cue. See details on booleans at the beginning of this section.


/cue/{number}/videoEffect/{name}/move {newIndex}

view edit control query +/-?

Move the video effect specified by name to position newIndex. If newIndex is greater than one plus the number of video effects currently in use by the cue, the effect will be moved to the end of the list of video effects. name must correspond to a video effect in use by the cue, and newIndex must be a whole number, 0 or higher. If there is more that one video effect with the same name in use by the cue, this command addresses the first instance of the video effect.


/cue/{number}/videoEffectIndex/{index}/move {newIndex}

view edit control query +/-?

Move the video effect at position index to position newIndex. If newIndex is greater than one plus the number of video effects currently in use by the cue, the effect will be moved to the end of the list of video effects. index must correspond to a position of a video effect, and both index and newIndex must be whole numbers, 0 or higher.


/cue/{number}/videoEffect/{name}/parameter/{parameterKey} {setting}

/cue/{number}/videoEffect/{name}/parameter/{parameterKey}/live {setting}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the current setting or value for the given parameter of the specified video effect on the specified cue. parameterKey must be the OSC parameter name of the specified video effect. The video effect is specified by name which is the OSC name of the video effect.

Write: If setting is given, set the value of the given parameter of the specified video effect on the specified cue to setting. setting must be valid for the given parameter. parameterKey must be the OSC parameter name of the specified video effect. The video effect is specified by name which is the OSC name of the video effect.


/cue/{number}/videoEffectIndex/{index}/parameter/{parameterKey} {setting}

/cue/{number}/videoEffectIndex/{index}/parameter/{parameterKey}/live {setting}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return the current setting or value for the given parameter of the specified video effect on the specified cue. parameterKey must be the OSC parameter name of the specified video effect. The video effect is specified by index which is a zero-indexed count of the video effects in use by the cue.

Write: If setting is given, set the value of the given parameter of the specified video effect on the specified cue to setting. setting must be valid for the given parameter. parameterKey must be the OSC parameter name of the specified video effect. The video effect is specified by index.


/cue/{number}/videoEffect/{name}/parameters {json_string}

/cue/{number}/videoEffect/{name}/parameters/live {json_string}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return a JSON string containing the names and current settings or values for the given parameter of the specified video effect on the specified cue in the form {"parameter1_name":value,"parameter2_name",value...}. The video effect is specified by name which is the OSC name of the video effect.

Write: If json_string is given, set the value of the parameters of the specified video effect on the specified cue according to json_string. json_string must be formatted appropriately and contain only valid parameter names and values for the specified video effect. The video effect is specified by name which is the OSC name of the video effect.

Example

Assuming cue 1 is a Video cue with the Color Controls video effect, the following OSC message would appropriately set all four parameters of that video effect:

/cue/1/videoEffect/ColorControls/parameters "{\"inputContrast\":1,\"inputAngle\":0,\"inputBrightness\":0.25,\"inputSaturation\":1}"

Note the backslashes surrounding most of the quotation marks; these are necessary because those quotation marks are part of the JSON string that needs to be sent, but QLab uses quotation marks to denote the beginning and end of a text string in OSC messages. The backslashes tell QLab’s OSC interpreter to send the quote as part of the string and not use it to mark the end of the string.


/cue/{number}/videoEffectIndex/{index}/parameters {json_string}

/cue/{number}/videoEffectIndex/{index}/parameters/live {json_string}

view edit control query +/-? live
read read/write read control

Read: If no argument is given, return a JSON string containing the names and current settings or values for the given parameter of the specified video effect on the specified cue in the form {"parameter1_name":value,"parameter2_name",value...}. The video effect is specified by index which is a zero-indexed count of the video effects in use by the cue.

Write: If json_string is given, set the value of the parameters of the specified video effect on the specified cue according to json_string. json_string must be formatted appropriately and contain only valid parameter names and values for the specified video effect. The video effect is specified by index which is a zero-indexed count of the video effects in use by the cue.

Example

Assuming cue 1 is a