Video Subtitle Generator

Multilingual video subtitle generation and translation toolkit built on WhisperX.

Features

• - Speech transcription: Extract audio from video and transcribe it into subtitles with automatic source language detection
• Multilingual translation: Translate subtitles from any source language into a configurable target language
• Bilingual subtitles: Generate source + target bilingual subtitles

Prerequisites

• - Python 3.9+
• ffmpeg (required by WhisperX for audio extraction)

CODEBLOCK0

Resource requirements

Before running, confirm the user is aware of the following costs:

Always confirm with the user before installing packages or downloading models, as these operations consume storage and bandwidth.

Translation requires an LLM API and will incur costs. Before executing the translation step:

1. 1. Ask the user for the API provider, key, and base URL — or present any auto-discovered configuration for review
2. Inform the user that translation calls a remote LLM and will consume tokens (i.e. real money)
3. Do NOT proceed with translation until the user explicitly confirms the provider and acknowledges the cost

Usage

1. Environment setup

CODEBLOCK1

On Windows, use python instead of python3 in all commands below.

2. Transcribe video (auto-detect language)

CODEBLOCK2

Output: video.{detected_lang}.srt (e.g. video.en.srt, video.ja.srt)

Arguments:

• - -o: Output directory
• INLINECODE8: Model size (tiny, base, small, medium, large)
• INLINECODE14: Device (cuda, cpu, mps), auto-detected by default
• INLINECODE18: Force source language code (e.g. en, ja, zh). Auto-detect if omitted

3. Batch-process a directory

CODEBLOCK3

4. Translate subtitles

Cost warning: This step calls a remote LLM API. Ensure the user has confirmed the API provider, key, and billing awareness before running.

CODEBLOCK4

Arguments:

• - -t, --target-lang: Target language code (default: zh)
• INLINECODE25: Generate bilingual (source + target) subtitles
• INLINECODE26: Generate target-language-only subtitles
• INLINECODE27: Translation model (default: google/gemini-3-flash-preview)
• INLINECODE29: Batch size (default: 10)

When neither --bilingual nor --target-only is specified, both are generated.

5. Run the full pipeline

CODEBLOCK5

Environment variables for run.py:

• - VIDEO_DIR: Video source directory (default: ./videos)
• INLINECODE36: Transcription output directory (default: ./output)
• INLINECODE38: Translation output directory (default: ./translated)
• INLINECODE40: Target language code (default: zh)
• INLINECODE42: Whisper model size (default: medium)

Model selection

Output files

For each video, the tool generates:

• - *.{lang}.srt - Source-language subtitles (language auto-detected, e.g. video.en.srt)
• INLINECODE46 - Full transcription data with timestamps
• INLINECODE47 - Bilingual subtitles (source + target) after translation
• INLINECODE48 - Target-language-only subtitles after translation (e.g. video.zh.srt)

Script overview

scripts/transcribe.py

Uses WhisperX for transcription and supports:

• - Automatic source language detection (or manual override via -l)
• Timestamp alignment
• Batch processing with model reuse across files

scripts/translate.py

Uses an LLM API to translate subtitles and supports:

• - Configurable target language (-t)
• Batch translation for better efficiency
• Bilingual or target-language-only output
• Custom models and API endpoints
• Automatic retry with exponential backoff on API failures

scripts/run.py

Cross-platform one-command runner that executes the transcription and translation pipeline automatically.
Paths, target language, and model size are configurable via environment variables.