故障排查

常见问题的恢复办法——找不到工具、下载出错、阶段卡住、烧录失败。

大多数问题会自己报出来。OpenBBQ 报错时会带一个稳定的错误码，通常还有一条 fix——具体的下一步。先按它说的做。

先从这里开始

需要看得更全面时，两条命令基本能告诉你问题出在哪：

openbbq doctor
openbbq --json status --workspace workspaces/demo

doctor 检查你的电脑；status 告诉你某个工作区里进行到了哪一步。

确认 uv 装好了这个工具、并且 shell 能找到它：

uv tool list
uv tool update-shell

打开一个新的 shell，再试一次 openbbq --help。

识别器是可选组件。安装或修复它，然后检查：

uv tool install --force 'openbbq[whispercpp]'
openbbq doctor

模型需要单独下载。先看看缓存里已有什么，再下载一个：

openbbq models list
openbbq models pull large-v3-turbo

也可以让识别器在听写时顺手下载：

openbbq transcribe --model large-v3-turbo --auto-download

下载中断后，只要服务器支持断点续传（HTTP range），重新下载会接着上次的进度继续。如果下完的文件大小不对，OpenBBQ 会删掉这个无效文件并请你重试。

默认使用 --gpu。改用 CPU 重试：

openbbq transcribe --model large-v3-turbo --cpu --workspace workspaces/demo

原生后端有时只在受限的沙盒环境里失败，在普通终端里却没问题。先在正常的用户环境里试一次，再判断后端本身坏了。

openbbq doctor
ffmpeg -hide_banner -filters

把字幕烧进画面需要 ass 和 subtitles 两个 filter。缺了就装一个带 libass 的 FFmpeg 构建（见安装），或者给 burn 指定一个带这些 filter 的 FFmpeg：

openbbq burn --ffmpeg /path/to/ffmpeg --workspace workspaces/demo

在工作区文件夹里运行命令，或者显式传给它：

openbbq status --workspace /path/to/workspace

有效的工作区里要有 OpenBBQ 的 manifest.json——它的进度日志——而不是随便一个同名文件。工作区的概念见工作区与阶段。

有些平台要先登录、或证明“你是人”，才肯交出视频。登录一次，然后重新下载：

openbbq auth browser-login youtube
openbbq auth status youtube
openbbq fetch --workspace workspaces/demo

如果公开视频只在登录状态下失败，可以不带登录态下载：

openbbq fetch --workspace workspaces/demo --no-auth

如果保存的登录状态本身坏了，清掉再重新登录：

openbbq auth clear youtube
openbbq auth browser-login youtube

openbbq translate check zh --workspace workspaces/demo

它会列出还缺译文的字幕行 id。补上之后重新检查。导出时的 --allow-missing 只用于有意为之的草稿——没翻的行会回退成原文。

通常发生在重跑 segment 之后，因为字幕行被重新切了。重新生成工作表之前，先把旧工作表备份好，再按行 id 和原文把译文对应回新的字幕行。注意：translate init --force 会立刻丢弃旧文件。

openbbq export --to zh --mode bilingual --format ass --workspace workspaces/demo
openbbq burn --workspace workspaces/demo

某一步 60 秒没有心跳——没有任何动静——status 就会把它标记为 stale（陈旧）。先确认确实没有进程还在跑（看看它的日志），再重跑对应的命令。重跑会刷新这一阶段，并让依赖它的下游结果失效——阶段之间的依赖关系见质量关卡。

CLI 参考列出了每条命令和每个选项；工作区文件解释工作区里每个文件的用途。