jianchang512 /
趋势观察中pyvideotrans
Translate the video from one language to another and embed dubbing & subtitles.
原始仓库简介 · 中文摘要待补充 · speech-to-text / stt / subtitle-translation / text-to-speech / tts / video-transition
README / 项目原文
README.md ↗抓取于 2026/10/27 13:19:48
# pyVideoTrans
Sponsors Recall.ai Meeting Transcription API If you’re looking for a transcription API for meetings, consider checking out Recall.ai , an API that works with Zoom, Google Meet, Microsoft Teams, and more OfoxAI: Text, speech, image and video model APIs Access GPT, Claude, Gemini and DeepSeek text models, ElevenLabs speech models, and image and video generation models with one API key—choose the models that fit your creative needs. infistar - 160+ 模型,一个 Key infistar 是 OpenAI 兼容中转,一个 Key 随时切 160+ 模型,挑出翻得最准又最省的那个
A Powerful Open Source Video Translation / Audio Transcription / AI Dubbing / Subtitle Translation Tool
简体中文 | Documentation | Online Q&A
pyVideoTrans is dedicated to seamlessly converting videos from one language to another, offering a complete workflow that includes speech recognition, subtitle translation, multi-role dubbing, and audio-video synchronization. It supports both local offline deployment and a wide variety of mainstream online APIs.
Core Features
- Fully Automatic Video Translation: One-click workflow: Speech Recognition (ASR) → Subtitle Translation → Speech Synthesis (TTS) → Video Synthesis.
- Audio Transcription / Subtitle Generation: Batch convert audio/video to SRT subtitles, supporting Speaker Diarization to distinguish between different roles.
- ️Multi-Role AI Dubbing: Assign different AI dubbing voices to different speakers.
- Voice Cloning: Integrates models like F5-TTS, CosyVoice, GPT-SoVITS for zero-shot voice cloning.
- Powerful Model Support:
- ASR: Faster-Whisper (Local), OpenAI Whisper, Alibaba Qwen, ByteDance Volcano, Azure, Google, etc.
- LLM Translation: DeepSeek, ChatGPT, Claude, Gemini, MiniMax, Ollama (Local), Alibaba Bailian, etc.
- TTS: Edge-TTS (Free), OpenAI, Azure, Minimaxi, ChatTTS, ChatterBox, etc.
- ️Interactive Editing: Supports pausing and manual proofreading at each stage (recognition, translation, dubbing) to ensure accuracy.
- ️Utility Toolkit: Includes auxiliary tools such as vocal separation, video/subtitle merging, audio-video alignment, and transcript matching.
- Command Line Interface (CLI): Supports headless operation, convenient for server deployment or batch processing.
- Web Interface (WebUI): Browser-based interface for remote access or internal network deployment.
Quick Start (Windows Users)
We provide a pre-packaged .exe version for Windows 10/11 users, requiring no Python environment configuration.
- Download: Click to download the latest pre-packaged version
- Unzip: Extract the compressed file to a path without Chinese characters or spaces (e.g.,
D:\pyVideoTrans). - Run: Double-click
sp.exeinside the folder to launch.
Note:
- Do not run directly from within the compressed archive.
- To use GPU acceleration(NVIDIA GPU only), ensure CUDA 12.8 and cuDNN 9.11 are installed.
️ Source Deployment (macOS / Linux / Windows Developers)
We recommend using uv for package management for faster speed and better environment isolation.
1. Prerequisites
- Python: Recommended version 3.10
- FFmpeg: Must be installed and configured in the environment variables.
- 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: Download FFmpeg and configure Path, or place
ffmpeg.exeandffprobe.exedirectly in the project directory.
2. Install uv (If not installed)
# 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. Clone and Install
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans
uv sync
By default,
whisper.netandWebUIare not installed locally.
- To install all optional channels:
uv sync --all-extras- To install whisper.net:
uv sync --extra dotnet- To install WebUI:
uv sync --extra webui
4. Launch Software
GUI:
uv run sp.py
CLI:
# Video Translation
uv run cli.py --task vtv --name "./video.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural"
# Audio to Subtitle
uv run cli.py --task stt --name "./audio.wav" --model_name large-v3
# Subtitle Translation
uv run cli.py --task sts --name "./subs.srt" --target_language_code en
# Text to Speech
uv run cli.py --task tts --name "./subs.srt" --voice_role "zh-CN-YunyangNeural"
WebUI (for remote/internal network access):
uv sync --extra webui
uv run webui.py
Docker (containerized deployment):
# Build
docker build -t pyvideotrans-webui .
# Run
docker run -d -p 7860:7860 --name pyvideotrans pyvideotrans-webui
# With persistent config and output
docker run -d -p 7860:7860 \
-v ./data/output:/app/output \
-v ./data/config:/app/videotrans \
--name pyvideotrans pyvideotrans-webui
5. (Optional) NVIDIA GPU Acceleration Configuration
If you have an NVIDIA graphics card, execute the following commands to install the CUDA-supported PyTorch version:
# Uninstall CPU version
uv remove torch torchaudio
# Install CUDA version (Example for 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
Supported Channels & Models (Partial)
| Category | Channel/Model | Description |
|---|---|---|
| ASR (Speech Recognition) | Faster-Whisper (Local) | Recommended, fast speed, high accuracy |
| WhisperX / Parakeet | Supports timestamp alignment & speaker diarization | |
| Alibaba Qwen3-ASR / ByteDance Volcano | Online API, excellent for Chinese | |
| Translation (LLM/MT) | DeepSeek / ChatGPT | Supports context understanding, more natural translation |
| infistar AI | infistar - 160+ models, one Key, OpenAI compatible gateway, switch to 160+ models at any time with one Key | |
| Atlas Cloud | OpenAI-compatible gateway, one Key for DeepSeek, GLM, Kimi, Qwen, MiniMax and proxied vendor models | |
| Opper | EU-hosted OpenAI-compatible gateway, one Key for 700+ models from 50+ providers | |
| Runcrate | GPU cloud with an OpenAI-compatible API: DeepSeek, GLM, Qwen, Kimi and gpt-oss, open models are free with your GitHub account | |
| MiniMax AI | MiniMax M3 LLM, latest flagship model, OpenAI-compatible | |
| Google / Microsoft | Traditional machine translation, fast speed | |
| Ollama / M2M100 | Fully local offline translation | |
| TTS (Speech Synthesis) | Edge-TTS | Microsoft free interface, natural effect |
| F5-TTS / OmniVoice / Qwen3-TTS | Supports Voice Cloning | |
| GPT-SoVITS / Index-TTS / ChatTTS | High-quality open-source TTS, requires local deployment | |
| 302.AI / OpenAI / Azure | High-quality commercial API |
Documentation & Support
- Official Documentation: https://pyvideotrans.com (Includes detailed tutorials, API configuration guides, FAQ)
- Online Q&A Community: https://bbs.pyvideotrans.com (Submit error logs for automated AI analysis and answers)
- GitHub Wiki: architecture.md | Add new Translator Channel | cli.md | webui.md | Synchronize.md | faq.md
Disclaimer
This software is an open-source, free, non-commercial project. Users are solely responsible for any legal consequences arising from the use of this software (including but not limited to calling third-party APIs or processing copyrighted video content). Please comply with local laws and regulations and the terms of use of relevant service providers.
Acknowledgements
This project mainly relies on the following open-source projects (partial):
- FFmpeg
- PySide6
- sherpa-onnx
- faster-whisper
- openai-whisper
- edge-tts
- F5-TTS
- Confucius4-TTS
- OmniVoice
- CosyVoice
- Gradio (WebUI)
Created by jianchang512
docs/README_CN.md ↗抓取于 2026/10/27 13:19:48
# pyVideoTrans
Sponsors Recall.ai Meeting Transcription API If you’re looking for a transcription API for meetings, consider checking out Recall.ai , an API that works with Zoom, Google Meet, Microsoft Teams, and more OfoxAI：文本、语音、图像、视频，多模型 API 资源 一个 API Key 接入 GPT、Claude、Gemini、DeepSeek 等文本模型及 ElevenLabs 语音模型，同时提供图像与视频生成模型，按创作需求灵活选择。 infistar - 160+ 模型,一个 Key infistar 是 OpenAI 兼容中转,一个 Key 随时切 160+ 模型,挑出翻得最准又最省的那个
pyVideoTrans 致力于无缝地将视频从一种语言转换为另一种语言，包含语音识别、字幕翻译、多角色配音及音画同步等全套流程。支持本地离线部署与多种主流在线 API。
✨ 核心功能
- 全自动视频翻译: 一键完成：语音识别(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): 基于浏览器的界面，适合远程访问或局域网部署。
🚀 快速开始 (Windows 用户)
我们为 Windows 10/11 用户提供了预打包的 .exe 版本，无需配置 Python 环境。
- 下载: 点击下载最新预打包版本
- 解压: 将压缩包解压到一个不包含中文、空格的路径下 (例如
D:\pyVideoTrans)。 - 运行: 双击文件夹内的
sp.exe启动。
注意:
- 请勿直接在压缩包内运行。
- 如需使用 GPU 加速(仅支持英伟达显卡加速)，请确保安装 CUDA 12.8 和 cuDNN 9.11。
️ 源码部署 (macOS / Linux / Windows 开发者)
推荐使用 uv 进行包管理，速度更快且环境隔离更好。
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://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans
uv sync
默认不安装
whisper.net本地渠道，若需要全部安装请执行uv sync --all-extras
- 单独安装
whisper.net：uv sync --extra dotnet
4. 启动软件
启动 GUI 界面:
uv run sp.py
使用 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"
启动 WebUI (适合远程访问或局域网部署):
uv sync --extra webui
uv run webui.py
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
5. (可选) GPU 加速配置(NVIDIA GPU only)
- 如果您拥有 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
支持的渠道与模型 (部分)
| 类别 | 渠道/模型 | 说明 |
|---|---|---|
| 语音识别 (ASR) | Faster-Whisper (本地) | 推荐，速度快，精度高 |
| WhisperX / Parakeet | 支持时间轴对齐与说话人分离 | |
| 阿里 Qwen3-ASR / 字节火山 | 在线 API，中文效果极佳 | |
| 翻译 (LLM/MT) | DeepSeek / ChatGPT | 支持上下文理解，翻译更自然 |
| infistar AI | infistar - 160+ 模型,一个 Key, OpenAI 兼容中转,一个 Key 随时切 160+ 模型 | |
| Atlas Cloud | OpenAI 兼容网关，一个 Key 调用 DeepSeek、GLM、Kimi、Qwen、MiniMax 及代理的闭源模型 | |
| Opper | 欧盟托管的 OpenAI 兼容网关，一个 Key 调用 50+ 家供应商的 700+ 个模型 | |
| Runcrate | GPU 云，兼容 OpenAI 的 API：DeepSeek、GLM、Qwen、Kimi、gpt-oss，用 GitHub 账号即可免费使用开源模型 | |
| MiniMax AI | MiniMax M3 大模型，最新旗舰模型，OpenAI兼容接口 | |
| Google / Microsoft | 传统机器翻译，速度快 | |
| Ollama / M2M100 | 完全本地离线翻译 | |
| 语音合成 (TTS) | Edge-TTS | 微软免费接口，效果自然 |
| F5-TTS / OmniVoice / Qwen3-TTS | 支持 声音克隆 | |
| GPT-SoVITS / ChatTTS / Index-TTS | 高质量开源 TTS,要求本地部署 | |
| 302.AI / OpenAI / Azure | 高质量商业 API |
文档与支持
- 官方文档: https://pyvideotrans.com (包含详细教程、API配置指南、常见问题)
- 在线问答社区: https://bbs.pyvideotrans.com (提交报错日志，AI 自动分析回答)
- GitHub Wiki: 架构说明 | 新增渠道 | CLI 文档 | WebUI 说明 | 音画对齐原理 | 常见问题
️ 免责声明
本软件为开源免费非商业项目，使用者需自行承担因使用本软件（包括但不限于调用第三方 API、处理受版权保护的视频内容）所产生的一切法律后果。请遵守当地法律法规及相关服务商的使用协议。
致谢
本项目主要依赖以下开源项目 (部分)：
- FFmpeg
- PySide6
- sherpa-onnx
- faster-whisper
- openai-whisper
- edge-tts
- F5-TTS
- Confucius4-TTS
- OmniVoice
- CosyVoice
- Gradio (WebUI)
Created by jianchang512