Subtitles

Updated November 2023.

One of the most labor-intensive tasks in QLab is creating a cue list for a lot of very similar cues, which vary only in their content. If you are doing a show in which you want to add subtitles (or supertitles or captions) to other video content using the same displays, you may have to program thousands of cues. Wouldn't it be great to just have all the subtitles in a text file, hit one button, and before you have time to make a cup of coffee, have a performance-ready workspace automatically generated?

In this example, you need a plain text document with each of your titles on its own line. Open the example QLab workspace and your text file, press ⌃S (control-S), and the process begins.

Here is a screen recording of a solution in action. Best viewed full screen.

How It Works

The scripts in this chapter were written for QLab 5. With a few alterations, however, they can work in QLab 3 and QLab 4 as well The edits required are listed at the end of the article.

The workspace uses three Script cues in a Group cue. The Script cues are contained in a separate cue list in the workspace.

The Script cue numbered "TITLES" imports the paragraphs of the text document into Text cues, using the font style set in Workspace Settings → Templates → Cue Templates. The script counts the number of paragraphs in the text document and then creates one Text cue for each paragraph, setting the text and the cue name of each cue to the imported text.

When each paragraph of your text file is read in, it is examined to see if it contains any forward slash ( / ) symbols. If it finds any, it adds a return before the next item of text. It does this by setting the text delimiters to the forward slash temporarily. Using this method, if your text file contains:

Subtitle 1/Subtitle2/Subtitle3/subtitle4

that will be rendered in a Text cue as:

applescript
tell application "TextEdit"
  set thetext to the text of the front document
  set thecount to the number of paragraphs in thetext
end tell

tell application id "com.figure53.QLab.5" to tell front workspace
  repeat with i from 1 to thecount
    make type "Text"
    set selectedCues to selected as list
    set newCue to last item of (selected as list)
    set thecuenumber to q number of newCue
    set thetitle to paragraph i of thetext
    set oldDelims to AppleScript's text item delimiters
    set AppleScript's text item delimiters to {"/"}
    set theparagraph to ""
    set theItemCount to number of text items in thetitle
    repeat with i from 1 to theItemCount
      set theparagraph to theparagraph & (text item i of thetitle) & return
      set q name of newCue to thetitle
      set the text of newCue to theparagraph
    end repeat
    set AppleScript's text item delimiters to oldDelims
  end repeat
end tell  

The Script cue numbered "MAKE" generates a Group cue that fades the old title and starts the new title and fades it in. Rich Walsh contributed several improvements to the first version of this.

At the top of the script are some variables you can edit to set the timing of the cues.

applescript
set userUpTime to 2 -- Time for images to fade up in
set userDownTime to 1 -- Time for images to fade down in
set userHoldTime to 0.5 -- Time to wait between starting fade down and starting fade up

-- Declarations
set notFirstCue to false

-- Main routine

tell application id "com.figure53.QLab.5" to tell front workspace
  set selectedCues to every cue as list
  repeat with eachcue in selectedCues
    if q type of eachcue is "Text" then -- Any other selected cues will be ignored; the sequence will end up after them
      
      -- Make a fade out cue (not for the first cue)
      if notFirstCue then
        make type "Fade" -- Cue numbers and names not altered from QLab defaults
        set fadeOutCue to last item of (selected as list)
        set cue target of fadeOutCue to previousCue
        set duration of fadeOutCue to userDownTime
        set do opacity of fadeOutCue to true
        set opacity of fadeOutCue to 0
        set stop target when done of fadeOutCue to true
      end if
      
      -- Make a fade in cue
      make type "Fade" -- Cue numbers and names not altered from QLab defaults
      set fadeInCue to last item of (selected as list)
      set opacity of eachcue to 0
      set cue target of fadeInCue to eachcue
      set pre wait of fadeInCue to userHoldTime
      set duration of fadeInCue to userUpTime
      set do opacity of fadeInCue to true
      
      -- Make a Group Cue (have to do this here to get round QLab's auto-grouping of selections ≥ 2 cues)
      make type "Group" -- Cue numbers not altered from QLab defaults
      set groupCue to last item of (selected as list)
      set mode of groupCue to timeline
      set q name of groupCue to "Crossfade to " & q list name of eachcue
      
      -- Move cues into right place
      
      move cue id (uniqueID of eachcue) of parent of eachcue to end of groupCue
      if notFirstCue then move cue id (uniqueID of fadeOutCue) of parent of fadeOutCue to end of groupCue
      move cue id (uniqueID of fadeInCue) of parent of fadeInCue to end of groupCue
      
      -- Setup variables for next pass
      set previousCue to eachcue
      set notFirstCue to true
    end if
  end repeat
end tell

The Script cue numbered "NUMB" cleans up the numbering, numbering all the generated Group cues sequentially.

applescript
tell application id "com.figure53.QLab.5" to tell front workspace
  set thecuelist to current cue list
  set selectedCues to every cue
  repeat with eachcue in selectedCues
    if q type of eachcue is in {"Group", "Text", "Fade"} then
      set the q number of eachcue to ""
    end if
  end repeat
  set thecuenumber to 1
  set selectedCues to every cue in front cue list whose q type is "Group"
  repeat with eachcue in selectedCues
    set the q number of eachcue to thecuenumber
    set thecuenumber to thecuenumber + 1
  end repeat
end tell

Adaptations for QLab 3 and QLab 4

To make these scripts work with earlier versions of QLab:

1. Alter the application id to the relevant version. i.e. change tell application id "com.figure53.qlab.5" to tell front workspace to tell application id "com.figure53.qlab.4" or application id "com.figure53.qlab.3"
2. Since Text cues were called Titles cues in QLab 3, replace all references to type "Text" to type "Titles"
3. The Timeline mode of Group cues was referred to as "fire all" in QLab 3 and 4. Change the script numbered "MAKE" to from set mode of groupCue to timeline to set mode of groupCue to fire_all

These adaptations have been made in the downloadable examples for QLab 3 and 4.