pyVideoTrans 开源视频翻译配音工具实战指南：语音识别、字幕翻译与 AI 配音全流程

• 音视频
• AI 应用
• 语音
• 本地部署

pyVideoTrans（pyvideotrans）是一款开源的视频翻译配音工具，将"语音识别（ASR）→ 字幕翻译 → 语音合成（TTS）→ 视频合成"整合为一条自动化流水线，同时支持本地离线部署与多种主流在线 API。读完本文，你将掌握从 Windows 一键包到源码部署、从 CLI 无头批处理到 Docker/WebUI 远程部署的完整落地方法，并能理解其 9 阶段任务流水线、多线程队列架构与核心配置项的真实作用。

项目定位与核心能力

pyVideoTrans 致力于无缝地将视频从一种语言转换为另一种语言，包含语音识别、字幕翻译、多角色配音及音画同步等全套流程。其核心功能包括：

• 全自动视频翻译：一键完成"语音识别（ASR）→ 字幕翻译 → 语音合成（TTS）→ 视频合成"的完整链路。
• 语音转录 / 字幕生成：批量将音频或视频转为 SRT 字幕，支持说话人分离，可区分不同角色。
• 多角色 AI 配音：支持根据不同说话人分配不同的 AI 配音角色，实现多人对话场景的差异化配音。
• 声音克隆：集成F5-TTS、CosyVoice、GPT-SoVITS等模型，支持零样本声音克隆，可从原视频截取参考音频片段生成近似音色。
• 强大的模型支持：
  • ASR：Faster-Whisper（本地）、OpenAI Whisper、阿里 Qwen、字节火山、Azure、Google 等。
  • LLM 翻译：DeepSeek、ChatGPT、Claude、Gemini、MiniMax、Ollama（本地）、阿里百炼等。
  • TTS：Edge-TTS（免费）、OpenAI、Azure、Minimaxi、ChatTTS、ChatterBox 等。
• 交互式编辑：支持在识别、翻译、配音的每个阶段暂停并人工校对，确保精准度。
• 实用工具集：包含人声分离、视频/字幕合并、音画对齐、文稿匹配等辅助工具。
• 命令行模式（CLI）：支持无头模式运行，方便服务器部署或批处理。
• Web 界面（WebUI）：基于浏览器的界面，适合远程访问或局域网部署。

技术架构与设计原理详见 docs/architecture.md。

从源码结构看，其能力体系在 videotrans/recognition（语音识别渠道）、videotrans/translator（翻译渠道）、videotrans/tts（配音渠道）三个目录中分层实现，TTS 渠道数量达到 30+，识别与翻译渠道各 20+，均由统一入口函数调度（详见后文"流水线背后的源码实现"）。

快速开始：Windows 预打包版

项目为 Windows 10/11 用户提供了预打包的.exe版本，无需配置 Python 环境，适合零基础快速上手：

1. 下载：获取最新预打包版本（Releases 页面）。
2. 解压：将压缩包解压到一个不包含中文、空格的路径下（例如D:\pyVideoTrans）。
3. 运行：双击文件夹内的sp.exe启动。

注意：

• 请勿直接在压缩包内运行，必须先解压。
• 如需使用 GPU 加速，请确保安装CUDA 12.8和cuDNN 9.11。

预打包版内置了 FFmpeg 等运行时依赖（项目根目录的 ffmpeg 目录存放 ffmpeg 及 sox 二进制文件），因此无需额外配置环境变量即可运行。

源码部署（macOS / Linux / Windows 开发者）

推荐使用 **uv声明了requires-python = ">=3.10, <3.11"，即支持 Python 3.10。

1. 前置准备

• Python：建议版本 3.10。
• FFmpeg：必须安装并配置到环境变量。
  • macOS：

    brew install libsndfile git python@3.10 brew uninstall --ignore-dependencies ffmpeg brew tap homebrew-ffmpeg/ffmpeg brew install homebrew-ffmpeg/ffmpeg/ffmpeg

  • Linux (Ubuntu/Debian)：sudo apt-get install ffmpeg libsndfile1-dev
  • Windows：下载 FFmpeg 并配置 Path，或者直接将ffmpeg.exe和ffprobe.exe放在项目目录下。

2. 安装 uv（如果尚未安装）

# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 克隆与安装

git clone https://gitcode.com/gh_mirrors/py/pyvideotrans.git cd pyvideotrans uv sync

可选依赖说明：默认不安装whisper.net与WebUI渠道。

• 安装全部可选渠道：uv sync --all-extras
• 单独安装whisper.net：uv sync --extra dotnet
• 安装 WebUI：uv sync --extra webui（对应 pyproject.toml 中[project.optional-dependencies] webui = ["gradio"]）

4. 启动软件

启动 GUI 界面：

uv run sp.py

sp.py 是唯一入口：它依次完成multiprocessing.freeze_support()、设置spawn启动方式、抑制 Qt 警告、创建无边框半透明启动画面（StartWindow）、加载 videotrans/styles/style.qss 样式表，最终实例化MainWindow并进入 Qt 事件循环。

使用 CLI 命令行：

# 视频翻译示例 uv run cli.py --task vtv --name "./video.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" # 语音转字幕示例 uv run cli.py --task stt --name "./audio.wav" --model_name large-v3 # 字幕翻译示例 uv run cli.py --task sts --name "./subs.srt" --target_language_code en # 文字配音示例 uv run cli.py --task tts --name "./subs.srt" --voice_role "zh-CN-YunyangNeural"

CLI 全部参数与详细用法见 docs/cli.md。

启动 WebUI（适合远程访问或局域网部署）：

uv sync --extra webui uv run webui.py

WebUI 使用说明见 docs/webui.md。

Docker 部署（容器化部署）：

# 构建镜像 docker build -t pyvideotrans-webui . # 运行 docker run -d -p 7860:7860 --name pyvideotrans pyvideotrans-webui # 持久化配置和输出 docker run -d -p 7860:7860 \ -v ./data/output:/app/output \ -v ./data/config:/app/videotrans \ --name pyvideotrans pyvideotrans-webui

仓库根目录的 Dockerfile 支持 CPU 与 GPU 两种构建方式：默认基于python:3.10-slim；当docker build --build-arg USE_CUDA=true时则基于nvidia/cuda:12.8.0-cudnn-runtime-ubuntu22.04，并自动安装 CUDA 版 PyTorch 与nvidia-cublas-cu12、nvidia-cudnn-cu12。镜像内部通过静态 FFmpeg 包安装ffmpeg/ffprobe到/usr/local/bin，WebUI 服务监听0.0.0.0:7860。

5.（可选）GPU 加速配置

如果拥有 NVIDIA 显卡，请执行以下命令以安装支持 CUDA 的 PyTorch 版本：

# 卸载 CPU 版本 uv remove torch torchaudio # 安装 CUDA 版本 (以 CUDA 12.x 为例) uv add torch==2.7 torchaudio==2.7 --index-url https://download.pytorch.org/whl/cu128 uv add nvidia-cublas-cu12 nvidia-cudnn-cu12

若使用 AMD 显卡，可参考 docs/whisper_net_setup.md 尝试加速。

支持的渠道与模型（部分）

各渠道的音色配置以 JSON 形式存放在 videotrans/voicejson 目录（如edge_tts.json、azure_voice_list.json、qwen3tts.json等）；F5-TTS 的按语言音色配置则位于 videotrans/voicejson/f5ttscfg，仓库根目录的 f5-tts 目录存放了多语言声音克隆参考音频。

CLI 无头模式：四种任务类型

cli.py 是命令行入口，通过--task指定四种任务，各自对应不同的流水线与任务子类：

全局选项

典型组合实战

以下命令均以"中文视频60.mp4、中文字幕zw.srt、目标语言英文、Edge-TTS 的en-US-GuyNeural音色"为前提：

场景 1：仅语音转录

uv run cli.py --task stt --name "60.mp4" --detect_language zh-cn --cuda

场景 2：仅字幕翻译

uv run cli.py --task sts --name "zw.srt" --source_language_code zh-cn --target_language_code en

场景 3：仅文字配音（为中文字幕生成英文配音）

uv run cli.py --task tts --name "zw.srt" --voice_role "en-US-GuyNeural" --target_language_code en

场景 4：完整视频翻译（中文 → 英文，带配音）

uv run cli.py --task vtv --name "60.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --cuda

场景 5：高质量翻译（分离人声 + GPU + 二次识别 + 大模型）

uv run cli.py --task vtv --name "60.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --cuda --is_separate --recogn2pass --model_name large-v3

场景 6：双语硬字幕

uv run cli.py --task vtv --name "60.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --subtitle_type 3 --cuda

场景 7：批量处理（Shell 循环）

# Bash / Git Bash for f in *.mp4; do uv run cli.py --task vtv --name "$f" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --cuda done

# PowerShell Get-ChildItem *.mp4 | ForEach-Object { uv run cli.py --task vtv --name $_.FullName --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --cuda }

查询可用渠道、语言与模型

uv run cli.py --list providers # 列出 STT / 翻译 / TTS 全部渠道及编号 uv run cli.py --list languages # 列出全部语言代码（en、zh-cn、ja、ko 等） uv run cli.py --list models # 列出 faster-whisper 可用模型（tiny/base/small/medium/large-v3/large-v3-turbo）

从 cli.py 源码看，--list providers依次遍历recognition.RECOGN_NAME_LIST、translator.TRANSLASTE_NAME_LIST、tts.TTS_NAME_LIST输出带编号的渠道清单，编号即可直接用于--recogn_type、--translate_type、--tts_type。

常用 Edge-TTS 音色速查

退出码约定

WebUI 与 Docker 部署要点

WebUI 基于 Gradio 实现，仅实现了部分功能，主要用于云服务器远程部署、局域网部署与 Docker 容器化部署场景；如需完整功能（实时交互编辑、批量处理等），应使用桌面客户端（sp.exe）或源码运行（sp.py）。

• 启动服务：uv run webui.py（默认0.0.0.0:7860），支持--port 8080、--host 127.0.0.1、--share（创建 Gradio 公网临时链接）。
• 渠道设置与高级选项与桌面版通用，配置保存在videotrans/params.json中；使用 API 渠道前需先用桌面版配置好 API 地址和 SK 密钥。
• Docker 持久化：-v ./data/output:/app/output -v ./data/config:/app/videotrans；GPU 加速需安装 nvidia-container-toolkit 后加--gpus all。

详细说明见 docs/webui.md。

流水线背后的源码实现

九阶段处理流程与五个控制标志位

视频翻译配音过程被分解为 9 个独立阶段，形成自动化流水线：

每个任务通过 5 个布尔标志位控制哪些阶段被跳过（定义于 videotrans/task/_base.py）：

should_recogn: bool # 是否需要语音识别（无已有字幕则为 True） should_trans: bool # 是否需要翻译（源语言 ≠ 目标语言则为 True） should_dubbing: bool # 是否需要配音（选择了配音角色且非 'No' 则为 True） should_hebing: bool # 是否需要嵌入合并（非 'tiqu' 模式且有配音或字幕嵌入则为 True） should_separate: bool # 是否需要人声背景分离

不同功能即标志位组合的结果：视频翻译（✓✓✓✓）、转录翻译 tiqu（✓ 可选 ✗ ✗）、语音转录（✓✗✗✗）、文字配音（✗✗✓✓）、翻译字幕（✗✓✗✗）。

多线程队列架构与子进程保护

软件采用基于"生产者-消费者"模式的多线程多队列架构：MultVideo线程作为生产者将任务推入prepare_queue，9 种BaseWorker子类作为消费者监听专属队列逐级流转（prepare_queue → regcon_queue → diariz_queue → trans_queue → dubb_queue → align_queue → regcon2_queue → assemb_queue → taskdone_queue），每级根据trk的标志位决定下一跳。批量提交支持batch_nums参数控制并发（0全量并发、1逐个、>1每批 N 个）。

为避免faster-whisper、F5-TTS 等重型渠道崩溃导致整个软件退出，部分渠道通过BaseCon._new_process()委托给 videotrans/process/signelobj.py 中的GlobalProcessManager（类级别单例，含 CPU/GPU 双multiprocessing.Pool，maxtasksperchild=1防内存泄漏）在独立子进程中执行；子进程通过写入 JSON 日志文件报告进度，_signal_of_process()轮询该文件解析进度。

动态渠道加载与统一入口

videotrans/init.py 提供通用的懒加载机制get_class()：通过importlib.import_module(f'videotrans.{provider_type}...')按渠道编号动态加载对应模块类。三大模块各自维护_ID_NAME_DICT渠道注册表（识别 20+、翻译 20+、配音 30+），并提供统一的run()入口函数与is_input_api()API Key 校验。翻译模块还实现了基于 MD5 的翻译缓存（缓存 key =md5(渠道+url+模型+源语言+目标语言+文本)，存储于{TEMP_ROOT}/translate_cache/），重复翻译可显著提速。

交互式单视频模式

当用户选择 1 个视频且在标准模式下时，程序改用 videotrans/task/only_one.py 中的Worker(QThread)在单个线程内串行执行全部阶段，并在识别、翻译、配音之后设置三个暂停点弹出校对对话框（原始字幕编辑、说话人角色分配、配音结果试听重配），配合app_cfg.set_countdown()倒计时实现自动继续或无限期暂停。批量模式则不支持这种中间人工校对。

常见问题速览

• 如何查看所有渠道和音色？uv run cli.py --list providers，或在 GUI 的 TTS 设置中查看音色下拉列表。
• 路径含空格怎么办？使用英文双引号包裹：--name "D:/my videos/60.mp4"。
• 如何启用 GPU 加速？添加--cuda，前提是已安装 NVIDIA 驱动、CUDA 12.8+、cuDNN 9.11+。
• 翻译后的字幕和声音不同步？添加--voice_autorate（自动加速音频）或--video_autorate（自动慢速视频）。
• 如何只翻译不配音？不指定--voice_role或指定为No。
• 处理速度太慢？添加--cuda；改用小模型--model_name tiny；跳过--is_separate与--recogn2pass。
• 如何保留缓存调试？使用--no-clear-cache（默认--clear_cache为 true，完成即清理）。
• 详细日志？-v或--log-level DEBUG。

文档与支持

• 中文 README：docs/README_CN.md
• 技术架构与实现原理：docs/architecture.md
• CLI 命令行文档：docs/cli.md
• WebUI 使用说明：docs/webui.md
• 音画对齐原理：docs/Synchronize.md
• 常见问题：docs/faq.md
• AMD GPU 加速（Whisper.NET）：docs/whisper_net_setup.md

免责声明

本软件为开源免费非商业项目（GPL-3.0，见 LICENSE），使用者需自行承担因使用本软件（包括但不限于调用第三方 API、处理受版权保护的视频内容）所产生的一切法律后果。请遵守当地法律法规及相关服务商的使用协议。项目主要依赖 FFmpeg、PySide6、sherpa-onnx、faster-whisper、openai-whisper、edge-tts、F5-TTS、Confucius4-TTS、OmniVoice、CosyVoice、Gradio（WebUI）等开源项目。

• 音视频
• AI 应用
• 语音
• 本地部署