Workspace files

One video, one workspace folder. Every step of the pipeline saves its result as a plain file you can open and inspect. This page explains what each file is for; CLI reference lists the commands that produce them.

Workspace layout

A fully processed workspace commonly contains:

workspace/
├── manifest.json
├── media/
│   ├── <downloaded media>
│   ├── <thumbnail>
│   └── audio.16k.wav
├── transcript.json
├── cues.json
├── translation.zh.json
├── review.zh.json
├── .openbbq/
│   ├── asr-review.json
│   ├── translation-audit.zh.json
│   ├── qa.json
│   ├── artifacts.json
│   └── review/
│       ├── journal.json
│       ├── checkpoints/
│       └── cache/
└── out/
    ├── en.srt
    ├── zh.ass
    └── zh-burned.mp4

Only artifacts produced by commands are created. A local source stays at its original absolute path; media fetched from a URL lives under media/.

manifest.json

The manifest schema is currently openbbq/manifest@1. It records:

• Creation time.
• Source type and reference.
• Fetched title, author, and thumbnail when available.
• Bound glossary name.
• Per-stage status, artifact, progress heartbeat, update time, and error.

It is a validated work log maintained by commands — not a pipeline configuration file.

transcript.json

What the recognizer heard: the detected or forced language, media duration, backend and model metadata, segments, and word-level timing and confidence when the backend supplies them.

Regenerate it with transcribe. Malformed or incompatible files are rejected with an invalid_transcript error.

cues.json

The subtitle-line timeline, derived deterministically from the transcript. It includes:

• Source language.
• The segmentation parameters used.
• Stable line ids, start/end times, and source text.

Translation worksheets and exports depend on line identity. Rerunning segment can require reconciling existing worksheets.

translation.<lang>.json

One editable worksheet per target language. Unfilled targets stay null, so the remaining work is easy to discover. Use translate apply for controlled batch updates and translate check for integrity.

review.<lang>.json

Per-line review state — review.source.json when you review the source only. The schema is openbbq/review@1. It stores per-line status, notes, content fingerprints, the selected target language, and revision metadata. It does not duplicate the subtitle text.

Review edits keep cues.json and all worksheets aligned. Mutations go through recoverable checkpoints and a cross-file journal, and undo/redo is available during the active session.

.openbbq/review/ holds the checkpoints, the journal, the single-editor lock, and waveform/proxy caches. These are implementation state, not authored content.

.openbbq/ state

Small state files that the quality gates read and write:

out/

Generated subtitles and hard-subtitled videos. Default names derive from language and format, but --output can write elsewhere.

Shared OpenBBQ home

OPENBBQ_HOME defaults to ~/.openbbq and stores reusable or sensitive state:

~/.openbbq/
├── auth/<site>/
├── glossaries/<name>.json
└── models/<provider>/

Do not commit this directory. Auth cookies are account data — keep them private and remove them with openbbq auth clear <site> when no longer needed.

Environment variables

An isolated, writable home:

OPENBBQ_HOME=/tmp/openbbq-home openbbq models list

A mirror, only when intentionally selected:

HF_ENDPOINT=https://hf-mirror.com openbbq models pull large-v3-turbo