QLab cue list 顯示大量建立的字幕 Timeline Groups

如何從 Excel、CSV 或 TXT 快速製作 QLab 字幕


如果演出本來就由 QLab 控制,真正費時的通常不是接上投影機。

真正費時的,是把劇本、譯文、試算表或純文字文件,整理成數百條可以可靠觸發的字幕,同時不打亂既有演出檔。

舞台監督手上可能是 Word 劇本,譯者交來 Excel 工作表,技術人員拿到的則是純文字清單。QLab 操作員需要的是另一種東西:能放進演出時間軸、經得起排練與移動、可以重新編號,並能在壓力下可靠觸發的 Text cues

本文整理一套從 Excel、CSV 或 TXT 建立字幕的 QLab 5 工作流程,也逐項對照 QLab 官方文件,釐清哪些功能由 QLab 直接提供、哪些需要 AppleScript 自動化,以及什麼時候應改用經過審閱的 QLab Projection Pack,避免演出檔成為字幕文字唯一的存放處。

QLab 可以顯示字幕嗎?

可以。在 QLab 裡,字幕或舞台字幕通常以 Text cue 製作。

QLab 5 官方文件指出,Text cue 會把設定好樣式的文字轉成視訊輸出。字型、字級、樣式、對齊、文字色彩與背景色都可調整;cue 執行時,QLab 會將文字渲染成影像。Text cue 屬於 QLab 視訊系統,因此可指定到視訊輸出 Stage 進行投影。

對劇場團隊而言,字幕可以像一般 QLab cue 一樣運作:

  • 可以與聲音、視訊、燈光、Wait cue 與待機段落放在同一份 cue list
  • 可以指定到投影機或螢幕使用的 Stage
  • 可以像其他視覺素材一樣設定格式
  • 可以透過 GO、cue trigger、Timeline Group、OSC、MIDI 或其他演出控制邏輯觸發

這是 QLab 的強項。

但 QLab 不是翻譯編輯器,不負責把劇本切成字幕,也不是多語言觀眾端 Viewer。若每一條字幕都在 QLab 裡手動建立,排練開始前便可能先耗掉好幾個小時。

官方 QLab 文件支援什麼

在建立工作流程之前,值得將官方 QLab 行為與製作捷徑分開。

需求 官方 QLab 文件支援什麼 本文補充什麼
顯示投影文字 QLab Text cue 會把設定好樣式的文字轉為視訊輸出,並可指定到視訊輸出 Stage。 把每一條字幕做成一個 QLab Text cue。
大量建立 cues QLab AppleScript 字典支援 make type "text",並提供 texttext alignmentfixed widthstage nametranslation xtranslation y 等 cue 屬性。 讓試算表的每一列或每個文字區塊對應一個 Text cue。
使用試算表 QLab Cookbook 提供由試算表驅動的範例:讀取 Excel 列、建立 Group 與 Text cues、設定文字格式,再把 cues 移入 Group。 沿用這個方法製作字幕與舞台字幕,而不是範例中的字卡。
把 XLSX 原生匯入為字幕 QLab 公開文件示範的是 Excel 自動化,不是一鍵匯入 XLSX 字幕的內建功能。 以 Excel、CSV 或 TXT 保存來源資料,再由腳本或匯入器建立 QLab cues。
同步觀眾手機 QLab Text cues 負責本地投影,本身不會把瀏覽器字幕狀態發送到觀眾手機。 完成演出部署後,SurtitleLive QLab Projection Pack 可為每個來源 cue 加入一個本機 Script child;操作員仍須明確連接並啟用正常的 ASM console,才能發佈 Viewer 狀態。

這種區別對於 SEO 和製作準確性很重要。安全的說法不是「QLab 原生匯入 Excel 字幕」。更安全、更準確的說法是:

你可以透過試算表或腳本驅動的流程,從 Excel、CSV 或 TXT 建立 QLab 字幕 Text cues。

這與 QLab Cookbook 處理試算表自動化的方式一致。

最快上手的結構:每列一條字幕

若來源是 Excel 或 Google 試算表,請讓每一列只放一條字幕。

工作表愈單純愈好。到了技術排練,清楚往往比花巧更可靠。

QLab 字幕的簡潔 Excel 試算表結構 完整配套套件包含本文使用的 AppleScript、Excel 範本與螢幕截圖:下載 QLab 字幕示範素材(ZIP)

欄位 範例 重要性
cue_number 10 預定使用的 QLab cue 編號。
subtitle_text 歡迎觀賞。 觀眾看到的文字。
operator_note 門鈴響後 給操作員看的 cue 註記。
language zh-TW 準備多個語言版本時便於辨識。
stage (空白) 留白即可使用 QLab 預設 Stage;只有需要明確路由時才填入名稱。
alignment center 通常是 center,但請明確指出。

對於第一次嘗試,只有兩個欄位是必不可少的:

cue_number,subtitle_text
10,歡迎觀賞。
11,請關閉你的手機。
12,演出即將開始。

若字幕由譯者提供,請避免合併儲存格、只靠顏色表達狀態,或把製作註記藏在儲存格註解裡。文字與狀態應各自放在明確欄位中,讓腳本讀得到,也讓操作員查得到。

方法一:從 Excel 建立 QLab Text cues

這個方法最接近 QLab 官方 Cookbook 的做法。

想法很簡單:

  1. 在 Excel 中打開字幕試算表。
  2. 開啟目標 QLab 5 workspace。
  3. 先手動建立並投影一個 Text cue,確認 Video License、Stage、輸出路徑與投影機都能正常工作。
  4. 執行逐列讀取資料的 AppleScript。
  5. 每一列建立一個頂層 Timeline Group,內含字幕 Text cue;從第二條字幕開始,再加入清除上一行的 Fade cue。
  6. 設定操作員會看見的 cue 編號與名稱,以及字幕文字、對齊、寬度、註記和選用的 Stage。
  7. 正式使用前,先在目前的 QLab cue list 審閱所有新建的頂層 Groups。

官方 Cookbook 範例以 Excel 建立較複雜的視覺 workspace,每列包含 Group 與多個 Text cues。製作字幕時可以簡化為:試算表每一列對應一個字幕 Text cue。

一個最小的 AppleScript 骨架可能看起來像這樣:

-- Official QLab 5 pattern:
-- https://qlab.app/docs/v5/scripting/examples/#create-and-move-a-new-cue
on makeCueInGroup(cueType, destinationContainer)
  tell application id "com.figure53.QLab.5" to tell front workspace
    make type cueType
    set newCue to last item of (selected as list)
    set q number of newCue to ""
    set newCueID to uniqueID of newCue
    set sourceList to parent of newCue
    move cue id newCueID of sourceList to end of destinationContainer
    return cue id newCueID of destinationContainer
  end tell
end makeCueInGroup

完整配套腳本會讓演出期間的 QLab cue list 保持清楚:

  • 每條字幕都是目前 cue list 中的頂層 Timeline Group,不會再用一個額外的匯入 Group 把所有演出 cues 包住。
  • 聲音、燈光、視訊、Wait cue 與其他演出 cues,因此可以放在任意兩個字幕步驟之間。
  • Excel 的 cue_number 成為 QLab 的 編號
  • Excel 的 subtitle_text 成為操作員可見的時間軸群組的 QLab 名稱
  • 因此,操作員看到的是 20 | 今晚要去哈特洛克家嗎,瑪格麗特?,而不僅僅是 20 | 字幕 20
  • 從第二條字幕開始,每個 Timeline Group 先執行 CLEAR PREVIOUS,再執行 DISPLAY zh-TW。新的 Text cue 設有 0.05 秒 pre-wait,讓上一行先淡出並停止,再顯示新字幕。
  • 第一個字幕只包含 DISPLAY zh-TW,因為沒有先前的字幕需要清除。
  • 最後一個頂層 CLEAR LAST SUBTITLE 步驟會在字幕序列結束時移除最後一行。

這不是一個完成的製作匯入器。它是一個可讀的起點。

正式演出使用的腳本,寫入 QLab workspace 前至少應加入以下檢查:

  • cue 編號空白時停止
  • cue 編號已存在時停止
  • 從字幕文字中修剪多餘的空格
  • 如果一行太長則發出警告
  • 拒絕標記為草稿或未批准的行
  • 先在 QLab workspace 的測試副本中建立
  • 保留含時間戳記的 QLab workspace 備份

最穩妥的做法,是先在 QLab workspace 的測試副本建立 cues,審閱所有頂層 Groups,再依製作的變更管理方式,把通過審閱的內容匯入正式 workspace,或移入正式演出檔。

方法 2:CSV 到 QLab 字幕

CSV 往往比 XLSX 更適合作為交換格式。

Excel 方便編輯。CSV 方便自動化。

常見的 CSV 流程如下:

  1. 在 Excel、Google 試算表、Numbers 或 Airtable 中編輯字幕。
  2. 匯出為 CSV。
  3. 執行小型匯入器,讀取 CSV 並建立 QLab Text cues。
  4. 排練前先審閱新建的 QLab cues。

好處是匯入器不必直接控制 Excel,只需讀取單純的 CSV 檔案。這套流程更容易納入版本管理、測試與重複執行。

CSV 也可以交由 Git 管理,讓團隊不必開啟 QLab workspace,便能看出 cue 42 的譯文前後改了什麼。

這對劇場團隊格外實用,因為字幕總在變動:

  • 譯文需要縮短
  • 演員改了停頓
  • 笑點需要另一種斷行
  • 後期刪去了一頁
  • 導演要求把字幕提早兩個 cues

只要來源資料保持結構化,重建 QLab cue list 就能成為可重複的流程,而不是每次從頭手做。

方法三:從 TXT 建立 QLab 字幕

當你還沒有試算表時,純文字是最快的起點。

使用簡單的區塊格式:

10
歡迎觀賞。

11
請關閉你的手機。

12
演出即將開始。

在這種格式中,每個字幕區塊都有:

  1. cue 編號
  2. 一行或多行字幕文字
  3. 下一個區塊前的空白行

TXT 匯入器可以根據空白行分割檔案,將第一行讀取為 QLab cue 編號,並將其餘行視為字幕文字。

這個方法很快,卻也最脆弱。純文字適合小型活動或早期排練;一旦需要多種語言、核准狀態、操作員註記、場次編號、角色名稱或修訂紀錄,便很難再維持清楚。

正式製作舞台字幕時,只要資料開始變得複雜,就應儘早把 TXT 轉成試算表,或移入專用舞台字幕編輯器。

投影設定:別忘了 Stage

建立 Text cues 只完成了一半。QLab 還需要一條完整路徑:從 Text cue 到 Stage,再從 Stage 到 Output Route,最後抵達實體顯示器或投影機。

QLab 官方文件明確指出,使用 Text cue 需要 Video License。本文因此假設 QLab 已啟用 Video License,或含視訊功能的 Bundle License。若沒有,匯入器仍可能建立 Text cues,但 QLab 會將其標示為 broken,無法投影。詳情請見 QLab 官方 Text Cues 文件授權功能表

繼續之前,請開啟 QLab → Manage Your Licenses,確認 Video License 已啟用。只有 Audio License 並不足以使用 Text cues。

初次設定:連接一台投影機

執行 Excel 匯入器前,先完成以下設定:

  1. 把投影機或外接顯示器接上 Mac,並開啟電源。
  2. 前往 macOS 系統設定 → 顯示器,確認投影機已出現。一般舞台字幕應使用延伸顯示器,而不是鏡像操作畫面。
  3. 開啟 QLab。可以的話,接好投影機後再建立新的 workspace;QLab 建立 workspace 時,通常會為已連接的顯示器建立 Stage。
  4. 開啟 Workspace Settings → Video
  5. Video Outputs 找到投影機使用的 Stage,確認 Devices 欄列出正確的投影機或外接顯示器。沒有裝置的 Stage 無法投影字幕。
  6. 若沒有合適的 Stage,開啟 Output Routing,以投影機為裝置建立 Output Route;回到 Video Outputs,再選擇 New Video Stage → Stage with output 及該路徑。
  7. 為 Stage 取一個簡單名稱,例如 Surtitles。若 Excel 會以名稱指定它,匯入後便不要任意改名。

QLab 的術語描述了訊號路徑:

Text cue → Stage → Region → Output Route → 投影機

其中任何一環缺失,QLab 都可能建立 cue,卻把它標示為 broken,或無法在投影機上顯示。

匯入 Excel 前,先測試一個 Text cue

  1. 在 QLab 手動建立一個 Text cue。
  2. 輸入簡短測試文字,例如 字幕測試
  3. 在 Text cue 的 I/O Inspector 選擇投影機 Stage。
  4. 執行 cue。
  5. 確認文字真的出現在投影機上,而不只是在 QLab preview 或 Stage Monitor 裡。
  6. 調整字型、字級、色彩、寬度、對齊與位置,直到後排也能清楚閱讀。

只有手動 Text cue 正常投影後,才執行 Excel 匯入器。

Excel 的 stage 欄位中應填寫什麼

  • 最簡單的做法是把 stage 留白,讓腳本為每個新 Text cue 保留 QLab 的預設 Stage。
  • 只有確實建立了指定 Stage,而且拼法與 QLab 完全一致時,才填入名稱。
  • 若試算表中的 Stage 名稱不存在,配套腳本會保留預設 Stage,並在 cue 註記中記錄這次 fallback。

QLab Text cue 的 I/O 面板顯示視訊 Stage 指派

如果匯入器執行但字幕沒有投影

你看到的 這意味著什麼 該怎麼辦
QLab 顯示 QLab Video License or output required 字幕 cues 已建立,但至少一個 Text cue 處於 broken 狀態。 先確認 Video 或 Bundle License 已啟用,再設定 Workspace Settings → Video 並測試既有 cues;不要重新匯入。
所有新建 Text cues 都 broken,而且沒有可用的 Video Stage QLab 沒有有效的 Video License。 安裝或啟用 Video 或 Bundle License;否則 Text cues 無法投影。
Text cue 出現紅色錯誤標記或顯示 broken 指定的 Stage、Route 或輸出裝置無法使用。 先檢查 Text cue 的 I/O Stage,再檢查 Stage 的 Region、Route 與裝置。
cue 已執行,投影機卻沒有畫面 QLab 可能選錯 Stage,或 Route 指向錯誤顯示器。 在 Text cue 選擇預定 Stage,並核對 Route 的裝置。
腳本回報 cue 編號 10 已存在 先前匯入或其他演出 cue 已使用該編號。 改用新的或複製的 workspace;確認安全後,才移除先前測試匯入。
QLab 已有新建字幕 Groups,再次執行腳本卻失敗 第一次匯入的結構其實已經完成。 修正視訊輸出後使用既有 cues,不要再次匯入重複內容。

自動化只會忠實複製現有設定。若輸出路徑或 Text cue 樣式錯了,它也會很快把錯誤複製數百次。

DIY QLab 字幕工作流程中通常會出錯的地方

當問題很簡單時,DIY QLab 字幕建立效果很好:

我有文字,需要把它變成 QLab Text cues。

當問題實際上是這樣時,它會變得更困難:

我有翻譯劇本、臨時修訂、多個版本、投影螢幕與觀眾手機;演員可能跳詞或重複,操作員還要立刻找回正確 cue。

常見的故障點包括:

  • cue 編號重複
  • Stage 指派遺失
  • 字幕寬得超出螢幕
  • Excel 裡正常、投影後卻不合適的斷行
  • cues 匯入後譯文又有更動
  • QLab 演出檔成為字幕文字唯一的存放處
  • 無法清楚比較譯文第 3 版與第 4 版
  • 投影與手機字幕逐漸不同步
  • 演員跳詞、重複或改變次序時,操作員無法迅速復原

這就是「快速 QLab 自動化」與實際舞台字幕製作工作流程之間的界限。

什麼時候應改用 SurtitleLive

若只需要本機投影,QLab Text cue 流程可能已經足夠。

若還需要翻譯審閱、穩定 cue key、手機觀看,或讓投影與觀眾手機使用同一批內容,字幕便應在進入 QLab 前擁有一套專用工作流程。

SurtitleLive QLab 工作流程有兩個層次。

QLab Projection Pack

需要由 QLab 負責本機投影時,使用這個套件。

工作流程是:

SurtitleLive 編輯器 → QLab Projection Pack → QLab Text cues → 投影機

團隊在 SurtitleLive 準備劇本與字幕段落,審閱譯文與 cue 順序,再匯出可供 QLab 使用的 cues。QLab 仍是場館端的播放環境。

當技術操作以 QLab 為核心、字幕內容卻不適合逐條在 QLab 內製作時,這套分工尤其實用。

下載的套件會把資料與可執行指示分開:1 - START HERE.txt 說明操作流程,2a - Import into QLab.applescript 是固定的匯入器,2b - QLab Cue Data.json 則保存已準備好的 cue 資料。從編輯器下載的套件只負責離線投影交接;它不會建立部署、開啟 ASM,或向 Viewer 發佈內容。

每一條來源字幕都保有穩定的 SurtitleLive cue key。因此,重新匯入修訂版時,可以原位更新相符的 SurtitleLive caption Groups、插入新增的來源 cues,並把已從 SurtitleLive 移除的字幕標示出來,交由操作員處理。它不會默默刪除舊 Group,也不會覆寫不屬於 SurtitleLive 的聲音、燈光、視訊、待機或舞台管理 cues。

匯出選項也會定義預定的投影輸出。一個來源 cue 可以包含供不同語言或螢幕使用的多個 Text children,同時維持為一個操作時刻。同一螢幕上的語言必須使用不同字幕位置;送往不同投影機的輸出則需要不同的 QLab Stage 名稱。所有 Stage 指派都應在實際場館重新測試。

完成部署後,讓 QLab 與 Viewer 同步

當 QLab 繼續控制演出時間軸,而已部署的 SurtitleLive Viewer 需要跟隨同一個來源 cue 時,才使用這條路徑。

工作流程是:

QLab → 本地投影 → 投影機

同一個 cue 時刻則是:

QLab Script child → loopback bridge → 已開啟的 ASM console → 既有 control channel → Viewer

對已完成部署的演出,Deployment Cockpit 下載的 QLab Projection Pack 可把每條來源字幕匯入為一個 Timeline Group。Group 內可有一個或多個 Text children,供不同語言或投影輸出使用;但每個來源 Group 最多只有一個本機 Script child。所有 children 共用同一個穩定的 SurtitleLive cue key。

Script child 會把不含機密的 JSON cue 身分資料送到綁定於 127.0.0.1:37621 的 bridge。Bridge 不會呼叫 SurtitleLive 後端,也不攜帶 ASM 密碼、Viewer 連結、runtime token 或雲端憑證。它只把本機 cue 事件交給已開啟的 ASM console;真正透過 control channel 發佈既有 cue.jump 狀態的,仍然是 ASM。

這條路徑必須由操作員主動啟用:

  1. 在 Deployment Cockpit 為已完成的演出啟用 QLab,並下載新的 QLab Projection Pack。
  2. 把套件匯入 QLab,按兩下 3 - Start Local Bridge.command,演出期間保持該 Terminal 視窗開啟。
  3. 開啟並解鎖平常使用的 ASM console。
  4. 點選 QLab enabled,再選 Connect local bridge
  5. 等待 Viewer sync 就緒,以正常且明確的 Go Live 操作開始演出,之後才選擇 Allow QLab control

Bridge 連線不會自動開始演出。若本機 bridge 無法使用,應中斷 QLab control,改回正常的 ASM 手動控制。

graph TD
    %% Style Definitions
    classDef qlab fill:#1a1c23,stroke:#5856d6,stroke-width:2px,color:#fff;
    classDef hardware fill:#2a2b36,stroke:#8e8e93,stroke-width:2px,color:#fff;
    classDef cloud fill:#0d2d5e,stroke:#007aff,stroke-width:2px,color:#fff;
    classDef audience fill:#103823,stroke:#34c759,stroke-width:2px,color:#fff;
    
    subgraph Venue ["Local Venue (Theatre)"]
        QLab["QLab 5 Workspace
(Show Control Mac)"]:::qlab Projector["Stage Projector"]:::hardware Screen["Subtitle Screen / LED Wall"]:::hardware Bridge["Loopback Bridge
(127.0.0.1:37621)"]:::qlab ASM["Open, Unlocked ASM Console
(QLab Control Armed)"]:::qlab end subgraph CloudSpace ["Cloud Service"] Cloud["SurtitleLive Cloud Platform
(Real-time Sync)"]:::cloud end subgraph Viewers ["Audience Devices"] Phone1["Audience Phone A
(Web Browser)"]:::audience Phone2["Audience Phone B
(Web Browser)"]:::audience PhoneN["...Other Phones"]:::audience end %% Connection Logic QLab -->|"1. Video Output (HDMI/SDI)"| Projector Projector --> Screen QLab -->|"2. Script Cue POST
(Non-secret JSON identity)"| Bridge Bridge -->|"3. Local browser event"| ASM ASM -->|"4. Existing control-channel cue.jump"| Cloud Cloud -->|"5. Viewer update"| Phone1 Cloud -->|"5. Viewer update"| Phone2 Cloud -->|"5. Viewer update"| PhoneN %% Subgraph Styling style Venue fill:#f9f9fb,stroke:#ccc,stroke-width:1px; style CloudSpace fill:#f0f7ff,stroke:#b3d7ff,stroke-width:1px; style Viewers fill:#f2fff5,stroke:#c2f0cc,stroke-width:1px;

觀眾裝置不應直接與 QLab 通訊,loopback bridge 也不應變成第二條雲端控制路徑。QLab 執行本機時間軸,bridge 在演出 Mac 上傳遞範圍受限的 cue 身分,ASM 套用操作員主動啟用的控制狀態,再由既有 SurtitleLive control channel 更新 Viewer。

最佳實用建議

小型單次活動:

用 Excel 或 TXT 建立 QLab Text cues。維持單純,測試投影機,也保存備份。

翻譯劇場演出:

在 QLab 之外準備字幕,待文字通過審閱後再匯入。

多語言或手機觀看的演出:

使用 SurtitleLive QLab Projection Pack。只有 Viewer 必須跟隨 QLab 時,才加入已完成部署的 ASM 同步路徑,並在演出前由操作員明確啟用。

重點不是取代 QLab,而是讓它專注於最擅長的工作:現場演出控制。

字幕準備、翻譯審閱、手機觀看與 cue 狀態同步,則各自需要合適的工作流程。

常見問題

QLab 可以顯示字幕嗎?

可以。QLab Text cues 能以視訊輸出顯示設定好樣式的文字,因此常用於投影字幕、舞台字幕、說明、公告及其他文字畫面。

我可以直接將 Excel 字幕匯入 QLab 嗎?

QLab 官方 Cookbook 示範的是以 AppleScript 讀取 Excel 並建立 cues,並非內建的一鍵 XLSX 字幕匯入。實際做法是以 Excel 保存來源資料,再執行腳本或匯入器建立 QLab Text cues。

我可以從 CSV 建立 QLab 字幕嗎?

可以,但需要匯入器。CSV 是純文字,通常比 XLSX 更容易解析;腳本可逐列讀取,為每條字幕建立一個 Text cue。

我可以從 TXT 建立 QLab 字幕嗎?

可以,前提是 TXT 採用固定結構。例如每個區塊先放 cue 編號,再放字幕文字,區塊之間留一行空白;腳本便可把它們轉成 QLab Text cues。

字幕應該使用 QLab Text cue 還是 Video cue?

需要在現場修改的文字,適合使用 Text cue。字幕若已烤進輸出的影片或圖像,才考慮 Video cue。Text cue 較容易修訂、設定格式,也能從結構化文字大量建立。

QLab 會將字幕同步到觀眾手機嗎?

QLab 可以在本機投影 Text cues,但觀眾手機需要瀏覽器端流程。已完成部署的 SurtitleLive QLab Projection Pack 可加入本機 Script children,把同一批來源 cues 識別給明確連線並啟用的 ASM console。Bridge 留在演出 Mac 上;透過既有 control channel 發佈 Viewer 狀態的是 ASM,而不是 QLab 或 bridge。

我應該何時停止使用 DIY QLab 字幕腳本?

當流程開始涉及翻譯審閱、多種語言、穩定 cue key、手機觀看、排練時的跳轉復原,或匯入後反覆更新,便不宜只靠 DIY 腳本。這時應使用專用舞台字幕流程,再把內容匯入 QLab,而不是把所有字幕都手動維護在 QLab workspace 裡。

相關資源

相關資源