A command-line tool for generating and translating subtitles using OpenAI's APIs. Generate accurate subtitles for your videos with Whisper API and translate them to any language with GPT models, all from your terminal.
- Generate Subtitles from video files using OpenAI's Whisper API
- Translate Subtitles to any language using OpenAI's GPT models
- Batch Processing of entire directories of videos or subtitle files
- Parallel Processing for faster generation and translation
- Automatic Retries for handling API transient errors
- Backup Original Subtitles during translation
- Multiple Format Support (SRT, VTT, JSON, TXT)
- Context-Aware Translation preserves dialogue flow and meaning
- Python 3.8 or newer
- An OpenAI API key with access to Whisper and GPT models
pip install git+https://github.com/johnyrose/gen-subtitles.gitgit clone https://github.com/yourusername/gen-subtitles.git
cd gen-subtitles
pip install -e .To use the tool, you need the OPENAI_API_KEY environment variable set. You can set it as an environment variable instead of passing it with each command:
On Linux or MacOS:
export OPENAI_API_KEY=your-api-key-hereOn Windows:
set OPENAI_API_KEY=your-api-key-heregen-subtitles generate video.mp4 -l engen-subtitles translate su
A501
btitles.srt -l fr -o french_subtitles.srtgen-subtitles generate-dir /path/to/videos -l engen-subtitles translate-dir /path/to/subtitles -l esGenerate subtitles for a single video file.
gen-subtitles generate VIDEO -l LANGUAGE [OPTIONS]
Arguments:
VIDEO: Path to the input video file
Required Options:
-l, --language TEXT: Language of the audio (e.g., 'en' for English, 'fr' for French, 'nl' for Dutch)
Options:
-o, --output TEXT: Path to save the output subtitle file (default: filename.srt)-f, --format [srt|vtt|json|txt]: Format of the output subtitle file (default: srt)-k, --api-key TEXT: OpenAI API key (if not set in environment variable)--limit-chars / --no-limit-chars: Limit subtitle segments to a maximum of characters (default: enabled)
Example:
gen-subtitles generate documentary.mp4 -l en -o documentary_subs.srt -f vttGenerate subtitles for all video files in a directory.
gen-subtitles generate-dir DIRECTORY -l LANGUAGE [OPTIONS]
Arguments:
DIRECTORY: Directory containing video files to process
Required Options:
-l, --language TEXT: Language of the audio (e.g., 'en' for English, 'fr' for French, 'nl' for Dutch)
Options:
-e, --extension TEXT: File extension to look for (default: mp4)-od, --output-dir TEXT: Directory to save subtitle files (default: same as videos)-f, --format [srt|vtt|json|txt]: Format of the output subtitle file (default: srt)-k, --api-key TEXT: OpenAI API key (if not set in environment variable)-w, --max-workers INTEGER: Maximum number of videos to process in parallel (default: 5)-r, --max-retries INTEGER: Maximum number of retries for failed videos (default: 3)--limit-chars / --no-limit-chars: Limit subtitle segments to a maximum of characters (default: enabled)
Example:
gen-subtitles generate-dir /path/to/lectures -l fr -e mkv -od /path/to/subtitles -w 8Translate a subtitle file to another language.
gen-subtitles translate INPUT -l LANGUAGE [OPTIONS]
Arguments:
INPUT: Path to the input subtitle file
Required Options:
-l, --language TEXT: Target language code (e.g., 'en' for English, 'fr' for French, 'nl' for Dutch)
Options:
-o, --output TEXT: Path to save the translated subtitle file (default: translated.srt)-k, --keep-original: Keep original subtitles alongside translations (default: disabled)-m, --model TEXT: OpenAI model to use for translation (default: gpt-4o-mini)-c, --context / --no-context: Include surrounding subtitle context for better translations (default: enabled)-api, --api-key TEXT: OpenAI API key (if not set in environment variable)
Example:
gen-subtitles translate english_subtitles.srt -l de -o german_subtitles.srt -k -m gpt-4Translate all subtitle files in a directory.
gen-subtitles translate-dir DIRECTORY -l LANGUAGE [OPTIONS]
Arguments:
DIRECTORY: Directory containing subtitle files to translate
Required Options:
-l, --language TEXT: Target language code (e.g., 'en' for English, 'fr' for French, 'nl' for Dutch)
Options:
-e, --extension TEXT: File extension to look for (default: srt)-od, --output-dir TEXT: Directory to save translated subtitle files (default: same as originals)-k, --keep-original: Keep original subtitles alongside translations (default: disabled)-m, --model TEXT: OpenAI model to use for translation (default: gpt-4o-mini)-c, --context / --no-context: Include surrounding subtitle context for better translations (default: enabled)-api, --api-key TEXT: OpenAI API key (if not set in environment variable)-w, --max-workers INTEGER: Maximum number of files to process in parallel (default: 5)-r, --max-retries INTEGER: Maximum number of retries for failed files (default: 3)
Example:
gen-subtitles translate-dir /path/to/english_subs -l ja -e vtt -od /path/to/japanese_subs -k -w 3Both directory commands (generate-dir and translate-dir) use parallel processing to speed up operations. You can control the degree of parallelism with the -w, --max-workers option.
The tool automatically retries failed API operations to handle transient errors. Configure retries with the -r, --max-retries option.
The tool supports multiple subtitle formats:
- SRT: Standard subtitle format supported by most players
- VTT: Web Video Text Tracks format, used for HTML5 video
- JSON: Machine-readable format with detailed timestamp data
- TXT: Plain text transcription without timing information
When translating subtitles, the tool can consider surrounding subtitles for better context-aware translations. This produces more coherent and natural translations, especially for dialogues and multi-part sentences.
When using the translate-dir command, the tool automatically creates an original_subtitles directory and backs up all original files before processing.
You can set the OpenAI API key as an environment variable instead of passing it with each command:
export OPENAI_API_KEY=your-api-key-here