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.bat

python video_dub.py input.mp4 -o output.mp4

python 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.mp4

python 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.mp4

python 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 混音合成
  │                                               │
  └───────────────────────────────────────────────┘
                        ↓
                   输出配音视频

1. faster-whisper 时间戳：ASR 返回每段语音的精确起止时间（精确到词级别）
2. FFmpeg atempo：将 TTS 音频拉伸/压缩至匹配原时长（±30% 内质量可接受）
3. adelay 定位：将每段 TTS 音频精确放置在原始时间位置
4. 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