Quickstart

This guide takes an English video file and finishes with a Chinese-over-English subtitled video. There are two ways to get there:

• With an agent: hand over the job and let the agent run the workflow.
• By hand: run every command yourself and see what happens at each stage.

For agents

If you use an agent like Claude Code or Codex, you do not need to memorize the commands. Teach the agent the workflow once:

openbbq skill install --agent claude

Use --agent codex for Codex, or plain openbbq skill install for the shared agents directory. Then paste one prompt:

Make this a bilingual Chinese-English subtitled video: https://www.youtube.com/watch?v=xxx

The agent initializes one workspace, then follows the single next action returned by OpenBBQ until the draft is ready. It can download a model if needed, transcribe, fix structural listening problems, translate in bounded batches, export, and burn. It pauses when a step needs you, such as signing in.

The finished file is out/zh-burned.mp4. OpenBBQ labels the automatic result as an editable draft; it only becomes human-reviewed after someone checks every current cue in openbbq review. See Workflow model for the Agent contract and safe recovery rules.

A local file works just as well. Give the agent a path such as ./video.mp4 instead of a URL.

For humans

Prefer to drive yourself, or want to understand what the agent does under the hood? Run the same grill by hand. Swap in your own file and language codes as you go.

1. Check your setup

openbbq doctor

Fix anything it flags, then make sure you have a recognition model:

openbbq models list
openbbq models pull large-v3-turbo

2. Create a workspace

One video lives in one workspace folder:

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

Move into it so later commands find it on their own:

cd workspaces/demo

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

3. Prepare the audio

openbbq extract-audio

This gives the recognizer a clean audio track to listen to.

4. Write down what it hears

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

OpenBBQ listens to the audio and writes every sentence with its timing to transcript.json. This takes a while for long videos; openbbq status shows the progress from another terminal.

5. Check the listening

Before anything gets translated, OpenBBQ points at the words it wasn't sure about:

openbbq asr check

• ready: true: nothing suspicious, move on.
• Not ready: it lists the spots it doubts. Transcription and listening checks shows how to confirm or fix them. Cutting into lines waits until this passes.

6. Cut into subtitle lines

openbbq segment

The transcript becomes cues.json, a set of subtitle lines with start and end times, sized for comfortable reading.

7. Translate

Create a translation worksheet:

openbbq translate init zh

Open translation.zh.json: every line has the source text and an empty target waiting for your translation. For a handful of lines, edit it directly. For more, write small batches and merge them in:

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

openbbq translate apply zh targets.json

Then check the work:

openbbq translate check zh

It catches missing lines, lines too long to read, and inconsistent names. Fix what it reports until it answers ready: true.

8. Export bilingual subtitles

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

You get out/zh.ass, with Chinese above English and styling for horizontal video. Preview it in a player that understands ASS before burning anything.

9. Burn it in (optional)

openbbq burn

A few minutes later you have out/zh-burned.mp4, with the subtitles as part of the picture.

10. Before you serve it

openbbq delivery check --to zh

This is the final gate before publishing. It checks the listening decisions, translation, review state, and burned video again. If something is still open, such as the full line-by-line review, it tells you what remains and how to finish it. Quality gates explains the idea.

Your workspace now

workspaces/demo/
├── manifest.json        # progress log
├── media/               # prepared audio
├── transcript.json      # what it heard
├── cues.json            # subtitle lines
├── translation.zh.json  # your translation
└── out/                 # subtitles and burned video

Where next?

• Working from a YouTube link instead? See Getting video.
• Letting an Agent drive? Read the Workflow model.
• Want to check everything on screen before publishing? Try Visual review.
• Curious what each file is? Workspace files.