What is Subtitle CLI?
Subtitle CLI (subtitle-generator) is a lightweight, modular command-line tool and Python library that wraps whisper.cpp (custom fork with native video input) to transcribe local media files, URLs, and entire folders into clean subtitles — completely offline on your own machine.
Install it via pip, run subtitle setup-whisper once, and generate VTT, SRT, TXT, JSON, LRC, or CSV subtitles from any video or audio file in seconds.
Core Capabilities
One-Command Transcription
Point subtitle at any video, audio file, HTTP/HTTPS URL, or Google Drive link. Original media files are never modified.
Soft Mux & Hard Burn
Embed selectable subtitle tracks (--merge) with automatic container codec detection, or hardcode subtitles (--burn) while preserving the original audio stream.
Parallel Batch Processing
Process entire directories concurrently with configurable --workers, --threads, --resume state recovery, and Markdown summary reports.
Modular Python SDK
Plug SubtitleGenerator, WhisperCppTranscriber, BatchProcessor, VideoProcessor, ModelManager, and SubtitleFormatterFactory directly into your own apps.
Architecture
Subtitle CLI separates CLI orchestration, model caching, transcription strategies, FFmpeg video operations, and subtitle formatters into clean, independently testable modules.
CLI (`subtitle ...`) or Python SDK (`subtitle_generator`)
│
├── ModelManager → Downloads & caches GGML models in per-OS cache dir
├── Downloader → Fetches HTTP(S) & Google Drive media into temp storage
├── WhisperCppTranscriber → Invokes `whisper-cli` (-vi native or FFmpeg WAV fallback)
├── VideoProcessor → Soft-muxes (--merge) or hard-burns (--burn) via FFmpeg
├── BatchProcessor → ThreadPoolExecutor + .batch_state.json + batch_report.md
└── Formatters → Parse & convert VTT, SRT, CSV, LRC, and TXT
Quick Links
Getting Started
Install subtitle-generator, build whisper-cli once on macOS, Linux, or Windows, and generate your first subtitle.
CLI Reference
Complete reference for every command, flag, short-form caption option, and translation workflow.
Batch Processing
Transcribe directories in parallel with worker tuning, resume support, and Markdown reports.
Python API
Embed subtitle generation, format conversion, and custom strategies in Python.
Stack
| Layer | Technology |
|---|---|
| Runtime | Python 3.9+ |
| Engine | whisper.cpp (whisper-cli compiled via subtitle setup-whisper) |
| Video / Audio | FFmpeg (ffmpeg-python) |
| Models | GGML Whisper models (tiny, base, small, medium, large-v3, turbo, quantized) |
| Formats | vtt, srt, txt, json, lrc, csv |
| Distribution | PyPI (pip install subtitle-generator) |
| License | MIT |