subtitle-engine

Generate .srt subtitle files from audio or video files using WhisperX. Optionally generate a caption from the transcript with a local Ollama LLM.

Installation

Requires Python 3.12 or newer.

pip install subtitle-engine

Or install from source:

git clone https://github.com/leevipuntanen/subtitle-engine.git
cd subtitle-engine
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

# Basic usage — writes <input>.srt next to the source file
subeng video.mp4

# Specify output file
subeng video.mp4 --output subtitles.srt

# Use a different model or language
subeng video.mp4 --model medium --language fi

# Force CPU / CUDA
subeng video.mp4 --device cpu

# Speaker diarization (requires a Hugging Face token)
subeng video.mp4 --diarize --hf-token $HF_TOKEN

# Generate a caption from the transcript using Ollama
subeng video.mp4 --caption --ollama-model qwen3.5:0.6b

# Generate a caption from an existing SRT file
subeng caption subtitles.srt

# Short-form subtitles (2-5 words per line, default)
subeng video.mp4 --preset shortform

# Long-form subtitles (10-14 words per line)
subeng video.mp4 --preset longform

Subtitle quality

The segmenter applies several quality passes by default. Each can be turned off or tuned via a CLI flag.

The sentence splitter now considers context before splitting, so a mid-thought period like I found a bug. reports say... stays in the same subtitle (no capital, no pause, no speaker change → no split). To get the old aggressive behavior back, set --sentence-pause-threshold 0.

Disable every quality pass to reproduce the legacy behavior:

subeng video.mp4 \
  --no-cleanup \
  --no-clause-boundaries \
  --no-sentence-split \
  --no-line-balance \
  --no-cps-limit \
  --no-min-duration

Options

Development

Run the test suite:

pytest

License

MIT