YouTube AI Subtitle Streamer

YouTube 영상에 AI 번역 자막을 실시간으로 오버레이하는 도구입니다. A tool for overlaying real-time AI-translated subtitles on YouTube videos.

Google Gemini API를 사용하여 영어 자막을 한국어, 일본어, 중국어 등 다양한 언어로 번역합니다. Uses Google Gemini API to translate English subtitles into Korean, Japanese, Chinese, and other languages.

주요 기능 / Features

자동 자막 추출 / Auto Subtitle Extraction: YouTube 영상에서 자막을 자동으로 추출합니다. Automatically extracts subtitles from YouTube videos.
문장 재조립 / Sentence Reconstruction: 파편화된 자막을 자연스러운 문장 단위로 재조립합니다. Reconstructs fragmented subtitles into natural sentence units.
AI 번역 / AI Translation: Gemini API를 통해 고품질 번역을 제공합니다. Provides high-quality translation via Gemini API.
다국어 지원 / Multi-language Support: 한국어, 일본어, 중국어, 스페인어, 프랑스어, 독일어 지원. Supports Korean, Japanese, Chinese, Spanish, French, and German.
번역 캐싱 / Translation Caching: 번역 결과를 캐싱하여 재사용합니다. Caches translation results for reuse.
중단 재개 / Resume on Interruption: 번역 중단 시 다음 실행에서 자동으로 이어서 진행합니다. Automatically resumes from where it stopped on next run.
mpv 플레이어 연동 / mpv Player Integration: 번역된 자막과 함께 영상을 바로 재생합니다. Plays video with translated subtitles directly.

사전 요구사항 / Prerequisites

Python 3.10 이상 / Python 3.10 or higher
uv 패키지 매니저 / uv package manager
Google Gemini API 키 / Google Gemini API key
mpv 플레이어 (영상 재생용) / mpv player (for video playback)

설치 방법 / Installation

1. uv 패키지 매니저 설치 / Install uv Package Manager

uv는 빠른 Python 패키지 매니저입니다. 다음 명령으로 설치합니다. uv is a fast Python package manager. Install it with the following command.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널을 재시작하세요. Restart your terminal after installation.

설치 확인 / Verify installation:

uv --version

2. 저장소 클론 / Clone Repository

git clone https://github.com/metamath1/aitube-trans-live.git
cd aitube-trans-live

3. Python 의존성 설치 / Install Python Dependencies

uv sync

4. 환경 변수 설정 / Set Environment Variables

.env 파일을 생성하고 API 키와 모델을 설정합니다. Create a .env file and configure the API key and model.

# 필수: Gemini API 키 / Required: Gemini API Key
GEMINI_API_KEY=your_api_key_here

# 선택: 사용할 모델 (기본값: gemini-2.5-flash-lite)
# Optional: Model to use (default: gemini-2.5-flash-lite)
GEMINI_MODEL=gemini-2.5-flash-lite

API 키는 Google AI Studio에서 발급받을 수 있습니다. You can get an API key from Google AI Studio.

사용 가능한 모델 목록은 Gemini Models에서 확인하세요. See available models at Gemini Models.

5. mpv 플레이어 설치 (Windows) / Install mpv Player (Windows)

5-1. mpv 다운로드 / Download mpv

다음 사이트에서 최신 빌드를 다운로드합니다. Download the latest build from the following site.

https://github.com/shinchiro/mpv-winbuild-cmake/releases

예: mpv-i686-20260122-git-6e54aa3.7z

다운로드한 파일을 원하는 폴더에 압축 해제합니다 (예: C:\mpv). Extract the downloaded file to your preferred folder (e.g., C:\mpv).

5-2. yt-dlp 다운로드 / Download yt-dlp

다음 사이트에서 yt-dlp.exe를 다운로드합니다. Download yt-dlp.exe from the following site.

https://github.com/yt-dlp/yt-dlp/releases

다운로드한 yt-dlp.exe를 mpv 폴더에 복사합니다 (예: C:\mpv\yt-dlp.exe). Copy the downloaded yt-dlp.exe to the mpv folder (e.g., C:\mpv\yt-dlp.exe).

5-3. PATH 환경변수 설정 / Set PATH Environment Variable

mpv.exe가 있는 폴더를 시스템 PATH에 추가합니다. Add the folder containing mpv.exe to the system PATH.

Windows 설정 방법 / Windows Setup:

시스템 환경 변수 편집 열기 / Open "Edit the system environment variables"
환경 변수 클릭 / Click "Environment Variables"
Path 선택 후 편집 / Select "Path" and click "Edit"
새로 만들기로 mpv 폴더 경로 추가 / Add mpv folder path (e.g., C:\mpv)
확인 후 터미널 재시작 / Click OK and restart terminal

설치 확인 / Verify installation:

mpv --version

사용법 / Usage

기본 사용법 / Basic Usage

# YouTube 영상 ID 또는 URL 입력
# Enter YouTube video ID or URL
uv run main.py [YOUR VIDEO ID]

타겟 언어 변경 / Change Target Language

# 일본어로 번역 / Translate to Japanese
uv run main.py [YOUR VIDEO ID] -t ja

# 중국어 간체로 번역 / Translate to Simplified Chinese
uv run main.py [YOUR VIDEO ID] -t zh

# 중국어 번체로 번역 / Translate to Traditional Chinese
uv run main.py [YOUR VIDEO ID] -t zh-TW

자막만 생성 (재생 안 함) / Generate Subtitles Only (No Playback)

uv run main.py [YOUR VIDEO ID] --no-play

여러 영상 일괄 처리 / Batch Processing

# 여러 영상 ID를 한번에 지정
# Specify multiple video IDs at once
uv run main.py VIDEO_ID_1 VIDEO_ID_2 VIDEO_ID_3

# 파일에서 영상 목록 읽기 (한 줄에 하나씩, #으로 주석)
# Read video list from file (one per line, # for comments)
uv run main.py --batch videos.txt

번역된 영상 목록 보기 및 재생 / List and Play Translated Videos

# 화살표 키로 영상 선택 후 바로 재생
# Select video with arrow keys and play immediately
uv run main.py --list

캐시 무시하고 재번역 / Re-translate Ignoring Cache

uv run main.py [YOUR VIDEO ID] --force-translate

타이밍 오프셋 조정 / Adjust Timing Offset

# 자막을 0.5초 앞당김 (기본값)
# Shift subtitles 0.5 seconds earlier (default)
uv run main.py [YOUR VIDEO ID] --time-offset -0.5

# 자막을 1초 앞당김
# Shift subtitles 1 second earlier
uv run main.py [YOUR VIDEO ID] --time-offset -1.0

명령줄 옵션 / Command Line Options

옵션 / Option	설명 / Description	기본값 / Default
`urls`	YouTube 영상 URL 또는 Video ID (복수 가능) / YouTube video URL(s) or Video ID(s)	(`--list` 사용 시 생략 가능)
`--list`	번역된 영상 목록 보기 / List all translated videos	`false`
`--batch`	영상 목록 파일 경로 / Path to file containing video URLs/IDs
`-o`, `--output`	출력 자막 파일 경로 / Output subtitle file path	`subtitle.srt`
`-l`, `--language`	원본 자막 언어 코드 / Source subtitle language code	`en`
`-t`, `--target-lang`	번역 타겟 언어 코드 / Target translation language code	`ko`
`--no-play`	재생 없이 자막만 생성 / Generate subtitles without playback	`false`
`--batch-size`	번역 배치 크기 / Translation batch size	`10`
`--time-offset`	자막 시작 시간 오프셋 (초) / Subtitle start time offset (seconds)	`-0.5`
`--force-translate`	모든 캐시 무시하고 처음부터 재처리 / Ignore all caches and re-process from scratch	`false`

지원 언어 / Supported Languages

코드 / Code	언어 / Language
`ko`	한국어 / Korean
`ja`	일본어 / Japanese
`zh`	중국어 간체 / Simplified Chinese
`zh-TW`	중국어 번체 / Traditional Chinese
`es`	스페인어 / Spanish
`fr`	프랑스어 / French
`de`	독일어 / German

새로운 언어를 추가하려면 prompts.json 파일을 편집하세요. To add new languages, edit the prompts.json file.

출력 파일 구조 / Output File Structure

output/
└── {video_id}/
    ├── raw.json              # 원본 자막 데이터 / Raw subtitle data
    ├── merged.json           # 병합된 문장 / Merged sentences
    ├── metadata.json         # 영상 메타데이터 / Video metadata (title, languages)
    ├── translated_ko.json    # 한국어 번역 캐시 / Korean translation cache
    ├── translated_ja.json    # 일본어 번역 캐시 / Japanese translation cache
    └── ko.srt                # 최종 SRT 파일 / Final SRT file

작동 원리 / How It Works

자막 추출 / Subtitle Extraction: youtube-transcript-api를 사용하여 YouTube에서 자막을 추출합니다. Extracts subtitles from YouTube using youtube-transcript-api.
문장 재조립 / Sentence Reconstruction: Variable Window Merging 알고리즘을 사용하여 파편화된 자막을 완전한 문장으로 재조립합니다. Reconstructs fragmented subtitles into complete sentences using Variable Window Merging algorithm.
- 문장 부호 기반 병합 / Punctuation-based merging
- 최대 길이 초과 시 강제 분할 / Force split when exceeding max length
- 짧은 문장 병합 / Short sentence merging
AI 번역 / AI Translation: Gemini API를 사용하여 배치 단위로 번역합니다. Translates in batches using Gemini API.
- 번호 매칭 방식으로 정확한 번역 / Accurate translation with number matching
- 번역 결과 캐싱 / Translation result caching
SRT 생성 및 재생 / SRT Generation & Playback: SRT 파일을 생성하고 mpv 플레이어로 재생합니다. Generates SRT file and plays with mpv player.

문제 해결 / Troubleshooting

"GEMINI_API_KEY not found" 오류 / Error

.env 파일이 프로젝트 루트에 있는지 확인하세요. Make sure the .env file exists in the project root.

echo "GEMINI_API_KEY=your_api_key_here" > .env

"mpv: command not found" 오류 / Error

mpv가 PATH에 올바르게 설정되었는지 확인하세요. Make sure mpv is correctly set in PATH.

mpv --version

라이선스 / License

MIT License

기여 / Contributing

이슈와 풀 리퀘스트를 환영합니다! Issues and pull requests are welcome!

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
assets		assets
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
README.md		README.md
main.py		main.py
prompts.json		prompts.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

YouTube AI Subtitle Streamer

주요 기능 / Features

사전 요구사항 / Prerequisites

설치 방법 / Installation

1. uv 패키지 매니저 설치 / Install uv Package Manager

2. 저장소 클론 / Clone Repository

3. Python 의존성 설치 / Install Python Dependencies

4. 환경 변수 설정 / Set Environment Variables

5. mpv 플레이어 설치 (Windows) / Install mpv Player (Windows)

5-1. mpv 다운로드 / Download mpv

5-2. yt-dlp 다운로드 / Download yt-dlp

5-3. PATH 환경변수 설정 / Set PATH Environment Variable

사용법 / Usage

기본 사용법 / Basic Usage

타겟 언어 변경 / Change Target Language

자막만 생성 (재생 안 함) / Generate Subtitles Only (No Playback)

여러 영상 일괄 처리 / Batch Processing

번역된 영상 목록 보기 및 재생 / List and Play Translated Videos

캐시 무시하고 재번역 / Re-translate Ignoring Cache

타이밍 오프셋 조정 / Adjust Timing Offset

명령줄 옵션 / Command Line Options

지원 언어 / Supported Languages

출력 파일 구조 / Output File Structure

작동 원리 / How It Works

문제 해결 / Troubleshooting

"GEMINI_API_KEY not found" 오류 / Error

"mpv: command not found" 오류 / Error

라이선스 / License

기여 / Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages