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
Что это такое?Инструмент с открытым исходным кодом для перевода и озвучивания видео: он переводит видео с одного языка на другой за один клик — распознавание речи, перевод субтитров, озвучка через TTS и сборка итогового видео.
Это десктопная программа, утилита командной строки или веб-сервис?Всё сразу в одном пакете: десктопный интерфейс на PySide6, CLI для пакетной работы без графики и браузерный WebUI для удалённого доступа — плюс вариант с Docker для развёртывания в контейнере.
Как его запустить?На Windows 10/11 скачайте готовый .exe — Python не нужен — распакуйте и дважды щёлкните по sp.exe. На macOS/Linux (или если вы разработчик) установите Python 3.10 и FFmpeg, склонируйте репозиторий и настройте всё через uv.
Нужны ли API-ключи или можно работать полностью офлайн?Для локального использования ключи не нужны: Faster-Whisper работает локально, Ollama или M2M100 переводят полностью офлайн, а Edge-TTS бесплатный. API-ключи понадобятся, только если выберете онлайн-сервисы вроде OpenAI, DeepSeek или Azure. При установке из исходников также нужен FFmpeg в PATH.
Есть ли подводные камни перед установкой?Сборку для Windows нужно распаковать в путь без китайских иероглифов и пробелов и запускать через sp.exe — не изнутри архива. Для ускорения на GPU дополнительно требуются CUDA 12.8 и cuDNN 9.11.
Она бесплатная и можно ли переводить ею видео, защищённые авторским правом?Лицензия — GPL-3.0, использование бесплатное и некоммерческое. В README предупреждают, что всю ответственность за юридические последствия вы несёте сами, в том числе при обращении к сторонним API или обработке видео, защищённого авторским правом.
Он использует мою видеокарту NVIDIA или AMD?Да — на картах NVIDIA нужно установить сборку PyTorch с поддержкой CUDA (нужны CUDA 12.8 + cuDNN 9.11), а видеокарты AMD поддерживаются через Whisper.NET.
Что он умеет, кроме перевода целых видео?Это ещё и набор медиаинструментов: пакетное создание SRT-субтитров из аудио и видео с определением говорящих, разделение вокала, склейка видео и субтитров, синхронизация аудио с видео и сопоставление расшифровок.
Какие модели и сервисы ИМ можно к нему подключить?ASR: Faster-Whisper (рекомендуемый локальный), WhisperX, Parakeet, Alibaba Qwen, Azure, Google. Перевод: DeepSeek, ChatGPT, Claude, Gemini, Ollama, машинный перевод Google/Microsoft. TTS: Edge-TTS, F5-TTS, CosyVoice, GPT-SoVITS, ChatTTS, OpenAI, Azure.
Могу ли я вычитать перевод до того, как он озвучит видео?Да — конвейер может останавливаться на каждом этапе (распознавание, перевод, озвучка), чтобы вы вручную проверили и поправили результат перед продолжением.
Поддерживается ли клонирование голоса и озвучка нескольких говорящих?И то, и другое: разным говорящим в видео можно назначить разные ИИ-голоса, а F5-TTS, CosyVoice или GPT-SoVITS дают клонирование голоса zero-shot — эти модели клонирования требуют локального развёртывания.
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, speech-synthesis, voice-cloning, gradio, whisper, webui, speech-to-text
Creator
jianchang512
Size
488 MB
Stars
19.4K
Updated
CommitOct 15Releasev4.16Oct 13
Age
3y
Commits · 90 Days