Quickstart

This guide uses an English local video and produces Chinese-over-English ASS subtitles. Replace paths and language codes to match your material.

1. Check the environment

openbbq doctor
openbbq models list

If you do not have a cached model yet:

openbbq models pull large-v3-turbo

2. Create a workspace

openbbq init --workspace workspaces/demo /path/to/video.mp4

init records the source and creates workspaces/demo/manifest.json. It does not copy or process the video.

Move into the workspace so later commands can discover it automatically:

cd workspaces/demo
openbbq status

You can stay elsewhere and pass --workspace workspaces/demo to every command instead.

3. Normalize the audio

openbbq extract-audio

This writes media/audio.16k.wav, a 16 kHz mono WAV suitable for ASR.

4. Transcribe

openbbq transcribe --model large-v3-turbo --language en --gpu

The result is transcript.json. --gpu is the default; use --cpu if the native backend cannot use the available accelerator or fails in a restricted environment.

If the model name is missing from the cache, either pull it first or opt into automatic download:

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

5. Build subtitle cues

openbbq segment

This deterministically converts the transcript into cues.json, using a language profile for timing, characters per line, and characters per second. The result reports any over-CPS or over-width cues for review.

6. Create a translation worksheet

openbbq translate init zh

Open translation.zh.json. Every item has a stable cue id, source text, timing information, translation budget, and a target field to fill.

For a small project, edit the target fields directly. For repeatable batches, create a JSON object:

{
  "1": "第一句译文",
  "2": "第二句译文"
}

Save it as targets.json, then merge it:

openbbq translate apply zh targets.json
openbbq translate check zh

apply is repeatable. check reports missing cues, translations over budget, and glossary term warnings.

7. Export bilingual ASS

openbbq export --to zh --mode bilingual --format ass --ass-preset fansub

The default output is out/zh.ass. Bilingual mode renders the target language above the source language.

Preview the ASS file in a compatible player before burning it into a video.

8. Burn subtitles (optional)

openbbq burn

burn uses the last exported ASS artifact and creates out/zh-burned.mp4. It requires a video source and FFmpeg with libass filters.

Inspect progress at any time

openbbq status

For scripts or agents:

openbbq --json status

Long-running commands update manifest.json; another process can poll status without parsing progress bars.

Final workspace

workspaces/demo/
├── manifest.json
├── media/
│   └── audio.16k.wav
├── transcript.json
├── cues.json
├── translation.zh.json
└── out/
    ├── zh.ass
    └── zh-burned.mp4

Next, see Local files and online video for URL sources or Export and burn for SRT, ASS modes, and presets.