# zero-caption

**Repository Path**: zeropxf/zero-caption

## Basic Information

- **Project Name**: zero-caption
- **Description**: 视频翻译字幕软件
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zero-caption

Windows 本地优先的视频字幕生成与翻译桌面应用。

## Status

当前已完成开发计划中阶段 0 至阶段 7 的主要能力：

- PySide6 桌面入口与分层项目结构
- 配置、日志、运行时探针和项目工作区
- FFmpeg / ffprobe 适配器
- faster-whisper 本地语音识别适配器
- NVIDIA GPU 自动探测、CPU 回退和 `small` / `medium` 模型切换
- 字幕去重、时间轴规整和 SRT 写出
- 无界面的单视频识别主链路与缓存复用
- 云端字幕翻译、外挂字幕和 FFmpeg 烧录导出
- PySide6 后台任务、进度总线和集中式任务创建表单
- 多视频后台并发，识别与视频导出等高资源阶段自动串行
- 按视频聚合的持久化任务工作区、阶段详情和逐句译文
- 指定字幕译文的手工编辑、持久化保存和单句重新翻译
- SQLite 项目/任务/字幕/导出记录、旧库迁移和检查点续跑
- 翻译完成后由用户主动选择目录，下载外挂或烧录字幕成品
- 下载成品使用独立文件名，不覆盖作为输入的原始视频
- ASS 字幕、项目日志、诊断包和 Windows 打包烟测脚本

首次启动会在工作区内创建 `zero_caption.sqlite3`，用于保存项目历史和任务状态。

## Run

```powershell
pip install -e .
python -m app.main
```

## Test

```powershell
python -m pytest
```

## Windows 发布包

```powershell
powershell -ExecutionPolicy Bypass -File scripts/build_windows.ps1
```

构建脚本会同时生成：

- `dist/ZeroCaption/`：免安装便携目录。
- `dist/installer/ZeroCaption-0.1.0-win64-setup.exe`：推荐给最终用户的单用户安装包。

安装向导始终提供安装目录选择页。为保证卸载时能够彻底清除程序文件，自定义目录必须
是空目录或已有的 Zero Caption 安装目录，不要把软件直接装进存放个人文件的共享目录。
卸载时会清空安装目录，并询问是否同时删除 `%LOCALAPPDATA%\ZeroCaption` 中的项目历史、
字幕、缓存、日志和本机设置；选择保留后，重新安装仍可继续使用原有数据。

两个版本均已包含 Python、VC 运行库、Qt、FFmpeg、ffprobe、`faster-whisper`、
`cuBLAS 12` 运行依赖，以及 `small`、`medium` 两套本地模型。自动模式会在可用的 5GB 以上
NVIDIA CUDA GPU 上选择 `medium + float16`，无可用 GPU 时选择 `small + CPU + int8`。
用户也可以在设置页自行选择模型、设备和精度；CUDA 初始化失败时默认自动回退 CPU。
目标电脑无需安装 Python、FFmpeg、完整 CUDA Toolkit 或临时下载识别模型，只需保持
NVIDIA 显卡驱动可用。字幕翻译仍需要用户配置可访问的
大模型 API，但不会要求安装任何翻译客户端。

## Runtime Check

在处理真实视频前，可以先运行：

```powershell
python scripts/check_runtime.py
```

这个脚本会检查 `ffmpeg`、`ffprobe`、`faster-whisper`、两套内置模型、
CUDA 硬件建议以及关键翻译配置是否已经准备好。

## Local Transcription

可以通过命令行运行本地识别，不依赖桌面交互页面：

```powershell
python scripts/transcribe_video.py path/to/video.mp4 --source-language auto --output D:\字幕\video.srt
```

原文字幕会保留在项目目录；传入 `--output` 时还会写到指定位置。桌面“创建视频任务”表单提供
“自动识别语言并生成原文字幕（本地）”处理方式，未配置大模型时会默认选中该方式，并跳过翻译和视频导出。
仅识别模式可在表单中选择原文字幕保存目录，并实时预览最终路径。

## Complete MVP Pipeline

可在桌面应用的“设置”页配置翻译接口地址、模型、API 密钥和系统提示词；也可以使用
`OPENAI_API_KEY` 环境变量作为密钥回退。设置页支持输入用户提示词后台测试当前表单配置。
正式翻译会逐条独立调用模型，并在任务页实时追加原文和译文。配置完成后，可以运行完整无界面主链路：

```powershell
python scripts/process_video.py path/to/video.mp4 --source-language auto --target-language zh-CN --output D:\成品\video-字幕.mp4
```

命令会在项目目录中保留原文字幕和译文字幕，并根据显式命令参数生成视频副本与同名外挂字幕。
需要烧录字幕时追加 `--export-mode burn_in`。

桌面完整流程会在译文字幕生成后结束，不会自动写入或覆盖原视频。任务页随后会启用
“下载成品…”按钮；用户点击按钮、选择外挂或烧录模式和目标目录后，应用才生成
`原文件名-字幕` 视频，外挂模式还会在同一目录生成同名 `.srt`。

任务失败或应用异常退出后，任务页会显示“从检查点继续”。继续操作沿用原项目编号，
并复用已经生成的音频、原文字幕和逐句译文。字幕人工修订后，可以在同一页面选择
外挂字幕或烧录字幕，再次点击“下载成品…”选择目标目录。

桌面任务页默认允许同时推进 2 个视频流程。逐句翻译等轻量阶段可以并行；音频识别
和视频导出共享 1 个高资源槽位，会自动排队串行执行，避免多个模型或 FFmpeg 进程
同时占满电脑。开发配置可通过 `[task]` 下的 `max_concurrency` 和
`max_heavy_concurrency` 调整这两层上限。