VoxCPM2 Video Dub — AI Agent 自动给视频配音

通过 faster-whisper 本地 ASR 提取视频中的语音文本，VoxCPM2 TTS 生成新配音，FFmpeg 合成输出视频。无需 VPN，无需 API Key，语音识别完全本地运行，ASR 模型从魔搭社区（ModelScope）下载。

快速开始

# 替换配音（零样本音色）
python video_dub.py input.mp4 -o output.mp4

# 克隆原说话人音色
python video_dub.py input.mp4 --ref-audio speaker.wav -o output.mp4

# 无音频视频，使用字幕文件配音
python video_dub.py input.mp4 --subtitle subtitles.srt -o output.mp4

# 翻译配音（中文→英文，翻译功能需要腾讯云SecretId/SecretKey）
python video_dub.py input.mp4 --target-lang en -o output.mp4

# 保留原始背景音
python video_dub.py input.mp4 --keep-bg -o output.mp4

# 使用轻量 ASR 模型（低内存）
python video_dub.py input.mp4 --asr-model base -o output.mp4

# 使用 GPU 加速 ASR
python video_dub.py input.mp4 --asr-device cuda --asr-compute-type float16 -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/mp3 | wav | | --asr-model | faster-whisper 模型大小 | large-v3 | | --asr-device | ASR 推理设备 cpu/cuda | cpu | | --asr-compute-type | ASR 计算精度 int8/float16/float32 | 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 |

三种配音模式

1. 音色替换模式

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

提取原文 → 零样本 TTS 生成新配音 → 替换原音轨
适合换声音、修复音质
无需任何 API Key

2. 音色克隆模式

python video_dub.py input.mp4 --ref-audio speaker.wav -o output.mp4

使用参考音频克隆音色，保持声音一致性
适合统一角色配音
无需任何 API Key

3. 翻译配音模式

python video_dub.py input.mp4 --target-lang en -o output.mp4

提取原文 → LLM 翻译 → TTS 生成 → 对齐合成
支持任意语言对，翻译时自动约束文本长度以匹配原时长
翻译功能需要腾讯云 SecretId/SecretKey，ASR 始终本地运行

ASR 模型选择

| 模型 | 内存需求 | 速度 | 精度 | 说明 | |------|---------|------|------|------| | 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 | ⚡⚡ | ★★★★ | 推荐平衡选择 |

工作流程

当用户请求给视频配音时，按以下步骤执行：

WORKFLOW = [
    {
        "step": 1,
        "name": "validate_input",
        "tasks": ["检查视频文件存在", "检查 FFmpeg 已安装", "检查 TTS API 连接"]
    },
    {
        "step": 2,
        "name": "extract_audio",
        "command": "ffmpeg -i {video} -vn -acodec pcm_s16le -ar 16000 -ac 1 extracted.wav",
        "tasks": ["从视频提取音轨", "转为 16kHz 单声道 WAV"]
    },
    {
        "step": 3,
        "name": "transcribe",
        "command": "faster_whisper.WhisperModel.transcribe(extracted.wav)",
        "tasks": ["从魔搭社区（ModelScope）下载并加载 faster-whisper 本地模型", "识别语音内容", "获取带时间戳的文本片段", "检测语言"],
        "note": "完全本地运行，模型从魔搭社区下载（国内可访问），无需 VPN 和 API Key"
    },
    {
        "step": 4,
        "name": "translate",
        "condition": "target_lang is specified",
        "tasks": ["调用腾讯混元 ChatTranslations API 翻译文本", "逐片段翻译"],
        "note": "仅翻译模式需要腾讯云 SecretId/SecretKey，ASR 始终本地运行"
    },
    {
        "step": 5,
        "name": "generate_tts",
        "command": "voxcpm2_api /v1/audio/speech (per segment)",
        "tasks": ["逐片段生成 TTS 音频", "支持音色克隆", "支持并发请求"]
    },
    {
        "step": 6,
        "name": "align_audio",
        "tasks": ["使用 FFmpeg atempo 调整每段音频时长", "对齐原始时间轴"]
    },
    {
        "step": 7,
        "name": "compose_video",
        "command": "ffmpeg amix + map",
        "tasks": ["将 TTS 音频叠加到时间轴", "可选保留背景音", "合成最终视频"]
    },
    {
        "step": 8,
        "name": "deliver_result",
        "tasks": ["确认输出文件已生成", "告知用户文件路径"]
    }
]

音频时长对齐策略

核心挑战是让 TTS 生成的音频与原始语音的时间轴对齐：

faster-whisper 时间戳：ASR 返回每段语音的精确起止时间
FFmpeg atempo：将 TTS 音频拉伸/压缩至匹配原时长（±30% 以内质量可接受）
adelay 定位：将每段 TTS 音频精确放置在原始时间位置
amix 混合：多轨音频混合为最终音轨

前置要求

| 依赖 | 说明 | |------|------| | Python >= 3.8 | 运行环境 | | FFmpeg | 系统安装并加入 PATH | | faster-whisper | 本地 ASR，首次运行自动安装 | | modelscope | 从魔搭社区下载 ASR 模型 | | tencentcloud-sdk-python | 腾讯云 SDK，调用混元翻译接口 | | VoxCPM2 API | vllm_omni 服务（TTS 生成） | | TENCENTCLOUD_SECRET_ID / KEY | 仅翻译功能需要，配音替换无需（腾讯云密钥） |

故障排除

| 问题 | 解决方案 | |------|---------| | 模型下载慢 | 模型从魔搭社区（ModelScope）下载，国内直连无需 VPN | | 内存不足 | 使用 --asr-model base 或 --asr-model distil-small.en | | ffmpeg not found | 安装 FFmpeg 并加入 PATH | | ASR 识别不准 | 换用更大模型，或 --source-lang 指定语言 | | 视频无音轨 | 使用 --subtitle 提供 SRT/ASS 字幕文件 | | TTS 连接超时 | 检查 --tts-api 地址是否正确、服务是否启动 | | 音画不同步 | ASR 精度有限，尝试较短视频或手动调整 | | 翻译缺少密钥 | 设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 环境变量 | | 长视频处理慢 | T4 上 RTF 1.2-1.5，10分钟视频约需 5-8 分钟 |