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.
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/CHANGELOG.md +20 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/MANIFEST.in +2 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/PKG-INFO +9 -10
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/README.md +8 -0
- subtitle_generator-3.2.1/docs/src/content/batch-processing.md +63 -0
- subtitle_generator-3.2.1/docs/src/content/cli-reference.md +118 -0
- subtitle_generator-3.2.1/docs/src/content/contributing.md +74 -0
- subtitle_generator-3.2.1/docs/src/content/formats.md +74 -0
- subtitle_generator-3.2.1/docs/src/content/getting-started.md +108 -0
- subtitle_generator-3.2.1/docs/src/content/index.md +83 -0
- subtitle_generator-3.2.1/docs/src/content/models.md +60 -0
- subtitle_generator-3.2.1/docs/src/content/python-api.md +163 -0
- subtitle_generator-3.2.1/docs/src/content/troubleshooting.md +71 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/environment.yml +3 -3
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/pyproject.toml +11 -11
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/requirements.txt +4 -4
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/__init__.py +1 -1
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/cli/commands.py +86 -10
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/batch_processor.py +14 -2
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/transcriber.py +5 -1
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/video_processor.py +56 -19
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/models/model_manager.py +30 -20
- subtitle_generator-3.2.1/subtitle_generator/utils/downloader.py +223 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/formatters.py +19 -11
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator.egg-info/SOURCES.txt +9 -0
- subtitle_generator-3.2.0/subtitle_generator/utils/downloader.py +0 -190
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/CONTRIBUTING.md +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/LICENSE +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/PYPI_README.md +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/docs/API.md +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/docs/TROUBLESHOOTING.md +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/setup.cfg +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/setup.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/cli/__init__.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/__init__.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/core/subtitle_gen.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/models/__init__.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/__init__.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/exceptions.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/file_handler.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/paths.py +0 -0
- {subtitle_generator-3.2.0 → subtitle_generator-3.2.1}/subtitle_generator/utils/validators.py +0 -0
- {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
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: subtitle-generator
|
|
3
|
-
Version: 3.2.
|
|
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://
|
|
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.
|
|
33
|
-
Requires-Dist: gdown>=5.2
|
|
31
|
+
Requires-Dist: tqdm>=4.70.1
|
|
32
|
+
Requires-Dist: gdown>=6.5.2
|
|
34
33
|
Provides-Extra: dev
|
|
35
|
-
Requires-Dist: pytest>=
|
|
36
|
-
Requires-Dist: pytest-cov>=
|
|
37
|
-
Requires-Dist: build>=1.
|
|
38
|
-
Requires-Dist: twine>=
|
|
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
|
+
```
|