CLI 参考

OpenBBQ 的所有命令，按流水线顺序排列。处理视频的命令都在工作区里进行；工作区文件解释了那里每个文件的作用。

全局语法

openbbq [--json] COMMAND [ARGS]...

选项	说明
`--json`	输出一个机器可读的 JSON 对象，必须放在命令之前。
`--help`	显示当前命令或命令组的帮助。
`--install-completion`	安装 shell 补全。
`--show-completion`	输出 shell 补全代码。

大多数工作区命令接受 --workspace PATH（简写 -w PATH）；省略时，OpenBBQ 会从当前目录向上查找工作区。

`agent`

一句提示词工作流的默认 facade。只初始化一次，之后持续请求唯一权威的下一步：

openbbq --json agent init SOURCE [--workspace PATH] [--to CODE] [--glossary NAME]
openbbq --json agent next [--workspace PATH] [--to CODE]
openbbq --json agent apply RESPONSE.json [--workspace PATH] [--to CODE]
openbbq --json agent finish [--workspace PATH] [--to CODE]

命令	说明
`agent init`	创建工作区和一个 Agent session。`--to` 默认为 `zh`；显式传入 `--glossary` 会绑定已有的全局术语表。
`agent next`	只返回 `run_command`、`review_source`、`translate`、`finish` 或 `done` 其中一个 action。每个 action 成功后再次调用。
`agent apply`	原子应用当前语义 lease 的完整 JSON 响应。缺少、额外、过期或 policy 不匹配的内容都会被拒绝。
`agent finish`	导出双语 ASS、烧录视频、检查交付，并发布符合条件的 glossary 学习。只在 `agent next` 返回它时运行。

原样使用返回的 argv，并遵守其中的 execution policy。Lease、有界翻译、中断恢复和底稿质量语义见工作流模型。

`doctor`

openbbq doctor

检查环境：Python、FFmpeg、字幕滤镜、yt-dlp、识别器后端、已缓存模型和 Agent Skill。只读且幂等——不会改动任何东西。

`init`

openbbq init [--workspace PATH] [--glossary NAME] SOURCE

输入	说明
`SOURCE`	必填，URL 或本地视频/音频路径。
`--workspace`、`-w`	工作区目录。省略时在当前目录下创建一个 slug 子目录；用 `.` 表示当前目录本身。
`--glossary`	初始化时直接绑定已有的全局术语表。

只创建工作区和它的 manifest，还不会下载或处理任何内容。

`status`

openbbq status [--workspace PATH]

报告来源元数据、绑定的术语表、工作表、已记录的阶段及进度、产物、失败记录，以及卡在“运行中“的过期阶段。

`fetch`

openbbq fetch [--workspace PATH] [--auth SITE | --no-auth] [--max-height INT]

选项	说明
`--auth SITE`	使用已保存的网站会话，目前是 `youtube`。
`--no-auth`	强制匿名下载。
`--max-height INT`	限制视频分辨率上限，例如 `1080`。

只对 URL 来源有效。支持的 YouTube 链接会自动使用已配置的会话，除非传入 --no-auth。

`extract-audio`

openbbq extract-audio [--workspace PATH]

把来源媒体标准化为 media/audio.16k.wav——16 kHz 单声道，也就是识别器“听“的那条音频。

`transcribe`

openbbq transcribe [OPTIONS]

选项	默认值	说明
`--model NAME_OR_PATH`	缓存中质量最佳的模型	缓存模型名，或 ggml `.bin` 文件的直接路径。
`--backend NAME`	`auto`	识别器后端：`auto` 或 `whisper.cpp`。
`--language CODE`	自动检测	强制指定原语言，例如 `en`。
`--prompt TEXT`	无	识别器的初始 prompt。
`--glossary NAME`	manifest 绑定	覆盖已绑定的术语表。
`--gpu` / `--cpu`	`--gpu`	开关 GPU 加速。
`--auto-download`	关闭	听写前自动下载缺失的命名模型。

需要先运行 extract-audio。写出 transcript.json——它听到的每句话，都带时间。

`segment`

openbbq segment [OPTIONS]

选项	说明
`--lang CODE`	覆盖听写稿的原语言。
`--glossary NAME`	覆盖用于别名纠错的已绑定术语表。
`--max-cps FLOAT`	最大每秒字符数。
`--max-chars-per-line INT`	每行字符预算。
`--max-lines INT`	每条字幕的最大行数。
`--min-dur FLOAT`	字幕最短时长（秒）。
`--max-dur FLOAT`	字幕最长时长（秒）。
`--min-gap FLOAT`	字幕之间的最小间隔（秒）。
`--pause-threshold FLOAT`	触发切分的停顿时长（秒）。

把听写稿切成一行行字幕，写出 cues.json。内置 en、zh、ja、ko 四种语言配置，其他语言回退到通用拉丁配置。

`asr`

听写检查：在切字幕和翻译之前，先核实识别器听到的内容。

`asr check`

openbbq asr check [--workspace PATH] [--max-prob FLOAT]

报告存疑的位置，以及是否每个问题都已有了决定（ready）。--max-prob 设定置信度阈值，低于它的词会被列为存疑。

`asr batch`

openbbq asr batch [--workspace PATH] [--offset INT] [--limit INT] [--only-unresolved | --all] [--max-prob FLOAT]

读取一个有上限的问题批次——先列字幕段异常，再列低置信度词的出现位置。

选项	默认值	说明
`--offset INT`	`0`	跳过前 N 条。
`--limit INT`	`20`	每批最多条数。
`--only-unresolved` / `--all`	`--only-unresolved`	只看未解决，或看全部。
`--max-prob FLOAT`	—	与 `asr check` 相同的置信度阈值。

`asr apply`

openbbq asr apply [--workspace PATH] DECISIONS.json

合并你的决定。词和专名用 accept 或 replace——replace 需要精确的 find 原文和 replacement；重复的字幕段用 keep_first 或 drop。每个决定都必须写明理由。

`asr amend`

openbbq asr amend [--workspace PATH] AMENDMENTS.json

对检测器没有标记的错误做一次性的短语修正。每条包含 segment_id、find、replacement 和 reason。

`translate`

`translate init`

openbbq translate init [--workspace PATH] [--glossary NAME] [--force] LANG

根据 cues.json 创建 translation.<lang>.json。--force 会丢弃已有工作表，包括所有已翻译的内容。

`translate batch`

openbbq translate batch [--workspace PATH] [LANG] [--from INT] [--limit INT] [--only-missing] [--context INT]

读取工作表中一段有上限的切片，并带上相邻字幕行作为上下文——谁都不用一次加载整个文件。

选项	默认值	说明
`--from INT`	`1`	起始行，最小 `1`。
`--limit INT`	`20`	读取行数，`1`–`200`。
`--only-missing`	关闭	只读还缺译文的行。
`--context INT`	`1`	每侧带的相邻行数，`0`–`5`。

`translate apply`

openbbq translate apply [--workspace PATH] LANG TARGETS.json

合并一个把字幕行 id 映射到译文的 JSON 对象，可以一批接一批反复执行。未知或格式错误的 id 会被拒绝。

`translate check`

openbbq translate check [--workspace PATH] [LANG]

报告完整度、缺失 id、超出长度预算的行、术语警告和字幕行完整性。只有一个工作表时会自动推断语言。

`translate audit`

openbbq translate audit [--workspace PATH] [LANG] [--offset INT] [--limit INT] [--only-unreviewed | --all] [--coverage risks|all]

读取一批有上限的字幕行做语义审校——风险高的排前面，每行都带相邻上下文。

选项	默认值	说明
`--offset INT`	`0`	跳过前 N 条。
`--limit INT`	`20`	每批最多条数。
`--only-unreviewed` / `--all`	`--only-unreviewed`	只看未审校，或看全部。
`--coverage risks\|all`	`all`	只看风险行，或覆盖整个工作表。

`translate audit-apply`

openbbq translate audit-apply [--workspace PATH] LANG DECISIONS.json

合并 accept/revise 决定。每个决定都要写理由，revise 还要带上修改后的译文。

`review`

openbbq review [--workspace PATH] [--to CODE] [--port PORT] [--no-open] [--prepare] [--apply FILE]

打开一个只监听本机的浏览器编辑器：视频预览、波形和字幕行时间线、原文/译文编辑、校对备注和状态。--to 选择初始翻译工作表；省略时以仅原文模式启动，也可以在编辑器里再选字幕语言。--port 指定端口，--no-open 不自动打开浏览器。

--prepare 不启动服务器，而是输出一份 agent 预分析 JSON（含已算好的各 cue rule issues 与响应 schema）；--prepare --apply FILE 校验 agent 的响应并归档为待处理的 review 建议。两个步骤都不持有校对锁、不启动服务器。

修改会原子写入 cues.json、所有受影响的 translation.<lang>.json，以及 review.<lang>.json（或 review.source.json）。同一工作区同一时间只允许一个校对会话持有锁。

`glossary`

`glossary list` / `show` / `new` / `use`

openbbq glossary list
openbbq glossary show NAME
openbbq glossary new [--context TEXT] NAME
openbbq glossary use [--workspace PATH] NAME

列出术语表、查看某一个、新建一个，或把一个绑定到工作区。

`glossary suggest`

openbbq glossary suggest [--workspace PATH] [OPTIONS]

从识别器没听准的词里挑出候选，建议加入术语表。

选项	默认值	说明
`--glossary NAME`	无	排除该术语表已收录的词。
`--max-prob FLOAT`	`0.6`	只取平均置信度低于此值的词。
`--min-count INT`	`1`	最小出现次数。
`--max INT`	`30`	最多返回的候选数。

`glossary audit`

openbbq glossary audit [--workspace PATH] [--offset INT] [--limit INT] [--glossary NAME]

逐页翻查每个已解决的听写段及其证据。跟着 next_offset 一直读到没有剩余。

选项	默认值	说明
`--offset INT`	`0`	跳过前 N 条。
`--limit INT`	`20`	每页条数，最大 `20`。
`--glossary NAME`	—	用指定的术语表审校。

`glossary apply`

openbbq glossary apply [--workspace PATH] CHANGES.json [--glossary NAME]

从文件中的 terms 数组原子地新增或更新至多 20 个词条。

`export`

openbbq export [OPTIONS]

选项	默认值	说明
`--to CODE`	无	目标工作表语言。
`--mode source\|target\|bilingual`	无 `--to` 时 source，否则 target	文件里放哪些文字。
`--format srt\|ass`	`srt`	字幕格式。
`--output PATH`	`out/<lang>.<format>`	输出路径。
`--ass-preset default\|fansub\|fansub-compact\|mobile`	`default`	ASS 样式预设，只对 ASS 有效。
`--allow-missing`	关闭	译文为空的行回退到原文。
`--allow-unreviewed`	关闭	绕过校对关卡，导出一份明知是草稿的字幕。
`--allow-quality-warnings`	关闭	在仍有未决质量问题时，有意导出草稿。

`burn`

openbbq burn [--workspace PATH] [--subtitle FILE.ass] [--output FILE.mp4] [--ffmpeg PATH]

把字幕烧进画面。省略 --subtitle 时使用最近一次导出的产物；默认输出名由字幕文件名推导，例如 out/zh-burned.mp4。要求视频来源和 ASS 输入。工作区内被改动或未登记的 ASS 会被拒绝——--allow-stale 只留给有意为之的手工草稿。

`qa`

可选的人工视觉诊断：亲眼看看烧好视频的真实画面。

`qa render`

openbbq qa render [--workspace PATH] [--count INT] [--ffmpeg PATH]

从烧好的 MP4 里抽取带字幕的画面帧。--count 选帧数，1–9，默认 7。

`qa check`

openbbq qa check [--workspace PATH]

只读核验当前 MP4 与各帧的哈希，以及视觉检查状态。

`qa attest`

openbbq qa attest [--workspace PATH] --result pass|fail --reason TEXT [--issue CODE]

记录一次视觉判定。--issue 可以重复，附上多个问题代码。

`delivery`

openbbq delivery check [--workspace PATH] [--to CODE]

硬性交付关卡：在所有质量检查通过之前以非零状态退出——听写决定、翻译检查、语义审校、ASS 内容精确一致、导出与烧录的新鲜度、烧录来源，以及 MP4 非空。

`models`

openbbq models list
openbbq models pull NAME

list 报告来源、近似大小和缓存状态；pull 校验模型名，并以可恢复的传输下载到全局缓存。

常用选择：

模型	近似大小	用途
`base`	148 MB	快速预览
`small`	488 MB	适中成本下更好的质量
`large-v3-turbo-q5_0`	574 MB	量化正式字幕选项
`large-v3-turbo`	1.6 GB	推荐的正式字幕起点
`large-v3`	3.1 GB	目录中质量最高的大模型

完整目录（包括英文专用和量化变体）以 models list 为准。

`auth`

openbbq auth browser-login youtube
openbbq auth status youtube
openbbq auth clear youtube

通过浏览器登录、查看已保存的会话，或删除它。目前只有 youtube 这个站点键。

`skill`

openbbq skill install [OPTIONS]
openbbq skill show [OPTIONS]

Install 选项：

选项	默认值	说明
`--agent claude\|codex\|agents\|all`	`agents`	安装到哪个 Agent 目录。
`--target PATH`	目标默认目录	自定义目录，其中包含安装好的 Skill 文件夹。
`--name openbbq-subtitles\|bilibili-cover-safe-area`	`openbbq-subtitles`	随包 Skill。
`--force`	关闭	覆盖已安装的 Skill。

skill show 接受相同的 --name 选择，以及 --language en\|zh-CN（默认 en）。

CLI 参考

本页目录