While having a list of available OSC and AppleScript commands is all well and good, it can sometimes be difficult to put the pieces together into something complete and useful. What follows here is a collection of annotated examples to help get you started. Remember, you can always write to support@figure53.com and send us your script-in-progress, and we’ll do our best to get you going.

Remember, too, that there is usually more than one way to get something done, and the examples here are not meant to be authoritatively the “right” or even “best” way to do things.

The AppleScript examples here can be run from within a Script cue or from another application such as Script Editor. The OSC examples can be run from a Network cue or sent from another program or device.

Adjusting Audio Levels

The following AppleScript and OSC examples both set the main level of all selected cues to -10 dB. You could easily replace -10 with some other number, but remember that you always need to explicitly specify whether a level is positive or negative when using AppleScript or OSC.

AppleScript

tell application id "com.figure53.qlab.5"
  repeat with theCue in (selected of front workspace as list)
	try
	  theCue setLevel row 0 column 0 db -10
	end try
  end repeat
end tell

tell is how AppleScript starts a block of code. com.figure53.qlab.5 is how you instruct the AppleScript interpreter to send the contents of this block of code to QLab 5.

repeat starts another block of code which will be repeated until a particular condition is met, and with indicates that the condition has to do with a variable. theCue creates this variable, which is just a blank container waiting to be used. in (selected of front workspace as list) sets up the details of the condition: find all of the cues in the front workspace which are selected, make a list of those cues, and then repeat the following code once for each item in the list, replacing theCue with each successive item.

try starts yet another block of code with a special condition: if, for some reason, the code inside this block doesn’t work for a particular iteration of theCue, don’t stop running the script. Just skip over the rest of this block and then keep running. This allows the script to handle a case wherein some of the selected cues don’t have audio levels. We want to be able to select a bunch of cues and run the script without worrying about whether every single cue is appropriate; if we select five Audio cues and one Memo cue, the script should adjust the Audio cues and ignore the Memo cue. The try block allows that to happen.

setLevel is a QLab-specific AppleScript command which sets the level of the specified matrix crosspoint in the specified cue. theCue is the variable which represents each item in the list of selected cues, row 0 is the main output row of the audio levels matrix mixer, column 0 is the main input column of the audio levels matrix mixer, and db -10 states the level that you want to set.

end try closes the try block.

end repeat closes the repeat block.

end tell closes the tell block.

OSC

The OSC solution to this problem is rather simpler; it’s just a single command:

/cue/selected/level/0/0 -10

/cue/selected directs the OSC message to all selected cues.

/level says that the value we’re sending (-10 in this case) should be used to adjust the audio level. /0/0 represents the row and column of the crosspoint that should be adjusted, which in this case is row 0, column 0.

And finally -10 is the value that gets sent.

QLab always ignores OSC messages when they’re inapplicable, so AppleScript’s concept of “try” is unnecessary.

Disarming A Specific Cue

The following AppleScript and OSC examples show how to disarm a specific cue. In this example, the cue is numbered “4”, but the same thing works with any cue that has a cue number. Remember that cue numbers in QLab don’t have to be numbers; they can be any text. So cue “panda” works too, if you have cue in your workspace numbered “panda”. Since cue numbers have to be unique across a workspace and are always human-readable (because they were human-created), they are the best identifier to use with scripting.

AppleScript

tell application id "com.figure53.qlab.5" to tell front workspace
  set armed of cue "4" to false
end tell

It seems simple enough, but there are a couple of important details in there.

First, notice that the tell block says “tell something to tell something else”. The reason for that is that QLab can have more than one workspace open at a time, and each workspace could have a cue numbered “4”. So we need to specify which workspace we want to address. If we wanted to address a specific workspace, whether or not it was in front, we could instead write:

tell application id "com.figure53.qlab.5" to tell workspace "Hamlet.qlab5"

That only works, obviously, if the workspace is saved with the name “Hamlet”.

The second important thing is that the cue number is in quotation marks. If you did not put quotes around the number, QLab would think you were trying to refer to the fourth cue in the workspace, rather than the cue whose cue number is “4”. It’s a small difference that makes a big difference.

OSC

The OSC version of this operation is fairly similar:

/cue/4/armed 0

The OSC message /armed interprets “0” as “false” and any other number as true. You could also use /F in place of the 0, because /F is the special OSC operator which means “false”.

Create And Move a New Cue

This example is not necessarily the most immediately practical, but it demonstrates several useful concepts which can be applied to many different kinds of situations.

AppleScript

This script creates a new Memo cue and then moves the newly created cue into a Group cue. It asks the human to enter the cue number of the Group cue that they want the Memo cue moved into, and if a Group cue is selected, it offers the cue number of that as the default choice.

tell application id "com.figure53.QLab.5" to tell front workspace
	
	set theGroupNumber to ""
	
	try
		set theSelectedCue to last item of (selected as list)
		if q type of theSelectedCue is "Group" then
			set theGroupNumber to q number of theSelectedCue
		end if
	end try
	
	display dialog "Enter the cue number of the Group cue that the new cue will be created in:" default answer theGroupNumber with icon note with title "New Cue In Group" buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel"
	
	set theGroupNumber to text returned of result
	set theGroup to the first cue whose q number is theGroupNumber
	
	make type "Memo"
	set newCue to last item of (selected as list)
	set newCueId to uniqueID of newCue
	set cueList to parent of newCue
	move cue id newCueId of cueList to end of theGroup
	
end tell

First, the tell block directs the AppleScript at the front workspace in QLab.

Next, we set theGroupNumber to "" which creates an empty variable theGroupNumber. This is necessary because later on, the script is going to check the contents of that variable. An empty variable is not the same thing as a non-existent one, so doing this up front guarantees that there will be something to check.

Next comes a try block, which means “if the code inside this block returns an error, just forget about it and move on.” That’s necessary because the first line in the block is set theSelectedCue to last item of (selected as list). This line creates a variable, theSelectedCue, and sets its contents to the selected cue. If more that one cue is selected, the last selected cue is the one that goes into the variable. This line assumes that there is at least one selected cue, and if there is not it returns an error. The try block prevents the script from halting as a result, because the script doesn’t require a selected cue to operate correctly, so we want to allow for the possibility that no cues are selected.

If a cue is selected, we want to save its cue number for future reference, but only if it’s a Group cue. So we use an if statement to open another block: if q type of theSelectedCue is "Group" then. If the selected cue is a Group cue, then the code inside the block is executed and the cue number of the cue is stored in theGroupNumber: set theGroupNumber to q number of theSelectedCue. If the selected cue is any other type of cue, the if block is skipped.

The next line displays a dialog box on screen which asks the human for input. This line has a lot of pieces:

• display dialog "Some text" is the basic form of this message. The text inside quotation marks will appear as a prompt to the human. This is the only necessary part of this line. Everything that follows is optional.
• default answer theGroupNumber fills in a default answer using the contents of the variable theGroupNumber.
• with icon note shows an icon in the box. There are three options… icon note shows the application icon, icon stop shows a stop sign with the application icon as a badge, and icon caution shows a caution triangle with the application icon as a badge.
• with title "New Cue In Group" sets the text which appears in the title bar of the dialog box.
• buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel" tells the box to show two buttons with the labels “Cancel” and “OK”. Then, it tells AppleScript that the button labeled “OK” should be the default button, which is shown in color and uses the return or enter key for a keyboard shortcut, and that the button labeled “Cancel” should be the cancel button, which stops the rest of the script from running when it’s clicked and which uses the escape key for a keyboard shortcut.

The first line after the display dialog line stores the text that the human entered in the variable called theGroupNumber: set theGroupNumber to text returned of result

Then, set theGroup to the first cue whose q number is theGroupNumber sets theGroup to refer to the actual cue that has that number.

Next, the script creates a new Memo cue with make type "Memo". Newly created cues are automatically selected, which means they are necessarily the last selected item. We can refer directly to a newly created cue by creating a variable to store a reference to it: set newCue to last item of (selected as list)

Moving cues can be complicated because they have to be moved relative to the cue list that they are contained within, rather than to the workspace as a while, and they have to be addressed by their uniqueID when moving them. set newCueId to uniqueID of newCue gets the uniqueID of the new cue and saves it in a variable called newCueId

Next, we need to find out what cue list contains the new cue, and store that in another variable: set cueList to parent of newCue

At last, we know everything we need to know to move the new cue into the Group: move cue id newCueId of cueList to end of theGroup

And then we wrap it all up with end tell which closes the outermost block of the script.

OSC

The above can be approximated with a series of OSC messages…

/new memo
/cue/selected/name #/cue/selected/uniqueID#
/move/#/cue/selected/name# {1} {group_cue_id}

First, create a new Memo cue. Then set the name of the selected cue (which is that new cue) to its own uniqueID using an OSC query. Then move the cue to within the Group cue, again using a query to grab the name of the selected cue (which we just set to the uniqueID of that cue).

Create Fade-in Cues

This is the most complex of these examples: create fade-in cues for every selected cue, fading the main audio level to the level that the source cue is set to, and if the source cue is a Video cue, fade the opacity in as well.

While it’s technically possible to achieve this via OSC, there’s a lot of decision making in this script which is not what OSC is good at. OSC is about sending individual messages, and sometimes those messages can be chained together. But as you’ll see, this example gets information from QLab, interprets it, and then makes decisions about how to proceed.

If you skipped over the first example, I recommend going back and reading it first. This example builds on those concepts.

tell application id "com.figure53.qlab.5"
  try
	repeat with sourceCue in (selected of front workspace as list)
	  if q type of sourceCue is "Audio" or q type of sourceCue is "Mic" or q type of sourceCue is "Video" or q type of sourceCue is "Camera" then
		set sourceCueLevel to sourceCue getLevel row 0 column 0
		sourceCue setLevel row 0 column 0 db -120
		make front workspace type "Fade"
		set newCue to last item of (selected of front workspace as list)
		set cue target of newCue to sourceCue
		newCue setLevel row 0 column 0 db sourceCueLevel

		if q type of sourceCue is "Video" or q type of sourceCue is "Camera" then
		  set sourceOpacity to opacity of sourceCue
		  set opacity of sourceCue to 0
		  set opacity of newCue to sourceOpacity
		  set do opacity of newCue to true
		end if

	  else if q type of sourceCue is "Text" then
		make front workspace type "Fade"
		set newCue to last item of (selected of front workspace as list)
		set cue target of newCue to sourceCue
		set sourceOpacity to opacity of sourceCue
		set opacity of sourceCue to 0
		set opacity of newCue to sourceOpacity
		set do opacity of newCue to true
	  end if
	end repeat
  end try
end tell

We start with a tell block, as always, and immediately follow up with a try block. In this case, we’re going to use other rules to narrow the scope of how the script behaves, so the try block is more of a safety net than anything else, guarding against unexpected outcomes.

repeat with sourceCue in (selected of front workspace as list) tells AppleScript that we’re going to repeat this block of code once for each selected cue, and we’re going to replace sourceCue with each successive cue on each repetition.

The next line is our first if statement, and it’s a fairly complex one: if q type of sourceCue is "Audio" or q type of sourceCue is "Mic" or q type of sourceCue is "Video" or q type is "Camera" then

AppleScript reads a lot like plain English, so the meaning of this line is actually fairly straightforward. Remember that each time the repeat block loops through, sourceCue represents one of the selected cues in the cue list. So the if statement looks at that cue, and if that cue is an Audio, Mic, Video, or Camera cue, then the code within the if block is executed. If the cue is any other type of cue, the code within the if block is skipped over.

Assuming the cue passes the test, we move into the if block.

set sourceCueLevel to sourceCue getLevel row 0 column 0 creates a variable called sourceCueLevel, and then fills that variable with the main level of sourceCue. Later, we’re going to plug that level into a new Fade cue, so that we can fade this cue up to the level it was set to.

Once we’ve stored the level, we can set sourceCue to silent by setting its main level to -120, which is the lowest possible audio level in QLab: sourceCue setLevel row 0 column 0 db -120

Then, we make a new Fade cue with the command make front workspace type "Fade". That “front workspace” part tells AppleScript which workspace the new cue should be made in.

set newCue to last item of (selected of front workspace as list) creates a new variable, newCue, and fills it with the Fade cue we just created.

set cue target of newCue to sourceCue sets the target of the new Fade cue to the cue currently being represented by sourceCue for this loop.

newCue setLevel row 0 column 0 db sourceCueLevel sets the main audio level of the new Fade cue to the level we fetched from sourceCue and stored in the variable sourceCueLevel.

Now, we dive one level deeper with another if block: if q type of sourceCue is "Video" or q type of sourceCue is "Camera" then

This isn’t the most efficient thing, to check on the type of cue twice, but it’s not so terrible and it makes the code easier to read. Here, we’ve already set the audio level of the new Fade cue, and we check to see if sourceCue is a Video or Camera cue which needs its opacity to be faded in as well.

set sourceOpacity to opacity of sourceCue creates a variable called sourceOpacity, and then fills that variable with the opacity of sourceCue. Now that we’ve stored it, we can set opacity of sourceCue to 0 so that it’s ready to fade in.

set opacity of newCue to sourceOpacity sets the opacity of the new Fade cue to the stored sourceOpacity, and set do opacity of newCue to true checks the Opacity checkbox in the Fade cue.

end if closes the inner if block.

The next line is an else statement, which is a cousin to the if statement. This line is only evaluated when the answer to the first if question is “no”. So the first if statement asks “is sourceCue an Audio, Mic, Video, or Camera cue?” and if the answer is yes, the code inside the if block executes. If the answer is no, then the script skips down to this else statement, which asks “OK, well is sourceCue a Text cue?” If the answer is still no, this block is also skipped over. But if the answer is yes, then the code is executed.

The reason we need the else statement is that Text cues have no audio component. The code inside the else block is a copy of the opacity-related second half of the block above.

end if closes the main if block, end repeat closes the repeat block, end try closes the try block, and end tell closes the tell block.