pyvideotrans README

The project's README from github.com/jianchang512/pyvideotrans. As one markdown file: README.md.

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

pyVideoTrans

A Powerful Open Source Video Translation / Audio Transcription / AI Dubbing / Subtitle Translation Tool

中文 | Documentation | Online Q&A

License Python Platform

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.

image

Core Features

Technical Architecture and Principles

Quick Start (Windows Users)

We provide a pre-packaged .exe version for Windows 10/11 users, requiring no Python environment configuration.

  1. Download: Click to download the latest pre-packaged version
  2. Unzip: Extract the compressed file to a path without Chinese characters or spaces (e.g., D:\pyVideoTrans).
  3. Run: Double-click sp.exe inside the folder to launch.

Note:

  • Do not run directly from within the compressed archive.
  • To use GPU acceleration, 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

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.net and WebUI are 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"

CLI documentation with all parameters

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

WebUI documentation

5. (Optional) 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

AMD GPU acceleration via Whisper.NET

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
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 / CosyVoice Supports Voice Cloning, requires local deployment
GPT-SoVITS / ChatTTS High-quality open-source TTS
302.AI / OpenAI / Azure High-quality commercial API

Documentation & Support

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):

Created by jianchang512

pyvideotrans (jianchang512/pyvideotrans)

Searching Database…

19.4K ·GitHub
Pyvideotrans
What is this?An open-source video translation and dubbing tool: it converts a video from one language to another through a one-click pipeline of speech recognition, subtitle translation, TTS dubbing, and video synthesis.
Is it a desktop program, a CLI, or a web service?All three in one package: a desktop GUI built on PySide6, a CLI for headless batch runs, and a browser WebUI for remote access — plus a Docker option for containerized deployment.
How do I get it running?On Windows 10/11, download the pre-packaged .exe — no Python needed — unzip it and double-click sp.exe. On macOS/Linux (or as a developer), install Python 3.10 and FFmpeg, clone the repo, and set it up with uv.
Do I need API keys, or can it work fully offline?Local use needs no keys: Faster-Whisper runs locally, Ollama or M2M100 translate fully offline, and Edge-TTS is free. API keys are only required if you pick online channels like OpenAI, DeepSeek or Azure. Source installs also need FFmpeg in PATH.
Any pitfalls before I install it?The Windows build must be unzipped to a path without Chinese characters or spaces and launched via sp.exe — not from inside the archive. GPU acceleration additionally requires CUDA 12.8 and cuDNN 9.11.
Is it free, and am I allowed to translate copyrighted videos with it?It is GPL-3.0, free and non-commercial. The README warns that you are solely responsible for any legal consequences, including from calling third-party APIs or processing copyrighted video content.
Will it use my NVIDIA or AMD graphics card?Yes — on NVIDIA cards you install the CUDA-enabled PyTorch build (needs CUDA 12.8 + cuDNN 9.11), and AMD GPUs are supported through Whisper.NET.
What can it do besides translating whole videos?It doubles as a media toolkit: batch audio/video to SRT subtitles with speaker diarization, vocal separation, video/subtitle merging, audio-video alignment, and transcript matching.
Which AI models and services can I plug into it?ASR: Faster-Whisper (recommended local), WhisperX, Parakeet, Alibaba Qwen, Azure, Google. Translation: DeepSeek, ChatGPT, Claude, Gemini, Ollama, Google/Microsoft MT. TTS: Edge-TTS, F5-TTS, CosyVoice, GPT-SoVITS, ChatTTS, OpenAI, Azure.
Can I proofread the translation before it dubs it?Yes — the pipeline can pause at each stage (recognition, translation, dubbing) so you can manually proofread and fix things before continuing.
Does it support voice cloning and multi-speaker dubbing?Both: different speakers in a video can get different AI voices, and F5-TTS, CosyVoice or GPT-SoVITS provide zero-shot voice cloning — those cloning models require local deployment.
What are similar projects?voice-pro, VideoLingo, VideoHighlighter, WhisperLiveKit, yovoice, autoshorts, autoclip, OmniVoice
Which topics is it in?dubbing, srt, stt, speaker-diarization, batch-processing, transcription, voice-cloning, speech-synthesis, gradio, whisper, speech-to-text, webui
Creator
jianchang512
Size
488 MB
Stars
19.4K
Updated
CommitOct 15Releasev4.16Oct 13
Age
3y
Commits · 90 Days