工作区文件

一个视频对应一个工作区文件夹。流水线的每一步都会把结果存成可以直接打开查看的普通文件。本页讲每个文件的作用；CLI 参考列出产生它们的命令。

工作区结构

完整处理后的工作区通常包含：

workspace/
├── manifest.json
├── media/
│   ├── <下载的媒体>
│   ├── <封面>
│   └── audio.16k.wav
├── transcript.json
├── cues.json
├── translation.zh.json
├── review.zh.json
├── .openbbq/
│   ├── asr-review.json
│   ├── translation-audit.zh.json
│   ├── qa.json
│   ├── artifacts.json
│   └── review/
│       ├── journal.json
│       ├── checkpoints/
│       └── cache/
└── out/
    ├── en.srt
    ├── zh.ass
    └── zh-burned.mp4

只有命令实际生成的产物才会出现。本地来源保留在原绝对路径；从 URL 下载的媒体放在 media/ 下。

manifest.json

当前 manifest schema 是 openbbq/manifest@1，记录：

• 创建时间。
• 来源类型和引用。
• 能获取到的标题、作者和封面。
• 绑定的术语表名称。
• 每个阶段的状态、产物、进度心跳、更新时间和错误。

它是由各命令维护并校验的工作日志——不是流水线配置文件。

transcript.json

识别器听到的内容：检测或指定的语言、媒体时长、后端与模型信息、听写段，以及后端能提供的词级时间和置信度。

用 transcribe 重新生成。格式错误或不兼容的文件会被拒绝，报 invalid_transcript。

cues.json

由听写稿确定性生成的字幕行时间轴，包含：

• 原语言。
• 本次使用的切分参数。
• 稳定的行 id、开始/结束时间和原文。

翻译工作表和导出都依赖行身份。重跑 segment 后，可能需要重新协调已有工作表。

translation.<lang>.json

每个目标语言一份可编辑工作表。未填写的 target 保持为 null，方便发现剩余工作。用 translate apply 做受控的分批更新，用 translate check 检查完整性。

review.<lang>.json

逐字幕行的校对状态——只校对原文时是 review.source.json,schema 为 openbbq/review@1。它保存每行的状态、备注、内容指纹、当前选择的目标语言和修订元数据，不重复保存字幕正文。

校对时的修改会保持 cues.json 与所有工作表对齐。变更通过可恢复的 checkpoint 和跨文件 journal 写入；会话进行中也支持撤销和重做。

.openbbq/review/ 保存 checkpoint、journal、单编辑者锁，以及波形/代理缓存。这些是实现状态，不是人工创作的内容。

.openbbq/ 状态

质量关卡读写的小型状态文件：

out/

生成的字幕和硬字幕视频。默认名称由语言和格式推导，也可以用 --output 写到别处。

OpenBBQ 共享目录

OPENBBQ_HOME 默认为 ~/.openbbq，保存可复用或敏感的状态：

~/.openbbq/
├── auth/<site>/
├── glossaries/<name>.json
└── models/<provider>/

不要提交这个目录。Auth cookie 属于账号数据——注意保密，不再需要时用 openbbq auth clear <site> 删除。

环境变量

隔离的可写 home:

OPENBBQ_HOME=/tmp/openbbq-home openbbq models list

镜像，只在明确选择时使用：

HF_ENDPOINT=https://hf-mirror.com openbbq models pull large-v3-turbo