AI Agent 自动给视频配音。通过 faster-whisper 本地 ASR 提取视频原文，VoxCPM2 TTS 生成新配音，FFmpeg 合成输出视频。语音识别完全本地运行，无需 VPN，无需 API Key，ASR 模型从魔搭社区（ModelScope）下载。
- Python >= 3.8
- FFmpeg 已安装并加入 PATH
- 可访问的 VoxCPM2 vllm_omni API 地址（TTS 生成）
- ~1-10 GB 内存/显存（取决于选择的 ASR 模型大小）
翻译配音功能额外需要腾讯云 SecretId/SecretKey（在腾讯云访问管理获取），但基本的音色替换/克隆配音无需任何密钥。
无需额外安装步骤，直接运行脚本即可。首次运行会自动安装 Python 依赖（httpx、faster-whisper、modelscope、tencentcloud-sdk-python）。
也可使用安装脚本：
# Linux/macOS
bash setup.sh
# Windows
setup.batpython video_dub.py input.mp4 -o output.mp4python video_dub.py input.mp4 --ref-audio speaker.wav -o output.mp4# 提供 SRT 字幕文件，跳过 ASR
python video_dub.py input.mp4 --subtitle subtitles.srt -o output.mp4
# 也可使用 ASS 字幕
python video_dub.py input.mp4 --subtitle subtitles.ass -o output.mp4# 中文→英文（翻译需要腾讯云SecretId/Key）
python video_dub.py input.mp4 --target-lang en -o output.mp4python video_dub.py input.mp4 --keep-bg -o output.mp4# CUDA 加速（需 NVIDIA GPU + CUDA）
python video_dub.py input.mp4 --asr-device cuda --asr-compute-type float16 -o output.mp4# base 模型仅需 ~1.5 GB 内存
python video_dub.py input.mp4 --asr-model base -o output.mp4python video_dub.py input.mp4 --tts-api http://192.168.1.100:8000 -o output.mp4| 参数 | 说明 | 默认值 |
|---|---|---|
video |
输入视频文件路径（必需） | - |
-o, --output |
输出视频文件路径 | output_dubbed.mp4 |
--target-lang |
目标语言代码（如 en, ja, ko） | 无 |
--source-lang |
源语言代码 | 自动检测 |
--ref-audio |
参考音频（本地路径/URL） | 无 |
--subtitle |
字幕文件路径 (.srt/.ass)，跳过 ASR | 无 |
--tts-api |
VoxCPM2 TTS API 地址 | http://localhost:8000 |
--tts-key |
TTS API 密钥 | sk-empty |
--tts-model |
TTS 模型名称 | voxcpm2 |
--tts-format |
TTS 输出格式 | wav |
--asr-model |
faster-whisper 模型大小 | large-v3 |
--asr-device |
ASR 推理设备 cpu/cuda | cpu |
--asr-compute-type |
ASR 计算精度 int8/float16 | int8 |
--translate-model |
翻译模型 | hunyuan-translation-lite |
--translate-secret-id |
腾讯云 SecretId | TENCENTCLOUD_SECRET_ID 环境变量 |
--translate-secret-key |
腾讯云 SecretKey | TENCENTCLOUD_SECRET_KEY 环境变量 |
--keep-bg |
保留原始背景音 | 关闭 |
--bg-volume |
背景音量比例 0.0-1.0 | 0.2 |
--concurrency |
TTS 并发请求数 | 5 |
| 模型 | 内存需求 | 速度 | 精度 | 说明 |
|---|---|---|---|---|
tiny |
~1 GB | ⚡⚡⚡ | ★★☆ | 快速测试 |
base |
~1.5 GB | ⚡⚡⚡ | ★★★ | 轻量使用 |
small |
~2 GB | ⚡⚡ | ★★★★ | 日常使用 |
medium |
~5 GB | ⚡ | ★★★★★ | 高精度 |
large-v3 |
~10 GB | 🐢 | ★★★★★+ | 最高精度（默认，ModelScope: Systran/faster-whisper-large-v3） |
distil-large-v3 |
~3 GB | ⚡⚡ | ★★★★ | 精度与速度平衡（推荐） |
distil-small.en |
~1 GB | ⚡⚡⚡ | ★★★ | 仅英文，最轻量 |
模型首次使用时从魔搭社区（ModelScope）下载到
~/.cache/modelscope/，后续使用直接加载缓存。国内直连无需 VPN。
输入视频
│
├─→ FFmpeg 提取音轨
│ │
│ └─→ faster-whisper 本地 ASR（带时间戳，模型从魔搭社区下载）
│ │
│ └─→ [可选] LLM 翻译文本（需要 API）
│ │
│ └─→ VoxCPM2 TTS 批量生成
│ │
│ └─→ FFmpeg atempo 时长对齐
│ │
│ └─→ FFmpeg amix 混音合成
│ │
└───────────────────────────────────────────────┘
↓
输出配音视频
- faster-whisper 时间戳：ASR 返回每段语音的精确起止时间（精确到词级别）
- FFmpeg atempo：将 TTS 音频拉伸/压缩至匹配原时长（±30% 内质量可接受）
- adelay 定位：将每段 TTS 音频精确放置在原始时间位置
- amix 混合：多轨音频混合为最终音轨
voxcpm2-video-skill/
├── SKILL.md # Skill 定义文件（AI Agent 读取）
├── README.md # 本文件
├── video_dub.py # 主脚本（CLI 入口）
├── setup.sh # Linux/macOS 安装脚本
└── setup.bat # Windows 安装脚本
| 模型 | 1分钟音频耗时 | 内存 |
|---|---|---|
| base | ~10s | ~1.5 GB |
| small | ~20s | ~2 GB |
| large-v3 | ~60s | ~10 GB |
| distil-large-v3 | ~30s | ~3 GB |
使用 CUDA GPU 可加速 3-10 倍。
| 视频时长 | 片段数 | 预估耗时 |
|---|---|---|
| 1 分钟 | ~10 | ~1 分钟 |
| 5 分钟 | ~40 | ~4 分钟 |
| 10 分钟 | ~80 | ~8 分钟 |
| 问题 | 解决方案 |
|---|---|
| 模型下载慢 | 模型从魔搭社区（ModelScope）下载，国内直连无需 VPN |
| 内存不足 | 使用 --asr-model base 或 --asr-model distil-small.en |
| ASR 识别不准 | 换用更大模型，或 --source-lang 指定语言 |
| 无音频视频 | 使用 --subtitle 提供 SRT/ASS 字幕文件 |
| 翻译需要 API Key | 设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 环境变量，国内可用无需 VPN |
| 音画不同步 | Whisper 识别精度有限，尝试较短视频或手动调整 |
- VoxCPM2 TTS App: https://github.com/Young140430/VoxCPM2-TTS-App
- VoxCPM2 OpenAI Skill: https://github.com/Young140430/voxcpm2-openai-skill
- VoxCPM2 TTS Skill: https://github.com/Young140430/voxcpm2-skill
- VoxCPM 模型: https://github.com/OpenBMB/VoxCPM
- faster-whisper: https://github.com/SYSTRAN/faster-whisper
- ModelScope: https://www.modelscope.cn/models/OpenBMB/VoxCPM2