Video Translator

video_translator 是一个纯离线的视频翻译与中文配音命令行工具，面向“本地完成字幕提取、翻译、配音和混音”的工作流。

默认面向两类用户：

• 普通用户：安装一次后，只传一个视频路径
• 进阶用户：按需覆盖字幕、分离、翻译、配音和混音参数

当前产品只保留两条核心能力：

• 本地 HY-MT 翻译
• 本地 GPT-SoVITS 配音

进入本地翻译流程前，也可以先把在线视频下载为本地视频文件。

产品目标是不依赖 Google Translate、Edge TTS 或其他在线 SaaS 能力；运行时不主动访问公网翻译或公网 TTS 服务。

特性

• OCR-first 字幕获取：优先内嵌字幕，其次 OCR，最后回退 WhisperX ASR
• WhisperX 对齐时间戳，并可用 pyannote 为多角色配音分配说话人
• 全链路本地运行：翻译使用本地 HY-MT，配音使用本地 GPT-SoVITS HTTP API
• URL 输入下载层：当前默认使用 yt-dlp，可直接处理 YouTube 链接，并为 Bilibili 等更多站点保留统一扩展接口
• 支持 MDX-Net、Demucs、ffmpeg 多种分离策略
• 自动保留背景声并重新混音
• 输出 source.srt、translated.srt、带说话人的 SRT、manifest.json、audio_audit.log
• 对异常偏静的 TTS 片段自动重试 2 次

当前架构

• 字幕获取：内嵌字幕提取 -> OCR -> WhisperX ASR 回退
• 翻译：本地 tencent/HY-MT1.5-1.8B
• 配音：本地 GPT-SoVITS API
• 混音：ffmpeg 将背景轨与配音轨重新封装回原视频

更完整的架构说明见 DESIGN.MD。

快速开始

对普通用户，推荐流程只有两步。

第一步：执行一键安装

./install.sh

安装脚本会处理以下事情：

• 创建本地虚拟环境 .venv
• 安装 Python 依赖
• 安装当前项目
• 检查 ffmpeg 和 ffprobe
• 自动执行 ./init.sh

初始化脚本会继续处理：

• 自动检测已有 GPT-SoVITS 服务仓库
• 若本机没有仓库，默认克隆到同级目录 ../GPT-SoVITS
• 准备或复用 GPT-SoVITS 的 Python 环境
• 预下载本地翻译、ASR、MDX、Demucs 所需模型
• 把这些运行时模型统一缓存到 .video-translator/models/
• 通过和运行时一致的 transformers 加载路径预热 HY-MT 完整权重，避免首次翻译时再下载大体积 checkpoint
• 准备自动音色克隆所需的默认参考配置
• 生成 video_translator.defaults.json 运行默认配置
• 生成 gpt_sovits.local.json 本地服务配置
• 启动本地 GPT-SoVITS 服务

如果你只想先装主程序、不初始化服务，也可以：

./install.sh --skip-init
./init.sh

第二步：只传入视频路径

./video-translator /path/to/video.mov

如果你更喜欢直接调用虚拟环境里的 CLI，也可以：

./.venv/bin/video-translator /path/to/video.mov

也可以直接传入在线视频链接，程序会先下载视频，再复用同一套翻译与配音流程：

./video-translator "https://www.youtube.com/watch?v=VIDEO_ID"

安装脚本生成的默认配置会自动提供：

• 目标语言：中文
• GPT-SoVITS 本地地址
• 自动按说话人克隆原视频音色
• 保守回退男声/女声参考音频路径

默认简单模式下，程序会先用 pyannote 给字幕片段分配说话人，再优先为每个说话人从当前输入视频里自动挑选一段较干净的原声音频，并直接用该片段的原文做 GPT-SoVITS 参考文本。

如果自动抽取失败，程序会进入保守模式：

• 优先按检测到的说话人音高，在 male1.mp3、male2.mp3 或 female1.mp3、female2.mp3 之间为不同角色轮换选择参考音频
• 若这两个文件缺失或转写失败，再回退到仓库内置的固定参考音频

环境准备

• Python 3.10+
• 首次安装阶段需要可访问对应模型源，用于下载本地翻译、ASR 与分离模型

install.sh 和 init.sh 会尽可能处理本地环境；在 macOS 且已安装 Homebrew 的情况下，它们会自动补齐 ffmpeg，并在缺失时安装 [email protected] 供 GPT-SoVITS 使用。

GPT-SoVITS 前置条件

本仓库不把 GPT-SoVITS 推理代码直接 vendor 进当前仓库，但现在会在 init.sh 中自动检测或克隆官方仓库，并把服务启动准备好。默认 HTTP 地址仍然是：

http://127.0.0.1:9880

对于普通用户，这三项默认由 init.sh 生成并写入 video_translator.defaults.json；只有进阶用户才需要手动覆盖：

• 一段参考音频 --gpt-sovits-ref-audio
• 该参考音频对应的文本 --gpt-sovits-prompt-text
• 参考音频语言 --gpt-sovits-prompt-lang

如果你要启用保守模式里的男女回退参考，请把你准备好的两个文件放在项目根目录：

• ./female.mp3
• ./male.wav

用法

小白模式

安装完成后，最简单的单文件用法是：

./video-translator ./video_test.mov

也支持直接把视频路径作为唯一参数传给 CLI：

./.venv/bin/video-translator ./video_test.mov

在这个模式下，不需要手动指定参考音频。程序会优先尝试“原视频单旁白音色 -> 中文配音”，只有在自动抽取失败时才回退到 female.mp3 / male.wav 或仓库内置参考音色。

进阶模式

当你想替换默认参考音频或其他行为时，再显式传参数。

最小单文件显式参数示例：

video-translator \
	--video ./video_test.mov \
	--gpt-sovits-ref-audio ./ref_voice.wav \
	--gpt-sovits-prompt-lang zh \
	--gpt-sovits-prompt-text "这是参考音频对应的文本" \
	--keep-workdir

批量处理目录：

video-translator \
	--input-dir ./videos \
	--gpt-sovits-ref-audio ./ref_voice.wav \
	--gpt-sovits-prompt-lang zh \
	--gpt-sovits-prompt-text "这是参考音频对应的文本" \
	--keep-workdir

批量模式默认输出到输入目录下的 translated_videos/。

常用参数

普通用户通常只需要：

• video-translator /path/to/video.mov

只有在需要自定义时，再使用下面这些参数：

• --video path/to/video.mov：处理单个视频
• --video-url https://...：先下载在线视频，再翻译
• --input-dir path/to/videos：批量处理目录
• --output output.mov：指定单文件输出路径
• --output output_dir/：批量模式指定输出目录
• --download-provider yt-dlp：URL 下载后端，当前默认值也是 yt-dlp
• --download-dir path/to/downloads：指定 URL 源视频下载目录
• --list-download-formats：只列出当前链接可下载的格式/清晰度，不真正下载
• --download-max-height 720：限制 URL 下载的最大清晰度，例如 360、480、720、1080
• --download-format "137+140"：高级格式选择，直接透传给 yt-dlp
• --download-cookie-file cookies.txt：给需要登录态的网站传入 cookies 文件
• --download-cookies-from-browser chrome：直接从浏览器导入 cookies，适合 Bilibili/YouTube 登录态下载
• --workdir path/to/workdir：指定中间产物目录
• --keep-workdir：保留中间文件，方便复查
• --subtitle-source auto|ocr|asr：字幕来源策略
• --separator auto|mdx|demucs|ffmpeg|none：分离策略
• --mdx-model UVR_MDXNET_KARA_2.onnx：指定 MDX 模型
• --asr-model tiny|small|medium|large-v3：WhisperX ASR 模型大小
• --speaker-diarization auto|on|off：是否使用 pyannote 做多说话人分配；on 会在 pyannote 不可用时直接报错
• --hf-token hf_...：pyannote 模型需要 Hugging Face 访问权限时传入 token，也可用 HF_TOKEN 环境变量
• --chunk-seconds 300：长视频 ASR 分块时长
• --translate-context-window 3：翻译当前字幕段时参考前后各几句上下文，范围 2-10
• --ocr-fps 1.0：OCR 抽帧频率
• --trim-start 8：处理前先裁掉开头 8 秒
• --trim-end 5：处理前再裁掉结尾 5 秒
• --hy-device auto|cpu|mps|cuda：HY-MT 运行设备
• --hy-model tencent/HY-MT1.5-1.8B：HY-MT 模型 ID
  • 该模型包含 Hugging Face 自定义生成代码，会自动使用 trust_remote_code=True 进行加载
• --gpt-sovits-url http://127.0.0.1:9880：本地 GPT-SoVITS API
• --gpt-sovits-ref-audio ./ref.wav：参考音频
• --gpt-sovits-prompt-lang zh：参考音频语言
• --gpt-sovits-prompt-text "..."：参考音频对应文本
• --gpt-sovits-text-lang zh：目标文本语言
• --gpt-sovits-text-split-method cut5：GPT-SoVITS 切句策略
• --gpt-sovits-speed 1.0：GPT-SoVITS 基础语速
• --dub-volume 0.78：配音混音权重
• --background-volume 1.18：背景混音权重

示例

最简单示例

./install.sh
./video-translator ./samples/video_test_5.mov

去掉片头/片尾版权画面：

./video-translator ./samples/video_test_5.mov --trim-start 8 --trim-end 5

从音频提取带时间戳字幕：

./asr-subtitles ./audio.wav --output ./audio.srt --source-language auto

默认会把中文 ASR 文本转成简体中文，并且不会加载 WhisperX 的 wav2vec2 对齐模型，因此只需要本地已有的 Whisper/Faster-Whisper ASR 模型。也可以使用已安装的命令，并额外保留 ASR 片段 JSON：

asr-subtitles \
	--audio ./audio.mp3 \
	--output ./audio.srt \
	--json-output ./audio.segments.json \
	--asr-model small \
	--source-language zh

如果你已经单独准备好了 WhisperX 对齐模型，并希望得到更细的时间戳，可以追加 --align。 如果想保留 ASR 原始繁简输出，可以追加 --chinese-script original。

直接翻译 YouTube 视频：

./video-translator \
	--video-url "https://www.youtube.com/watch?v=VIDEO_ID" \
	--trim-start 8

直接翻译 Bilibili 视频：

./video-translator \
	--video-url "https://www.bilibili.com/video/BV16woRBfEsH/"

先查看当前链接有哪些可选清晰度：

./video-translator \
	--video-url "https://www.bilibili.com/video/BV16woRBfEsH/" \
	--list-download-formats

如果 Bilibili 需要更高清晰度，通常要带上登录态。比如从 Chrome 导入 cookies 后再限制到 1080p：

./video-translator \
	--video-url "https://www.bilibili.com/video/BV16woRBfEsH/" \
	--download-cookies-from-browser chrome \
	--download-max-height 1080

指定下载为 720p 再翻译：

./video-translator \
	--video-url "https://www.youtube.com/watch?v=VIDEO_ID" \
	--download-max-height 720

当前默认下载后端是 yt-dlp。它本身支持大量站点，所以同一入口通常也可用于 Bilibili 等受支持网站；如果后续要接入自建下载服务或站点专用适配器，可以继续扩展 --download-provider。

当前已验证可直接下载：

• YouTube / youtu.be
• Bilibili

yt-dlp 官方支持范围非常广，除了 YouTube 和 Bilibili，还内置了大量常见站点提取器，例如 TikTok、X/Twitter、Facebook、Instagram、Vimeo、Dailymotion、Twitch、SoundCloud、Douyin、小红书、优酷、爱奇艺、腾讯视频部分场景 等。是否最终可用仍取决于站点是否变更、是否需要登录态，以及地区限制。

对 Bilibili 这类站点要特别注意：匿名状态下常常只能拿到 360p 或 480p，更高的 720p、1080p、1080P 高码率、4K 往往需要大会员或至少需要登录 cookies。

批量处理目录并统一裁掉片头：

./video-translator \
	--input-dir ~/Downloads/prehistoric_planet_s1 \
	--trim-start 8 \
	--gpt-sovits-ref-audio ./male.wav \
	--gpt-sovits-prompt-lang zh \
	--gpt-sovits-prompt-text "您好，很高兴能为您提供配音服务，选择您感兴趣的音色，让我们一起开启声音创作的奇幻之旅吧。"

注意：换行续写命令时，反斜杠 \ 后面不能再有空格，否则 shell 会把空格当成参数，并把下一行的 --input-dir 当成一条新命令。

显式指定参考音频

使用中文参考音频生成中文配音：

video-translator \
	--video ./samples/video_test_5.mov \
	--output ./samples/video_test_5_gpt_sovits.mov \
	--workdir ./artifacts/gpt_sovits_video_test_5 \
	--keep-workdir \
	--separator mdx \
	--gpt-sovits-url http://127.0.0.1:9880 \
	--gpt-sovits-ref-audio ./artifacts/gpt_sovits_ref.wav \
	--gpt-sovits-prompt-lang zh \
	--gpt-sovits-prompt-text "这是参考音频对应的文本" \
	--gpt-sovits-text-lang zh

使用已有中文成片中的旁白抽取参考音频后再克隆：

ffmpeg -y -ss 16.3 -to 26.3 -i ./samples/translated_videos/video_test_5_zh_CN.mov -vn -ac 1 -ar 32000 ./artifacts/ref_from_translated_video.wav

video-translator \
	--video ./samples/video_test_5.mov \
	--gpt-sovits-ref-audio ./artifacts/ref_from_translated_video.wav \
	--gpt-sovits-prompt-lang zh \
	--gpt-sovits-prompt-text "毫无疑问，有史以来最杰出的动物之一，也是最为著名的生物之一，就是恐龙。" \
	--gpt-sovits-text-lang zh \
	--keep-workdir

输出内容

每次运行会生成：

• 最终配音视频
• source.srt
• translated.srt
• source.with_speakers.srt
• translated.with_speakers.srt
• asr/whisperx_source.srt
• asr/whisperx_segments.json
• speaker_turns.json
• manifest.json
• audio_audit.log
• tts/、timeline/、ocr/ 等中间目录

其中 audio_audit.log 用于人工审核：

• 每段 TTS 是否生成
• 原始音频和拟合后音频路径
• 每段时长与音量指标
• 是否命中 very-quiet 自动重试
• 最终 dub_track、背景轨和输出视频时长

说明

• video_translator.defaults.json 是本地运行默认配置，主要用于“只传视频路径”的简化模式。
• gpt_sovits.local.json 是本地 GPT-SoVITS 服务启动配置，由 init.sh 生成。
• .video-translator/models/ 是本地运行模型缓存目录，init.sh 会提前准备 HY-MT、faster-whisper、MDX-Net、Demucs 所需资产。
• GPT-SoVITS 虽通过本地 HTTP API 调用，但服务应部署在本机或内网环境中。
• video-translator 在检测到本地服务未启动时，会优先尝试自动拉起 GPT-SoVITS。
• ffmpeg 降级方案的人声分离效果不如 MDX-Net 或 Demucs。

仓库内容

• video_translator.py：主 CLI 和视频翻译主流程
• ocr_subtitles.py：OCR 字幕提取
• pyproject.toml：包元数据
• requirements.txt：运行依赖
• DESIGN.MD：架构设计说明
• README.md：用户使用说明

License

本项目使用 MIT License，详见 LICENSE。