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

AppleScript

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.

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

AppleScript

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.

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.

Create Fade-in Cues

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 if block.

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

Now, we dive one level deeper with another if block: 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 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, 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.