Skip to content
Subtitle CLI
Navigation
Subtitle CLI

Subtitle CLI

Generate, convert, embed, and burn accurate subtitles for any video or audio file locally using whisper.cpp. Zero cloud lock-in, modular Python API, and parallel batch processing.

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


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