openbbq 0.0.1__tar.gz

openbbq-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 ACAne0320
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

openbbq-0.0.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: openbbq
+Version: 0.0.1
+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: faster-whisper>=1.2.1 ; extra == 'faster-whisper'
+Requires-Dist: mlx-whisper>=0.4.3 ; extra == 'mlx-whisper'
+Requires-Dist: pywhispercpp>=1.5.0 ; extra == 'whispercpp'
+Requires-Dist: whisperx>=3.8.6 ; extra == 'whisperx'
+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: faster-whisper
+Provides-Extra: mlx-whisper
+Provides-Extra: whispercpp
+Provides-Extra: whisperx
+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 composable tools for video download, audio extraction, ASR transcription, segmentation, translation, review, subtitle export, and subtitle burning.
+It does not force one fixed pipeline. The goal is to let an agent choose the right workflow for each task.
+
+## 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.
+
+## Quick Start
+
+## 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
+
+## For Agent
+
+```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
+```
+
+## Use
+
+Human workflow:
+
+```bash
+openbbq init --workspace workspaces/demo 'https://www.youtube.com/watch?v=...'
+cd workspace/demo
+openbbq fetch
+openbbq extract-audio
+openbbq transcribe --model large-v3-turbo --language en --gpu
+openbbq segment
+openbbq translate init zh
+# fill in translations in workspaces/demo/translation.zh.json
+openbbq translate check zh
+openbbq export --to zh --mode bilingual --format ass --output out/zh.ass
+openbbq burn
+```
+
+Agent workflow:
+
+```bash
+openbbq --json status --workspace workspaces/demo
+```
+
+Agents should use `--json` and pass the workspace explicitly with `-w`.
+For long-running tasks, poll the workspace state with `openbbq status`.
+For subtitle tasks, follow `skills/openbbq-subtitles/SKILL.md`.
+
+For local files, YouTube login, ASS presets, outputs, and command details, see
+[docs/usage.md](docs/usage.md).
+
+## Roadmap
+
+[ ] Windows/Linux support
+[ ] More ASR backends
+[ ] More video platform authentication support
+[ ] A visual translation step for people who want to translate manually
+[ ] ...
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

openbbq-0.0.1/README.md

@@ -0,0 +1,85 @@
+# 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 composable tools for video download, audio extraction, ASR transcription, segmentation, translation, review, subtitle export, and subtitle burning.
+It does not force one fixed pipeline. The goal is to let an agent choose the right workflow for each task.
+
+## 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.
+
+## Quick Start
+
+## 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
+
+## For Agent
+
+```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
+```
+
+## Use
+
+Human workflow:
+
+```bash
+openbbq init --workspace workspaces/demo 'https://www.youtube.com/watch?v=...'
+cd workspace/demo
+openbbq fetch
+openbbq extract-audio
+openbbq transcribe --model large-v3-turbo --language en --gpu
+openbbq segment
+openbbq translate init zh
+# fill in translations in workspaces/demo/translation.zh.json
+openbbq translate check zh
+openbbq export --to zh --mode bilingual --format ass --output out/zh.ass
+openbbq burn
+```
+
+Agent workflow:
+
+```bash
+openbbq --json status --workspace workspaces/demo
+```
+
+Agents should use `--json` and pass the workspace explicitly with `-w`.
+For long-running tasks, poll the workspace state with `openbbq status`.
+For subtitle tasks, follow `skills/openbbq-subtitles/SKILL.md`.
+
+For local files, YouTube login, ASS presets, outputs, and command details, see
+[docs/usage.md](docs/usage.md).
+
+## Roadmap
+
+[ ] Windows/Linux support
+[ ] More ASR backends
+[ ] More video platform authentication support
+[ ] A visual translation step for people who want to translate manually
+[ ] ...
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

openbbq-0.0.1/README.zh-CN.md

@@ -0,0 +1,84 @@
+# OpenBBQ
+
+[English README](README.md) · [使用指南](docs/usage.zh-CN.md)
+
+**OpenBBQ** 是一个专为智能体（Agent）设计的用于视频翻译和字幕制作的命令行工具。
+
+OpenBBQ 提供了一系列可组合的工具，涵盖视频下载、音频提取、ASR 转录、分段、翻译、校对、字幕导出以及烧录字幕等环节。
+不强制采用固定的处理流程，而是更希望 Agent 根据用户的不同目标，灵活制定最合适的工作流程。
+
+## Why OpenBBQ?
+
+在中国字幕组和创作者社群中，翻译并制作外语视频字幕的过程通常被称为“烤肉”。
+未经翻译的原始素材通常被称作“生肉”，而经过翻译和添加字幕的成品则变成了“熟肉”。
+
+所以 OpenBBQ 的愿景是，做一个开源、开放的字幕翻译平台。
+
+## 快速开始
+
+## 前置条件
+
+- Python 3.12 或更新版本
+- [uv](https://docs.astral.sh/uv/)，用于安装 `openbbq` 命令和管理 Python 依赖
+- [ffmpeg](https://www.ffmpeg.org/)，用于下载视频、合并音视频、抽取音频和视频烧录；如果有烧录字幕的需求，FFmpeg 还需要 `libass` 支持
+- 一个 ASR 后端，目前仅支持 [whisper.cpp](https://github.com/absadiki/pywhispercpp) (Python Binding)
+- 一个 ASR 模型，模型不随安装包一起下载，安装后用 `openbbq models list` 查看可用档位，再显式执行 `openbbq models pull ...`。
+- 如果需要下载的视频平台要求登录、人机验证或浏览器挑战，需要本机桌面浏览器；
+
+## For Agent
+
+```markdown
+查看[安装指南](https://raw.githubusercontent.com/ACAne0320/OpenBBQ/main/docs/install-agent.zh-CN.md)，帮我安装[OpenBBQ](https://github.com/ACAne0320/OpenBBQ)
+```
+
+## 手动安装
+
+```bash
+uv tool install 'openbbq[whispercpp]'
+openbbq doctor
+openbbq models list
+openbbq models pull large-v3-turbo
+openbbq doctor
+```
+
+## 使用
+
+Human 工作流：
+
+```bash
+openbbq init --workspace workspaces/demo 'https://www.youtube.com/watch?v=...'
+cd workspace/demo
+openbbq fetch
+openbbq extract-audio 
+openbbq transcribe --model large-v3-turbo --language en --gpu
+openbbq segment
+openbbq translate init zh
+# 在 workspaces/demo/translation.zh.json 中填写翻译内容
+openbbq translate check zh 
+openbbq export --to zh --mode bilingual --format ass --output out/zh.ass
+openbbq burn
+```
+
+Agent 工作流：
+
+```bash
+openbbq --json status --workspace workspaces/demo
+```
+
+Agent 通常使用 `--json`，并且使用 `-w` 显式指明 workspace
+当进行长任务时，使用 `openbbq status` 轮询工作空间状态
+在具体的字幕任务中参考 `skills/openbbq-subtitles/SKILL.md` 中的使用方法
+
+本地文件流程、YouTube 登录、ASS 预设、输出文件和完整命令说明见
+[docs/usage.zh-CN.md](docs/usage.zh-CN.md)。
+
+## 路线图
+[ ] Windows/Linux 支持
+[ ] 更多 ASR 后端支持
+[ ] 更多视频平台鉴权支持
+[ ] 可视化翻译步骤（给想自己翻译的人）
+[ ] ...
+
+## 许可证
+
+Apache-2.0，见 [LICENSE](LICENSE)。

openbbq-0.0.1/docs/install-agent.md

@@ -0,0 +1,99 @@
+# OpenBBQ Agent Install Playbook
+
+This guide is for AI agents. The goal is to install OpenBBQ on the user's machine and only add the dependencies needed for the user's task.
+
+## Principles
+
+- Do not install system dependencies without asking.
+- Do not download models without asking.
+- Ask the questions that affect install size and install path first.
+- Run `openbbq doctor --json`, then add only the missing pieces.
+- Ask before installing system packages, downloading models, writing browser login state, or configuring API keys.
+- Finish with a passing `openbbq doctor`.
+
+## Ask First
+
+Confirm these details before installing:
+
+- Platform: macOS, Linux, or Windows.
+- Input source: local video, local audio, YouTube, or another online video platform.
+- Source language and target language.
+- Model size: `base` for a quick preview, `large-v3` or `large-v3-turbo` for production subtitles.
+- Whether the user needs hard-subtitle burning.
+- Whether the user needs speaker diarization.
+- Whether the user wants API translation.
+- Whether the machine has a GPU, and roughly what kind: Apple Silicon, NVIDIA, AMD / Intel, or CPU only.
+
+## Bootstrap
+
+Prefer the published package:
+
+```bash
+uv tool install openbbq
+```
+
+If the user has confirmed the default whisper.cpp backend:
+
+```bash
+uv tool install 'openbbq[whispercpp]'
+```
+
+Use a local repository install only for development or before a package has been published:
+
+```bash
+uv tool install '.[whispercpp]'
+```
+
+## Check The Environment
+
+```bash
+openbbq doctor --json
+```
+
+Use the output to decide what is missing:
+
+- Python must be 3.12 or newer.
+- If FFmpeg is missing, install an FFmpeg build with `libass`. Hard-subtitle burning needs the `ass` and `subtitles` filters.
+- If the ASR backend is missing, install `pywhispercpp` by default. macOS wheels usually include Metal support. NVIDIA / Vulkan routes may need local toolkits and source builds.
+- If the model is missing, ask the user to confirm the model size, then run `openbbq models pull <model>`.
+- If YouTube requires login or human verification, run `openbbq auth browser-login youtube`.
+- If the user needs speaker diarization, install whisperX and confirm the Hugging Face token.
+- If the user wants API translation, configure the provider key.
+
+## Models
+
+List model sizes and cache state:
+
+```bash
+openbbq models list
+```
+
+Quick preview:
+
+```bash
+openbbq models pull base
+```
+
+Production subtitles:
+
+```bash
+openbbq models pull large-v3-turbo
+```
+
+If the user has trouble reaching Hugging Face, ask before using a mirror:
+
+```bash
+HF_ENDPOINT=https://hf-mirror.com openbbq models pull large-v3-turbo
+```
+
+Models are stored in OpenBBQ's global cache and reused across workspaces. They are not written into the video project directory.
+
+## Finish
+
+Run:
+
+```bash
+openbbq doctor
+```
+
+If the user needs subtitle burning, confirm that FFmpeg has both the `ass` and `subtitles` filters. Once the check passes, continue to the subtitle workflow.

openbbq-0.0.1/docs/install-agent.zh-CN.md

@@ -0,0 +1,99 @@
+# OpenBBQ Agent 安装 Playbook
+
+这份说明给 AI Agent 使用。目标是把 OpenBBQ 装到用户本机，并且只补齐用户当前任务真正需要的依赖。
+
+## 原则
+
+- 不偷偷安装系统依赖，不偷偷下载模型。
+- 先问清楚会影响下载量和安装方式的问题。
+- 先跑 `openbbq doctor --json`，再根据结果只补缺失项。
+- 安装系统包、下载模型、写入浏览器登录态、配置 API key 前，都先让用户确认。
+- 最后以 `openbbq doctor` 通过作为安装完成的门槛。
+
+## 先问用户
+
+开始前确认这些信息：
+
+- 平台：macOS、Linux 还是 Windows。
+- 用户是否有[uv](https://docs.astral.sh/uv/)
+- 主要输入来源：本地视频、本地音频，还是 YouTube / 其他在线视频。
+- 源语言和目标语言。
+- 模型档位：`base` 适合快速预览，`large-v3` 或 `large-v3-turbo` 适合正式字幕。
+- 是否需要烧录硬字幕。
+- 是否需要说话人分离。
+- 是否需要调用 API 翻译。
+- 本机是否有 GPU，以及大致类型：Apple Silicon、NVIDIA、AMD / Intel，或只用 CPU。
+
+## Bootstrap
+
+优先使用发布包：
+
+```bash
+uv tool install openbbq
+```
+
+如果用户已经确认使用默认 whisper.cpp 后端，也可以直接安装 extra：
+
+```bash
+uv tool install 'openbbq[whispercpp]'
+```
+
+基于本仓库开发时，才在仓库目录下安装本地版本：
+
+```bash
+uv tool install '.[whispercpp]'
+```
+
+## 检查环境
+
+```bash
+openbbq doctor --json
+```
+
+按输出补缺失项。常见项如下：
+
+- Python 需要 3.12 或更新版本。
+- 缺 FFmpeg 时，安装带 `libass` 的 FFmpeg。烧录硬字幕需要 `ass` 和 `subtitles` filter。
+- 缺 ASR 后端时，默认补 `pywhispercpp`。macOS 通常可直接用 wheel 的 Metal 支持；NVIDIA / Vulkan 路线可能需要本机 toolkit 和源码编译。
+- 缺模型时，先让用户确认模型大小，再执行 `openbbq models pull <model>`。
+- YouTube 需要登录或人机验证时，执行 `openbbq auth browser-login youtube`。
+- 如果用户要说话人分离，再安装 whisperX 并确认 Hugging Face token。
+- 如果用户要 API 翻译，再配置对应 provider 的 key。
+
+## 模型
+
+先看可用档位和缓存状态：
+
+```bash
+openbbq models list
+```
+
+快速预览：
+
+```bash
+openbbq models pull base
+```
+
+正式字幕：
+
+```bash
+openbbq models pull large-v3-turbo
+```
+
+如果用户网络访问 Hugging Face 不稳定，可以让用户确认后设置镜像：
+
+```bash
+HF_ENDPOINT=https://hf-mirror.com openbbq models pull large-v3-turbo
+```
+
+模型放在 OpenBBQ 的全局缓存里，跨 workspace 复用，不写进视频项目目录。
+
+## 完成检查
+
+安装和模型下载完成后再跑：
+
+```bash
+openbbq doctor
+```
+
+如果用户要烧录字幕，确认 FFmpeg 的 `ass` 和 `subtitles` filter 都可用。检查通过后，再进入具体字幕工作流。