AI Agent 自动给视频配音。通过 faster-whisper 本地 ASR 提取视频原文，MiMo V2.5 TTS 生成新配音，FFmpeg 合成输出视频。语音识别完全本地运行，无需 VPN；TTS 使用小米 MiMo 云端 API，无需本地部署 TTS 服务。

• Python >= 3.8
• FFmpeg 已安装并加入 PATH
• MiMo API Key（在 MiMo 开放平台获取）
• ~1-10 GB 内存/显存（取决于选择的 ASR 模型大小）

翻译配音功能额外需要腾讯云 SecretId/SecretKey（在腾讯云访问管理获取），但基本的音色替换/克隆配音无需腾讯云密钥。

无需额外安装步骤，直接运行脚本即可。首次运行会自动安装 Python 依赖（openai、faster-whisper、modelscope）。

也可使用安装脚本：

# Linux/macOS
bash setup.sh

# Windows
setup.bat

变量	说明	必需
MIMO_API_KEY	MiMo API 密钥	是
TENCENTCLOUD_SECRET_ID	腾讯云 SecretId（仅翻译需要）	否
TENCENTCLOUD_SECRET_KEY	腾讯云 SecretKey（仅翻译需要）	否

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

python video_dub.py input.mp4 --voice "茉莉" -o output.mp4

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

python video_dub.py input.mp4 --tts-mode voicedesign --context "中年男性，沉稳有力" -o output.mp4

python video_dub.py input.mp4 --voice "冰糖" --context "用温柔的语气，语速稍慢" -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

参数	说明	默认值
video	输入视频文件路径（必需）	-
-o, --output	输出视频文件路径	output_dubbed.mp4
--target-lang	目标语言代码（如 en, ja, ko）	无
--source-lang	源语言代码	自动检测
--voice	预置音色名称	冰糖
--ref-audio	参考音频（本地路径，用于音色克隆）	无
--context	自然语言风格控制指令 / 音色描述	无
--tts-mode	TTS 模式 auto/preset/voicedesign/voiceclone	auto
--subtitle	字幕文件路径 (.srt/.ass)，跳过 ASR	无
--mimo-api-key	MiMo API 密钥	MIMO_API_KEY 环境变量
--mimo-api-base	MiMo API 地址	https://api.xiaomimimo.com/v1
--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

• 使用 MiMo V2.5 内置精品音色，8 种音色可选
• 支持自然语言风格控制、音频标签控制、唱歌
• 无需本地部署，云端 API 调用

音色名	语言	性别	风格
冰糖	中文	女性	活泼少女
茉莉	中文	女性	知性女声
苏打	中文	男性	阳光少年
白桦	中文	男性	成熟男声
Mia	English	Female	Lively girl
Chloe	English	Female	Sweet Dreamy
Milo	English	Male	Sunny boy
Dean	English	Male	Steady Gentle

• 通过文本描述自动生成独特音色
• --context 参数同时控制音色和风格
• 适合需要独特音色、角色配音的场景

• 使用音频样本精准复刻音色
• 支持 --context 添加导演模式指令
• 参考音频仅支持 mp3/wav，最大 10 MB

技巧： 可以先用 voicedesign 模式生成满意音色的音频，再将该音频作为 voiceclone 的参考样本，实现「设计 → 克隆」工作流。

模型	内存需求	速度	精度	说明
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（带时间戳，模型从魔搭社区下载）
  │               │
  │               └─→ [可选] 混元翻译文本（需要腾讯云 API）
  │                       │
  │                       └─→ MiMo V2.5 TTS 批量生成
  │                               │
  │                               └─→ FFmpeg atempo 时长对齐
  │                                       │
  │                                       └─→ FFmpeg amix 混音合成
  │                                               │
  └───────────────────────────────────────────────┘
                        ↓
                   输出配音视频

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

mimo-video-dub-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 倍。

MiMo V2.5 为云端 API，生成速度取决于网络延迟和 API 负载，通常每段语音 1-3 秒。

问题	解决方案
MIMO_API_KEY 未设置	设置环境变量或使用 --mimo-api-key 参数
TTS 返回错误	检查 API 密钥是否正确，是否已开通 MiMo TTS 服务
模型下载慢	模型从魔搭社区（ModelScope）下载，国内直连无需 VPN
内存不足	使用 --asr-model base 或 --asr-model distil-small.en
ASR 识别不准	换用更大模型，或 --source-lang 指定语言
无音频视频	使用 --subtitle 提供 SRT/ASS 字幕文件
翻译需要 API Key	设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 环境变量
音画不同步	ASR 精度有限，尝试较短视频或手动调整
参考音频过大	音色克隆参考音频不超过 10 MB，仅支持 mp3/wav

• MiMo 开放平台: https://platform.xiaomimimo.com/
• MiMo-Skills: https://github.com/XiaomiMiMo/MiMo-Skills
• VoxCPM2 Video Dub Skill: https://github.com/Young140430/voxcpm2-video-dub-skill
• faster-whisper: https://github.com/SYSTRAN/faster-whisper
• ModelScope: https://www.modelscope.cn/