subtitle-generator 3.2.0__tar.gz → 3.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/CHANGELOG.md +20 -0
  2. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/MANIFEST.in +2 -0
  3. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/PKG-INFO +9 -10
  4. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/README.md +8 -0
  5. subtitle_generator-3.2.1/docs/src/content/batch-processing.md +63 -0
  6. subtitle_generator-3.2.1/docs/src/content/cli-reference.md +118 -0
  7. subtitle_generator-3.2.1/docs/src/content/contributing.md +74 -0
  8. subtitle_generator-3.2.1/docs/src/content/formats.md +74 -0
  9. subtitle_generator-3.2.1/docs/src/content/getting-started.md +108 -0
  10. subtitle_generator-3.2.1/docs/src/content/index.md +83 -0
  11. subtitle_generator-3.2.1/docs/src/content/models.md +60 -0
  12. subtitle_generator-3.2.1/docs/src/content/python-api.md +163 -0
  13. subtitle_generator-3.2.1/docs/src/content/troubleshooting.md +71 -0
  14. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/environment.yml +3 -3
  15. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/pyproject.toml +11 -11
  16. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/requirements.txt +4 -4
  17. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/__init__.py +1 -1
  18. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/cli/commands.py +86 -10
  19. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/batch_processor.py +14 -2
  20. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/transcriber.py +5 -1
  21. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/video_processor.py +56 -19
  22. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/models/model_manager.py +30 -20
  23. subtitle_generator-3.2.1/subtitle_generator/utils/downloader.py +223 -0
  24. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/formatters.py +19 -11
  25. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator.egg-info/SOURCES.txt +9 -0
  26. subtitle_generator-3.2.0/subtitle_generator/utils/downloader.py +0 -190
  27. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/CONTRIBUTING.md +0 -0
  28. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/LICENSE +0 -0
  29. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/PYPI_README.md +0 -0
  30. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/docs/API.md +0 -0
  31. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/docs/TROUBLESHOOTING.md +0 -0
  32. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/setup.cfg +0 -0
  33. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/setup.py +0 -0
  34. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/cli/__init__.py +0 -0
  35. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/__init__.py +0 -0
  36. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/subtitle_gen.py +0 -0
  37. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/models/__init__.py +0 -0
  38. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/__init__.py +0 -0
  39. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/exceptions.py +0 -0
  40. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/file_handler.py +0 -0
  41. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/paths.py +0 -0
  42. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/validators.py +0 -0
  43. {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/whisper_setup.py +0 -0
@@ -3,6 +3,26 @@
3
3
  All notable changes follow [Keep a Changelog](https://keepachangelog.com/) and
4
4
  [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## [3.2.1] - 2026-11-21
7
+
8
+ ### Added
9
+ - Online documentation site at [subtitle.vedgupta.in](https://subtitle.vedgupta.in) built with Vite + Tailwind CSS v4 and auto-deployed via Cloudflare Pages.
10
+ - `--threads` / `-t` and `--processors` / `-p` options on `subtitle batch` and `BatchProcessor`.
11
+ - Automatic Google Drive URL detection in `download_file()` (routes `drive.google.com` links to `gdown`) and `output_dir` support.
12
+
13
+ ### Fixed
14
+ - `VideoProcessor.burn_subtitles()` now preserves the original audio stream (`acodec="copy"`) when burning hardcoded subtitles instead of dropping audio, and escapes `[` / `]` in subtitle paths.
15
+ - `VideoProcessor` now captures FFmpeg stdout/stderr so errors surface clean stderr diagnostics.
16
+ - `WhisperCppTranscriber` now extracts 16 kHz mono WAV via FFmpeg for non-WAV audio formats (e.g. `.m4a`, `.aac`, `.wma`) when using stock `whisper-cli` binaries without `-vi`.
17
+ - `ModelManager` now serializes model downloads with a thread lock (preventing `.part` races in parallel batch jobs) and fixes `tqdm` progress bar overshoot.
18
+ - `VTTFormatter` and `SRTFormatter` now handle Windows CRLF (`\r\n`) line endings, UTF-8 BOM headers, `MM:SS.mmm` WebVTT timestamps, and integer-millisecond timestamp rounding.
19
+ - `TXTFormatter.format([])` now returns `""` instead of `"\n"`.
20
+ - Moved `logging.basicConfig()` out of module import time into CLI `main()` so library callers' logging is never modified.
21
+ - Made `--merge` and `--burn` mutually exclusive in the CLI, cleaned up temporary downloaded URL media automatically, and added `--help` support to `subtitle formats`.
22
+
23
+ ### Changed
24
+ - Updated dependencies to latest versions (`tqdm>=4.70.1`, `gdown>=6.5.2`, `setuptools>=84.0`, `wheel>=0.48.0`, dev tools) and modernized PEP 639 SPDX license metadata in `pyproject.toml`.
25
+
6
26
  ## [3.2.0] - 2026-10-23
7
27
 
8
28
  ### Added
@@ -9,6 +9,8 @@ include environment.yml
9
9
 
10
10
  # Include documentation
11
11
  recursive-include docs *.md
12
+ prune docs/node_modules
13
+ prune docs/dist
12
14
 
13
15
  # Exclude development and build artifacts
14
16
  exclude .env
@@ -1,12 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: subtitle-generator
3
- Version: 3.2.0
3
+ Version: 3.2.1
4
4
  Summary: AI-powered subtitle generation from video/audio using Whisper.
5
5
  Author-email: Ved Gupta <vedgupta@protonmail.com>
6
6
  Maintainer-email: Ved Gupta <vedgupta@protonmail.com>
7
- License: MIT
7
+ License-Expression: MIT
8
8
  Project-URL: Homepage, https://github.com/innovatorved/subtitle
9
- Project-URL: Documentation, https://github.com/innovatorved/subtitle#readme
9
+ Project-URL: Documentation, https://subtitle.vedgupta.in
10
10
  Project-URL: Repository, https://github.com/innovatorved/subtitle.git
11
11
  Project-URL: Issues, https://github.com/innovatorved/subtitle/issues
12
12
  Project-URL: Changelog, https://github.com/innovatorved/subtitle/releases
@@ -14,7 +14,6 @@ Keywords: subtitle,transcription,whisper,whisper.cpp,ai,speech-to-text,video,aud
14
14
  Classifier: Development Status :: 4 - Beta
15
15
  Classifier: Intended Audience :: Developers
16
16
  Classifier: Intended Audience :: End Users/Desktop
17
- Classifier: License :: OSI Approved :: MIT License
18
17
  Classifier: Operating System :: OS Independent
19
18
  Classifier: Programming Language :: Python :: 3
20
19
  Classifier: Programming Language :: Python :: 3.9
@@ -29,13 +28,13 @@ Requires-Python: >=3.9
29
28
  Description-Content-Type: text/markdown
30
29
  License-File: LICENSE
31
30
  Requires-Dist: ffmpeg-python>=0.2.0
32
- Requires-Dist: tqdm>=4.67.0
33
- Requires-Dist: gdown>=5.2.0
31
+ Requires-Dist: tqdm>=4.70.1
32
+ Requires-Dist: gdown>=6.5.2
34
33
  Provides-Extra: dev
35
- Requires-Dist: pytest>=8.3.0; extra == "dev"
36
- Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
37
- Requires-Dist: build>=1.2.0; extra == "dev"
38
- Requires-Dist: twine>=6.0.0; extra == "dev"
34
+ Requires-Dist: pytest>=9.2.0; extra == "dev"
35
+ Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
36
+ Requires-Dist: build>=1.6.1; extra == "dev"
37
+ Requires-Dist: twine>=7.0.0; extra == "dev"
39
38
  Dynamic: license-file
40
39
 
41
40
  # Subtitle Generator
@@ -6,6 +6,14 @@
6
6
 
7
7
  Generate subtitles for video/audio files using `whisper.cpp`.
8
8
 
9
+ ## Documentation
10
+
11
+ Documentation is live at **[subtitle.vedgupta.in](https://subtitle.vedgupta.in)** and lives in the `docs/` directory (Vite + Tailwind CSS v4). Run it locally with Bun:
12
+
13
+ ```bash
14
+ cd docs && bun install && bun run dev
15
+ ```
16
+
9
17
  ## Install
10
18
 
11
19
  ```bash
@@ -0,0 +1,63 @@
1
+ ---
2
+ title: Batch Processing
3
+ description: Transcribe entire directories of videos in parallel with resume capability and Markdown summary reports.
4
+ ---
5
+
6
+ ## Overview
7
+
8
+ `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.
9
+
10
+ ```bash
11
+ subtitle batch --input-dir ./videos --output-dir ./subtitles --model turbo --format srt --workers 4
12
+ ```
13
+
14
+ ---
15
+
16
+ ## Batch Options
17
+
18
+ | Flag | Short | Default | Description |
19
+ |------|-------|---------|-------------|
20
+ | `--input-dir DIR` | `-i` | *(required)* | Directory containing video files |
21
+ | `--output-dir DIR` | `-o` | same as input | Destination directory for subtitle files and report |
22
+ | `--workers N` | `-w` | `4` | Number of parallel worker threads |
23
+ | `--threads N` | `-t` | `4` | `whisper-cli` threads per worker |
24
+ | `--processors N` | `-p` | `1` | `whisper-cli` processors per worker |
25
+ | `--model MODEL` | `-m` | `base` | Whisper model to use |
26
+ | `--format FMT` | `-f` | `vtt` | Output subtitle format (`vtt`, `srt`, `txt`, `json`, `lrc`, `csv`) |
27
+ | `--language CODE` | `-l` | `None` | Spoken language code (`en`, `es`, `auto`, etc.) |
28
+ | `--translate` | `-tr` | `False` | Translate speech to English |
29
+ | `--max-len N` | `-ml` | `0` | Maximum cue length in characters |
30
+ | `--split-on-word` | `-sow` | `False` | Split segments on word boundaries |
31
+ | `--prompt TEXT` | | `None` | Initial prompt for vocabulary/style |
32
+ | `--resume` | `-r` | `False` | Skip files already recorded in `.batch_state.json` |
33
+ | `--extensions LIST` | `-e` | `mp4,mkv,avi,mov,webm,m4v,flv,wmv` | Comma-separated file extensions to include |
34
+ | `--whisper-binary PATH` | | auto | Override `whisper-cli` binary path |
35
+ | `--models-dir DIR` | | cache | Override model cache directory |
36
+
37
+ <Aside type="tip">
38
+ To avoid oversubscribing CPU cores during parallel runs, balance `--workers` and `--threads` so `workers × threads ≈ CPU cores`. For example, on an 8-core machine use `--workers 2 --threads 4` or `--workers 4 --threads 2`.
39
+ </Aside>
40
+
41
+ ---
42
+
43
+ ## Resuming Interrupted Batches
44
+
45
+ If a long batch run is cancelled (`Ctrl+C`) or a machine restarts, re-run the same command with `--resume`:
46
+
47
+ ```bash
48
+ subtitle batch -i ./course_videos -o ./subs --model small --format srt --resume
49
+ ```
50
+
51
+ - Completed and failed paths are persisted after every file in `<output-dir>/.batch_state.json`.
52
+ - When `--resume` is enabled, previously processed files are skipped automatically.
53
+ - Once a batch finishes with zero failures, `.batch_state.json` is cleaned up automatically.
54
+
55
+ ---
56
+
57
+ ## Summary Report
58
+
59
+ Every batch run writes `<output-dir>/batch_report.md` containing:
60
+
61
+ - Timestamp and total duration
62
+ - Counts of total, successful, failed, and skipped files
63
+ - Per-file table with status, duration, and output filename
@@ -0,0 +1,118 @@
1
+ ---
2
+ title: CLI Reference
3
+ description: Complete command-line reference for subtitle generation, embedding, burning, format conversion, model management, and batch processing.
4
+ ---
5
+
6
+ ## Commands Overview
7
+
8
+ | Command | Description |
9
+ |---------|-------------|
10
+ | `subtitle <media>` | Transcribe a local video/audio file or URL and write subtitles |
11
+ | `subtitle <media> --merge` | Transcribe and embed selectable soft subtitles into a copy of the video |
12
+ | `subtitle <media> --burn` | Transcribe and burn hardcoded subtitles into a copy of the video |
13
+ | `subtitle batch --input-dir <dir>` | Process all media files in a directory in parallel |
14
+ | `subtitle convert <in> [out]` | Convert existing subtitle files between `vtt`, `srt`, `csv`, `lrc`, and `txt` |
15
+ | `subtitle models --list` | List all available models and show which are downloaded |
16
+ | `subtitle models --download <name>` | Pre-download a specific GGML model |
17
+ | `subtitle formats` | Display supported subtitle output formats |
18
+ | `subtitle setup-whisper` | One-time build and install of `whisper-cli` |
19
+
20
+ ---
21
+
22
+ ## Transcribe (`subtitle <media>`)
23
+
24
+ Transcribe a local file (`mp4`, `mkv`, `avi`, `mov`, `webm`, `mp3`, `wav`, `flac`, `m4a`, `ogg`, etc.) or an HTTP(S) / Google Drive URL.
25
+
26
+ ```bash
27
+ subtitle video.mp4 [OPTIONS]
28
+ ```
29
+
30
+ ### Options
31
+
32
+ | Flag | Short | Default | Description |
33
+ |------|-------|---------|-------------|
34
+ | `--model MODEL` | `-m` | `base` | GGML Whisper model name (e.g. `tiny`, `base`, `small`, `turbo`, `large-v3`) |
35
+ | `--format FMT` | `-f` | `vtt` | Output format: `vtt`, `srt`, `txt`, `json`, `lrc`, `csv` |
36
+ | `--language CODE` | `-l` | `None` | Spoken language code (`en`, `es`, `fr`, `hi`, `auto`, etc.) |
37
+ | `--translate` | `-tr` | `False` | Translate spoken audio from source language to English |
38
+ | `--max-len N` | `-ml` | `0` | Maximum characters per subtitle cue (`0` = unlimited) |
39
+ | `--split-on-word` | `-sow` | `False` | Split segments on word boundaries (recommended with `--max-len`) |
40
+ | `--prompt TEXT` | | `None` | Initial prompt to guide domain terms, names, or punctuation |
41
+ | `--merge` | | `False` | Mux soft subtitles into `<name>_subtitled.<ext>` (mutually exclusive with `--burn`) |
42
+ | `--burn` | | `False` | Hardcode subtitles into `<name>_burned.<ext>` (mutually exclusive with `--merge`) |
43
+ | `--output-dir DIR` | `-o` | CWD | Directory where output files are written |
44
+ | `--threads N` | `-t` | `4` | Number of CPU threads for `whisper-cli` |
45
+ | `--processors N` | `-p` | `1` | Number of processors for `whisper-cli` |
46
+ | `--whisper-binary PATH` | | auto | Override the auto-discovered `whisper-cli` binary |
47
+ | `--models-dir DIR` | | cache | Override the GGML model cache directory |
48
+ | `--verbose` | `-v` | `False` | Enable debug logging and detailed progress output |
49
+ | `--version` | `-V` | | Print installed version and exit |
50
+
51
+ ### Common Recipes
52
+
53
+ ```bash
54
+ # Short-form / Reels / TikTok captions (max 16 chars, word-boundary split)
55
+ subtitle reel.mp4 --format srt --max-len 16 --split-on-word
56
+
57
+ # Translate Spanish speech to English SRT
58
+ subtitle entrevista.mp4 --language es --translate --format srt
59
+
60
+ # Guide proper nouns and technical jargon
61
+ subtitle talk.mp4 --model turbo --prompt "Whisper.cpp, FFmpeg, PyPI, Kubernetes"
62
+
63
+ # Transcribe directly from a URL into ~/subs
64
+ subtitle "https://example.com/lecture.mp4" --format vtt --output-dir ~/subs
65
+ ```
66
+
67
+ ---
68
+
69
+ ## Models (`subtitle models`)
70
+
71
+ ```bash
72
+ subtitle models --list
73
+ subtitle models --download turbo
74
+ subtitle models --download small.en --models-dir ./my-models
75
+ ```
76
+
77
+ | Flag | Short | Description |
78
+ |------|-------|-------------|
79
+ | `--list` | `-l` | Show cache directory, all models, and `[x]` markers for downloaded ones |
80
+ | `--download MODEL` | `-d` | Download a model immediately with retry and atomic replacement |
81
+ | `--models-dir DIR` | | Custom cache directory |
82
+
83
+ ---
84
+
85
+ ## Convert (`subtitle convert`)
86
+
87
+ Convert existing subtitle files between `vtt`, `srt`, `csv`, `lrc`, and `txt`:
88
+
89
+ ```bash
90
+ subtitle convert video.vtt video.srt
91
+ subtitle convert video.vtt --format srt
92
+ subtitle convert video.srt --format txt
93
+ subtitle convert transcript.raw out.vtt --source-format srt
94
+ ```
95
+
96
+ | Argument / Flag | Description |
97
+ |-----------------|-------------|
98
+ | `input_path` | Path to the source subtitle file |
99
+ | `output_path` | Optional destination file path (inferred from `--format` if omitted) |
100
+ | `--format`, `-f` | Target format (`vtt`, `srt`, `csv`, `lrc`, `txt`) |
101
+ | `--source-format` | Explicit source format when the input extension is non-standard |
102
+
103
+ ---
104
+
105
+ ## Setup Whisper (`subtitle setup-whisper`)
106
+
107
+ ```bash
108
+ subtitle setup-whisper
109
+ subtitle setup-whisper --force
110
+ subtitle setup-whisper --ref develop --no-pull
111
+ ```
112
+
113
+ | Flag | Description |
114
+ |------|-------------|
115
+ | `--repo URL` | Override the default `whisper.cpp` fork URL |
116
+ | `--ref REF` | Git branch, tag, or commit to build (default: `develop`) |
117
+ | `--force` | Wipe and re-clone the source checkout before building |
118
+ | `--no-pull` | Skip `git fetch`/`pull` for offline rebuilds |
@@ -0,0 +1,74 @@
1
+ ---
2
+ title: Contributing
3
+ description: Local development setup, running the test suite, building distributions, and contributing to Subtitle CLI.
4
+ ---
5
+
6
+ ## Development Setup
7
+
8
+ ```bash
9
+ git clone https://github.com/innovatorved/subtitle.git
10
+ cd subtitle
11
+
12
+ # Install package and dev dependencies in editable mode
13
+ pip install -e ".[dev]"
14
+
15
+ # One-time build of whisper-cli (optional for unit tests, required for live transcription)
16
+ subtitle setup-whisper
17
+ ```
18
+
19
+ ---
20
+
21
+ ## Running Tests
22
+
23
+ The test suite uses `pytest` and runs in under a second with no network or binary required:
24
+
25
+ ```bash
26
+ pytest -v
27
+ pytest --cov=subtitle_generator tests/unit/
28
+ ```
29
+
30
+ ---
31
+
32
+ ## Building the Package
33
+
34
+ Verify sdist and wheel builds cleanly with `build` and `twine`:
35
+
36
+ ```bash
37
+ python -m build
38
+ python -m twine check dist/*
39
+ ```
40
+
41
+ ---
42
+
43
+ ## Running the Docs Locally
44
+
45
+ The documentation site lives in `docs/` and is built with Vite and Tailwind CSS v4:
46
+
47
+ ```bash
48
+ cd docs
49
+ bun install
50
+ bun run dev
51
+ ```
52
+
53
+ Build the static site for production:
54
+
55
+ ```bash
56
+ cd docs
57
+ bun run build
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Project Layout
63
+
64
+ ```
65
+ subtitle/
66
+ ├── subtitle_generator/
67
+ │ ├── cli/ # Argument parsers, ConsoleProgressObserver, CLI runner
68
+ │ ├── core/ # Transcriber, SubtitleGenerator, VideoProcessor, BatchProcessor
69
+ │ ├── models/ # Thread-safe ModelManager singleton & HF downloader
70
+ │ └── utils/ # Formatters, validators, downloader, paths, whisper_setup
71
+ ├── tests/unit/ # Fast unit tests
72
+ ├── docs/ # Static documentation site (Vite + Tailwind CSS v4)
73
+ └── pyproject.toml # PEP 621 package metadata & entry points
74
+ ```
@@ -0,0 +1,74 @@
1
+ ---
2
+ title: Formats & Embedding
3
+ description: Supported subtitle output formats, offline format conversion, soft muxing (--merge), and hard burning (--burn).
4
+ ---
5
+
6
+ ## Supported Subtitle Formats
7
+
8
+ | Format | Flag | Description | Convertible via `subtitle convert` |
9
+ |--------|------|-------------|-------------------------------------|
10
+ | **WebVTT** | `--format vtt` | Web video standard (`HH:MM:SS.mmm`) *(default)* | Yes |
11
+ | **SubRip** | `--format srt` | Universal desktop & editor format (`HH:MM:SS,mmm`) | Yes |
12
+ | **Plain Text** | `--format txt` | Clean transcript without timestamps | Yes |
13
+ | **LRC** | `--format lrc` | Synchronized lyrics format (`[mm:ss.xx]`) | Yes |
14
+ | **CSV** | `--format csv` | Millisecond-aligned `start,end,text` spreadsheet | Yes |
15
+ | **JSON** | `--format json` | Structured `whisper.cpp` JSON output | Generation only |
16
+
17
+ ---
18
+
19
+ ## Converting Subtitle Files
20
+
21
+ Convert any existing subtitle file without re-running transcription:
22
+
23
+ ```bash
24
+ # Infer formats from file extensions
25
+ subtitle convert video.vtt video.srt
26
+
27
+ # Derive output filename automatically from --format
28
+ subtitle convert video.vtt --format srt
29
+ subtitle convert video.srt --format txt
30
+ subtitle convert video.srt --format csv
31
+
32
+ # Specify source format explicitly
33
+ subtitle convert captions.raw captions.vtt --source-format srt
34
+ ```
35
+
36
+ <Aside type="note">
37
+ Parsers automatically normalize Windows (`\r\n`) and Unix (`\n`) line endings, strip UTF-8 BOM headers, and support both `HH:MM:SS.mmm` and `MM:SS.mmm` WebVTT timestamps.
38
+ </Aside>
39
+
40
+ ---
41
+
42
+ ## Soft Subtitles (`--merge`) vs Hardcoded (`--burn`)
43
+
44
+ Subtitle CLI **never modifies your original media file**. Both options write a new video alongside the generated subtitle file.
45
+
46
+ ### Soft Subtitles (`--merge`)
47
+
48
+ Muxes the subtitle file as a selectable subtitle track with zero video re-encoding (`vcodec=copy`, `acodec=copy`), making it near-instant:
49
+
50
+ ```bash
51
+ subtitle lecture.mp4 --format srt --merge
52
+ # Writes: ./lecture.srt and ./lecture_subtitled.mp4
53
+ ```
54
+
55
+ Container codecs are selected automatically based on output extension:
56
+
57
+ | Container | Subtitle Codec |
58
+ |-----------|----------------|
59
+ | `.mp4`, `.m4v`, `.mov` | `mov_text` |
60
+ | `.mkv` | `srt` |
61
+ | `.webm` | `webvtt` |
62
+
63
+ ### Hardcoded Subtitles (`--burn`)
64
+
65
+ Renders subtitles directly into video frames using FFmpeg's `subtitles` filter while preserving the original audio track (`acodec=copy`):
66
+
67
+ ```bash
68
+ subtitle reel.mp4 --format srt --max-len 16 --split-on-word --burn
69
+ # Writes: ./reel.srt and ./reel_burned.mp4
70
+ ```
71
+
72
+ <Aside type="caution">
73
+ `--merge` and `--burn` are mutually exclusive. Because `--burn` re-encodes the video stream to draw subtitles into each frame, it takes longer than `--merge`.
74
+ </Aside>
@@ -0,0 +1,108 @@
1
+ ---
2
+ title: Getting Started
3
+ description: Install subtitle-generator, build the whisper-cli binary once, and transcribe your first video or audio file.
4
+ ---
5
+
6
+ ## Prerequisites
7
+
8
+ `subtitle setup-whisper` compiles `whisper.cpp` locally for maximum native performance (Apple Metal/Accelerate on macOS, native SIMD/CPU on Linux and Windows). You need `git`, `cmake`, a C++ compiler, and `ffmpeg` on your `PATH`.
9
+
10
+ <Tabs>
11
+ <TabItem label="macOS">
12
+ ```bash
13
+ xcode-select --install
14
+ brew install cmake ffmpeg
15
+ ```
16
+ </TabItem>
17
+ <TabItem label="Linux (Debian / Ubuntu)">
18
+ ```bash
19
+ sudo apt-get update
20
+ sudo apt-get install -y build-essential cmake git ffmpeg
21
+ ```
22
+ </TabItem>
23
+ <TabItem label="Windows">
24
+ Install **Git for Windows**, **CMake**, **Visual Studio Build Tools** (C++ workload), and **FFmpeg** (for example via `winget install Gyan.FFmpeg Kitware.CMake Git.Git`).
25
+ </TabItem>
26
+ </Tabs>
27
+
28
+ ---
29
+
30
+ ## Installation
31
+
32
+ <Steps>
33
+ 1. **Install the Python package from PyPI**
34
+
35
+ ```bash
36
+ pip install subtitle-generator
37
+ ```
38
+
39
+ 2. **Build `whisper-cli` (one-time setup)**
40
+
41
+ ```bash
42
+ subtitle setup-whisper
43
+ ```
44
+
45
+ This clones `innovatorved/whisper.cpp` (`develop` branch with native `-vi` video input support), compiles a static Release binary, and installs it into your per-OS user data directory. It is auto-discovered on every future run.
46
+
47
+ 3. **Verify your installation**
48
+
49
+ ```bash
50
+ subtitle --version
51
+ subtitle models --list
52
+ ```
53
+ </Steps>
54
+
55
+ <Aside type="tip">
56
+ Already have a stock `whisper-cli` binary installed? Point `--whisper-binary /path/to/whisper-cli` or `SUBTITLE_WHISPER_BINARY` at it. If the binary does not support `-vi`, Subtitle CLI automatically extracts a temporary 16 kHz mono WAV via FFmpeg and cleans it up afterwards.
57
+ </Aside>
58
+
59
+ ---
60
+
61
+ ## Your First Subtitle
62
+
63
+ Generate a WebVTT (`.vtt`) subtitle file in your current directory:
64
+
65
+ ```bash
66
+ subtitle video.mp4
67
+ ```
68
+
69
+ On first run, the default `base` model (~140 MB) is automatically downloaded to your user cache directory with a progress bar.
70
+
71
+ Generate an SRT file using the fast, high-accuracy `turbo` (`large-v3-turbo`) model:
72
+
73
+ ```bash
74
+ subtitle video.mp4 --model turbo --format srt
75
+ ```
76
+
77
+ Embed soft subtitles into a copy of the video (original video is never touched):
78
+
79
+ ```bash
80
+ subtitle video.mp4 --merge --format srt
81
+ # Creates ./video.srt and ./video_subtitled.mp4
82
+ ```
83
+
84
+ Burn hardcoded subtitles directly into the video stream (audio track preserved):
85
+
86
+ ```bash
87
+ subtitle video.mp4 --burn --format srt
88
+ # Creates ./video.srt and ./video_burned.mp4
89
+ ```
90
+
91
+ ---
92
+
93
+ ## Storage & Environment Variables
94
+
95
+ Subtitle CLI stores downloaded models and the built `whisper-cli` binary in standard per-OS user directories so it works cleanly from any working directory.
96
+
97
+ | Resource | macOS | Linux | Windows |
98
+ |----------|-------|-------|---------|
99
+ | Models cache | `~/Library/Caches/subtitle-generator/models` | `${XDG_CACHE_HOME:-~/.cache}/subtitle-generator/models` | `%LOCALAPPDATA%\subtitle-generator\Cache\models` |
100
+ | `setup-whisper` data & binary | `~/Library/Application Support/subtitle-generator` | `${XDG_DATA_HOME:-~/.local/share}/subtitle-generator` | `%LOCALAPPDATA%\subtitle-generator` |
101
+
102
+ Override any location with environment variables:
103
+
104
+ | Variable | Purpose |
105
+ |----------|---------|
106
+ | `SUBTITLE_WHISPER_BINARY` | Explicit path to `whisper-cli` |
107
+ | `SUBTITLE_MODELS_DIR` | Custom directory for cached GGML models |
108
+ | `SUBTITLE_DATA_DIR` | Custom directory for `setup-whisper` source & binary |
@@ -0,0 +1,83 @@
1
+ ---
2
+ title: Subtitle CLI
3
+ description: Fast, offline, AI-powered subtitle generation for video and audio files powered by whisper.cpp.
4
+ template: splash
5
+ hero:
6
+ tagline: Generate, convert, embed, and burn accurate subtitles for any video or audio file locally using whisper.cpp. Zero cloud lock-in, modular Python API, and parallel batch processing.
7
+ actions:
8
+ - text: Get Started
9
+ link: /docs/getting-started
10
+ icon: right-arrow
11
+ variant: primary
12
+ - text: CLI Reference
13
+ link: /docs/cli-reference
14
+ icon: external
15
+ variant: minimal
16
+ ---
17
+
18
+ ## What is Subtitle CLI?
19
+
20
+ Subtitle CLI (`subtitle-generator`) is a lightweight, modular command-line tool and Python library that wraps [whisper.cpp](https://github.com/ggml-org/whisper.cpp) ([custom fork with native video input](https://github.com/innovatorved/whisper.cpp)) to transcribe local media files, URLs, and entire folders into clean subtitles — completely offline on your own machine.
21
+
22
+ Install it via `pip`, run `subtitle setup-whisper` once, and generate **VTT**, **SRT**, **TXT**, **JSON**, **LRC**, or **CSV** subtitles from any video or audio file in seconds.
23
+
24
+ ---
25
+
26
+ ## Core Capabilities
27
+
28
+ <CardGrid>
29
+ <Card title="One-Command Transcription">
30
+ Point `subtitle` at any video, audio file, HTTP/HTTPS URL, or Google Drive link. Original media files are never modified.
31
+ </Card>
32
+ <Card title="Soft Mux & Hard Burn">
33
+ Embed selectable subtitle tracks (`--merge`) with automatic container codec detection, or hardcode subtitles (`--burn`) while preserving the original audio stream.
34
+ </Card>
35
+ <Card title="Parallel Batch Processing">
36
+ Process entire directories concurrently with configurable `--workers`, `--threads`, `--resume` state recovery, and Markdown summary reports.
37
+ </Card>
38
+ <Card title="Modular Python SDK">
39
+ Plug `SubtitleGenerator`, `WhisperCppTranscriber`, `BatchProcessor`, `VideoProcessor`, `ModelManager`, and `SubtitleFormatterFactory` directly into your own apps.
40
+ </Card>
41
+ </CardGrid>
42
+
43
+ ---
44
+
45
+ ## Architecture
46
+
47
+ Subtitle CLI separates CLI orchestration, model caching, transcription strategies, FFmpeg video operations, and subtitle formatters into clean, independently testable modules.
48
+
49
+ ```
50
+ CLI (`subtitle ...`) or Python SDK (`subtitle_generator`)
51
+ │
52
+ ├── ModelManager → Downloads & caches GGML models in per-OS cache dir
53
+ ├── Downloader → Fetches HTTP(S) & Google Drive media into temp storage
54
+ ├── WhisperCppTranscriber → Invokes `whisper-cli` (-vi native or FFmpeg WAV fallback)
55
+ ├── VideoProcessor → Soft-muxes (--merge) or hard-burns (--burn) via FFmpeg
56
+ ├── BatchProcessor → ThreadPoolExecutor + .batch_state.json + batch_report.md
57
+ └── Formatters → Parse & convert VTT, SRT, CSV, LRC, and TXT
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Quick Links
63
+
64
+ <CardGrid>
65
+ <LinkCard title="Getting Started" href="/docs/getting-started" description="Install subtitle-generator, build whisper-cli once on macOS, Linux, or Windows, and generate your first subtitle." />
66
+ <LinkCard title="CLI Reference" href="/docs/cli-reference" description="Complete reference for every command, flag, short-form caption option, and translation workflow." />
67
+ <LinkCard title="Batch Processing" href="/docs/batch-processing" description="Transcribe directories in parallel with worker tuning, resume support, and Markdown reports." />
68
+ <LinkCard title="Python API" href="/docs/python-api" description="Embed subtitle generation, format conversion, and custom strategies in Python." />
69
+ </CardGrid>
70
+
71
+ ---
72
+
73
+ ## Stack
74
+
75
+ | Layer | Technology |
76
+ |-------|-----------|
77
+ | Runtime | Python 3.9+ |
78
+ | Engine | `whisper.cpp` (`whisper-cli` compiled via `subtitle setup-whisper`) |
79
+ | Video / Audio | FFmpeg (`ffmpeg-python`) |
80
+ | Models | GGML Whisper models (`tiny`, `base`, `small`, `medium`, `large-v3`, `turbo`, quantized) |
81
+ | Formats | `vtt`, `srt`, `txt`, `json`, `lrc`, `csv` |
82
+ | Distribution | PyPI (`pip install subtitle-generator`) |
83
+ | License | MIT |
@@ -0,0 +1,60 @@
1
+ ---
2
+ title: Models
3
+ description: Complete catalog of supported GGML Whisper models, quantization tradeoffs, and offline model management.
4
+ ---
5
+
6
+ ## Recommended Models
7
+
8
+ Models are downloaded automatically from Hugging Face (`ggerganov/whisper.cpp`) the first time you request them, verified atomically via a `.part` file, and cached in your user cache directory.
9
+
10
+ | Model | Approx. Size | Speed | Accuracy | Best For |
11
+ |-------|-------------|-------|----------|----------|
12
+ | `tiny` / `tiny.en` | ~75 MB | Fastest | Low | Quick drafts, low-RAM machines |
13
+ | `base` / `base.en` | ~140 MB | Fast | Medium *(default)* | Everyday videos, fast turnarounds |
14
+ | `small` / `small.en` | ~460 MB | Medium | Good | Podcasts, talks, tutorials |
15
+ | `medium` / `medium.en` | ~1.5 GB | Slow | Great | Noisy audio, accents, multilingual |
16
+ | `turbo` (`large-v3-turbo`) | ~1.5 GB | Fast | Near-best | Best overall speed-to-accuracy ratio |
17
+ | `large` (`large-v3`) | ~3.0 GB | Slowest | Best | Highest accuracy, archival transcription |
18
+
19
+ <Aside type="tip">
20
+ For English-only videos, the `.en` variants (`tiny.en`, `base.en`, `small.en`, `medium.en`) are noticeably more accurate than their multilingual counterparts at the same size.
21
+ </Aside>
22
+
23
+ ---
24
+
25
+ ## Quantized & Specialized Variants
26
+
27
+ Quantized models (`-q5_0`, `-q5_1`, `-q8_0`) reduce disk size and memory usage by 30–60% with minimal quality loss — ideal for laptops and parallel batch workers.
28
+
29
+ | Family | Available Identifiers |
30
+ |--------|-----------------------|
31
+ | Tiny | `tiny`, `tiny.en`, `tiny-q5_1`, `tiny.en-q5_1`, `tiny-q8_0`, `tiny.en-q8_0` |
32
+ | Base | `base`, `base.en`, `base-q5_1`, `base.en-q5_1`, `base-q8_0`, `base.en-q8_0` |
33
+ | Small | `small`, `small.en`, `small.en-tdrz`, `small-q5_1`, `small.en-q5_1`, `small-q8_0`, `small.en-q8_0` |
34
+ | Medium | `medium`, `medium.en`, `medium-q5_0`, `medium.en-q5_0`, `medium-q8_0`, `medium.en-q8_0` |
35
+ | Large v1/v2 | `large-v1`, `large-v2`, `large-v2-q5_0`, `large-v2-q8_0` |
36
+ | Large v3 | `large-v3`, `large-v3-q5_0`, `large` *(alias)*, `large-q5_0` *(alias)* |
37
+ | Large v3 Turbo | `large-v3-turbo`, `large-v3-turbo-q5_0`, `large-v3-turbo-q8_0`, `turbo` *(alias)* |
38
+
39
+ ---
40
+
41
+ ## Managing Models
42
+
43
+ List all available models and see which ones are already cached locally:
44
+
45
+ ```bash
46
+ subtitle models --list
47
+ ```
48
+
49
+ Pre-download a model before going offline:
50
+
51
+ ```bash
52
+ subtitle models --download large-v3-turbo-q5_0
53
+ ```
54
+
55
+ Use a custom cache directory (per-command or via environment variable):
56
+
57
+ ```bash
58
+ export SUBTITLE_MODELS_DIR=/mnt/fast-ssd/whisper-models
59
+ subtitle video.mp4 --model turbo
60
+ ```