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 email@example.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.
The following AppleScript and OSC examples both set the master 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.
tell application id "com.figure53.qlab.4" 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.4 is how you instruct the AppleScript interpreter to send the contents of this block of code to QLab 4.
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 master output row of the audio levels matrix mixer,
column 0 is the master 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.
The OSC solution to this problem is rather simpler; it's just a single command:
/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.
-10 is the value that gets sent.
QLab always ignores OSC messages when they're inapplicable, so AppleScript's concept of "try" is unnecessary.
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 number. Remember that cue numbers in QLab don't have to be numbers; they can be any text. So cue "panda" works too. Since cue numbers have to be unique across a workspace, they are the best identifier to use with scripting.
tell application id "com.figure53.qlab.4" 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.4" to tell workspace "Hamlet.qlab4"
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.
The OSC version of this operation is fairly similar:
The OSC message
/armed interprets "0" as "false" and any other number as true.
This is the most complex of these examples: create fade-in cues for every selected cue, fading the master 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.4" 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" 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" 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 "Camera" or 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" 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, or Video 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
set sourceCueLevel to sourceCue getLevel row 0 column 0 creates a variable called
sourceCueLevel, and then fills that variable with the master 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 master 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 master audio level of the new Fade cue to the level we fetched from
sourceCue and stored in the variable
Now, we dive one level deeper with another
if q type of sourceCue is "Video" 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 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
set do opacity of newCue to true checks the Opacity checkbox in the Fade cue.
end if closes the inner
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, or Video 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 Camera or 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 Camera and Text cues have no audio component. The code inside the
else block is the opacity-related second half of the block above, since Camera and Text cues have opacity, but no audio levels.
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.