Installation

OpenBBQ needs a few ingredients before it can cook. Two ways to stock the kitchen:

• With an agent: paste one sentence and let it install.
• By hand: install each piece yourself, then check the kitchen.

For agents

Paste one sentence to your agent — Claude Code, Codex, or similar:

Read the OpenBBQ agent install playbook and help me install OpenBBQ: https://openbbq.acane.dev/install-agent.md

It asks a few questions first — input source, model size, GPU — installs only what you need, and verifies with openbbq doctor.

For humans

Prefer to drive yourself, or want to see what the agent does under the hood? Install each piece yourself.

What you need

• Python 3.12 or newer.
• uv: the installer that puts the openbbq command on your machine.
• FFmpeg: extracts audio from video and handles media processing. Burning subtitles into the picture also needs the ass and subtitles filters from libass.
• A recognizer: the part that listens to the audio and writes down what it hears. OpenBBQ uses whisper.cpp, installed through its Python binding (the whispercpp extra below).
• A downloaded model: the file the recognizer listens with. No model ships in the package; you choose one and download it.
• A local desktop browser, for when a video platform asks you to log in or pass a human check.

Install the CLI

uv tool install 'openbbq[whispercpp,review]'

The brackets name add-ons: whispercpp brings the recognizer, review adds the browser-based visual review screen. If you don't want the review screen, install 'openbbq[whispercpp]' instead.

If your shell can't find openbbq afterwards, follow the PATH instruction printed by uv, then open a new shell.

Install FFmpeg

On macOS, the regular Homebrew build covers transcription and most media tasks:

brew install ffmpeg

For burning subtitles into video, install a build that includes libass, for example:

brew install ffmpeg-full

openbbq doctor checks both required filters and, on Homebrew systems, can find ffmpeg-full on its own.

Check the environment

openbbq doctor

doctor is read-only, so you can run it as often as you like. It checks Python, FFmpeg, the subtitle filters, yt-dlp, the recognizer, cached models, and the agent skill that ships with the package. If something required is missing, it prints a fix; follow that.

For machine-readable output (handy when an AI agent is driving):

openbbq --json doctor

Download a model

Models are not bundled with the package. See the catalog and what's already cached:

openbbq models list

For a quick taste, base is about 148 MB. For real subtitles, start with large-v3-turbo at about 1.6 GB:

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

Downloads resume if interrupted, and land in ~/.openbbq/models/whisper.cpp/ by default. Set OPENBBQ_HOME if you want OpenBBQ to keep its data somewhere else.

Verify the installation

openbbq doctor
openbbq --help

If you plan to burn subtitles, confirm that doctor's ffmpeg subtitle filters line reports both ass and subtitles.

Upgrade or repair

uv tool upgrade openbbq

To change the add-ons or repair a broken install, force a reinstall:

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

Install from the repository

Only needed if you want to develop OpenBBQ itself:

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

Everything green? The Quickstart walks your first video from raw to cooked.