"Could not find the whisper-cli binary"
Run the one-time setup command to compile and install whisper-cli into your user data directory:
subtitle setup-whisper
Make sure git, cmake, a C++ compiler, and ffmpeg are on your PATH:
# macOS
xcode-select --install && brew install cmake ffmpeg
# Linux (Debian / Ubuntu)
sudo apt-get install -y build-essential cmake git ffmpeg
If you already have a whisper-cli binary elsewhere, point to it explicitly:
export SUBTITLE_WHISPER_BINARY=/path/to/whisper-cli
# or per command:
subtitle video.mp4 --whisper-binary /path/to/whisper-cli
Slow Transcription or High CPU Usage
- Use a smaller or quantized model:
--model tiny,--model base.en, or--model large-v3-turbo-q5_0 - Tune thread count:
--threads 8(for single files) - For batch jobs, balance workers and threads:
subtitle batch -i ./videos --workers 2 --threads 4 - For English-only audio, prefer
.enmodels (base.en,small.en) for faster, more accurate output
Out of Memory on Large Videos
Switch to a smaller/quantized model (--model small-q5_1 or --model large-v3-turbo-q5_0), or split very long recordings into chunks with FFmpeg:
ffmpeg -i large_video.mp4 -t 00:30:00 -c copy part1.mp4
Model Download Fails
Downloads retry automatically with exponential backoff and write atomically to .part files so interrupted downloads never leave corrupt models behind. To test a download directly:
subtitle models --download tiny
You can also download any ggml-*.bin file manually from ggerganov/whisper.cpp on Hugging Face and drop it into your models cache directory (printed at the top of subtitle models --list).
Still Stuck?
Open an issue at github.com/innovatorved/subtitle/issues with your OS, Python version, and the output of subtitle video.mp4 --verbose.