# dub-lite

**Repository Path**: chengegege/dub-lite

## Basic Information

- **Project Name**: dub-lite
- **Description**: `dub-lite` 是一个轻量、跨平台、易迁移的视频自动翻译配音工具，支持多语言配中文，目前更多还是英文->中文。后续需要自己让AI改代码。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dub-lite 轻量视频配音工具

> 只做核心链路：**本地语音识别 → API 翻译 → API 配音 → 合成**。
> 一个入口、一个参数，把任意视频翻译成中文配音视频。

`dub-lite` 是一个轻量、跨平台、易迁移的视频自动配音工具：

- 输入单个视频文件 → 同目录输出 `【译】{原名}.mp4`
- 输入文件夹 → 逐个处理其中所有视频，各自输出到原视频同目录

## 核心特性

- **TTS 只走 API**：默认免费 [edge-tts](https://github.com/rany2/edge-tts)（微软 Edge 免费服务，无需 API Key），不下载任何本地 TTS 模型，零模型体积
- **ASR 本地部署**：faster-whisper（CTranslate2 加速），音频不出本机，隐私安全
- **API 翻译**：DeepSeek（OpenAI 兼容协议），默认 `en → zh`，支持上下文窗口保证译文连贯
- **唯一入口**：只有一个位置参数，自动识别"单文件 / 文件夹"两种模式
- **音画同步**：片段级变速对齐（±15% 容差 atempo，保持音高）+ 全局匀速兜底，音频不截断
- **画质无损**：视频流 `copy` 不重编码
- **断点续传**：按视频粒度缓存，中断后重跑自动命中已完成的步骤
- **一键部署**：Windows / Linux / macOS 脚本安装，仅依赖 Python 包 + 系统 FFmpeg

## 工作原理

```
视频 ──► [1] FFmpeg 提取音轨 (16k 单声道 wav)
         │
         ▼
        [2] faster-whisper 本地识别 ──► 时间戳片段 [{start, end, text}]
         │
         ▼
        [3] 短片段合并预处理 (减少 TTS 请求数)
         │
         ▼
        [4] DeepSeek API 翻译 ──► 每片段中文译文 (zh_text)
         │
         ▼
        [5] edge-tts API 配音 ──► 每片段中文音频
         │
         ▼
        [6] 时间线对齐 + 全局匀速 ──► FFmpeg 合成 ──► 【译】xxx.mp4
```

- 片段变速使用 FFmpeg `atempo` 滤镜，**保持音高不变**（范围 0.5~2.0 自动链式拆分）
- 对齐容差 ±15% 内直接变速；超出限幅（0.7x~1.4x）按全局匀速整体调整，保证总时长吻合
- 视频流 `-c:v copy` 不重编码，仅替换音轨

## 环境要求

| 依赖 | 要求 | 说明 |
|------|------|------|
| Python | 3.10+ | 开发测试环境为 3.12 |
| FFmpeg | 任意较新版本 | 需在 PATH 中，或在 `config.yaml` 的 `ffmpeg.path` 配置绝对路径 |
| 磁盘 | ≥ 1GB | 含 Python 环境 + ASR 模型（base 约 150MB） |
| 网络 | 需能访问 DeepSeek / 微软 Edge | 国内环境模型下载自动走 hf-mirror + ModelScope 兜底 |

## 安装部署

### 一键安装（推荐）

**Windows（PowerShell）**

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1
# 加开关可同时下载 ASR 模型:
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -DownloadModels
```

**Linux / macOS**

```bash
bash setup.sh
# 加参数可同时下载 ASR 模型:
bash setup.sh --download-models
```

脚本会：创建 `.venv` 虚拟环境 → 用阿里云镜像安装依赖 → （可选）下载 ASR 模型。

### 手动安装

```bash
# 1. 创建虚拟环境
python -m venv .venv

# 2. 安装依赖（Windows / Linux/macOS 二选一）
.venv\Scripts\python -m pip install -r requirements.txt   # Windows
.venv/bin/python -m pip install -r requirements.txt       # Linux / macOS

# 3. （可选）预下载 ASR 模型
.venv\Scripts\python download_models.py
```

### FFmpeg 安装提示

- **Windows**：下载 [FFmpeg](https://www.gyan.dev/ffmpeg/builds/) 解压后，把 `bin` 目录加入系统 PATH
- **macOS**：`brew install ffmpeg`
- **Linux**：`sudo apt install ffmpeg`（Debian/Ubuntu）或 `sudo yum install ffmpeg`（CentOS/RHEL）

## 快速开始

### 1. 配置翻译 API Key

翻译使用 DeepSeek API（付费服务，需注册获取 Key）。三选一：

```bash
# 方式 A（推荐）：复制 .env.example 为 .env 并填入真实 Key
# Windows
Copy-Item .env.example .env
# Linux / macOS
cp .env.example .env
# 然后编辑 .env, 填入:
#   DEEPSEEK_API_KEY=sk-你的key

# 方式 B：系统环境变量
# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-你的key"
# Linux / macOS
export DEEPSEEK_API_KEY="sk-你的key"

# 方式 C：直接写入 config.yaml
#   translation:
#     api_key: "sk-你的key"
```

> **优先级**：系统环境变量 > `.env` 文件 > `config.yaml`。
> `.env` 已加入 `.gitignore`，不会被提交到 git；`.env.example` 是公开模板，只放占位符不放真实 Key。

### 2. 处理单个视频

```bash
# Windows
.venv\Scripts\python run.py "d:\videos\interview.mp4"
# Linux / macOS
.venv/bin/python run.py "/home/me/videos/interview.mp4"
```

输出：`d:\videos\【译】interview.mp4`（原文件不被修改）。

### 3. 批量处理文件夹

```bash
.venv\Scripts\python run.py "d:\videos"
```

自动识别文件夹中所有视频（支持 `.mp4/.mkv/.avi/.mov/.flv/.wmv/.webm/.ts/.m4v`），逐个处理；已存在 `【译】` 输出的自动跳过。

> 首次运行会自动下载 ASR 模型（约 150MB），请耐心等待。

## 完整配置（config.yaml）

所有功能参数都在 `config.yaml`，无需记忆命令行选项。

| 段落 | 配置项 | 默认值 | 说明 |
|------|--------|--------|------|
| `asr` | `model` | `base` | 识别模型：`tiny/base/small/medium/large-v2/large-v3`，越大越准越慢 |
| | `device` | `auto` | `auto`（有 CUDA 自动用 GPU）/ `cuda` / `cpu` |
| | `language` | `en` | 源语言（识别语言），如 `en`/`zh`/`ja`；填 `auto` 自动检测 |
| | `compute_type` | `""` | 留空自动：cuda→`float16`，cpu→`int8` |
| `translation` | `api_key` | `""` | 留空则读 `.env` / 环境变量 `DEEPSEEK_API_KEY` |
| | `base_url` | `https://api.deepseek.com` | API 地址（OpenAI 兼容） |
| | `model` | `deepseek-v4-flash` | 翻译模型名 |
| | `source_lang` / `target_lang` | `en` / `zh` | 语言方向，如 `en→zh`、`zh→en` |
| | `temperature` | `0.3` | 越低越稳定 |
| | `context_window` | `5` | 翻译时携带前 N 条译文作为上下文 |
| | `batch_size` | `10` | 每批翻译片段数，一次请求多条大幅提速（批量失败自动回退逐条） |
| | `max_retries` | `3` | 单条失败最大重试次数（指数退避） |
| `tts` | `engine` | `edge_tts` | 仅支持 edge_tts（API 模式） |
| | `voice` | `zh-CN-YunxiNeural` | 音色，如 `zh-CN-XiaoxiaoNeural`（女声） |
| | `edge_proxy` | `""` | 受限网络代理，如 `http://127.0.0.1:7897` |
| | `sample_rate` | `24000` | 配音采样率 |
| `align` | `tolerance` | `0.15` | ±15% 内变速对齐 |
| | `max_speed_ratio` | `1.4` | 单片段变速上限（防失真） |
| | `min_speed_ratio` | `0.7` | 单片段变速下限 |
| `output` | `prefix` | `【译】` | 输出文件名前缀 |
| | `skip_existing` | `true` | 输出已存在时跳过 |
| | `srt` | `false` | 额外生成中文 srt 字幕 |
| | `srt_suffix` | `.zh.srt` | 字幕文件后缀 |
| | `keep_temp` | `false` | `true` 时保留 `.dub_xxx/` 临时目录 |
| `ffmpeg` | `path` | `ffmpeg` | 可填绝对路径 |
| | `video_codec` | `copy` | 视频流不重编码，保持画质 |
| | `audio_codec` / `audio_bitrate` | `aac` / `192k` | 配音音轨编码 |
| `folder` | `recursive` | `false` | 文件夹模式是否递归子文件夹 |
| `models` | `dir` | `models` | ASR 模型目录（相对项目根） |
| | `hf_endpoint` | `https://hf-mirror.com` | 模型下载镜像，留空用官方 |

## 模型下载与迁移

- **自动下载**：首次处理视频时自动下载 ASR 模型到 `models/`。默认走 `hf-mirror.com` 镜像；若 HF 下载失败，会自动改用 **ModelScope 直连下载**（国内网络友好），无需任何配置。
- **预下载**：联网机器可先执行 `python download_models.py` 预下载（幂等，已存在则跳过）。
- **离线迁移**：把整个 `models/` 目录连同代码一起拷贝到目标机器即可离线运行 ASR（base 模型约 150MB）。这正是"模型下载要容易、迁移要容易"的设计。

### 模型选择建议

| 模型 | 大小 | 速度 | 准确率 | 适用场景 |
|------|------|------|--------|----------|
| `tiny` | ~75MB | 极快 | 低 | 快速预览、低配机器 |
| `base` | ~150MB | 快 | 中 | **默认，日常推荐** |
| `small` | ~480MB | 中 | 中高 | 口音较重、背景噪音多 |
| `medium` | ~1.5GB | 慢 | 高 | 高质量要求 |
| `large-v2/v3` | ~3GB | 很慢 | 最高 | 专业场景（建议 GPU） |

## 断点续传

- 处理过程按视频粒度缓存到 `<视频目录>/.dub_{视频名}/`：
  - `asr_audio.wav`：提取的音轨
  - `asr.json`：识别片段
  - `zh.json`：翻译结果
  - `tts_{i}.wav` + `tts_cache.json`：逐片段配音缓存
- **处理成功**：自动清理工作目录
- **处理失败**：保留工作目录，修复问题（如网络、代理）后重跑同一条命令，已完成的步骤自动"缓存命中"跳过，只重做失败步骤

## 目录结构

```
dub-lite/
├── run.py                 # 唯一入口（一个位置参数）
├── download_models.py     # 预下载 ASR 模型脚本
├── config.yaml            # 全部配置
├── .env.example           # 环境变量模板（复制为 .env 填 Key；.env 已被 git 忽略）
├── requirements.txt       # Python 依赖
├── setup.ps1              # Windows 一键安装
├── setup.sh               # Linux / macOS 一键安装
├── src/
│   ├── config.py          # 配置加载（默认值合并 + 环境变量覆盖）
│   ├── asr.py             # 本地 ASR（faster-whisper + 模型下载）
│   ├── translate.py       # API 翻译（DeepSeek）
│   ├── tts.py             # API 配音（edge-tts，持久事件循环）
│   ├── audio.py           # 音频处理（提取/变速/时间线对齐）
│   ├── video.py           # 视频合成（FFmpeg）
│   └── pipeline.py        # 主流水线（6 步 + 缓存续传）
├── models/                # ASR 模型目录（自动生成，可整体迁移）
└── test_media/            # 测试视频（可删除）
```

## 常见问题（FAQ）

**Q：提示"未找到 FFmpeg"？**
安装 FFmpeg 并加入 PATH，或修改 `config.yaml` 的 `ffmpeg.path` 为绝对路径。

**Q：提示"未配置翻译 API Key"？**
在 `.env`（复制 `.env.example` 生成）中填写 `DEEPSEEK_API_KEY`，或设置环境变量，或填写 `config.yaml` 的 `translation.api_key`。可到 [DeepSeek 开放平台](https://platform.deepseek.com) 注册获取。

**Q：翻译全部失败 / 输出为静音？**
检查 Key 是否有效、账户余额是否充足、`base_url` 与 `model` 是否可用。翻译失败的片段会用静音占位，建议先确认单条翻译正常再批量。

**Q：edge-tts 连续合成失败？**
多为网络问题。可设置 `tts.edge_proxy` 代理（如 `http://127.0.0.1:7897`）后重试；内置了 3 次自动重试。

**Q：识别不到内容 / 片段为空？**
视频可能是无声或纯音乐；或 `asr.language` 与音频语言不符，改为 `auto` 试一下。

**Q：模型下载失败？**
默认自动降级：先 hf-mirror，失败切换 ModelScope。若两者都失败，可手动下载后放入 `models/faster-whisper-{型号}/`（需含 `model.bin`），或直接使用 `download_models.py` 重试。

**Q：输出文件被再次扫描配音？**
不会。文件夹模式会自动排除已带 `【译】` 前缀的文件，避免重复配音。

**Q：CPU 太慢？**
换小模型（`tiny`/`base`）或开启 GPU（`asr.device: cuda`，需安装 PyTorch CUDA 版）。

## 依赖与许可说明

| 组件 | 性质 | 许可 |
|------|------|------|
| edge-tts | 免费 API，无需 Key | MIT（客户端库） |
| DeepSeek API | 付费 API | 按调用计费 |
| faster-whisper | 本地模型 | MIT |
| Whisper 模型权重 | 本地下载 | MIT |

> 免责声明：edge-tts 基于微软 Edge 免费朗读服务，仅限个人学习使用，请勿用于商业分发；视频内容版权归原作者所有，请确保你有权处理该视频。