Installation

Requirements

• Python 3.12 or newer.
• uv for installing the openbbq command.
• FFmpeg for audio extraction and video processing. Hard-subtitle burning requires the ass and subtitles filters from libass.
• An ASR backend. OpenBBQ currently supports whisper.cpp through pywhispercpp.
• An explicitly downloaded ASR model.
• A local desktop browser when an online platform requires login or human verification.

Install the CLI

Install the published package with the whisper.cpp backend and the local review UI:

uv tool install 'openbbq[whispercpp,review]'

If you do not need browser-based subtitle review, the review extra may be omitted.

If the openbbq command is not found after installation, follow the PATH instruction printed by uv, then open a new shell.

Install FFmpeg

On macOS, the regular Homebrew package is sufficient for transcription and most media tasks:

brew install ffmpeg

For hard-subtitle burning, install a build that includes libass. openbbq doctor checks both required filters and, on Homebrew systems, can also discover ffmpeg-full:

brew install ffmpeg-full

Check the environment

doctor is read-only and safe to run repeatedly:

openbbq doctor

It checks Python, FFmpeg, subtitle filters, yt-dlp, the ASR backend, cached models, and the packaged Agent skill. Follow the fix shown for any missing required item.

For machine-readable output:

openbbq --json doctor

Download a model

Models are not bundled with the package. List the catalog and current cache state:

openbbq models list

For a quick preview, download base (about 148 MB). For production subtitles, start with large-v3-turbo (about 1.6 GB):

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

Downloads are resumable and stored under ~/.openbbq/models/whisper.cpp/ by default. Set OPENBBQ_HOME to change the OpenBBQ data directory.

Verify the installation

openbbq doctor
openbbq --help

For hard-subtitle workflows, confirm that ffmpeg subtitle filters reports both ass and subtitles.

Upgrade or reinstall

uv tool upgrade openbbq

To change extras or repair the installation:

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

Install from this repository

Use a repository install only for development:

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