Overview
subtitle batch scans a directory for video files and processes them concurrently using a thread pool. It tracks per-file progress in .batch_state.json, lets you resume interrupted runs with --resume, and writes a formatted batch_report.md summary when finished.
subtitle batch --input-dir ./videos --output-dir ./subtitles --model turbo --format srt --workers 4
Batch Options
| Flag | Short | Default | Description |
|---|---|---|---|
--input-dir DIR |
-i |
(required) | Directory containing video files |
--output-dir DIR |
-o |
same as input | Destination directory for subtitle files and report |
--workers N |
-w |
4 |
Number of parallel worker threads |
--threads N |
-t |
4 |
whisper-cli threads per worker |
--processors N |
-p |
1 |
whisper-cli processors per worker |
--model MODEL |
-m |
base |
Whisper model to use |
--format FMT |
-f |
vtt |
Output subtitle format (vtt, srt, txt, json, lrc, csv) |
--language CODE |
-l |
None |
Spoken language code (en, es, auto, etc.) |
--translate |
-tr |
False |
Translate speech to English |
--max-len N |
-ml |
0 |
Maximum cue length in characters |
--split-on-word |
-sow |
False |
Split segments on word boundaries |
--prompt TEXT |
None |
Initial prompt for vocabulary/style | |
--resume |
-r |
False |
Skip files already recorded in .batch_state.json |
--extensions LIST |
-e |
mp4,mkv,avi,mov,webm,m4v,flv,wmv |
Comma-separated file extensions to include |
--whisper-binary PATH |
auto | Override whisper-cli binary path |
|
--models-dir DIR |
cache | Override model cache directory |
Resuming Interrupted Batches
If a long batch run is cancelled (Ctrl+C) or a machine restarts, re-run the same command with --resume:
subtitle batch -i ./course_videos -o ./subs --model small --format srt --resume
- Completed and failed paths are persisted after every file in
<output-dir>/.batch_state.json. - When
--resumeis enabled, previously processed files are skipped automatically. - Once a batch finishes with zero failures,
.batch_state.jsonis cleaned up automatically.
Summary Report
Every batch run writes <output-dir>/batch_report.md containing:
- Timestamp and total duration
- Counts of total, successful, failed, and skipped files
- Per-file table with status, duration, and output filename