Video Translate Dub — Data skill for Claude Code

Video Translate & Dub Pipeline

[English](README_EN.md) | [中文说明](README.md)

专为 **AI Coding Agent**（Claude Code, Codex, Cursor, Windsurf 等）与开发者打造的**全本地英文视频汉化与原声音色克隆配音管线**。

基于 whisper.cpp 词级对齐、IndexTTS-2.5 音色克隆、Demucs 人声分离与 FFmpeg 影视级渲染，100% 运行在 Mac Apple Silicon 本地，无需充值商业翻译或语音合成 API。

---

为什么做这个项目？

市面上的自动化视频翻译工具不少，但在实际工业化出片中，普遍存在几个让开发者头疼的硬伤：

1. 配音总是音画错位：传统工具依赖粗粒度的 VAD 静音切分，遇到背景音乐或语速突变，配音往往提前抢跑或滞后数秒；
2. 配音机械生硬：大部分工具采用死板的 Edge-TTS 播音腔，既丢掉了原视频主讲人的声线特质，又缺乏情绪起伏；
3. 中文译文机械超窗：很多管线要求“中文语速压到 4.2 字/秒以内”，导致大模型为了塞进时间窗口大肆删减原文核心信息，造成短句孤立、内容漏译；
4. 画面英文词卡无法汉化：只压字幕不改画面，视频中原本出现的英文教学卡片与中文字幕打架冲突；
5. 云端 API 账单昂贵：5 分钟的高清视频，商业克隆配音动辄数元到数十元，批量处理成本难以承受。

本项目通过 5 项核心机制解决上述问题：

• 纯 DTW 词级时间戳锚定：采用 whisper.cpp --dtw 提取首尾实词 token 真实发声起点收缩窗口，彻底杜绝背景音带偏；
• IndexTTS-2.5 纯净干音克隆 + 8 维情感微调：内置 VAD 纯度与零停顿打分算法，自动优选最干净的参考切片，配合 8 维情感向量控制（支持喜悦、平静、惊喜等微调），还原原片说话人音色；
• 实测回归估时模型与顺延借静音：基于 7 部片子 527 段真实合成数据训练估时公式（0.1801×汉字 + 0.0537×标点 + 1.1234）。明确短句固定开销，超窗自动借用段间自然静音或微调速（≤1.25x），宁保信息完整绝不删句；
• 差分掩膜双层横幅汉化：自动提取画面净背景帧作为硬切补丁（Patch），文字层淡入淡出，彻底解决画面英文残留与重影，同时驱动字幕智能抬高避让；
• 零 Token 消耗，全链路 Mac 本地加速：转写、人声分离、克隆合成、视频压制全部基于 Apple Silicon MPS 硬件加速。

---

安装方式

本项目既是一个可直接在终端执行的 CLI 工具链，也是一个遵循通用 Agent 规范的 **Agent Skill**。

方式一：通过 `npx skills` 一键安装到您的 AI Agent（推荐）

如果您使用 Claude Code、Cursor 或支持 Agent Skills 的智能体，可在终端执行：

npx skills add jryang1997/video-translate-dub

终端将弹出交互界面，自动为您把 `video-translate-dub` 技能软链接到您的全局或项目 Agent 配置中。此后只需对 Agent 说：

“*帮我把这个英文视频下载并汉化配音：https://www.youtube.com/watch?v=XXXX*”

Agent 将自主完成环境自检、分步执行、翻译预算校验与成品交付。

方式二：本地源码克隆（人类开发者模式）

git clone https://github.com/jryang1997/video-translate-dub.git
cd video-translate-dub

---

硬件要求与环境准备

1. 硬件基准

• 推荐机型：Apple Silicon Mac（M1/M2/M3/M4 系列），统一内存 ≥ 32GB；
• 并发约束：IndexTTS-2.5 在合成时单进程独占约 25~35GB 内存。严禁并行多进程跑合成，必须串行处理单个视频，否则必触发系统 Swap 耗尽被杀进程；
• 耗时基线：以 M1 Pro 为例，一段 5 分钟的视频，ASR 转写约 1.5 分钟，Demucs 人声分离约 2 分钟，IndexTTS 克隆合成约 16 分钟，总耗时约 30~35 分钟。

2. 系统依赖安装