安装

OpenBBQ 开火之前需要备齐几样东西。有两条路可以备：

• 交给 Agent：发一句话，让它装好并验证。
• 自己动手：逐个装好，最后把灶台检查一遍。

For Agent

把这句话发给 Agent（比如 Claude Code、Codex）：

帮我安装 OpenBBQ，参考这份安装 Playbook：https://openbbq.acane.dev/install-agent.zh-CN.md

它会先问你几个问题——输入来源、模型档位、GPU——只装需要的部分，装完用 openbbq doctor 验证。

For Human

想自己动手，或者想看看 Agent 在幕后做了什么？按下面的步骤逐个装好。

需要准备什么

• Python 3.12 或更新版本。
• uv：负责把 openbbq 命令装到电脑上。
• FFmpeg：负责从视频中提取音频和处理媒体文件。要把字幕烧进画面，还需要 libass 提供的 ass 和 subtitles 滤镜。
• 识别器：负责听音频，并把听到的话记成文字。OpenBBQ 使用 whisper.cpp，通过它的 Python 绑定安装，也就是下面的 whispercpp 可选组件。
• 下载好的模型：识别器真正用来“听”的文件。安装包里不带模型，需要自行选择并下载。
• 本机的桌面浏览器：视频平台要求登录或人机验证时会用到。

安装 OpenBBQ

uv tool install 'openbbq[whispercpp,review]'

方括号里是可选组件（extra）：whispercpp 带来识别器，review 带来浏览器里的可视化校对界面。不需要校对界面的话，改装 'openbbq[whispercpp]'。

装完后如果 shell 找不到 openbbq，按 uv 打印的 PATH 提示操作，然后打开一个新的 shell。

安装 FFmpeg

在 macOS 上，普通的 Homebrew 构建就够用来听写和大多数媒体处理：

brew install ffmpeg

要把字幕烧进画面，需要安装带 libass 的构建，比如：

brew install ffmpeg-full

openbbq doctor 会检查这两个必需的 filter；在 Homebrew 系统上，它也能自己找到 ffmpeg-full。

检查环境

openbbq doctor

doctor 只看不动，不会改动你的任何东西，可以放心反复运行。它会检查 Python、FFmpeg、字幕 filter、yt-dlp、识别器、缓存的模型，以及随包附带的 Agent Skill。缺了必需项时，它会打印一条 fix，照着做就行。

需要机器可读的输出时（比如让 AI Agent 来读）：

openbbq --json doctor

下载模型

模型不随安装包提供。先看看目录里有哪些模型、缓存里已有什么：

openbbq models list

想快速尝鲜，base 约 148 MB；正式做字幕，建议从约 1.6 GB 的 large-v3-turbo 开始：

openbbq models pull base
openbbq models pull large-v3-turbo

下载中断后可以续传，默认保存在 ~/.openbbq/models/whisper.cpp/。想让 OpenBBQ 把数据放在别处，就设置 OPENBBQ_HOME。

验证安装

openbbq doctor
openbbq --help

打算烧录字幕的话，确认 doctor 输出里 ffmpeg subtitle filters 一行同时报告了 ass 和 subtitles。

升级或修复

uv tool upgrade openbbq

要调整可选组件或修复损坏的安装，强制重装：

uv tool install --force 'openbbq[whispercpp,review]'

从仓库安装

只有想开发 OpenBBQ 本身时才需要：

git clone https://github.com/ACAne0320/OpenBBQ.git
cd OpenBBQ
uv sync --extra whispercpp --extra review --dev
uv run openbbq --help
uv run pytest

全部通过之后，去快速上手，把第一个视频从生肉烤成熟肉。