pyvideotrans

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 18,697 Open GitHub ↗

영상의 언어를 다른 언어로 번역하고 더빙 및 자막을 삽입합니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> 스폰서: \*\*[Recall.ai](https://www.recall.ai/product/meeting-transcription-api?utm\_source=github&utm\_medium=sponsorship&utm\_campaign=jianchang512-pyvideotrans) - 미팅 전사(Transcription) API\*\*
>
> 미팅용 전사 API를 찾고 계신다면, Zoom, Google Meet, Microsoft Teams 등과 연동되는 API인 \*\*[Recall.ai](https://www.recall.ai/product/meeting-transcription-api?utm\_source=github&utm\_medium=sponsorship&utm\_campaign=jianchang512-pyvideotrans)\*\*를 확인해 보세요.
---
# pyVideoTrans

\*\* 강력한 오픈소스 동영상 번역 / 오디오 전사 / AI 더빙 / 자막 번역 도구\*\*
[中文](docs/README\_CN.md) | [\*\*문서\*\*](https://pyvideotrans.com) | [\*\*온라인 Q&A\*\*](https://bbs.pyvideotrans.com)
[![License](https://img.shields.io/badge/License-GPL\_v3-blue.svg)](https://raw.githubusercontent.com/jianchang512/pyvideotrans/main/LICENSE) [![Python](https://img.shields.io/badge/Python-3.10%2B-green.svg)](https://www.python.org/) [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

\*\*pyVideoTrans\*\*는 음성 인식, 자막 번역, 다중 역할 더빙, 오디오-비디오 동기화가 포함된 완전한 워크플로우를 제공하여 한 언어의 비디오를 다른 언어로 원활하게 변환하는 데 특화되어 있습니다. 로컬 오프라인 배포와 다양한 주류 온라인 API를 모두 지원합니다.
![image](https://github.com/user-attachments/assets/25d78661-8b73-4f34-a3e5-205c7daba99b)
---
## 핵심 기능
> [기술 아키텍처 및 원칙](docs/architecture.md)
- \*\*완전 자동 비디오 번역\*\*: 원클릭 워크플로우: 음성 인식(ASR) → 자막 번역 → 음성 합성(TTS) → 비디오 합성.
- \*\*오디오 트랜스크립션 / 자막 생성\*\*: 오디오/비를 SRT 자막으로 일괄 변환하며, 서로 다른 역할을 구분하는 \*\*화자 분리(Speaker Diarization)\*\*를 지원합니다.
- \*\*멀티 롤 AI 더빙\*\*: 각 화자에게 서로 다른 AI 더빙 목소리를 할당합니다.
- \*\*음성 복제\*\*: 제로샷 음성 복제를 위해 \*\*F5-TTS, CosyVoice, GPT-SoVITS\*\* 같은 모델을 통합합니다.
- \*\*강력한 모델 지원\*\*:
- \*\*ASR\*\*: Faster-Whisper (로컬), OpenAI Whisper, Alibaba Qwen, ByteDance Volcano, Azure, Google 등.
- \*\*LLM 번역\*\*: DeepSeek, ChatGPT, Claude, Gemini, MiniMax, Ollama (로컬), Alibaba Bailian 등.
- \*\*TTS\*\*: Edge-TTS (무료), OpenAI, Azure, Minimaxi, ChatTTS, ChatterBox 등.
- \*\*대화형 편집\*\*: 정확성을 보장하기 위해 각 단계(인식, 번역, 더빙)에서 일시 중지 및 수동 교정을 지원합니다.
- \*\*유틸리티 툴킷\*\*: 보컬 분리, 비디오/자막 병합, 오디오-비디오 정렬, 트랜스크립트 매칭 등의 부가 도구를 포함합니다.
- \*\*명령줄 인터페이스(CLI)\*\*: 헤드레스(headless) 작동을 지원하여 서버 배포나 일괄 처리에 편리합니다.
- \*\*웹 인터페이스(WebUI)\*\*: 원격 접속이나 내부 네트워크 배포를 위한 브라우저 기반 인터페이스.
---
## 빠른 시작 (Windows 사용자)
Windows 10/11 사용자를 위해 Python 환경 설정이 필요 없는 사전 패키지된 `.exe` 버전을 제공합니다.
1. \*\*다운로드\*\*: [최신 사전 패키지 버전 다운로드 클릭](https://github.com/jianchang512/pyvideotrans/releases)
2. \*\*압축 해제\*\*: 압축파일을 중국어 문자나 공백이 없는 경로(예: `D:\pyVideoTrans`)에 해제합니다.
3. \*\*실행\*\*: 폴더 내부의 `sp.exe`를 더블클릭하여 실행합니다.
> \*\*참고\*\*:
> \* 압축 파일 내부에서 직접 실행하지 마세요.
> \* GPU 가속을 사용하려면 \*\*CUDA 12.8\*\*과 \*\*cuDNN 9.11\*\*이 설치되어 있는지 확인하세요.
---
## 소스 배포 (macOS / Linux / Windows 개발자)
더 빠른 속도와 더 나은 환경 격리를 위해 패키지 관리에 \*\*[`uv`](https://docs.astral.sh/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 다운로드](https://ffmpeg.org/download.html) 후 Path를 설정하거나, `ffmpeg.exe`와 `ffprobe.exe`를 프로젝트 디렉토리에 직접 배치하세요.
### 2. uv 설치 (설치되지 않은 경우)
```bash
# 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. 복제 및 설치
```bash
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans
uv sync
```
> 기본적으로 `whisper.net`과 `WebUI`는 로컬에 설치되지 않습니다.
> - 모든 선택적 채널을 설치하려면: `uv sync --all-extras`
> - whisper.net을 설치하려면: `uv sync --extra dotnet`
> - WebUI를 설치하려면: `uv sync --extra webui`
### 4. 소프트웨어 실행
\*\*GUI\*\*:
```bash
uv run sp.py
```
\*\*CLI\*\*:
```bash
# 비디오 번역
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 문서](docs/cli.md)
\*\*WebUI\*\* (원격/내부 네트워크 접속용):
```bash
uv sync --extra webui
uv run webui.py
```
\*\*Docker\*\* (컨테이너 기반 배포):
```bash
# 빌드
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
```
> [WebUI 문서](docs/webui.md)
### 5. (선택 사항) GPU 가속 설정
NVIDIA 그래픽 카드가 있는 경우, 다음 명령어를 실행하여 CUDA를 지원하는 PyTorch 버전을 설치하세요:
```bash
# 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
```
> [Whisper.NET을 이용한 AMD GPU 가속](docs/whisper\_net\_setup.md)
---
## 지원하는 채널 및 모델 (일부)
| 카테고리 | 채널/모델 | 설명 |
| :--- | :--- | :--- |
| \*\*ASR (음성 인식)\*\* | \*\*Faster-Whisper\*\* (로컬) | 권장, 빠른 속도, 높은 정확도 |
| | WhisperX / Parakeet | 타임스탬프 정렬 및 화자 분리(Diarization) 지원 |
| | Alibaba Qwen3-ASR / ByteDance Volcano | 온라인 API, 중국어에 탁월 |
| \*\*번역 (LLM/MT)\*\* | \*\*DeepSeek\*\* / ChatGPT | 문맥 이해 지원, 더 자연스러운 번역 |
| | MiniMax AI | MiniMax M3 LLM, 최신 플래그십 모델, OpenAI 호환 |
| | Google / Microsoft | 전통적인 기계 번역, 빠른 속도 |
| | Ollama / M2M100 | 완전한 로컬 오프라인 번역 |
| \*\*TTS (음성 합성)\*\* | \*\*Edge-TTS\*\* | Microsoft 무료 인터페이스, 자연스러운 효과 |
| | \*\*F5-TTS / CosyVoice\*\* | \*\*음성 복제(Voice Cloning)\*\* 지원, 로컬 배포 필요 |
| | GPT-SoVITS / ChatTTS | 고품질 오픈소스 TTS |
| | 302.AI / OpenAI / Azure | 고품질 상용 API |
---
## 문서 및 지원
\* \*\*공식 문서\*\*: [https://pyvideotrans.com](https://pyvideotrans.com) (상세 튜토리얼, API 설정 가이드, FAQ 포함)
\* \*\*온라인 Q&A 커뮤니티\*\*: [https://bbs.pyvideotrans.com](https://bbs.pyvideotrans.com) (오류 로그를 제출하면 AI가 자동으로 분석하여 답변)
\* \*\*GitHub Wiki\*\*: [architecture.md](docs/architecture.md) | [cli.md](docs/cli.md) | [webui.md](docs/webui.md) | [Synchronize.md](docs/Synchronize.md) | [faq.md](docs/faq.md)
## 면책 조항
이 소프트웨어는 오픈소스 기반의 무료 비상용 프로젝트입니다. 본 소프트웨어 사용으로 인해 발생하는 법적 책임(타사 API 호출 또는 저작권이 있는 비디오 콘텐츠 처리를 포함하되 이에 국한되지 않음)은 전적으로 사용자에게 있습니다. 현지 법률 및 규정, 관련 서비스 제공업체의 이용 약관을 준수해 주세요.
## 감사의 글
이 프로젝트는 주로 다음 오픈소스 프로젝트들을 기반으로 합니다 (일부):
\* [FFmpeg](https://github.com/FFmpeg/FFmpeg)
\* [PySide6](https://pypi.org/project/PySide6/)
\* [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)
\* [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
\* [openai-whisper](https://github.com/openai/whisper)
\* [edge-tts](https://github.com/rany2/edge-tts)
\* [F5-TTS](https://github.com/SWivid/F5-TTS)
\* [Confucius4-TTS](https://github.com/netease-youdao/Confucius4-TTS)
\* [OmniVoice](https://github.com/k2-fsa/omnivoice)
\* [CosyVoice](https://github.com/FunAudioLLM/CosyVoice)
\* [Gradio](https://www.gradio.app/) (WebUI)
---
\*Created by [

[jianchang512](https://github.com/jianchang512)\*

pyvideotrans

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README