📦 pyVideoTrans 详细部署教程

pyVideoTrans 是一款强大的开源视频翻译工具，支持完整的视频语言转换工作流：语音识别 (ASR)、字幕翻译、多角色 AI 配音和视频合成。它支持本地离线部署，并集成了多种主流在线 API。本教程将指导您完成从源码部署到运行的全过程。

⚙️ 部署前准备

1. 系统与环境要求

  • 操作系统：Windows 10/11、macOS、Linux。
  • Python 版本：Python 3.10（推荐）。使用 uv 管理。
  • FFmpeg：必须安装并添加到系统环境变量 PATH 中。它是处理音视频的核心依赖。
    • macOS: brew install ffmpeg libsndfile1-dev (需先安装 Homebrew)
    • Linux (Ubuntu/Debian): sudo apt-get install ffmpeg libsndfile1-dev
    • Windows: 从 FFmpeg 官网下载，或将 ffmpeg.exe 和 ffprobe.exe 直接放入项目根目录。
  • （可选）NVIDIA GPU 与 CUDA：如需 GPU 加速，需安装 CUDA 12.8 和 cuDNN 9.11。

🚀 部署方式一：Windows 预编译包（Windows 用户最简单）

适合不想配置 Python 环境的 Windows 用户。

  1. 下载：从项目 Releases 页面下载最新的预编译 .exe 压缩包。
  2. 解压：将压缩包解压到路径中不含中文字符或空格的文件夹（如 D:\pyVideoTrans）。
  3. 运行：双击文件夹中的 sp.exe 文件即可启动图形界面。

注意：不要直接在压缩包内运行，务必先解压。

🐍 部署方式二：从源码部署（推荐开发者/跨平台用户）

1. 安装 uv 包管理器

uv 是一个快速的 Python 包管理工具。

1
2
3
4
5
# 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"

2. 克隆并安装依赖

1
2
3
4
5
6
7
8
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans

# 基础安装（不含 whisper.net 和 WebUI 依赖）
uv sync

# 如需安装所有可选依赖（包括 WebUI、whisper.net 等）
uv sync --all-extras

3. 启动软件

  • 启动图形界面 (GUI)：

    1
    uv run sp.py

  • 启动 Web 界面 (WebUI)（适合远程访问或内网部署）：

    1
    2
    3
    # 需先安装 WebUI 依赖（如果未安装）
    uv sync --extra webui
    uv run webui.py

    默认访问地址为 http://localhost:7860。

  • 使用命令行 (CLI)（适合脚本化或无界面运行）：

    1
    2
    3
    4
    5
    # 视频翻译
    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

    更多 CLI 参数请参考项目文档。

🐳 部署方式三：Docker 部署（适合服务器/容器化环境）

Docker 方式可以快速创建一个隔离的 WebUI 服务。

  1. 构建镜像（在项目根目录下）：

    1
    docker build -t pyvideotrans-webui .

  2. 运行容器：

    1
    2
    3
    4
    5
    6
    7
    8
    # 基本运行
    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

    之后可通过 http://宿主机IP:7860 访问 WebUI。

🚀 GPU 加速配置（可选）

如果您有 NVIDIA 显卡，可以替换为 CUDA 版本的 PyTorch 以获得性能提升。

1
2
3
4
5
6
# 1. 移除 CPU 版本
uv remove torch torchaudio

# 2. 安装 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 GPU 加速可通过 Whisper.NET 实现，详见项目文档。

🔧 核心配置与模型集成

1. 语音识别 (ASR)

  • 本地：推荐使用 Faster-Whisper，速度快且准确率高。
  • 在线：支持阿里云、火山引擎、Azure、Google 等 API。

2. 字幕翻译 (LLM)

  • 本地：可使用 Ollama 或 M2M100 进行完全离线的翻译。
  • 在线：支持 DeepSeek、ChatGPT、Claude、MiniMax、Google 翻译等。

3. 语音合成 (TTS)

  • 免费：Edge-TTS（微软免费服务，效果自然）。
  • 本地克隆：F5-TTS、CosyVoice、GPT-SoVITS 支持零样本语音克隆。
  • 在线：OpenAI、Azure、MiniMax 等。

配置方法：在 GUI 或 WebUI 的设置页面中，填入对应服务的 API 密钥和参数即可。

❓ 常见问题

  • Q: Windows 下双击 sp.exe 无反应？
    • A: 确保已解压到无中文/空格的路径，并以管理员身份运行。检查是否安装了所需的 VC++ 运行库。
  • Q: 出现 FFmpeg 错误？
    • A: 确认 FFmpeg 已正确安装并添加到系统 PATH。在命令行输入 ffmpeg -version 测试是否生效。
  • Q: 如何更新到最新版本？
    • A: 对于源码部署，进入项目目录执行 git pull 拉取更新，然后重新运行 uv sync 更新依赖。Windows 预编译版需重新下载解压。
  • Q: 处理大视频时内存不足？
    • A: 可以尝试在设置中降低“同时处理的音频片段数”或使用“仅提取部分片段”功能。另外，使用命令行模式并通过参数分段处理也有帮助。

更详细的配置指南、API 密钥获取方法和故障排除，请务必查阅 pyVideoTrans 官方文档 和 社区问答。