Subtitle Generator

Generate subtitles for video/audio files using whisper.cpp.

Install

pip install subtitle-generator
subtitle setup-whisper          # one-time: clones + builds whisper-cli

subtitle setup-whisper needs git, cmake, a C++ compiler, and ffmpeg:

# macOS
xcode-select --install && brew install cmake ffmpeg
# Linux
sudo apt-get install -y build-essential cmake git ffmpeg
# Windows
# Install Git, CMake, VS Build Tools, ffmpeg.

The built binary lands in your per-OS user data dir (e.g. ~/Library/Application Support/subtitle-generator/bin/ on macOS) and is auto-discovered on every subsequent run.

subtitle setup-whisper builds innovatorved/whisper.cpp (develop), which includes -vi for direct video ingestion. If a stock whisper-cli without -vi is used instead, subtitle-generator automatically extracts 16 kHz mono WAV via ffmpeg.

Usage

# VTT (default), output in current directory
subtitle video.mp4

# SRT
subtitle video.mp4 --format srt

# Generate SRT and embed soft subtitles into the video
# Writes ./video.srt and ./video_subtitled.mp4
subtitle video.mp4 --merge --format srt

# Burn (hardcode) subtitles into the video
# Writes ./video.srt and ./video_burned.mp4
subtitle video.mp4 --burn --format srt

# Fast high-accuracy model (large-v3-turbo) or full large-v3
subtitle video.mp4 --model turbo
subtitle video.mp4 --model large

# Specify language or translate to English
subtitle video.mp4 --language es --translate

# Short-form / TikTok / Reels captions (word-boundary splitting)
subtitle video.mp4 --format srt --max-len 16 --split-on-word

# Initial prompt for vocabulary / proper nouns
subtitle video.mp4 --prompt "Whisper.cpp, PyPI, FFmpeg"

# Convert between subtitle formats (vtt, srt, csv, lrc, txt)
subtitle convert video.vtt video.srt

# Custom output directory
subtitle /path/to/video.mp4 --output-dir ~/subs --format srt

Subcommands

Options

Python API

from subtitle_generator.core import SubtitleGenerator, WhisperCppTranscriber
from subtitle_generator.models import ModelManager

generator = SubtitleGenerator(
    transcriber=WhisperCppTranscriber(),
    model_manager=ModelManager(),
)
result = generator.generate(
    input_path="video.mp4",
    model_name="base",
    output_format="srt",
)
print(result.output_path if result.success else result.error)

Links

• Source: https://github.com/innovatorved/subtitle
• Issues: https://github.com/innovatorved/subtitle/issues

License

MIT