Scripting

QLab's AppleScript Dictionary

The list of commands, functions, and properties that AppleScript can use to interact with an application is called that application's dictionary. You can find QLab's AppleScript dictionary here, or view it within the Script Editor application, which is found in /Applications/Utilities.

In Script Editor, choose Open Dictionary... from the File menu, and choose QLab from the list of applications.

The dictionary is grouped by "suite"; all applications that use AppleScript must include the Standard Suite, and then any application-specific commands or properties are generally grouped together into another suite named after the application.

continue modes

enum : Continue mode of a cue.

  • do_not_continue : Do not automatically continue to the next cue.
  • auto_continue : Automatically continue to the next cue after completing the post wait.
  • auto_follow : Automatically continue to the next cue after completing the action of the cue.

group modes

enum

  • cue_list : The group is a cue list.
  • fire_first_enter_group : Fire first child and enter into group.
  • fire_first_go_to_next_cue : Fire first child and go to next cue.
  • fire_all : Fire all children simultaneously.
  • fire_random : Fire a random child cue and then go to the next cue.

smpte format

enum : SMPTE timecode format.

  • fps_24 : 24 frames per second
  • fps_25 : 25 frames per second
  • fps_30_drop : 30 frames per second (drop frame)
  • fps_30_non_drop : 30 frames per second (non-drop)

osc type

enum

  • qlab : QLab OSC message.
  • custom : Custom OSC message.
  • udp : Raw UDP message.

mtc ltc

enum

  • mtc : MIDI Timecode
  • ltc : Linear / Logitudinal Timecode

midi type

enum

  • voice : MIDI Voice message ("Musical MIDI").
  • msc : MIDI Show Control message.
  • sysex : MIDI Sysex message.

midi command

enum

  • note_on : Note on.
  • note_off : Note off.
  • program_change : Program change.
  • control_change : Control change.
  • key_pressure : Key pressure (aftertouch).
  • channel_pressure : Channel pressure.
  • pitch_bend : Pitch bend (pitch wheel).

workspace

n [inh. document] : A QLab workspace.

Elements

  • contains cue lists, cues.

Properties

  • unique id (text, r/o) : The unique ID of the workspace.
  • current cue list (cue list) : The currently visible cue list for the workspace.
  • selected (list of cue) : The currently selected cue(s) in the currently visible cue list.
  • active cues (list of cue, r/o) : The list of active cues (running or paused) in this workspace.
  • edit mode (boolean) : Is the workspace currently in edit mode?
  • show mode (boolean) : Is the workspace currently in show mode?
  • live fade preview (enabled, disabled) : Live Fade Preview

Responds to

make, load, go, start, pause, stop, hardStop, reset, panic, moveSelectionUp, moveSelectionDown.

Inherited from document:

Elements

  • contained by application.

Properties

  • path (text) : The document's path.
  • modified (boolean, r/o) : Has the document been modified since the last save?
  • name (text) : The document's name.

Responds to

  • close, print, save.

cue

n : A cue.

Elements

  • contains cues; contained by workspaces, cues.

Properties

  • uniqueID (text, r/o) : The unique ID of the cue.
  • parent (cue, r/o) : The parent cue of this cue.
  • q type (text, r/o) : The name of this kind of cue, e.g. "Audio", "Video", "MIDI", etc.
  • q number (text) : The number of the cue. Unique if present.
  • q name (text) : The name of the cue. Not unique.
  • q list name (text, r/o) : The name of the cue as displayed in the cue list. (i.e. Might be a default name.)
  • q display name (text, r/o) : The name of the cue as displayed in the standby view. (i.e. Never empty.)
  • q default name (text, r/o) : The name QLab would give the cue by default, if any.
  • notes (text) : The notes for this cue.
  • cue target (cue) : The cue this cue targets, if any.
  • file target (file) : The file this cue targets, if any.
  • pre wait (real) : The time in seconds before the action is triggered.
  • duration (real) : The duration of the cue's action in seconds. Not editable for all cue types.
  • post wait (real) : The time in seconds until continuing on to the next cue.
  • continue mode (do_not_continue, auto_continue, auto_follow) : Continue mode of the cue.
  • flagged (boolean) : Is this cue flagged?
  • autoload (boolean) : Does this cue auto load?
  • armed (boolean) : Is this cue armed?
  • hotkey trigger (enabled, disabled) : State of the HotKey trigger.
  • midi trigger (enabled, disabled) : State of the MIDI trigger.
  • midi command (note_on, note_off, program_change, control_change, key_pressure, channel_pressure, pitch_bend) : Type of MIDI command that will trigger the cue. (NOTE: pitch_bend messages are NOT accepted as remote MIDI triggers.)
  • midi byte one (integer) : Byte 1 of the MIDI trigger.
  • midi byte two (integer) : Byte 2 of the MIDI trigger.
  • midi byte one string (text) : Display String of Byte 1 of the MIDI trigger.
  • midi byte two string (text) : Display String of Byte 2 of the MIDI trigger.
  • timecode trigger (enabled, disabled) : State of the timecode trigger.
  • wall clock trigger (enabled, disabled) : State of the wall clock trigger.
  • wall clock hours (integer) : Hours field of the wall clock trigger.
  • wall clock minutes (integer) : Minutes field of the wall clock trigger.
  • wall clock seconds (integer) : Seconds field of the wall clock trigger.
  • loaded (boolean, r/o) : Is this cue loaded?
  • running (boolean, r/o) : Is this cue running?
  • paused (boolean, r/o) : Is this cue paused?
  • broken (boolean, r/o) : Is this cue broken?
  • pre wait elapsed (real, r/o) : The time in seconds that have elapsed on the pre wait.
  • action elapsed (real, r/o) : The time in seconds that have elapsed in the action of the cue.
  • post wait elapsed (real, r/o) : The time in seconds that have elapsed on the post wait.
  • percent pre wait elapsed (real, r/o) : The percent of the pre wait that has elapsed.
  • percent action elapsed (real, r/o) : The percent of the cue's action that has elapsed.
  • percent post wait elapsed (real, r/o) : The percent of the post wait that has elapsed.

Responds to

  • load, preview, start, pause, stop, hardStop, reset, panic.

group cue

n [inh. cue] : A Group Cue.

Properties

  • mode (cue_list, fire_first_enter_group, fire_first_go_to_next_cue, fire_all, fire_random) : The firing style of this group.

cue list

n [inh. group cue > cue] : A cue list.

Elements

  • contained by workspaces.

Properties

  • playback position (cue) : The playback position of this cue list is the cue that will fire at the next GO.
  • sync to timecode (enabled, disabled) : Sync the cues in this cue list to incoming timecode.
  • sync mode (mtc, ltc) : Which kind of incoming timecode this cue list listens for.
  • smpte format (fps_24, fps_25, fps_30_drop, fps_30_non_drop) : SMPTE format of the incoming timecode.
  • mtc sync source name (text) : Name of the MIDI device which feeds us MTC timecode.
  • ltc sync channel (integer) : Audio channel that carries the LTC signal.

audio cue

n [inh. cue] : An Audio Cue.

Properties

  • patch (integer) : Audio device patch number.
  • start time (real) : Time in the file where playback begins.
  • end time (real) : Time in the file where playback ends.
  • play count (integer) : Number of times the audio between the start and end times plays. Always >= 1.
  • infinite loop (boolean) : Does the cue loop infinitely?
  • rate (real) : Playback rate of the audio cue.
  • integrated fade (enabled, disabled) : State of the integrated fade - enabled or disabled.
  • audio input channels (integer, r/o) : The number of audio input channels for the cue. (i.e. The number of distinct channels in the file.)
  • pitch shift (enabled, disabled) : Whether pitch shifting is enabled or disabled.

Responds to

  • getLevel, setLevel, getGang, setGang.

mic cue

n [inh. cue] : A Microphone Cue.

Properties

patch (integer) : Audio device patch number. audio input channels (integer, r/o) : The number of audio input channels for the cue.

Responds to

getLevel, setLevel, getGang, setGang.

video cue

n [inh. cue] : A Video Cue.

Properties

  • patch (integer) : Audio device patch number.
  • start time (real) : Time in the file where playback begins.
  • end time (real) : Time in the file where playback ends.
  • infinite loop (boolean) : Does the cue loop infinitely?
  • rate (real) : Playback rate of the video cue.
  • layer (integer) : Display layer of the video.
  • full screen (boolean) : Is the cue displaying in full screen mode?
  • preserve aspect ratio (boolean) : Does the cue preserve aspect ratio?
  • opacity (real) : Video opacity.
  • translation x (real) : Translation along the x axis.
  • translation y (real) : Translation along the y axis.
  • scale x (real) : Scale along the x axis.
  • scale y (real) : Scale along the y axis.
  • do video effect (boolean) : Apply a video effect?
  • custom quartz file (file) : The custom Quartz Composer file used to render this cue.
  • audio input channels (integer, r/o) : The number of audio input channels for the cue. (i.e. The number of distinct channels in the file.)
  • pitch shift (enabled, disabled) : Whether pitch shifting is enabled or disabled.
  • hold at end (boolean) : Should the final frame of the video be left visible when playback reaches the end of the file?

Responds to

  • getLevel, setLevel, getGang, setGang.

titles cue

n [inh. video cue > cue] : A Titles Cue.

Properties

  • text (text) : Text of the titles cue.
  • live text (text) : Live text of the titles cue. Setting this does not mark the workspace as edited.

camera cue

n [inh. cue] : A Camera Cue.

Properties

  • camera patch (integer) : Camera patch number.
  • layer (integer) : Display layer of the video.
  • full screen (boolean) : Is the cue displaying in full screen mode?
  • preserve aspect ratio (boolean) : Does the cue preserve aspect ratio?
  • opacity (real) : Video opacity.
  • translation x (real) : Translation along the x axis.
  • translation y (real) : Translation along the y axis.
  • scale x (real) : Scale along the x axis.
  • scale y (real) : Scale along the y axis.
  • do video effect (boolean) : Apply a video effect?
  • custom quartz file (file) : The custom Quartz Composer file used to render this cue.

fade cue

n [inh. cue] : A Fade Cue.

Properties

  • fade mode (absolute, relative) : Absolute or relative mode.
  • stop target when done (boolean) : Stop the target when this cue completes?
  • opacity (real) : Video opacity.
  • translation x (real) : Translation along the x axis.
  • translation y (real) : Translation along the y axis.
  • scale x (real) : Scale along the x axis.
  • scale y (real) : Scale along the y axis.
  • preserve aspect ratio (boolean) : Does the cue preserve aspect ratio?
  • rotation type (integer) : Quaternion, x-axis, y-axis, or z-axis.
  • rotation (real) : Rotation in degrees.
  • do opacity (boolean) : Does the cue animate opacity?
  • do translation (boolean) : Does the cue animate translation?
  • do scale (boolean) : Does the cue animate scale?
  • do rotation (boolean) : Does the cue animate rotation?

Responds to

  • getLevel, setLevel, getGang, setGang.

midi cue

n [inh. cue] : A MIDI Cue.

Properties

  • patch (integer) : MIDI device patch number.
  • message type (voice, msc, sysex) : The type of MIDI message.
  • command (note_on, note_off, program_change, control_change, key_pressure, channel_pressure, pitch_bend) : The MIDI command.
  • channel (integer) : MIDI channel number.
  • byte one (integer) : First byte of the message.
  • byte two (integer) : Second byte of the message.
  • byte combo (integer) : Value when first and second bytes are interpreted as parts of one number. Used for pitch bend messages.
  • start value (integer, r, o) : The start value for the MIDI fade.
  • end value (integer) : The end value for the MIDI fade.
  • fade (enabled, disabled) : State of the MIDI fade.
  • deviceID (integer) : MIDI Show Control device ID.
  • command format (integer) : MIDI Show Control command format.
  • command number (integer) : MIDI Show Control command.
  • q_number (text) : Q Number message parameter.
  • q_list (text) : Q List message parameter.
  • q_path (text) : Q Path message parameter.
  • macro (integer) : MSC macro.
  • control number (integer) : MSC control number.
  • control value (integer) : MSC control value.
  • hours (integer) : MSC hours parameter.
  • minutes (integer) : MSC minutes parameter.
  • seconds (integer) : MSC seconds parameter.
  • frames (integer) : MSC frames parameter.
  • subframes (integer) : MSC subframes parameter.
  • smpte format (fps_24, fps_25, fps_30_drop, fps_30_non_drop) : SMPTE format of the timecode parameters.
  • send time with set (boolean) : Send the timecode parameters with the SET command?
  • sysex message (text) : The raw SysEx message. Use only hexadecimal characters and whitespace. Omit the starting F0 and the ending F7.

midi file cue

n [inh. cue] : A MIDI File Cue.

Properties

  • patch (integer) : MIDI device patch number.
  • rate (real) : Playback rate of the MIDI File cue.

osc cue

n [inh. cue] : An OSC Cue.

Properties

  • patch (integer) : OSC destination patch number.
  • osc message type (qlab, custom, udp) : The type of OSC message.
  • q_num (text) : The QLab cue number, for QLab type messages.
  • q_command (number) : The QLab OSC command, for QLab type messages.
  • q_params (text) : The QLab command parameters, for QLab type messages. Not all messages have parameters.
  • custom message (text) : The custom OSC message, for custom type messages.
  • udp message (text) : The raw UDP message, for udp type messages.

timecode cue

n [inh. cue] : A Timecode Cue to generate MTC or LTC timecode.

Properties

  • patch (integer) : MIDI destination patch number.
  • smpte format (fps_24, fps_25, fps_30_drop, fps_30_non_drop) : SMPTE format of the outgoing timecode.
  • start time offset (real) : Time in seconds where the MTC clock begins counting.

devamp cue

n [inh. cue] : A Devamp Cue.

Properties

  • fire next cue when slice ends (boolean) : Fire the next cue at the moment the target slice ends?
  • stop target when slice ends (boolean) : Stop the target at the moment the target slice ends?

load cue

n [inh. cue] : A Load Cue.

Properties

  • load time (real) : Load target cue to this time.

target cue

n [inh. cue] : A Target Cue.

Properties

  • assigned number (text) : Number of cue to assign. The cue with this number will be assigned as the new target.

script cue

n [inh. cue] : A Script Cue.

Properties

  • script source (text) : AppleScript source for the cue. The script will be recompiled when set.

Responds to

  • compile.

make

v

make workspace
type text : Name of the kind of cue you want to make. (Audio, Video, Camera, MIDI, etc.) Pass "cue list" to make a new cue list.

load

v : Load a cue or workspace to a given time.

load specifier : The cue(s) or workspace(s) to load.
[time real] : Load time.

go

v : Make a workspace GO.

go specifier : The workspace to GO.

preview

v : Preview one or more cues.

Previewing starts only the action of the cue, skipping any pre-wait and not continuing to other cues.
preview specifier : The cue(s) to preview.

start

v : Start one or more cues or workspaces.

start specifier : The cue(s) or workspace(s) to start. For a workspace, "start" means to unpause all paused cues.

pause

v : Pause one or more cues or workspaces.

pause specifier : The cue(s) or workspace(s) to pause.

stop

v : Stop one or more cues or workspaces.

stop specifier : The cue(s) or workspace(s) to stop.

hardStop

v : Hard stop one or more cues or workspaces.

hardStop specifier : The cue(s) or workspace(s) to stop.

panic

v : Panic one or more cues or workspaces.

panic specifier : The cue(s) or workspace(s) to panic.

reset

v : Reset one or more cues or workspaces.

reset specifier : The cue(s) or workspace(s) to reset.

moveSelectionUp

v : Select the previous cue.

moveSelectionUp specifier : The workspace whose selection will change.

moveSelectionDown

v : Select the next cue.

moveSelectionDown specifier : The workspace whose selection will change.

getLevel

v

getLevel cue : The cue for which you want to get the volume level.
row integer : The row of the level matrix. Row 0 = the master and output levels.
column integer : The column of the level matrix. Column 0 = the master and input levels.
returns real : The value in decibels of the level at the specified location in the matrix.

setLevel

v

setLevel cue : The cue for which you want to adjust the volume level.
row integer : The row of the level matrix. Row 0 = the master and output levels.
column integer : The column of the level matrix. Column 0 = the master and input levels.
db real : The decibel value for the volume level.

getGang

v

getGang cue : The cue for which you want to adjust the gang.
row integer : The row of the level matrix. Row 0 = the master and output levels.
column integer : The column of the level matrix. Column 0 = the master and input levels.
returns text : The value of the gang at the specified location in the matrix.

setGang

v

setGang cue : The cue for which you want to adjust the gang.
row integer : The row of the level matrix. Row 0 = the master and output levels.
column integer : The column of the level matrix. Column 0 = the master and input levels.
gang text : The gang value to set.

compile

v

compile script cue : The Script cue whose source you want to recompile.