Skip to content

README.md

Latest commit

 

History

History
executable file
·
99 lines (69 loc) · 3.25 KB

README.md

File metadata and controls

executable file
·
99 lines (69 loc) · 3.25 KB
Raw

WhisperX Bulk SRT CLI

Interactive Windows-friendly CLI for generating .srt subtitles with WhisperX.

What It Does

  • Accepts one file or one folder path
  • Recursively scans folders for common audio and video files
  • Uses WhisperX with the turbo model
  • Auto-detects spoken language by default, with an optional manual override
  • Writes .srt subtitles next to each source file
  • Formats subtitles into shorter TV-style cues with up to 2 lines per cue
  • Skips files that already have a sibling .srt

Why custom subtitle formatting

WhisperX's default .srt writer emits long, dense cues that are hard to read on screen. Instead of using that writer, this tool takes WhisperX's word-level timings and re-segments them into shorter, TV-style cues: at most 2 lines, up to 42 characters per line, targeting roughly 2.8 s per cue, with breaks preferred at sentence/clause boundaries and natural speech pauses.

The target style is benchmarked against ElevenLabs subtitle output, which reads far better than the raw WhisperX cues. The regression test test_sample_comparison_reduces_long_cues_and_moves_toward_target_style measures generated cues against two fixtures in samples/: a long-cue baseline (the "before") and an ElevenLabs export (the target). It asserts the output moves toward the ElevenLabs metrics — shorter average duration, fewer cues over 5 s, and tighter line width — and away from the baseline.

Prerequisites

  • Python 3.10-3.13
  • whisperx installed in the same Python environment
  • ffmpeg available on your PATH
  • A CUDA-capable PyTorch install and NVIDIA GPU

This repo is now GPU-only. The script exits immediately if torch.cuda.is_available() is False.

Setup

Install WhisperX:

pip install whisperx

Install ffmpeg on Windows with one of these:

winget install --id Gyan.FFmpeg --exact --accept-package-agreements --accept-source-agreements

Install the CUDA-enabled PyTorch wheels used by this setup:

python -m pip install --upgrade --force-reinstall torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

Optional checks:

python -c "import whisperx; print('whisperx ok')"
ffmpeg -version
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'n/a')"

If torch.cuda.is_available() prints False, this CLI will not run.

Run

python .\whisperx_subtitles.py

The script will ask for:

  1. A file or folder path
  2. An optional audio language override such as en, de, or et

Then it shows a short run summary and starts generating .srt files. After processing finishes, it keeps the final stats on screen until you press Enter.

Supported Input Types

.aac, .avi, .flac, .m4a, .mkv, .mov, .mp3, .mp4, .ogg, .wav, .webm

Notes

  • Model used in the UI: turbo (optimized large-v3)
  • Internal WhisperX model id: turbo
  • Output format: .srt only
  • Subtitle formatting target: shorter readable cues, 2 lines max, 42 characters per line
  • Existing .srt files are never overwritten in v1
  • GPU-only: CPU fallback is disabled on purpose