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

# Burn subtitles into the video (requires ffmpeg on PATH)
subeng video.mp4 --burn

# Burn with a custom .ass style file
subeng video.mp4 --burn --style-file my-style.ass

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

Burning subtitles

Pass --burn to also re-encode the input video with the generated SRT rasterized into the frames (hardsub). The result is written next to the original as <input>.subtitled.<ext>; the source file is never modified.

subeng video.mp4 --burn

Burn requires ffmpeg on your PATH. Audio is stream-copied where possible, so only the video is re-encoded. To apply custom styling, point --style-file at an .ass file; the first Style: line is converted to ffmpeg's force_style argument:

subeng video.mp4 --burn --style-file my-style.ass

If the burn step fails (missing ffmpeg, no video stream, ffmpeg error), the SRT that was already written is kept on disk and its path is shown in the error message.

Options

Development

Run the test suite:

pytest

License

MIT