快速上手

这份指南把一个英语视频做成“中文在上、英文在下”的双语字幕视频。有两条路可以走：

• 交给 Agent：把整个任务交给它，让它运行工作流。
• 自己操作：逐条运行命令，看清每个阶段发生了什么。

For Agent

如果你在用 Claude Code 或 Codex 这样的 Agent，不必记住所有命令。先把工作流教给它，只需要一次：

openbbq skill install --agent claude

Codex 用 --agent codex，其他 Agent 用不带参数的 openbbq skill install（装到共享目录）。然后发一句话：

帮我把这个视频制作成中英双语字幕视频：https://www.youtube.com/watch?v=xxx

Agent 会先创建一个工作区，然后始终按照 OpenBBQ 返回的唯一下一步推进，直到字幕底稿可以交付。它可以下载所需模型、转录、处理结构性听写问题、分批翻译、导出和烧录；需要你操作时，例如登录账号，它会停下来。

最终文件位于 out/zh-burned.mp4。自动结果会明确标成可继续编辑的 draft；只有人通过 openbbq review 检查全部当前字幕后，状态才会变成 human-reviewed。Agent 的操作约定和中断恢复方式见工作流模型。

本地视频也一样用。把 URL 换成本地文件路径，例如 ./video.mp4。

For Human

想自己动手，或者想看看 Agent 在幕后做了什么？把同一条流水线手动跑一遍。操作时换成你自己的文件和语言代码即可。

1. 检查环境

openbbq doctor

按提示处理好它发现的问题，然后确认你已经有识别模型：

openbbq models list
openbbq models pull large-v3-turbo

2. 创建工作区

一个视频对应一个工作区文件夹：

openbbq init --workspace workspaces/demo /path/to/video.mp4

进入这个文件夹，后面的命令就能自动找到它：

cd workspaces/demo

你也可以待在原地，给每条命令加上 --workspace workspaces/demo。

3. 准备音频

openbbq extract-audio

这一步会给识别器准备一条干净的音频，方便它“听“。

4. 把听到的话记下来

openbbq transcribe --model large-v3-turbo --language en

OpenBBQ 听完音频后，会把每句话和对应时间写入 transcript.json。视频较长时要等一会儿，可以在另一个终端用 openbbq status 查看进度。

5. 检查听得对不对

翻译之前，OpenBBQ 会先把它们没听准的地方指出来：

openbbq asr check

• ready: true：没有可疑的地方，可以继续。
• 还没准备好：它会列出存疑的位置。听写与检查会说明怎样确认或修正。这一步通过之前，无法切字幕。

6. 切成一行行字幕

openbbq segment

听写稿会变成 cues.json，其中包含带起止时间的字幕行，长度按舒适的阅读速度切分。

7. 翻译

创建一份翻译工作表：

openbbq translate init zh

打开 translation.zh.json：每一行都有原文和一个空的 target 等你填写。只有几行的话，直接改这个文件就行；内容多就分批写、分批合并：

{
  "1": "第一句译文",
  "2": "第二句译文"
}

openbbq translate apply zh targets.json

然后检查一遍：

openbbq translate check zh

它会抓出漏译、长到读不完的句子，以及前后不一致的名字。处理掉它报告的问题，直到它回答 ready: true。

8. 导出双语字幕

openbbq export --to zh --mode bilingual --format ass --ass-preset fansub

你会得到 out/zh.ass，中文在上、英文在下，样式已经针对横屏视频调整。烧录之前，先在支持 ASS 的播放器中预览。

9. 烧进画面（可选）

openbbq burn

几分钟后得到 out/zh-burned.mp4，字幕已经成为画面的一部分。

10. 上桌之前

openbbq delivery check --to zh

这是发布前的最后一道关卡。它会重新核验听写决定、翻译、校对状态和烧好的视频。如果还有没完成的步骤，例如完整的逐句审校，它会说明剩下什么以及如何完成。质量关卡解释了背后的想法。

现在的工作区

workspaces/demo/
├── manifest.json        # 进度日志
├── media/               # 准备好的音频
├── transcript.json      # 听到的内容
├── cues.json            # 字幕行
├── translation.zh.json  # 你的译文
└── out/                 # 字幕和烧好的视频

接下来

• 视频在 YouTube 上？看获取视频。
• 准备交给 Agent？先读工作流模型。
• 发布前想在屏幕上通览一遍？试试可视化校对。
• 好奇每个文件是干什么的？看工作区文件。