# Video-tool

**Repository Path**: dubious/video-tool

## Basic Information

- **Project Name**: Video-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# yt2zh - YouTube 英文视频转中文配音+字幕工具

将英文视频自动转换为中文配音视频，包含完整流程：下载 → 语音识别 → 翻译 → 配音 → 合成。

## 功能特性

- **YouTube 下载**：支持 360p ~ 4K 分辨率
- **本地视频**：支持任意 mp4 视频文件
- **Whisper 识别**：支持 tiny/base/small/medium/large 模型，CPU/GPU 加速
- **DeepSeek 翻译**：高质量上下文翻译（默认引擎）
- **Google 翻译**：免费备选翻译引擎
- **Edge-TTS 配音**：免费微软 TTS，16 种中文声音可选
- **智能时间轴**：自动编排配音时间，段落不重叠
- **音量标准化**：loudnorm 自动拉到最佳响度
- **字幕烧录**：可配置字体大小、颜色、描边
- **YAML 配置**：所有参数通过 `config.yaml` 管理
- **断点续传**：已完成的步骤自动跳过

## 快速开始

### 安装依赖

```bash
pip install faster-whisper edge-tts deep-translator pyyaml
```

还需安装：
- **FFmpeg**：[官网下载](https://ffmpeg.org/download.html)，加入系统 PATH
- **yt-dlp**：`pip install yt-dlp`（仅下载 YouTube 视频需要）

### 配置

编辑 `config.yaml`，填入你的 DeepSeek API Key：

```yaml
translate:
  engine: deepseek
  deepseek:
    api_key: "sk-你的密钥"        # ← 填这里
    base_url: "https://api.deepseek.com/v1"
    model: "deepseek-chat"
```

也可以通过环境变量设置（优先级高于配置文件）：

```bash
# Windows
set DEEPSEEK_API_KEY=sk-xxx

# Linux/Mac
export DEEPSEEK_API_KEY=sk-xxx
```

### 运行

```bash
# 最简用法 — YouTube 链接直接转
python yt2zh.py --url "https://www.youtube.com/watch?v=QKgTZWbwD1U"

# 本地视频转换
python yt2zh.py --input my_video.mp4

# 使用 Google 免费翻译
python yt2zh.py --url "https://www.youtube.com/watch?v=xxx" --translate-engine google

# 使用自定义配置文件
python yt2zh.py --config my_config.yaml --url "..."
```

## 配置文件说明

所有参数都在 `config.yaml` 中配置，命令行参数可覆盖配置文件。

### 优先级

```
命令行参数 > 环境变量 > config.yaml > 内置默认值
```

### 完整配置示例

```yaml
# ==================== 翻译引擎 ====================
translate:
  engine: deepseek                    # deepseek / google
  deepseek:
    api_key: "sk-xxx"                 # DeepSeek API Key
    base_url: "https://api.deepseek.com/v1"
    model: "deepseek-chat"
    batch_size: 15                    # 每批翻译段数

# ==================== 语音识别 ====================
whisper:
  model: base                         # tiny / base / small / medium / large-v3
  device: cpu                         # cpu / cuda（需 NVIDIA 显卡）
  compute_type: int8                  # int8 / float16 / float32

# ==================== TTS 配音 ====================
tts:
  voice: "zh-CN-YunxiNeural"         # 中文声音 ID
  gap: 0.3                           # 段落间隔（秒）
  retry: 5                           # 网络重试次数

# ==================== 字幕样式 ====================
subtitle:
  enabled: true                       # 是否烧字幕
  font_size: 40                       # 字号
  font_name: "Arial"                  # 字体
  color: "&H00FFFFFF"                 # 白色
  outline_color: "&H00000000"         # 黑色描边
  outline_width: 2                    # 描边宽度

# ==================== 音频 ====================
audio:
  loudnorm: true                      # 自动音量标准化
  loudnorm_i: -14                     # 目标响度 (LUFS)
  loudnorm_tp: -1.5                   # 真峰值限制
  loudnorm_lra: 11                    # 响度范围
  volume_multiplier: null             # 手动音量倍数（关闭 loudnorm 时生效）
  bitrate: "192k"                     # 音频比特率

# ==================== 视频 ====================
video:
  resolution: 1080                    # 360 / 480 / 720 / 1080 / 1440 / 2160
  crf: 18                             # 编码质量（越小越好）

# ==================== 输出 ====================
output:
  dir: "./output"                     # 输出目录
  keep_intermediate: false            # 保留中间文件
```

## 可选中文 TTS 声音

| 声音 ID | 说明 |
|---------|------|
| `zh-CN-YunxiNeural` | 男声，年轻（默认） |
| `zh-CN-YunjianNeural` | 男声，成熟 |
| `zh-CN-YunyangNeural` | 男声，新闻播报 |
| `zh-CN-YunfengNeural` | 男声，纪录片 |
| `zh-CN-YunhaoNeural` | 男声，少年 |
| `zh-CN-YunzeNeural` | 男声，沉稳 |
| `zh-CN-XiaoxiaoNeural` | 女声，温柔 |
| `zh-CN-XiaoyiNeural` | 女声，活泼 |
| `zh-CN-XiaohanNeural` | 女声，甜美 |
| `zh-CN-XiaomengNeural` | 女声，可爱 |
| `zh-CN-XiaomoNeural` | 女声，成熟 |
| `zh-CN-XiaoruiNeural` | 女声，专业 |
| `zh-CN-XiaoshuangNeural` | 女童声 |
| `zh-CN-XiaoxuanNeural` | 女声，知性 |
| `zh-CN-XiaoyanNeural` | 女声，温柔 |
| `zh-CN-YunxiaNeural` | 男童声 |

## 命令行参数

命令行参数会覆盖 `config.yaml` 中的对应配置。

| 参数 | 覆盖配置项 | 说明 |
|------|-----------|------|
| `--url` | - | YouTube 视频链接 |
| `--input` | - | 本地视频文件路径 |
| `--output-dir` | `output.dir` | 输出目录 |
| `--config` | - | 指定配置文件路径 |
| `--resolution` | `video.resolution` | 下载分辨率 (360~2160) |
| `--crf` | `video.crf` | 视频编码质量 |
| `--whisper-model` | `whisper.model` | Whisper 模型 |
| `--whisper-device` | `whisper.device` | 计算设备 (cpu/cuda) |
| `--translate-engine` | `translate.engine` | 翻译引擎 |
| `--deepseek-api-key` | `translate.deepseek.api_key` | API Key |
| `--batch-size` | `translate.deepseek.batch_size` | 翻译批次大小 |
| `--tts-voice` | `tts.voice` | TTS 声音 |
| `--tts-gap` | `tts.gap` | 段落间隔秒数 |
| `--font-size` | `subtitle.font_size` | 字幕字号 |
| `--no-subtitle` | `subtitle.enabled` | 关闭字幕 |
| `--audio-bitrate` | `audio.bitrate` | 音频比特率 |
| `--no-loudnorm` | `audio.loudnorm` | 关闭音量标准化 |
| `--keep-intermediate` | `output.keep_intermediate` | 保留中间文件 |
| `--skip-download` | - | 跳过下载 |
| `--force` | - | 强制重新生成 |

## 使用示例

```bash
# 使用配置文件默认设置
python yt2zh.py --url "https://www.youtube.com/watch?v=xxx"

# 高清 + 女声 + 大字幕（命令行覆盖配置）
python yt2zh.py --url "https://www.youtube.com/watch?v=xxx" \
  --resolution 2160 --tts-voice zh-CN-XiaoxiaoNeural --font-size 48

# 使用自定义配置文件
python yt2zh.py --config production.yaml --url "..."

# GPU 加速
python yt2zh.py --url "..." --whisper-device cuda --whisper-compute-type float16

# 强制重新生成（忽略缓存）
python yt2zh.py --url "..." --force

# 不烧字幕，只配音
python yt2zh.py --url "..." --no-subtitle

# 关闭音量标准化，手动 3 倍音量
# (在 config.yaml 中设置 audio.loudnorm: false, audio.volume_multiplier: 3)
```

## 输出文件

| 文件 | 说明 |
|------|------|
| `output/output.mp4` | **最终视频**：中文配音 + 中文字幕 |
| `output/en.srt` | 英文原版字幕 |
| `output/zh.srt` | 中文翻译字幕 |

## 文件结构

```
video-tool/
├── yt2zh.py           # 主脚本
├── config.yaml        # 配置文件（编辑此文件管理所有参数）
└── README.md          # 本文档
```

## 注意事项

1. **API Key**：使用 DeepSeek 翻译需在 `config.yaml` 中配置 `translate.deepseek.api_key`
2. **首次运行**：Whisper 会自动下载模型（base 约 150MB）
3. **GPU 加速**：需安装 CUDA 版 PyTorch，配置 `whisper.device: cuda`
4. **Windows 路径**：输出目录避免使用中文路径
5. **pyyaml 依赖**：配置文件功能需要 `pip install pyyaml`