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 控制台,才能发布 Viewer 状态。

这种区别同时关系到搜索表述和制作准确性。准确的说法不是“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-CN 准备多个语言版本时便于识别。
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-CN。新的 Text cue 设有 0.05 秒 pre-wait,让上一行先淡出并停止,再显示新字幕。
  • 第一个字幕只包含 DISPLAY zh-CN,因为没有先前的字幕需要清除。
  • 最后一个顶层 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 控制台;真正通过 control channel 发布既有 cue.jump 状态的,仍然是 ASM。

这条路径必须由操作员主动启用:

  1. 在 Deployment Cockpit 为已完成的演出启用 QLab,并下载新的 QLab Projection Pack。
  2. 把投影包导入 QLab,双击 3 - Start Local Bridge.command,演出期间保持该 Terminal 窗口打开。
  3. 打开并解锁平常使用的 ASM 控制台。
  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 控制台。Bridge 留在演出 Mac 上;通过既有 control channel 发布 Viewer 状态的是 ASM,而不是 QLab 或 bridge。

我应该何时停止使用 DIY QLab 字幕脚本?

当流程开始涉及翻译审核、多种语言、稳定 cue key、手机观看、排练时的跳转复原,或导入后反复更新,便不宜只靠 DIY 脚本。这时应使用专用舞台字幕流程,再把内容导入 QLab,而不是把所有字幕都手动维护在 QLab workspace 里。

相关资源

相关资源