burn-subs

Transcribe MP4 videos with Whisper and burn the subtitles into the video. Output is a new MP4 with embedded subtitles (white text, black outline).

Requirements

• Python 3
• ffmpeg — install with your package manager:
  • Arch: sudo pacman -S ffmpeg
  • Ubuntu/Debian: sudo apt install ffmpeg
  • Fedora: sudo dnf install ffmpeg

Install

From the project directory:

./install.sh

This installs burn-subs and its dependencies (PyTorch, Whisper) into ~/.local by default. To use another prefix:

PREFIX=/opt/burn-subs ./install.sh

If ~/.local/bin is not in your PATH, add to ~/.bashrc or ~/.profile:

export PATH="$PATH:$HOME/.local/bin"

Note: The first run will download the Whisper large-v3 model (~3GB).

Use

Single video:

burn-subs input_video.mp4

Output: input_video_subtitled.mp4 in the same directory as the input.

With SRT file:

burn-subs input_video.mp4 --save-srt
# or short form:
burn-subs input_video.mp4 -s

Also outputs input_video_subtitled.srt alongside the video.

Directory (batch):

burn-subs /path/to/videos/

Finds all .mp4 files in that directory, transcribes each, and writes results into a sibling directory named with _transcribed appended: /path/to/videos_transcribed/. Each file becomes {stem}_subtitled.mp4 there. Invalid or non-video files are skipped with a warning.

Use -s or --save-srt to also save SRT files alongside each video.

The script transcribes with Whisper (English), generates SRT subtitles, then burns them into the video with ffmpeg. GPU is used automatically if available; otherwise it runs on CPU (slower). In directory mode the Whisper model is loaded once and reused for all videos.

License

Unlicense — public domain.