Metadata-Version: 2.4
Name: openbbq
Version: 0.0.11
Summary: Agent-friendly CLI for video translation and subtitle production.
Author: ACAne0320
Author-email: ACAne0320 <nyaashino@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: pydantic>=2.13.4
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.7
Requires-Dist: yt-dlp>=2026.6.9
Requires-Dist: fastapi>=0.128.0 ; extra == 'review'
Requires-Dist: uvicorn>=0.40.0 ; extra == 'review'
Requires-Dist: pywhispercpp>=1.5.0 ; extra == 'whispercpp'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/ACAne0320/OpenBBQ
Project-URL: Repository, https://github.com/ACAne0320/OpenBBQ
Project-URL: Issues, https://github.com/ACAne0320/OpenBBQ/issues
Project-URL: Documentation, https://github.com/ACAne0320/OpenBBQ/tree/main/docs
Provides-Extra: review
Provides-Extra: whispercpp
Description-Content-Type: text/markdown

# OpenBBQ

[中文说明](README.zh-CN.md) · [Usage Guide](docs/usage.md)

**OpenBBQ** is a command-line tool for agent-driven video translation and
subtitle production.

OpenBBQ provides a default `agent init/next/apply/finish` facade so different
agents can turn one simple prompt into an editable bilingual subtitle draft.
The default workflow aims for a reliable 70–80 point first pass: useful without
manual setup, but intentionally not presented as a professionally reviewed
final subtitle.

OpenBBQ keeps structural correctness, bounded translation batches, artifact
freshness, and one-time export/burn deterministic. The agent handles
translation and may correct an obvious ASR occurrence or learn a reusable
glossary term while translating. Low-confidence words, display budgets, and
glossary consistency are advisory, not mandatory review queues.

An explicit `--glossary` always wins. Otherwise, once a URL fetch identifies
the author, OpenBBQ binds a stable author-and-target glossary automatically.
Terms learned in the task overlay are published conflict-safely after delivery
and reused by later videos from the same author in that target language—without
asking the model to choose a glossary.

For professional work, open the same workspace with `openbbq review` or import
the exported ASS into Aegisub or an editor. Human edits are authoritative and
the automatic workflow does not overwrite them. Fine-grained ASR, glossary,
translation, export, and burn commands remain available as expert tools.

## Why OpenBBQ?

In Chinese fansub and creator communities, the process of translating and subtitling foreign-language videos is often called "barbecue".
Raw untranslated material is "raw meat"; the translated, subtitled result is "cooked meat".

OpenBBQ is meant to be an open-source, open subtitle translation platform.

## Requirements

- Python 3.12 or newer
- [uv](https://docs.astral.sh/uv/), used to install the `openbbq` command and manage Python dependencies
- [ffmpeg](https://www.ffmpeg.org/), used for video download, audio/video merging, audio extraction, and video burning; subtitle burning also needs FFmpeg with `libass` support
- An ASR backend. OpenBBQ currently supports [whisper.cpp](https://github.com/absadiki/pywhispercpp) through its Python binding
- An ASR model. Models are not downloaded with the package. After installation, run `openbbq models list`, then explicitly run `openbbq models pull ...`
- A local desktop browser if the video platform requires login, human verification, or a browser challenge

## Install

### Agent Install

```markdown
Read the [install guide](https://raw.githubusercontent.com/ACAne0320/OpenBBQ/main/docs/install-agent.md) and help me install [OpenBBQ](https://github.com/ACAne0320/OpenBBQ).
```

### Manual Install

```bash
uv tool install 'openbbq[whispercpp]'
openbbq doctor
openbbq models list
openbbq models pull large-v3-turbo
openbbq doctor
```

## Quickstart

After installing OpenBBQ and its agent skill, give the agent one simple prompt:

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

The agent should run the complete workflow and return the editable ASS plus the
hard-subtitled video. You do not need to describe ASR, batching, glossary
maintenance, export, or burning in the prompt.

The underlying agent entry point is:

```bash
openbbq --json agent init '<video-or-url>' --workspace workspaces/demo --to zh [--glossary <name>]
openbbq --json agent next --workspace workspaces/demo
```

Continue following `agent next` until it returns `done`. A normal task has only
mechanical commands, translation batches of at most 20 cues, one finish, and no
default visual QA.

For local files, YouTube login, professional review, ASS presets, outputs, and
command details, see the [Usage Guide](docs/usage.md).

For agent setup and the packaged OpenBBQ skill, see the
[Agent Install Guide](docs/install-agent.md) and the
[OpenBBQ Skill](src/openbbq/skills/openbbq-subtitles/SKILL.md).

## Roadmap

- [ ] Demo video
- [ ] Detailed documentation site
- [ ] Windows and Linux support
- [ ] More ASR backends
- [ ] More video-platform authentication support
- [ ] Agent-led discovery of videos worth translating
- [x] Reproducible target-language translation briefs
- [x] Visual translation review for manual translators
- [ ] More subtitle editing and publishing workflows

## License

Apache-2.0. See [LICENSE](LICENSE).
