QLab's OSC Dictionary

QLab has an extensive API (application program 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’s OSC implementation.

Transport layer

The QLab OSC API can be used over both UDP and TCP transport layers. QLab listens for incoming OSC on port 53000.

When talking to QLab via UDP, each OSC message corresponds to one UDP datagram. Replies to OSC via UDP are sent on port 53001.

When talking 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 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.


Reply format

All replies from QLab take the form:

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

The reply is sent to the IP address from which the original message was received.

The address of the reply starts with /reply/ and ends with the address of the invoked method.

json_string takes the form:

{
    "workspace_id" : string,
    "address": "/invoked/osc/method",
    "status": string,
    "data": value
}

workspace_id is optional, and only specified if the reply is specifically from the given workspace.

status is either ok or error.

data is the JSON-encoded result of invoking the method at address

For example, 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}


Update format

When a client has requested updates from a specific workspace (i.e. has sent that workspace the /workspace/{id}/updates 1 command), it will receive push notifications when the client needs to update state for a cue or workspace. The client may receive the following messages at any time:

/update/workspace/{workspace_id}

This message is sent if you need to reload the cue lists for the workspace, and also whenever various other aspects of a workspace are updated.

/update/workspace/{workspace_id}/cue_id/{cue_id}

This message is sent if you need to reload the state for the given cue. If the cue is a group cue or cue list, you should also reload the children of the cue.

/update/workspace/{workspace_id}/cueList/{cue_list_id}/playbackPosition {cue_id}

This message is sent when the playback position of {cue_list_id} changes to {cue_id}. If there is no current playback position, there will be no {cue_id} argument.

/update/workspace/{workspace_id}/disconnect

This message is sent if you need to disconnect from the given workspace (because it is going away).


Application methods

QLab will respond to the following general commands:

/alwaysReply {number}

By default, QLab will only send a reply if the method generates a reply to send.

However, if number is set to any non-zero number, QLab will send a reply for every OSC message it receives. Messages that would not normally generate a reply will generate one with a JSON string argument that contains:

{
    "workspace_id" : string,
    "address": "/invoked/osc/method",
    "status": string
}

The status string will be either “ok” or “error”.

Note that the data field does not exist in this reply.


/auditionWindow {number}

Show or hide the Audition Window. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current visibility of the Audition Window.


/toggleAuditionWindow

Show or hide the Audition Window.


/fontNames

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

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

/fontFamiliesAndStyles

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

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

/liveFadePreview {number}

Enable or disable live fade preview. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current status of live fade preview.


/toggleLiveFadePreview

Enable or disable live fade preview.


/overrides/artNetEnabled {number}

Set the Art-net output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the Art-net output override.


/overrides/toggleArtNet

Enable or disable Art-net output.


/overrides/midiInputEnabled {number}

Set the MIDI input override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MIDI input override.


/overrides/toggleMidiInput

Enable or disable MIDI input.


/overrides/midiOutputEnabled {number}

Set the MIDI output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MIDI output override.


/overrides/toggleMidiOutput

Enable or disable MIDI output.


/overrides/mscInputEnabled {number}

Set the MSC input override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MSC input override.


/overrides/toggleMscInput

Enable or disable MSC input.


/overrides/mscOutputEnabled {number}

Set the MSC output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MSC output override.


/overrides/toggleMscOutput

Enable or disable MSC output.


/overrides/sysexInputEnabled {number}

Set the MIDI SysEx input override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MIDI SysEx input override.


/overrides/toggleSysexInput

Enable or disable SysEx input.


/overrides/sysexOutputEnabled {number}

Set the MIDI SysEx output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the MIDI SysEx output override.


/overrides/toggleSysexOutput

Enable or disable SysEx output.


/overrides/oscInputEnabled {number}

Set the OSC input override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the OSC input override.


/overrides/toggleOscInput

Enable or disable OSC input.


/overrides/oscOutputEnabled {number}

Set the OSC output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the OSC output override.


/overrides/toggleOscOutput

Enable or disable OSC output.


/overrides/timecodeInputEnabled {number}

Set the timecode input override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the timecode input override.


/overrides/toggleTimecodeInput

Enable or disable timecode input.


/overrides/timecodeOutputEnabled {number}

Set the timecode output override to true or false. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current state of the timecode output override.


/overrides/toggleTimecodeOutput

Enable or disable timecode output.


/overrideWindow {number}

Show or hide the Override Window. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current visibility of the Override Window.


/toggleOverrideWindow

Show or hide the Override Window.


/replyFormat {format_string}

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

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

QLab will do its best to create a reply message with the format you specify. For example, let’s say you set QLab’s replay format with the following message:

/replyFormat “#address# #data#”

Then, if you sent /cue/1/colorName, you would get the reply: /cue/1/colorName green. The #address# token resolves to colorName, since that was the OSC address you sent, and the #data# token resolves to green, assuming the color of cue 1 is in fact green.


/timecodeWindow {number}

Show or hide the Timecode Window. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current visibility of the Timecode Window.


/toggleTimecodeWindow

Show or hide the Timecode Window.


/version

Return QLab’s version number.


/workingDirectory {path}

Get or set the current working directory. If provided, the path string is the working directory you wish to set. 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.”


/workspaces

Return an array of workspace dictionaries:

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

Workspace methods

Workspace OSC methods use the form /workspace/{id}/command, where {id} may be either the display name of the workspace, such as hamlet.qlab4, or the unique ID of the workspace, which can be found in the Info tab of the 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, diacritical, 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.qlab4/go

If you send a workspace method without the /workspace/{id} portion of the address, then the method will be sent to the current workspace, which is the front-most, active document. So, if your hamlet.qlab4 workspace is the front-most, active document, and you send QLab the OSC command /go, then hamlet.qlab4 will GO.

Workspaces respond to the following commands:


/workspace/{id}/basePath

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


/workspace/{id}/connect {passcode_string}

Connect to this workspace with an optional passcode string. If the workspace has a passcode, you MUST supply it before any other commands will be accepted by the workspace or the cues it contains. If the workspace does not have a passcode, the /workspace/{id}/connect method is optional.

Returns ok if there is no passcode, or the passcode matches.

Returns badpass if the passcode does not match.

Returns error if the workspace does not exist.


/workspace/{id}/disconnect

Disconnect from this workspace. You should invoke this method when you will no longer be sending messages to this workspace.

If you are communicating to 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. If you are disconnected and the workspace has a password, you will need to reconnect with that password before further commands will be accepted.

If you are communicating to QLab via TCP, QLab will not automatically disconnect your client. The client will remain connected until the client sends the disconnect message or the TCP connection itself is disconnected.


/workspace/{id}/doubleGoWindowRemaining

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}/cueLists

/workspace/{id}/selectedCues

/workspace/{id}/runningCues

/workspace/{id}/runningOrPausedCues

All return an array of cue dictionaries:

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

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

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

colorName may be none, red, orange, green, blue, or purple.

Note: Methods that reply with an array of cue dictionaries may generate large OSC messages. These messages can easily grow larger than the maximum size supported by UDP datagrams. If you need to access these methods you should communicate to QLab over a TCP connection rather than a UDP connection.

Starting with QLab 4.4.3, versions of these commands are available which return less data:

/cueLists/shallow

/selectedCues/shallow

/runningCues/shallow

/runningOrPausedCues/shallow

These methods are identical to the similar methods above, except they do not include any data for the children of Group cues.

/cueLists/uniqueIDs

/selectedCues/uniqueIDs

/runningCues/uniqueIDs

/runningOrPausedCues/uniqueIDs

These methods 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 is included.

/cueLists/uniqueIDs/shallow

/selectedCues/uniqueIDs/shallow

/runningCues/uniqueIDs/shallow

/runningOrPausedCues/uniqueIDs/shallow

These methods are identical to the similar methods above, except they do not include any data for the children of Group cues.


/workspace/{id}/dashboard/clear

/workspace/{id}/dashboard/updateLatestCue

/workspace/{id}/dashboard/updateOriginatingCues

/workspace/{id}/dashboard/updateSelectedCues

/workspace/{id}/dashboard/newCueWithAll

/workspace/{id}/dashboard/newCueWithChanges

/workspace/{id}/dashboard/recordAllToLatest

/workspace/{id}/dashboard/recordAllToSelected

/workspace/{id}/dashboard/revert

These commands are the equivalent of clicking their corresponding buttons in the Light Dashboard.


/workspace/{id}/dashboard/redo

Re-does the last action taken in the Light Dashboard. If nothing has been un-done in the Dashboard, this command has no effect.


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

Set the Light Dashboard’s view mode to string. Supported modes are sliders and tiles. If no argument is provided, this method does nothing.


/workspace/{id}/dashboard/nextMode

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


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

Set instrument or light group string to level setting in the Light 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.


/workspace/{id}/dashboard/undo

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


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

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

/workspace/{id}/delete/active

/workspace/{id}/delete/selected

Delete the specified cue(s).


/workspace/{id}/fullScreen {number}

Number is interpreted as a boolean, and sets whether the workspace is displayed in macOS’ full screen mode. If no argument is provided, this returns the current full screen status of the workspace.


/workspace/{id}/toggleFullScreen

Turn full screen mode on or off.


/workspace/{id}/go {cue_number}

Tell the current cue list of the given workspace to GO. cue_number is optional; if given, it 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.

In this OSC method, QLab cannot use the same technique it uses in other places to turn numbers into strings when necessary. Therefore, when using cue_number in this method, it must always be enclosed in quotation marks.

  • : /go
  • : /go "53"
  • : /go 53

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

Tell QLab to jump to cue cue_number and then GO. cue_number must match a cue number in the given workspace.


/workspace/{id}/lightDashboard {number}

Show or hide the Light Dashboard. number is interpreted as a boolean; 0 equals false, any other number equals true. If no argument is provided, return the current visibility of the Light Dashboard.


/workspace/{id}/toggleLightDashboard

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


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

Move the specified cue 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. new_parent_cue_id is optional, and must be a string.

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

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

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

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

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


/workspace/{id}/new {cue_type}

Create a new cue. cue_type is a string stating which kind 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 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}.

{cart_row} and {cart_column} must be integers.


/workspace/{id}/panic

Tell the workspace to panic. A panic is a brief gradual fade out leading into a hard stop. A double panic will trigger an immediate hard stop.


/workspace/{id}/panicInTime {number}

Panic over the specified time, rather than over the panic time defined in the workspace.


/workspace/{id}/pause

Pause all currently running cues in the workspace.


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

/workspace/{id}/playheadId/{cue_id}

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

/workspace/{id}/playbackPositionId/{cue_id}

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


/workspace/{id}/playhead/next

/workspace/{id}/playbackPosition/next

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


/workspace/{id}/playhead/previous

/workspace/{id}/playbackPosition/previous

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


/workspace/{id}/playhead/nextSequence

/workspace/{id}/playbackPosition/nextSequence

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


/workspace/{id}/playhead/previousSequence

/workspace/{id}/playbackPosition/previousSequence

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


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

Renumber the selected cues, starting at startNumber and incrementing by incrementNumber.


/workspace/{id}/reset

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


/workspace/{id}/resume

Un-pause all paused cues in the workspace.


/workspace/{id}/save

Tell the given workspace to save itself to disk.


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

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

Select the specified cue(s).


/workspace/{id}/select/next

Move the selection down one cue.


/workspace/{id}/select/previous

Move the selection up one cue.


/workspace/{id}/selectionIsPlayhead {number}

Number is interpreted as a boolean, and sets whether the selection is locked to the playhead. If no argument is provided, return whether the selection is currently locked to the playhead.


/workspace/{id}/toggleSelectionIsPlayhead

Lock or unlock the selection to the playhead.


/workspace/{id}/showMode {number}

Number is interpreted as a boolean, and sets whether the workspace is in show mode. If no argument is provided, return whether the workspace is currently in show mode.


/workspace/{id}/toggleEditShowMode

Switch between show mode and edit mode.


/workspace/{id}/stop

Stop playback but allow effects to continue rendering. e.g., playback stops, but reverbs decay naturally.


/workspace/{id}/hardStop

Stop playback and cut all effects immediately.


/workspace/{id}/thump

A simple heartbeat method for this workspace. Returns the data “thump”. (Thump-thump, thump-thump.)


/workspace/{id}/undo

/workspace/{id}/redo

Undo or redo the most recent change of the workspace.


/workspace/{id}/updates {number}

number is interpreted as a boolean. If yes, your client wants push notifications of cue changes. If no, your client no longer wants push notifications of cue changes.


Settings methods

Settings methods can be invoked either on a specific workspace (using the /workspace/{id}/settings/... address pattern) or “rootless”, where the /settings/... address pattern is applied to the current front-most workspace.


/settings/audio/maxVolume

/settings/audio/minVolume

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

Read-only; return a JSON dictionary of output names for Audio or Mic output patches. The keys in the dictionary are the patch numbers, and the values are dictionaries of output channel numbers and names. If a given patch does not have customized output names, that patch will not be included in the dictionary.


/settings/general/minGoTime {number}

If number is given, set the minimum time required between each GO to number seconds. If not, return the minimum time required between each GO.


/settings/video/surfaces

Read-only; return an array of dictionaries describing all video surfaces defined in the workspace.

Each dictionary takes the form:

{
    "surfaceID" : number,
    "surfaceName" : string,
    "width" : number,
    "height" : number,
    "warpType" : number,
    "patchSplitsX": array of numbers,
    "patchSplitsY": array of numbers,
    "screenAssignments": array (see below),
}

Each item in the screenAssignments array is a dictionary in this form:

{
    "name" : string,
    "frame" : string representation of a rectangle (i.e. "{{0,0} {1280,800}}"),
    "enableGrid" : number (BOOL),
    "enableGuides" : number (BOOL),
    "controlPoints" : array containing arrays of string representations of points (i.e. "{0,0}"),
}

/settings/video/surfaces/{surfaceID}

Read-only; return a dictionary for the specified surface. The dictionaries take the same form as above.


/settings/video/surfaces/{surfaceID}/{screenIndex}/enableGrid {number}

Shows or hides the grid display for the specified screen in the specified surface. number is interpreted as a boolean; 0 equals false (don’t show grid), any other number equals true (do show grid.) If no argument is provided, return the current display state of the grid. screenIndex is a range of whole numbers, starting with 0, representing the list of screens assigned to a surface. The first screen listed in the Surface Editor is screenIndex 0, the second is screenIndex 1, and so on.


/settings/video/surfaces/{surfaceID}/{screenIndex}/enableGuides {number}

Shows or hides the guides on the specified screen in the specified surface. number is interpreted as a boolean; 0 equals false (don’t show guides), any other number equals true (do show grid.) If no argument is provided, return the current display state of the guides.


/settings/video/surfaces/{surfaceID}/{screenIndex}/origin {location}

Set the origin point for the specified screen in the specified surface to location. location must be a string of the form: {xPosition,yPosition}, including the curly braces, where xPosition and yPosition are both integers.

If no argument is provided, return the current location of the origin for the specified screen in the specified surface.


/settings/video/surfaces/{surfaceID}/{screenIndex}/controlPoint {row_index} {column_index} {location}

Set the specified control point on the specified screen in the specified surface to location. location must be a string of the form: {xPosition,yPosition}, including the curly braces, where xPosition and yPosition are both integers.

row_index and column_index refer to the grid of control points in their original, unaltered positions.

If no argument is provided, return the current location of the specified control point on the specified screen in the specified surface.


/settings/video/surfaces/{surfaceID}/{screenIndex}/resetControlPoints

Reset all control points for the specified screen in the specified surface.


Cue methods

Cue methods can be invoked either on a specific workspace (using the /workspace/{id}/cue/... address pattern) or “rootless”, where the /cue/... address pattern is applied to the current, front-most workspace.

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 the commands below, any instance of the address pattern /cue/{number} can be replaced by the equivalent unique ID address pattern /cue_id/{id}.

Alternately, 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 {number} or {id}. For example:

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

Increment/Decrement Syntax

Simple number properties of cues can be incremented or decremented with the following syntax:

/cue/1/property/+ {delta}

/cue/1/property/- {delta}

For example, the command /cue/10/preWait/+ 1 would increase the preWait of cue 10 by one second.


/cue/{cue_number}/actionElapsed

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


/cue/{cue_number}/percentActionElapsed

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


/cue/{cue_number}/allowsEditingDuration

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


/cue/{cue_number}/armed {number}

Get or set the armed state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the armed state of the specified cue.


/cue/{cue_number}/autoLoad {number}

Get or set the auto-load state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the auto-load state of the specified cue.


/cue/{cue_number}/cartPosition

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


/cue/{number}/children/shallow

If the specified cue is a list, cart, or Group cue, return the cue numbers of the child cues of that list, cart, or Group. Nested Groups will not be queried, and so only the first “layer” of the cue hierarchy will be returned.


/cue/{number}/children/uniqueIDs

If the specified cue is a list, cart, or Group cue, return the cue IDs of the child cues of that list, cart, or Group, and the cue IDs of any children of nested Groups.


/cue/{number}/children/uniqueIDs/shallow

If the specified cue is a list, cart, or Group cue, return the cue IDs of the child cues of that list, cart, or Group. Nested Groups will not be queried, and so only the first “layer” of the cue hierarchy will be returned.


/cue/{cue_number}/colorName {string}

If string is given, set the color of the specified cue to string. If not, return the pre-wait of the specified cue. Valid colors are none, red, orange, green, blue, and purple. Certain other colors may also be valid…


/cue/{cue_number}/continueMode {number}

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

0 - NO CONTINUE
1 - AUTO CONTINUE
2 - AUTO FOLLOW

/cue/{cue_number}/cueTargetId {string}

If string is given, and if the specified cue can have cue targets, set the target of the specified cue to string. If not, return the cue ID of the target of the specified cue.


/cue/{cue_number}/cueTargetNumber {string}

If string is given, and if the specified cue can have cue targets, set the target of the specified cue to string. If not, return the cue number of the target of the specified cue.


/cue/{cue_number}/currentCueTarget

Read-only; return the cue ID of the current target of the specified cue.


/cue/{cue_number}/go

If the specified cue is not a cue list, tell QLab to jump to cue cue_number and then GO. cue_number must match a cue number in the given workspace.

If the specified cue is a cue list, then 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}/tempCueTargetNumber {string}

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. If string is not given, and the specified cue has a temporary target, return the cue number of that temporary target.


/cue/{cue_number}/tempCueTargetId

This works exactly the same as /tempCueTargetNumber, but uses the cue ID of the target instead of the cue number.


/cue/{cue_number}/currentDuration

Read-only; return the current duration of the specified cue.


/cue/{cue_number}/tempDuration {number}

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. If number is not given, and if the specified cue has a temporary duration, return that temporary duration.


/cue/{cue_number}/currentFileTime

Read-only; if the specified cue has a file target, return the current playback time of the target file in seconds. If the cue is not running, that’s 0. If the cue has been playing for ten and a half seconds, and the playback rate of the cue is 1.0, then the currentFileTime is 10.5.


/cue/{cue_number}/defaultName

Return the default name of the specified cue.


/cue/{cue_number}/displayName

Return the display name of the specified cue.


/cue/{cue_number}/listName

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}/duckLevel {number}

If number is given, set the duck (or boost) level of the specified cue to number. If not, return the duck or boost level of the specified cue.


/cue/{cue_number}/duckOthers {number}

Get or set the state of the Duck audio of other cues checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Duck audio of other cues checkbox of the specified cue.


/cue/{cue_number}/duckTime {number}

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


/cue/{cue_number}/duration {number}

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


/cue/{cue_number}/fadeAndStopOthers {number}

If number is given, set the Fade and stop mode of the specified cue to number. If not, return the Fade and stop mode of the specified cue. Mode 0 is equivalent to the Fade and stop checkbox being unchecked. Valid modes are:

0 - none
1 - peers
2 - list or cart
3 - all

/cue/{cue_number}/fadeAndStopOthersTime {number}

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


/cue/{cue_number}/fileTarget {string}

If string is given, and if the specified cue can have file targets, set the target of the specified cue to string. If not, return the target of the specified cue. You can provide a target using any of three kinds of paths:

  • 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 QLab’s /workingDirectory method to set or get the current working directory.


/cue/{cue_number}/flagged {number}

Get or set the flagged state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the flagged state of the specified cue.


/cue/{cue_number}/hasCueTargets

Read-only; return true if the specified cue is able to target another cue, such as a Fade or Stop cue.


/cue/{cue_number}/hasFileTargets

Read-only; return true if the specified cue is able to target a file, such as an Audio or Video cue.


/cue/{cue_number}/isActionRunning

Read-only; return true if the action of the specified cue (not the pre-wait or post-wait) is running.


/cue/{cue_number}/isBroken

Read-only; return true if the specified cue is broken.


/cue/{cue_number}/isLoaded

Read-only; return true if the specified cue is loaded.


/cue/{cue_number}/isOverridden

Read-only; return true if the specified cue’s output is currently suppressed by an override control.


/cue/{cue_number}/isPanicking

Read-only; return true if the specified cue is panicking.


/cue/{cue_number}/isPaused

Read-only; return true if the specified cue is paused.


/cue/{cue_number}/isRunning

Read-only; return true if the specified cue is running.


/cue/{cue_number}/isTailingOut

Read-only; return true if the specified cue has an AudioUnit which is decaying.


/cue/{cue_number}/load

Load the specified cue.


/cue/{cue_number}/loadAt {number}

If number is given, load the specified cue to number seconds. If not, this command is equivalent to load.


/cue/{cue_number}/loadActionAt {number}

If number is given, load the specified cue to number seconds. QLab will automatically add the pre-wait of the specified cue to number in order to load the cue to the correct time. If no number is given, this command is equivalent to load.


/cue/{cue_number}/loadAndSetPlayhead

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


/cue/{cue_number}/maxTimeInCueSequence

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}

If string is given, set the name of the specified cue to string. If not, return the name of the specified cue.


/cue/{cue_number}/notes {string}

If string is given, set the notes of the specified cue to string. If not, return the notes of the specified cue.


/cue/{cue_number}/number {string}

If string is given, set the cue number of the specified cue to string. If not, return the cue number of the specified cue.


/cue/{cue_number}/panic

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}

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


/cue/{cue_number}/pause

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


/cue/{cue_number}/hardPause

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


/cue/{cue_number}/togglePause

Toggle the paused state of the specified cue. That is, if the cue is playing, this command will pause it. If the cue is paused, this command will resume it. If the specified cue is not playing, this command has no effect.


/cue/{cue_number}/parent

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}/preview

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


/cue/{cue_number}/preWait {number}

If number is given, set the pre-wait of the specified cue to number. If not, return the pre-wait of the specified cue.


/cue/{cue_number}/preWaitElapsed

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


/cue/{cue_number}/percentPreWaitElapsed

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


/cue/{cue_number}/postWait {number}

If number is given, set the post-wait of the specified cue to number. If not, return the post-wait of the specified cue.


/cue/{cue_number}/postWaitElapsed

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


/cue/{cue_number}/percentPostWaitElapsed

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


/cue/{cue_number}/resume

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


/cue/{cue_number}/reset

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}/secondTriggerAction {number}

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

0 - does nothing
1 - panics
2 - stops
3 - hard stops
4 - hard stops & restarts

/cue/{cue_number}/secondTriggerOnRelease {number}

Get or set the state of the Second trigger on release checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Second trigger on release checkbox of the specified cue.


/cue/{cue_number}/soloCueInTime {number}

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 positive whole or decimal number.


/cue/{cue_number}/start

Start the specified cue.


/cue/{cue_number}/startAndAutoloadNext

Start the specified cue and load the following cue or cue sequence if that cue or cue sequence is set to auto-load.


/cue/{cue_number}/stop

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


/cue/{cue_number}/hardStop

HardStop the specified cue. If the specified cue is not playing, this command has no effect. HardStopped cues stop immediately; if the cue has an Audio Effect which ordinarily decays after stopping, such as a reverb, the Audio Effect is also stopped immediately.


/cue/{cue_number}/type

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


/cue/{cue_number}/uniqueID

Return the uniqueID of the specified cue.


/cue/{cue_number}/valuesForKeys {json_string}

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

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

would return the values of opacity and surfaceSize of cue 2, assuming cue 2 is a Video cue.


/cue/{cue_number}/valuesForKeysWithArguments {json_string}

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

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

would return a dictionary that contains the value of the master 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, Cue List, and Cart methods

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


/cue/{cue_number}/cartColumns

/cue/{cue_number}/cartRows

Read-only; if the specified cue is a cart, these messages return the number of rows or columns in the cart.


/cue/{cue_number}/children

Read-only; return a list of the cues contained within the specified Group, list, or cart. Returns the same data as the workspace /cueLists method.


/cue/{cue_number}/go

If the specified cue is a cue list, then 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}/mode {number}

If number is given, set the mode of the specified Group cue. If not, return the mode of the specified Group cue. number must be a whole number from 1 to 4. A cue list will return mode 0, but mode cannot be set to 0. A cue cart will return mode 5, but mode cannot be set to 5.


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

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.


/cue/{cue_number}/playhead {string}

/cue/{cue_number}/playbackPosition {string}

If the specified cue is a cue list, set the playhead (playback position) to cue string. If string is not specified, return the cue number of the standing-by cue, or “none” if there is no cue standing by.


/cue/{cue_number}/playheadId {string}

/cue/{cue_number}/playbackPositionId {string}

If the specified cue is a cue list, set the playhead (playback position) to the cue ID string. If string is none, unset the playhead. If string is not specified, return the cue ID of the standing-by cue, or “none” if there is no cue standing by.


/cue/{cue_number}/playhead/next

If the specified cue is a cue list, move the playhead (playback position) to the next cue.


/cue/{cue_number}/playhead/previous

If the specified cue is a cue list, move the playhead (playback position) to the previous cue.


Audio cue methods

Methods specific to Audio cues.


/cue/{cue_number}/doFade {number}

Get or set the state of the integrated fade curve of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the integrated fade curve of the specified cue.


/cue/{cue_number}/doPitchShift {number}

Get or set the state of the pitch shift checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the pitch shift checkbox of the specified cue.


/cue/{cue_number}/endTime {number}

If number is given, set the end time of the specified cue to number seconds. If not, return the end time of the specified cue. 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}

Get or set a single crosspoint gang.

inChannel is an integer from 0 to 24.

outChannel is either an integer from 0 to 64, or a string (the cue output name).

gang is an optional text string. When present it is the gang to set.

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


/cue/{cue_number}/infiniteLoop {number}

Get or set the infinite loop state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the infinite loop state of the specified cue.


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

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

Get or set a single crosspoint volume level.

inChannel is an integer from 0 to 24. 0 is the master column.

outChannel is either an integer from 0 to 64, or a string (the cue output name). 0 is the master row.

decibel is an optional whole or decimal number. When present it is the decibel value to set.

If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.

If no decibel is given, return the volume level of the specified crosspoint.


/cue/{cue_number}/levels

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: [row0Array, row1Array, row2Array, ...]

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


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

Read-only; return the RMS level of outputChannel. low and high are optional values to re-scale the output of this method. For example, sending the message /cue/1/liveAverageLevel/1 0 100 will return a 0 if the level of output 1 is silent, and 100 if the level of output 1 is as loud as is possible.


/cue/{cue_number}/lockFadeToCue {number}

Get or set the state of the Lock fade to start/end checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Lock fade to start/end checkbox of the specified cue.


/cue/{cue_number}/numChannelsIn

Read-only; return the number of input channels in the specified cue.


/cue/{cue_number}/patch {number}

If number is given, set the patch of the specified cue. If not, return the patch of the specified cue. number must be a whole number from 1 to the number of network destination patches in the workspace.


/cue/{cue_number}/patchList

Read-only; return a list of audio patches defined for this workspace:

[
    {
        "patchNumber": integer,
        "patchName": string
    }
]

/cue/{cue_number}/playCount {number}

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


/cue/{cue_number}/rate {number}

/cue/{cue_number}/liveRate {number}

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

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/setDefaultLevels

Set the audio levels of the specified cue to the workspace default levels.


/cue/{cue_number}/setSilentLevels

Set the audio levels of the specified cue to silent.


/cue/{cue_number}/sliceMarkers

Read-only; return a JSON dictionary (or array of dictionaries) listing the marker time and play count of all slices of the specified cue:

{
    "time": number,
    "playCount": number
}

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



/cue/{cue_number}/sliceMarker {index}

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

Read-only; return a JSON dictionary listing the marker time and play count of slice index of the specified cue. index can be zero or any positive whole number.


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

Read-only; return the marker time of slice index of the specified cue.


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

Read-only; return the play count of slice index of the specified cue.


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

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 not, set the play count to 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}/deleteSliceMarker {index}

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

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


/cue/{cue_number}/deleteSliceMarkers

Delete all slice markers of the specified cue.


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

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

Set the marker time and play count of slice index of the specified cue. 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.


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

Set the marker time of slice index of the specified cue. time can be any positive whole or decimal number.


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

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

Add or subtract delta to/from the marker time of slice index in the specified cue. delta can be any positive whole or decimal number.


/cue/{cue_number}/sliceMarkers/time/+ {delta}

/cue/{cue_number}/sliceMarkers/time/- {delta}

Add or subtract delta to/from the marker time of all slices in the specified cue. delta can be any positive whole or decimal number.


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

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


/cue/{cue_number}/sliceMarker/{index}/playCount/+ {delta}

/cue/{cue_number}/sliceMarker/{index}/playCount/- {delta}

Add or subtract delta to/from the play count of slice index in the specified cue. delta can be any positive whole number.


/cue/{cue_number}/lastSlicePlayCount {play_count}

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


/cue/{cue_number}/lastSliceInfiniteLoop {number}

If number is given, and is any positive whole number, set the last slice of the specified cue to loop infinitely. If number is 0, then set the last slice of the specified cue to not loop. If number is not given, return the infinite loop state of the last slice of the specified cue.


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

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

Get or set a single output slider volume level.

channel is either an integer from 0 to 64, or a string (the cue output name). 0 is the cue master slider.

decibel is an optional whole or decimal number. When present it is the decibel value to set.

If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.

If no decibel is given, return the volume level of the specified output slider.


/cue/{cue_number}/sliderLevels

Read-only; return an array of the output levels of the specified cue, including the cue master. The array is therefore 65 numbers.


/cue/{cue_number}/startTime {number}

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


Mic cue methods

Methods specific to Mic cues. Mic cues also respond to most Audio cue methods.


/cue/{cue_number}/channelOffset

Read-only; return the input channel offset of the specified cue, as set in the Audio Levels tab of the inspector.


/cue/{cue_number}/channels {number}

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


/cue/{cue_number}/setDefaultLevels

Set the audio levels of the specified cue to the workspace default levels.


/cue/{cue_number}/setSilentLevels

Set the audio levels of the specified cue to silent.


Video cue methods

Methods specific to Video cues.


/cue/{cue_number}/cueSize

Read-only; return the natural size of the cue’s video frame:

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

/cue/{cue_number}/doFade {number}

Get or set the state of the integrated fade curve of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the integrated fade curve of the specified cue.


/cue/{cue_number}/doPitchShift {number}

Get or set the state of the pitch shift checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the pitch shift checkbox of the specified cue.


/cue/{cue_number}/doEffect {number}

Get or set the state of the Apply effects checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Apply effects checkbox of the specified cue.


/cue/{cue_number}/effectIndex {number}

If number is given, set the video effect used for the specified cue. If not, return the index number of the video effect used for the specified cue. number can be any of the following:

1  - Color Controls
2  - Exposure
3  - Gamma
4  - Sepia Monochrome
5  - Min Max Invert
6  - White point
7  - Box / Disc / Gaussian Blurs
8  - Motion Blur
9  - Sharpen Luminance
10 - Unsharp Mask
11 - Zoom Blur
12 - Pixellation
13 - Screen
14 - Bloom and Gloom
15 - CMYK Halftone
16 - Color Posterize
17 - Crystallize and Pointillize
18 - Edge Work
19 - Kaleidoscope
20 - Median and Comic Effect
21 - Noise Reduction
22 - Circle Splash / Hole Distortion
23 - Pinch / Bump Distortion
24 - Torus / Lens Distortion
25 - Twirl / Circular Wrap / Vortex
26 - Glass Lozenge
27 - Op Tile
28 - Perspective Tile
29 - Quad Tiles
30 - Reflected Tiles
31 - Rotated Tiles
32 - Titles

Note: /effectIndex replaces /effect which worked in earlier versions of QLab 4, but which was removed for boring technical reasons.


/cue/{cue_number}/effectSet {parameter} {value}

/cue/{cue_number}/liveEffectSet {parameter} {value}

If value is given, set the specified video effect’s parameter to value. If not, return the value of the specified parameter.

parameter must be a string, and must match the name of a parameter of the video effect currently in use for the specified cue. For example, if the specified cue is using the “Color Controls” video effect, then parameter could be “Brightness”, “Contrast”, “Hue Angle”, or “Saturation”.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/endTime {number}

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


/cue/{cue_number}/fullScreen {number}

/cue/{cue_number}/fullSurface {number}

Get or set the full-surface state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the full-surface state of the specified cue.


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

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

Get or set a single crosspoint gang.

inChannel is an integer from 0 to 24.

outChannel is either an integer from 0 to 64, or a string (the cue output name).

gang is an optional text string. When present it is the gang to set.

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


/cue/{cue_number}/holdLastFrame {number}

Get or set the state of the hold last frame checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the hold last frame specified cue.


/cue/{cue_number}/infiniteLoop {number}

Get or set the infinite loop state of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the infinite loop state of the specified cue.


/cue/{cue_number}/layer {number}

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

A number between 0 and 1000, inclusive.


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

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

Get or set a single crosspoint volume level.

inChannel is an integer from 0 to 24. 0 is the master column.

outChannel is either an integer from 0 to 64, or a string (the cue output name). 0 is the master row.

decibel is an optional whole or decimal number. When present it is the decibel value to set.

If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.

If no decibel is given, return the volume level of the specified crosspoint.


/cue/{cue_number}/levels

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: [row0Array, row1Array, row2Array, ...]

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


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

Read-only; return the RMS level of outputChannel. low and high are optional values to re-scale the output of this method. For example, sending the message /cue/1/liveAverageLevel/1 0 100 will return a 0 if the level of output 1 is silent, and 100 if the level of output 1 is as loud as is possible.


/cue/{cue_number}/lockFadeToCue {number}

Get or set the state of the Lock fade to start/end checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Lock fade to start/end checkbox of the specified cue.


/cue/{cue_number}/numChannelsIn

Read-only; return the number of input channels in the specified cue.


/cue/{cue_number}/opacity {number}

If number is given, set the opacity of the specified cue to number. If not, return the opacity of the specified cue. number can be any decimal number between 0 and 1.


/cue/{cue_number}/originX {number}

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


/cue/{cue_number}/originY {number}

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


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

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


/cue/{cue_number}/patch {number}

If number is given, set the patch of the specified cue. If not, return the patch of the specified cue. number must be a whole number from 1 to 8.


/cue/{cue_number}/patchList

Read-only; return a list of audio patches defined for this workspace:

[
    {
        "patchNumber": integer,
        "patchName": string
    }
]

/cue/{cue_number}/playCount {number}

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


/cue/{cue_number}/preserveAspectRatio {number}

Get or set the state of the Preserve aspect ratio checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Preserve aspect ratio checkbox of the specified cue.


/cue/{cue_number}/quaternion {number number number number}

If four numbers are given, set the rotation of the specified cue. If not, return an array of four numbers representing the cue’s rotation as a quaternion. number can be any decimal number. Caution: you need to understand quaternion math to make any meaningful use of this method. Quaternion math is really hard. Good luck!


/cue/{cue_number}/rate {number}

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


/cue/{cue_number}/liveRate {number}

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

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/resetRotation

Reset the rotation of the specified cue.


/cue/{cue_number}/rotateX {number}

/cue/{cue_number}/rotateY {number}

/cue/{cue_number}/rotateZ {number}

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


/cue/{cue_number}/liveRotation/Xaxis {number}

/cue/{cue_number}/liveRotation/Yaxis {number}

/cue/{cue_number}/liveRotation/Zaxis {number}

/cue/{cue_number}/liveRotation/x {number}

/cue/{cue_number}/liveRotation/y {number}

/cue/{cue_number}/liveRotation/z {number}

Rotate the specified cue by number degrees in the X, Y, or Z axis. These are equivalent to using a Fade cue in single-axis mode to rotate the specified cue.

These “live” methods have no non-live counterparts. They operate on the active, “live” value of a running cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/scaleX {number}

/cue/{cue_number}/liveScaleX {number}

If number is given, set the X-axis scale of the specified cue to number. If not, return the X-axis scale of the specified cue. number can be any decimal number.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/scaleY {number}

/cue/{cue_number}/liveScaleY {number}

If number is given, set the Y-axis scale of the specified cue to number. If not, return the Y-axis scale of the specified cue. number can be any decimal number.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


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

/cue/{cue_number}/liveScale {x} {y}

If x and y are given, set the scale of the specified cue to (x,y). If not, return the current scale of the specified cue. x and y can be any decimal numbers.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/setDefaultLevels

Set the audio levels of the specified cue to the workspace default levels.


/cue/{cue_number}/setSilentLevels

Set the audio levels of the specified cue to silent.


/cue/{cue_number}sliceMarkers

Read-only; return a JSON dictionary (or array of dictionaries) listing the marker time and play count of all slices of the specified cue:

{
    "time": number,
    "playCount": number
}

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



/cue/{cue_number}/sliceMarker {index}

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

Read-only; return a JSON dictionary listing the marker time and play count of slice index of the specified cue. index can be zero or any positive whole number.


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

Read-only; return the marker time of slice index of the specified cue.


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

Read-only; return the play count of slice index of the specified cue.


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

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 not, set the play count to 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}/deleteSliceMarker {index}

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

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


/cue/{cue_number}/deleteSliceMarkers

Delete all slice markers of the specified cue.


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

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

Set the marker time and play count of slice index of the specified cue. 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.


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

Set the marker time of slice index of the specified cue. time can be any positive whole or decimal number.


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

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

Add or subtract delta to/from the marker time of slice index in the specified cue. delta can be any positive whole or decimal number.


/cue/{cue_number}/sliceMarkers/time/+ {delta}

/cue/{cue_number}/sliceMarkers/time/- {delta}

Add or subtract delta to/from the marker time of all slices in the specified cue. delta can be any positive whole or decimal number.


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

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


/cue/{cue_number}/sliceMarker/{index}/playCount/+ {delta}

/cue/{cue_number}/sliceMarker/{index}/playCount/- {delta}

Add or subtract delta to/from the play count of slice index in the specified cue. delta can be any positive whole number.


/cue/{cue_number}/lastSlicePlayCount {play_count}

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


/cue/{cue_number}/lastSliceInfiniteLoop {number}

If number is given, and is any positive whole number, set the last slice of the specified cue to loop infinitely. If number is 0, then set the last slice of the specified cue to not loop. If number is not given, return the infinite loop state of the last slice of the specified cue.


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

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

Get or set a single output slider volume level.

channel is either an integer from 0 to 64, or a string (the cue output name). 0 is the cue master slider.

decibel is an optional decimal number. When present it is the decibel value to set.

If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.

If no decibel is given, return the volume level of the specified output slider.


/cue/{cue_number}/sliderLevels

Read-only; return an array of the output levels of the specified cue, including the cue master. The array is therefore 65 numbers.


/cue/{cue_number}/startTime {number}

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


/cue/{cue_number}/surfaceID {number}

If number is given, set the surface of the specified cue. If not, return the surface ID of the surface of the specified cue.


/cue/{cue_number}/surfaceList

Read-only; return a list of surfaces defined for this workspace:

[
    {
        "surfaceName": string,
        "surfaceID": number
    }
]

/cue/{cue_number}/surfaceName {string}

If string is given, assign the specific cue to surface string. If not, return the name of the surface to which the specified cue is assigned. string must be the name of a surface in this workspace.


/cue/{cue_number}/surfaceSize

Read-only; returns the size of the cue’s display surface:

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

/cue/{cue_number}/translationX {number}

/cue/{cue_number}/liveTranslationX {number}

If number is given, set the X-axis translation of the specified cue to number. If not, return the X-axis translation of the specified cue. number can be any decimal number.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/translationY {number}

/cue/{cue_number}/liveTranslationY {number}

If number is given, set the Y-axis translation of the specified cue to number. If not, return the Y-axis translation of the specified cue. number can be any decimal number.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


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

/cue/{cue_number}/liveTranslation {x} {y}

If x and y are given, set the translation of the specified cue to (x,y). If not, return the current translation of the specified cue. x and y can be any decimal numbers.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


Camera cue methods

Methods specific to Camera cues. Camera cues also respond to most Video cue methods.


/cue/{cue_number}/cameraPatch

If number is given, set the camera patch of the specified cue. If not, return the camera patch of the specified cue. number must be a whole number from 1 to 8.


Text cue methods

Methods specific to Text cues. Text cues also respond to most Video cue methods.


/cue/{cue_number}/fixedWidth {number}

If number is given, and is greater than 0, set the fixed width of the specified cue to number. If number equals 0, set the width of the specified cue to automatic. If no number is given, return the width of the specified cue. number can be any positive whole or decimal number.


/cue/{cue_number}/text {string}

/cue/{cue_number}/liveText {string}

If string is given, set the text of the specified cue to string. If not, return the text of the specified cue. When setting text, the formatting will match the first character of the existing text.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


/cue/{cue_number}/text/format {json_string}

If json_string is given, this command can be used to set the formatting of one or more substrings of the specified cue. For example:

[
  {
    "fontFamily": string,
    "fontStyle": string,
    "fontName": string,
    "fontSize": number,
    "lineSpacing": number,
    "color": array of numbers representing RGBA percentage values,
    "range": optional array of numbers/percent strings representing a substring at [index, length]
  },
  { ... },
  { ... }
]

If json_string is not given, return an array of JSON dictionaries describing each substring in the text of the specified cue. A substring, in this case, is defined as a subset of the text with uniform format attributes. If the entire text string is uniformly formatted, the array will have only one dictionary.


/cue/{cue_number}/text/format/alignment {alignment}

If alignment is given, set the text alignment of the specified cue to alignment. If not, return the alignment of the specified cue. alignment may be left, center, right, or justify.


/cue/{cue_number}/text/format/fontFamily

Read-only; return the font family name (“Helvetica”, “Courier New”, etc.) used in the specified cue.

You may optionally send this command in the form: /cue/{cue_number}/text/format/fontFamily/{index}/{length}, in which index is a whole number or a percentage string (e.g. 53%) which lets you specify the start of a substring, and length is a number or percentage string which specifies the length of that substring. The first character is index 0. For example:

/cue/1/text/format/fontFamily/4/12 will return the font family name used for characters 5 through 17 of cue 1.

You may set length to -1 to specify “to end the of the string.”

You may also optionally send this command in the form: /cue/{cue_number}/text/format/fontFamily/word/{word_index}, in which word_index is a whole number which specifies a single word within the text of the cue. The first word is word 0.


/cue/{cue_number}/text/format/fontStyle

Read-only; return the style (“Bold Oblique”, “Regular”, etc.) used in the specified cue.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/format/fontFamilyAndStyle {family} {style}

If family and style are given, set the font family and style of the text of the specified cue to family and style. Otherwise, return the font family and style for the specified cue. Individual commands for font family and style are not available because the combination of both values is required to reliably describe an individual font.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/format/fontName {name}

If name is given, set the font of the text of the specified cue. If not, return the name of the font used for the specified cue.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/format/fontSize {number}

If number is specified, set the font size of the text of the specified cue to number. If not, return the font size of the text of the specified cue.

This command may use increment and decrement syntax as described above.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/format/lineSpacing {number}

If number is specified, set the line spacing of the text of the specified cue to number. If not, return the line spacing of the text of the specified cue.

This command may use increment and decrement syntax as described above.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily, although it only works if you index the first word or character in a line. It’s also important to remember that the invisible “return” character at the end of a line (created by pressing the “return” key) counts as a character.


/cue/{cue_number}/text/format/color {red} {green} {blue} {alpha}

/cue/{cue_number}/text/format/backgroundColor {red} {green} {blue} {alpha}

/cue/{cue_number}/text/format/strikethroughColor {red} {green} {blue} {alpha}

/cue/{cue_number}/text/format/underlineColor {red} {green} {blue} {alpha}

If red, green, blue, and alpha are specified, set the given color attribute of the specified cue to the corresponding color. If not, return the color for the given attribute of the specified cue. red, green, blue, and alpha can be decimal numbers between 0.0 and 1.0, where 1.0 is the maximum level. Thus, 1 0 0 1 is primary red, and 1 1 1 0.5 is white at 50% transparency.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/format/strikethroughStyle {style}

/cue/{cue_number}/text/format/underlineStyle {style}

If style is given, set the strikethrough or underline style of the text of the specified cue to style. Otherwise, return the strikethrough or underline style for the specified cue. style may be none, single, or double.

This command may also use the optional /{index}/{length} and /word/{word_index} forms as described above in the entry for /cue/{cue_number}/text/format/fontFamily.


/cue/{cue_number}/text/outputSize

/cue/{cue_number}/liveText/outputSize

Read-only; return a two-item array containing the width and height of the text or liveText of the specified cue.

“Live” methods are the same as their non-live counterparts, but operate on the active, “live” value of a running cue, rather than changing the “start state” of the cue. Invoking these methods does not cause the document to have unsaved changes.


Light cue methods

Methods specific to Light cues.


/cue/{cue_number}/alwaysCollate {number}

Get or set the state of the Always collate checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Always collate specified cue.


/cue/{cue_number}/collateAndStart

Collate and start the specified cue.


/cue/{cue_number}/lightCommandText {string}

If string is given, set the full command text of the specified cue to string. If not, return the full command text of the specified cue.


/cue/{cue_number}/prune

/cue/{cue_number}/pruneCommands

Prune the command text of the specified cue. Pruning removes any commands which have no effect. These two commands are equivalent.


/cue/{cue_number}/removeLightCommandsMatching {string}

If the specified cue contains a command that matches string, remove that command. Otherwise, do nothing.


/cue/{cue_number}/replaceLightCommand {old_command} {new_command}

If the specified cue contains a light command matching old_command, replace that command with new_command. Both old_command and new_command must be strings which are valid light commands.

This method replaces /updateLightCommand starting in QLab 4.4.


/cue/{cue_number}/safeSort

/cue/{cue_number}/safeSortCommands

Lexically (alphabetically) sort the command text of the specified cue, as long as sorting doesn’t change the cue’s output. These two commands are equivalent.


/cue/{cue_number}/setLight {string} {setting}

Add a command to the specified cue in the form string = setting. string can be the name of an instrument or group, with or without a parameter. setting must be an acceptable value for the specified parameter of the specified instrument or group.


/cue/{cue_number}/updateLightCommand {string} {number}

If the specified cue contains a command for the instrument or group string, then update that command to the specified value number. If the specified cue does not contain a command for the instrument or group string, then add a command in the form string = number. string can be the name of an instrument or group, with or without a parameter. number must be an acceptable value for the specified instrument or group.

This method is deprecated starting in QLab 4.4, and is replaced by /replaceLightCommand.


Fade cue methods

Methods specific to Fade cues.


/cue/{cue_number}/doOpacity {number}

/cue/{cue_number}/doRate {number}

/cue/{cue_number}/doRotation {number}

/cue/{cue_number}/doScale {number}

/cue/{cue_number}/doTranslation {number}

Get or set the state of the geometry parameter checkboxes of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the relevant geometry parameter checkbox of the specified cue.


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

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

If gang is given, set the gang of crosspoint (inChannel, outChannel) of the specified cue to gang. If not, return the gang of crosspoint (inChannel, outChannel) of the specified cue.

inChannel must be a whole number between 0 and 24; outChannel must be a whole number between 0 and 64. 0 is the master column or row.

decibel, if given, must be a whole number, decimal number, or a string. If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.


/cue/{cue_number}/geoMode {number}

If number is given, set the geometry fade mode of the specified cue. Mode 0 is absolute fade, mode 1 is relative fade. If number is not given, return the geometry fade mode of the specified cue.


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

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

If decibel is given, set the level of crosspoint (inChannel, outChannel) of the specified cue to decibel. If not, return the level of crosspoint (inChannel, outChannel) of the specified cue.

inChannel must be a whole number between 0 and 24; outChannel must be a whole number between 0 and 64. 0 is the master column or row.

decibel, if given, must be a whole number, decimal number, or a string. If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.


/cue/{cue_number}/levels

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: [row0Array, row1Array, row2Array, ...]

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


/cue/{cue_number}/mode {number}

If number is given, set the fade mode of the specified cue. Mode 0 is absolute fade, mode 1 is relative fade. If number is not given, return the fade mode of the specified cue.


/cue/{cue_number}/opacity {number}

If number is given, set the opacity of the specified cue to number. If not, return the opacity of the specified cue. number can be any decimal number between 0 and 1.


/cue/{cue_number}/preserveAspectRatio {number}

Get or set the state of the Preserve aspect ratio checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Preserve aspect ratio checkbox of the specified cue.


/cue/{cue_number}/quaternion {number number number number}

If four numbers are given, set the rotation of the specified cue. If not, return an array of four numbers representing the cue’s rotation as a quaternion. number can be any decimal number. Caution: you need to understand quaternion math to make any meaningful use of this method. Quaternion math is really hard. Good luck!


/cue/{cue_number}/rate {number}

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


/cue/{cue_number}/resetRotation

Reset the rotation of the specified cue. If the specified cue is using single-axis rotation, this has no visible effect; use /rotation instead.


/cue/{cue_number}/rotateX {number}

/cue/{cue_number}/rotateY {number}

/cue/{cue_number}/rotateZ {number}

If the specified cue is using 3D orientation, add number to the current quaternion rotation of the specified cue. number can be any decimal number. If the specified cue is using single-axis rotation, this method has no effect; use /rotation instead.


/cue/{cue_number}/rotation {number}

If number is given, and if the specified cue is using single-axis rotation, set the rotation in degrees to number. If no number is given, return the current rotation of the specified cue. For 3D orientation, use /quaternion or /rotate{N}.


/cue/{cue_number}/rotationType {number}

If number is given, set the rotation type of the specified cue to number. If not, return the rotation type of the specified cue. Valid rotation types are:

0 - 3D orientation
1 - X rotation
2 - Y rotation
3 - Z rotation

/cue/{cue_number}/scaleX {number}

If number is given, set the X-axis scale of the specified cue to number. If not, return the X-axis scale of the specified cue. number can be any decimal number.


/cue/{cue_number}/scaleY {number}

If number is given, set the Y-axis scale of the specified cue to number. If not, return the Y-axis scale of the specified cue. number can be any decimal number.


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

If x and y are given, set the scale of the specified cue to (x,y). If not, return the current scale of the specified cue. x and y can be any decimal numbers.


/cue/{cue_number}/setLevelsFromTarget

Set the audio levels, trim, and gangs of the specified cue to match those of its target. If the target cue has no audio levels then this command has no effect.


/cue/{cue_number}/setSilentLevels

Set the audio levels of the specified cue to silent.


/cue/{cue_number}/setGeometryFromTarget

Set the geometry of the specified cue to the geometry of its target cue. If the target cue has no geometry then this command has no effect.


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

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

Get or set a single output slider volume level.

channel is either an integer from 0 to 64, or a string (the cue output name). 0 is the cue master slider.

decibel is an optional whole or decimal number. When present it is the decibel value to set.

If decibel is sent as a string (e.g. “-inf”) QLab will use the minimum decibel value set in workspace settings.

If no decibel is given, return the volume level of the specified output slider.


/cue/{cue_number}/sliderLevels

Read-only; return an array of the output levels of the specified cue, including the cue master. The array is therefore 65 numbers.


/cue/{cue_number}/stopTargetWhenDone {number}

Get or set the state of the Stop target when done checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Stop target when done checkbox of the specified cue.


/cue/{cue_number}/translationX {number}

If number is given, set the X-axis translation of the specified cue to number. If not, return the X-axis translation of the specified cue. number can be any decimal number.


/cue/{cue_number}/translationY {number}

If number is given, set the Y-axis translation of the specified cue to number. If not, return the Y-axis translation of the specified cue. number can be any decimal number.


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

If x and y are given, set the translation of the specified cue to (x,y). If not, return the current translation of the specified cue. x and y can be any decimal numbers.


/cue/{cue_number}/willFade {row} {column} {number}

If number, row and column are all given, set the active state (i.e. yellow or grey) of crosspoint {row,column}. number is interpreted as a boolean; 0 equals false, any other number equals true. row and column must be whole numbers.

If row and column are given, but not number, return the active state of crosspoint {row,column}. If no arguments are given, return all the currently active crosspoints in the specified cue. The levels are returned as an array of arrays, like so: [row0Array, row1Array, row2Array, ...]


Network cue methods

Methods specific to Network cues.


/cue/{cue_number}/customString {string}

If string is given, set the OSC message of the specified cue to string. If not, return the OSC message of the specified cue.


/cue/{cue_number}/messageType {number}

If number is given, set the message type of the specified cue to number. If not, return the message type of the specified cue. Valid message types are:

1 - QLab message
2 - OSC message
3 - UDP message

/cue/{cue_number}/qlabCommand {number}

If number is given, set the QLab command of the specified cue to number. If not, return the message type of the specified cue. Valid QLab commands are:

1  - start
2  - stop
3  - hardStop
4  - pause
5  - resume
6  - togglePause
7  - load
8  - preview
9  - reset
10 - panic
11 - number
12 - name
13 - notes
14 - cueTargetNumber
15 - preWait
16 - duration
17 - postWait
18 - continueMode
19 - flagged
20 - armed
21 - colorName

/cue/{cue_number}/patch {number}

If number is given, set the OSC patch of the specified cue to number. If not, return the OSC patch of the specified cue. number must be a whole number from 1 to 16, inclusive.


/cue/{cue_number}/qlabCueNumber {string}

If string is given, set the target cue number for the command of the specified cue to string. If not, return the target cue number of the command of the specified cue.


/cue/{cue_number}/qlabCueParameters {string}

If string is given, set the parameters for the command of the specified cue to string. If not, return the parameters of the command of the specified cue.


/cue/{cue_number}/rawString {string}

/cue/{cue_number}/udpString {string}

If string is given, set the UDP string of the specified cue to string. If not, return the UDP string of the specified cue.


MIDI cue methods

Methods specific to MIDI cues.


/cue/{cue_number}/byte1 {number}

If number is given, set byte 1 of the MIDI message of the specified cue to number. If not, return byte 1 of the MIDI message of the specified cue. number must be a whole number from 0 to 127.


/cue/{cue_number}/byte2 {number}

If number is given, set byte 2 of the MIDI message of the specified cue to number. If not, return byte 2 of the MIDI message of the specified cue. number must be a whole number from 0 to 127.


/cue/{cue_number}/byteCombo {number}

If number is given, set both bytes of the MIDI message of the specified cue based on number. If not, return the value of bytes 1 and 2 (as a single number) of the MIDI message of the specified cue. number must be a whole number from 0 to 16383.


/cue/{cue_number}/channel {number}

If number is given, set the MIDI channel of the specified cue to number. If not, return the MIDI channel of the specified cue. number must be a whole number from 1 to 16.


/cue/{cue_number}/command {number}

If number is given, set the MSC command of the specified cue to number. If not, return the MSC command of the specified cue. number must be a whole number from 0 to 127, but only the following values are meaningful:

1  - GO
2  - STOP
3  - RESUME
4  - TIMED_GO
5  - LOAD
6  - SET
7  - FIRE
8  - ALL_OFF
9  - RESTORE
10 - RESET
11 - GO_OFF
16 - GO/JAM_CLOCK
17 - STANDBY_+
18 - STANDBY_-
19 - SEQUENCE_+
20 - SEQUENCE_-
21 - START_CLOCK
22 - STOP_CLOCK
23 - ZERO_CLOCK
24 - SET_CLOCK
25 - MTC_CHASE_ON
26 - MTC_CHASE_OFF
27 - OPEN_CUE_LIST
28 - CLOSE_CUE_LIST
29 - OPEN_CUE_PATH
30 - CLOSE_CUE_PATH

/cue/{cue_number}/commandFormat {number}

If number is given, set the MSC command format of the specified cue to number. If not, return the MSC command format of the specified cue. number must be a whole number from 0 to 127, but only the following values are meaningful:

127 - All Types
1   - Lighting (General)
2   - Moving Lights
3   - Color Changers
4   - Strobes
5   - Lasers
6   - Chasers
16  - Sound (General)
17  - Music
18  - CD Players
19  - EPROM Playback
20  - Audio Tape Machines
21  - Intercoms
22  - Amplifiers
23  - Audio Effects Devices
24  - Equalizers
32  - Machinery (General)
33  - Rigging
34  - Flys
35  - Lifts
36  - Turntables
37  - Trusses
38  - Robots
39  - Animation
40  - Floats
41  - Breakaways
42  - Barges
48  - Video (General)
49  - Video Tape Machines
50  - Video Cassette Machines
51  - Video Disc Players
52  - Video Switchers
53  - Video Effects
54  - Video Character Generators
55  - Video Still Stores
56  - Video Monitors
64  - Projection (General)
65  - Film Projectors
66  - Slide Projectors
67  - Video Projectors
68  - Dissolvers
69  - Shutter Controls
80  - Process Control (General)
81  - Hydraulic Oil
82  - H2O
83  - CO2
84  - Compressed Air
85  - Natural Gas
86  - Fog
87  - Smoke
88  - Cracked Haze
96  - Pyrotechnics (General)
97  - Fireworks
98  - Explosions
99  - Flame
100 - Smoke Pots

/cue/{cue_number}/controlNumber {number}

If number is given, set the MSC control number of the specified cue to number. If not, return the MSC control number of the specified cue. number must be a whole number from 0 to 16383.


/cue/{cue_number}/controlValue {number}

If number is given, set the MSC control value of the specified cue to number. If not, return the MSC control value of the specified cue. number must be a whole number from 0 to 16383.


/cue/{cue_number}/deviceID {number}

If number is given, set the outgoing MSC device ID of the specified cue to number. If not, return the outgoing MSC device ID of the specified cue. number must be a whole number from 0 to 127.


/cue/{cue_number}/doFade {number}

Get or set the state of the MIDI fade checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the MIDI fade checkbox of the specified cue.


/cue/{cue_number}/endValue {number}

If number is given, set the fade ending value of the MIDI message of the specified cue to number. If not, return the fade ending value of the MIDI message of the specified cue. number must be a whole number from 0 to 127, unless the message type of the specified cue is pitch bend, in which case number must be a whole number between 0 and 16383.


/cue/{cue_number}/hours {number}

/cue/{cue_number}/minutes {number}

/cue/{cue_number}/seconds {number}

/cue/{cue_number}/frames {number}

/cue/{cue_number}/subframes {number}

If number is given, set the appropriate section of the MSC timecode of the specified cue to number. If not, return the appropriate section of MSC timecode hours of the specified cue.


/cue/{cue_number}/macro {number}

If number is given, set the MSC macro of the specified cue to number. If not, return the MSC macro of the specified cue. number must be a whole number from 0 to 127.


/cue/{cue_number}/messageType {number}

If number is given, set the message type of the specified cue to number. If not, return the message type of the specified cue. Valid message types are:

1 - MIDI Voice Message ("Musical MIDI")
2 - MIDI Show Control Message (MSC)
3 - MIDI SysEx Message

/cue/{cue_number}/patch {number}

A number from 1 to 8.


/cue/{cue_number}/qList {string}

If number is given, set the outgoing MSC cue list number of the specified cue to number. If not, return the outgoing MSC cue list number of the specified cue.


/cue/{cue_number}/qNumber {string}

If number is given, set the outgoing MSC cue number of the specified cue to number. If not, return the outgoing MSC cue number of the specified cue.


/cue/{cue_number}/qPath {string}

If number is given, set the outgoing MSC cue path number of the specified cue to number. If not, return the outgoing MSC cue path number of the specified cue.


/cue/{cue_number}/rawString {string}

If string is given, set the MIDI SysEx of the specified cue to string. If not, return the MIDI SysEx string of the specified cue. string must be a valid SysEx string, formatted in hexadecimal, and omitting the starting F0 and ending F7.


/cue/{cue_number}/status {number}

If number is given, set the MIDI message type of the specified cue to number. If not, return the MIDI message type of the specified cue. Valid message types are:

0 - Note Off
1 - Note On
2 - Key Pressure (Aftertouch)
3 - Control Change
4 - Program Change
5 - Channel Pressure Change
6 - Pitch Bend Change

/cue/{cue_number}/timecodeFormat {number}

If number is given, set the MSC timecode format of the specified cue to number. If not, return the MSC timecode format of the specified cue. Valid formats are:

0 - 24 fps
1 - 25 fps
2 - 30 fps drop
3 - 30 fps non-drop

/cue/{cue_number}/timecodeString {string}

If number is given, set the MSC timecode string of the specified cue to number. If not, return the MSC timecode string of the specified cue.


MIDI file cue methods

Methods specific to MIDI File cues.


/cue/{cue_number}/patch {number}

If number is given, set the patch of the specified cue. If not, return the patch of the specified cue. number must be a whole number from 1 to 8.


/cue/{cue_number}/rate {number}

If number is given, set the rate of the specified cue. If not, return the rate of the specified cue.


Devamp cue methods

Methods specific to Devamp cues.


/cue/{cue_number}/startNextCueWhenSliceEnds {number}

Get or set the state of the Start next cue when slice ends checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Start next cue when slice ends checkbox of the specified cue.


/cue/{cue_number}/stopTargetWhenSliceEnds {number}

Get or set the state of the Stop target when slice ends checkbox of the specified cue. number is interpreted as a boolean; 0 equals false, any other number equals true. If no number is given, return the state of the Stop target when slice ends checkbox of the specified cue.


Script cue methods

Methods specific to Script cues.


/cue/{cue_number}/compileSource

Compile the script of the specified cue.


/cue/{cue_number}/scriptSource

Read-only; return the contents of the script of the specified cue.

Still have a question?

Our support team is always happy to help.

Business Hours
M-F 9am-7pm (ET)
Current time at our headquarters