subtitle-generator 3.0.2__tar.gz → 3.0.3__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 (39) hide show
  1. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/PKG-INFO +31 -13
  2. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/PYPI_README.md +30 -12
  3. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/pyproject.toml +1 -1
  4. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/__init__.py +1 -1
  5. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/cli/commands.py +117 -0
  6. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/paths.py +101 -23
  7. subtitle_generator-3.0.3/subtitle_generator/utils/whisper_setup.py +316 -0
  8. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator.egg-info/SOURCES.txt +2 -1
  9. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/CONTRIBUTING.md +0 -0
  10. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/LICENSE +0 -0
  11. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/MANIFEST.in +0 -0
  12. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/README.md +0 -0
  13. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/config/default.yaml +0 -0
  14. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/docs/API.md +0 -0
  15. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/docs/PACKAGING.md +0 -0
  16. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/docs/TROUBLESHOOTING.md +0 -0
  17. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/docs/example.md +0 -0
  18. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/environment.yml +0 -0
  19. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/requirements.txt +0 -0
  20. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/setup.cfg +0 -0
  21. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/setup.py +0 -0
  22. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/cli/__init__.py +0 -0
  23. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/config/__init__.py +0 -0
  24. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/config/config_loader.py +0 -0
  25. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/config/settings.py +0 -0
  26. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/__init__.py +0 -0
  27. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/async_processor.py +0 -0
  28. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/batch_processor.py +0 -0
  29. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/subtitle_gen.py +0 -0
  30. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/transcriber.py +0 -0
  31. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/core/video_processor.py +0 -0
  32. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/models/__init__.py +0 -0
  33. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/models/model_manager.py +0 -0
  34. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/__init__.py +0 -0
  35. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/downloader.py +0 -0
  36. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/exceptions.py +0 -0
  37. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/file_handler.py +0 -0
  38. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/formatters.py +0 -0
  39. {subtitle_generator-3.0.2 → subtitle_generator-3.0.3}/subtitle_generator/utils/validators.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: subtitle-generator
3
- Version: 3.0.2
3
+ Version: 3.0.3
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>
@@ -83,26 +83,44 @@ native code), so you need to provide it once.
83
83
  choco install ffmpeg
84
84
  ```
85
85
 
86
- - **whisper-cli** (the whisper.cpp transcription binary):
86
+ - **whisper-cli** (the whisper.cpp transcription binary). The recommended
87
+ setup is one command, run once after `pip install`:
88
+
87
89
  ```bash
88
- # macOS (recommended — also adds the binary to your PATH)
89
- brew install whisper-cpp
90
+ subtitle setup-whisper
91
+ ```
92
+
93
+ This clones the project's compatible whisper.cpp fork into your user
94
+ data directory (e.g. `~/Library/Application Support/subtitle-generator/`
95
+ on macOS) and builds it with CMake. Every subsequent `subtitle <video>`
96
+ invocation auto-discovers the binary — no env vars, no PATH editing.
97
+
98
+ Build prerequisites for `setup-whisper`:
99
+
100
+ ```bash
101
+ # macOS
102
+ xcode-select --install # provides clang++ + make
103
+ brew install cmake ffmpeg
90
104
 
91
- # Linux — build from source
92
- git clone https://github.com/ggml-org/whisper.cpp
93
- cd whisper.cpp && cmake -B build && cmake --build build --config Release
94
- export SUBTITLE_WHISPER_BINARY="$(pwd)/build/bin/whisper-cli"
105
+ # Linux (Debian/Ubuntu)
106
+ sudo apt-get install -y build-essential cmake git ffmpeg
95
107
 
96
- # Windows — download a prebuilt release
97
- # https://github.com/ggml-org/whisper.cpp/releases
98
- # then add the folder containing whisper-cli.exe to PATH
108
+ # Windows
109
+ # Install Visual Studio Build Tools, CMake, Git for Windows.
99
110
  ```
100
111
 
101
112
  The CLI auto-discovers the binary in this order:
102
113
  1. `--whisper-binary /path/to/whisper-cli`
103
114
  2. `SUBTITLE_WHISPER_BINARY` environment variable
104
- 3. `whisper-cli` / `whisper-cpp` / `main` on your `PATH`
105
- 4. `./binary/whisper-cli` relative to the current directory (legacy)
115
+ 3. The binary installed by `subtitle setup-whisper` (preferred over PATH)
116
+ 4. `whisper-cli` / `whisper-cpp` / `main` on your `PATH`
117
+ 5. `./binary/whisper-cli` relative to the current directory (legacy)
118
+
119
+ Note: Homebrew's `whisper-cpp` formula (currently 1.8.4) dropped the
120
+ `-vi` flag and only accepts pre-extracted audio (`flac/mp3/ogg/wav`),
121
+ so it is **not** sufficient for this package's "pass a video, get
122
+ subtitles" UX. Use `subtitle setup-whisper` to build a compatible
123
+ binary instead.
106
124
 
107
125
  ## Quick Start
108
126
 
@@ -38,26 +38,44 @@ native code), so you need to provide it once.
38
38
  choco install ffmpeg
39
39
  ```
40
40
 
41
- - **whisper-cli** (the whisper.cpp transcription binary):
41
+ - **whisper-cli** (the whisper.cpp transcription binary). The recommended
42
+ setup is one command, run once after `pip install`:
43
+
42
44
  ```bash
43
- # macOS (recommended — also adds the binary to your PATH)
44
- brew install whisper-cpp
45
+ subtitle setup-whisper
46
+ ```
47
+
48
+ This clones the project's compatible whisper.cpp fork into your user
49
+ data directory (e.g. `~/Library/Application Support/subtitle-generator/`
50
+ on macOS) and builds it with CMake. Every subsequent `subtitle <video>`
51
+ invocation auto-discovers the binary — no env vars, no PATH editing.
52
+
53
+ Build prerequisites for `setup-whisper`:
54
+
55
+ ```bash
56
+ # macOS
57
+ xcode-select --install # provides clang++ + make
58
+ brew install cmake ffmpeg
45
59
 
46
- # Linux — build from source
47
- git clone https://github.com/ggml-org/whisper.cpp
48
- cd whisper.cpp && cmake -B build && cmake --build build --config Release
49
- export SUBTITLE_WHISPER_BINARY="$(pwd)/build/bin/whisper-cli"
60
+ # Linux (Debian/Ubuntu)
61
+ sudo apt-get install -y build-essential cmake git ffmpeg
50
62
 
51
- # Windows — download a prebuilt release
52
- # https://github.com/ggml-org/whisper.cpp/releases
53
- # then add the folder containing whisper-cli.exe to PATH
63
+ # Windows
64
+ # Install Visual Studio Build Tools, CMake, Git for Windows.
54
65
  ```
55
66
 
56
67
  The CLI auto-discovers the binary in this order:
57
68
  1. `--whisper-binary /path/to/whisper-cli`
58
69
  2. `SUBTITLE_WHISPER_BINARY` environment variable
59
- 3. `whisper-cli` / `whisper-cpp` / `main` on your `PATH`
60
- 4. `./binary/whisper-cli` relative to the current directory (legacy)
70
+ 3. The binary installed by `subtitle setup-whisper` (preferred over PATH)
71
+ 4. `whisper-cli` / `whisper-cpp` / `main` on your `PATH`
72
+ 5. `./binary/whisper-cli` relative to the current directory (legacy)
73
+
74
+ Note: Homebrew's `whisper-cpp` formula (currently 1.8.4) dropped the
75
+ `-vi` flag and only accepts pre-extracted audio (`flac/mp3/ogg/wav`),
76
+ so it is **not** sufficient for this package's "pass a video, get
77
+ subtitles" UX. Use `subtitle setup-whisper` to build a compatible
78
+ binary instead.
61
79
 
62
80
  ## Quick Start
63
81
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "subtitle-generator"
7
- version = "3.0.2"
7
+ version = "3.0.3"
8
8
  description = "AI-powered subtitle generation from video/audio using Whisper."
9
9
  readme = "PYPI_README.md"
10
10
  license = {text = "MIT"}
@@ -5,4 +5,4 @@ A clean, modular subtitle generation system using Whisper.cpp
5
5
  with proper separation of concerns and design patterns.
6
6
  """
7
7
 
8
- __version__ = "3.0.2"
8
+ __version__ = "3.0.3"
@@ -396,6 +396,9 @@ def create_main_parser() -> argparse.ArgumentParser:
396
396
  description="Generate subtitles for video files using Whisper",
397
397
  formatter_class=argparse.RawDescriptionHelpFormatter,
398
398
  epilog="""
399
+ First-time setup (one-time):
400
+ subtitle setup-whisper Build the whisper-cli binary
401
+
399
402
  Examples:
400
403
  subtitle video.mp4 Generate VTT subtitles
401
404
  subtitle video.mp4 --merge Generate and embed subtitles
@@ -500,6 +503,62 @@ def create_models_parser() -> argparse.ArgumentParser:
500
503
  return parser
501
504
 
502
505
 
506
+ def create_setup_whisper_parser() -> argparse.ArgumentParser:
507
+ """Create parser for the `setup-whisper` subcommand.
508
+
509
+ The subcommand builds whisper.cpp from source into the user data
510
+ directory so the rest of the CLI can auto-discover the binary on
511
+ every subsequent invocation, without manual env vars or PATH
512
+ manipulation.
513
+ """
514
+ parser = argparse.ArgumentParser(
515
+ prog="subtitle setup-whisper",
516
+ description=(
517
+ "Clone, build, and install the whisper.cpp CLI into your "
518
+ "per-OS user data dir. One-time setup; auto-discovered "
519
+ "afterwards."
520
+ ),
521
+ formatter_class=argparse.RawDescriptionHelpFormatter,
522
+ epilog="""
523
+ Examples:
524
+ subtitle setup-whisper Build the default fork (recommended)
525
+ subtitle setup-whisper --force Wipe existing checkout and rebuild
526
+ subtitle setup-whisper --no-pull Rebuild offline from current sources
527
+ subtitle setup-whisper --ref v1.7.4 Pin to a specific tag/branch/commit
528
+
529
+ Requires git, cmake, and a C++ compiler on PATH.
530
+ """,
531
+ )
532
+ parser.add_argument(
533
+ "--repo",
534
+ type=str,
535
+ default=None,
536
+ metavar="URL",
537
+ help=(
538
+ "Git URL of the whisper.cpp source. Defaults to the project's "
539
+ "compatible fork (innovatorved/whisper.cpp)."
540
+ ),
541
+ )
542
+ parser.add_argument(
543
+ "--ref",
544
+ type=str,
545
+ default=None,
546
+ metavar="REF",
547
+ help="Branch, tag, or commit to check out (default: develop).",
548
+ )
549
+ parser.add_argument(
550
+ "--force",
551
+ action="store_true",
552
+ help="Wipe any existing checkout and re-clone from scratch.",
553
+ )
554
+ parser.add_argument(
555
+ "--no-pull",
556
+ action="store_true",
557
+ help="Skip `git fetch / pull` on an existing checkout (offline rebuild).",
558
+ )
559
+ return parser
560
+
561
+
503
562
  def create_batch_parser() -> argparse.ArgumentParser:
504
563
  """Create parser for batch subcommand."""
505
564
  parser = argparse.ArgumentParser(
@@ -571,6 +630,59 @@ Examples:
571
630
  return parser
572
631
 
573
632
 
633
+ def _handle_setup_whisper_command(args: argparse.Namespace) -> int:
634
+ """Handle the ``subtitle setup-whisper`` subcommand.
635
+
636
+ Kept at module scope (rather than as a method on ``SubtitleCLI``) so
637
+ that triggering the build doesn't require constructing a
638
+ ``ModelManager`` — useful when the user is running ``setup-whisper``
639
+ precisely because nothing works yet.
640
+ """
641
+ # Local import: keeps the heavy build logic out of CLI startup time
642
+ # for the 99% of invocations that aren't `setup-whisper`.
643
+ from ..utils.whisper_setup import (
644
+ DEFAULT_REF,
645
+ DEFAULT_REPO_URL,
646
+ WhisperSetupError,
647
+ setup_whisper,
648
+ )
649
+
650
+ repo = args.repo or DEFAULT_REPO_URL
651
+ ref = args.ref or DEFAULT_REF
652
+ force = bool(args.force)
653
+ pull = not bool(getattr(args, "no_pull", False))
654
+
655
+ print(f"[setup-whisper] repo={repo} ref={ref} force={force} pull={pull}")
656
+
657
+ def _stream(line: str) -> None:
658
+ print(line, flush=True)
659
+
660
+ try:
661
+ result = setup_whisper(
662
+ repo_url=repo,
663
+ ref=ref,
664
+ force=force,
665
+ pull=pull,
666
+ log_callback=_stream,
667
+ )
668
+ except WhisperSetupError as e:
669
+ print(f"\n[ERROR] setup-whisper failed: {e}", file=sys.stderr)
670
+ return 1
671
+ except KeyboardInterrupt:
672
+ print("\n\nOperation cancelled.", file=sys.stderr)
673
+ return 130
674
+
675
+ print(
676
+ "\n[DONE] whisper-cli installed.\n"
677
+ f" binary: {result.binary_path}\n"
678
+ f" source: {result.source_dir}\n"
679
+ f" ref: {result.ref}\n"
680
+ "You can now run `subtitle <video>` from anywhere — the binary "
681
+ "will be auto-discovered."
682
+ )
683
+ return 0
684
+
685
+
574
686
  def main(args: Optional[list[str]] = None) -> int:
575
687
  """Main entry point for CLI."""
576
688
  if args is None:
@@ -589,6 +701,11 @@ def main(args: Optional[list[str]] = None) -> int:
589
701
  cli = SubtitleCLI()
590
702
  return cli._handle_formats_command()
591
703
 
704
+ if args and args[0] == "setup-whisper":
705
+ parser = create_setup_whisper_parser()
706
+ parsed_args = parser.parse_args(args[1:])
707
+ return _handle_setup_whisper_command(parsed_args)
708
+
592
709
  if args and args[0] == "batch":
593
710
  parser = create_batch_parser()
594
711
  parsed_args = parser.parse_args(args[1:])
@@ -23,6 +23,7 @@ logger = logging.getLogger(__name__)
23
23
  # Environment variables that let users override defaults without code changes.
24
24
  ENV_WHISPER_BINARY = "SUBTITLE_WHISPER_BINARY"
25
25
  ENV_MODELS_DIR = "SUBTITLE_MODELS_DIR"
26
+ ENV_DATA_DIR = "SUBTITLE_DATA_DIR"
26
27
 
27
28
  # Names that whisper.cpp ships its CLI under across releases / package managers.
28
29
  # Order matters: we prefer the canonical upstream name first.
@@ -53,14 +54,19 @@ def find_whisper_binary(explicit: Optional[str] = None) -> Optional[str]:
53
54
  """Resolve the path to the whisper.cpp CLI binary.
54
55
 
55
56
  Lookup order (first hit wins):
56
- 1. `explicit` argument (e.g. from a CLI flag).
57
+ 1. ``explicit`` argument (e.g. from a CLI ``--whisper-binary`` flag).
57
58
  2. The ``SUBTITLE_WHISPER_BINARY`` environment variable.
58
- 3. ``shutil.which`` against known binary names. This picks up
59
- Homebrew installs (``brew install whisper-cpp``), system packages,
60
- and anything the user added to ``PATH``.
61
- 4. A legacy ``./binary/whisper-cli`` (or ``.exe`` on Windows) relative
62
- to the current working directory. This preserves backwards
63
- compatibility with this project's own ``setup_whisper.sh`` layout.
59
+ 3. The binary installed by ``subtitle setup-whisper`` into the
60
+ per-OS user data dir. This is checked before ``PATH`` so that
61
+ the project's known-compatible fork (which still supports the
62
+ ``-vi`` video-input flag and direct ``.mp4`` ingestion) is
63
+ preferred over any incompatible system-wide install (e.g.
64
+ Homebrew's ``whisper-cpp 1.8.4`` dropped ``-vi``).
65
+ 4. ``shutil.which`` against known binary names. Picks up system
66
+ installs and anything the user added to ``PATH``.
67
+ 5. A legacy ``./binary/whisper-cli`` (or ``.exe`` on Windows)
68
+ relative to the current working directory. Preserves
69
+ backwards compatibility with the project's checkout layout.
64
70
 
65
71
  Returns the absolute path to an executable, or ``None`` if no candidate
66
72
  is found. Callers are expected to surface a helpful error in the latter
@@ -95,6 +101,10 @@ def find_whisper_binary(explicit: Optional[str] = None) -> Optional[str]:
95
101
  env_value,
96
102
  )
97
103
 
104
+ bundled = installed_whisper_binary()
105
+ if bundled:
106
+ return bundled
107
+
98
108
  for name in _WHISPER_BINARY_NAMES:
99
109
  # `shutil.which` already handles PATHEXT (.exe) on Windows.
100
110
  on_path = shutil.which(name)
@@ -112,39 +122,47 @@ def find_whisper_binary(explicit: Optional[str] = None) -> Optional[str]:
112
122
  def whisper_binary_install_hint() -> str:
113
123
  """Return a user-facing string explaining how to obtain whisper-cli.
114
124
 
115
- Tailored per-OS so the error a user sees in their terminal is
116
- actionable rather than generic.
125
+ The first option is always ``subtitle setup-whisper``: that command
126
+ builds the project's own compatible fork (which still supports the
127
+ ``-vi`` video-input flag) into the user data dir, with no manual
128
+ PATH or env-var fiddling required. The remaining options are
129
+ fallbacks for users who prefer a system install or already have a
130
+ compatible binary somewhere.
117
131
  """
132
+ primary = (
133
+ "\n - Recommended: run `subtitle setup-whisper` once. This builds"
134
+ "\n whisper.cpp from source into your user data dir and is"
135
+ "\n auto-discovered on every subsequent invocation. Requires"
136
+ "\n git, cmake, and a C++ compiler on your machine."
137
+ )
118
138
  common = (
119
- "\n - Set the SUBTITLE_WHISPER_BINARY environment variable to the "
120
- "absolute path of an existing whisper-cli binary, or"
121
- "\n - Pass --whisper-binary /absolute/path/to/whisper-cli on the CLI."
139
+ "\n - Or set the SUBTITLE_WHISPER_BINARY environment variable to the"
140
+ "\n absolute path of an existing whisper-cli binary."
141
+ "\n - Or pass --whisper-binary /absolute/path/to/whisper-cli on the CLI."
122
142
  )
123
143
  if sys.platform == "darwin":
124
144
  os_hint = (
125
- "\n - macOS: install via Homebrew: brew install whisper-cpp"
126
- "\n (this places `whisper-cli` on your PATH automatically)"
145
+ "\n - macOS toolchain: install Xcode CLI tools and cmake:"
146
+ "\n xcode-select --install && brew install cmake ffmpeg"
127
147
  )
128
148
  elif sys.platform.startswith("linux"):
129
149
  os_hint = (
130
- "\n - Linux: build whisper.cpp from source:"
131
- "\n git clone https://github.com/ggml-org/whisper.cpp"
132
- "\n cd whisper.cpp && cmake -B build && cmake --build build --config Release"
133
- "\n then point SUBTITLE_WHISPER_BINARY at build/bin/whisper-cli"
150
+ "\n - Linux toolchain: install build essentials:"
151
+ "\n sudo apt-get install -y build-essential cmake git ffmpeg"
134
152
  )
135
153
  elif sys.platform == "win32":
136
154
  os_hint = (
137
- "\n - Windows: download a prebuilt release from "
138
- "https://github.com/ggml-org/whisper.cpp/releases"
139
- "\n and add the folder containing whisper-cli.exe to PATH."
155
+ "\n - Windows toolchain: install Visual Studio Build Tools, CMake,"
156
+ "\n and Git for Windows; or download a prebuilt whisper-cli.exe"
157
+ "\n release and add its folder to PATH."
140
158
  )
141
159
  else:
142
160
  os_hint = (
143
- "\n - Build whisper.cpp from source: "
144
- "https://github.com/ggml-org/whisper.cpp"
161
+ "\n - Toolchain: install git, cmake, make, and a C++ compiler."
145
162
  )
146
163
  return (
147
164
  "Could not find the `whisper-cli` binary on this system."
165
+ + primary
148
166
  + os_hint
149
167
  + common
150
168
  )
@@ -197,3 +215,63 @@ def default_output_dir() -> str:
197
215
  import tempfile
198
216
 
199
217
  return os.path.join(tempfile.gettempdir(), "subtitle-generator")
218
+
219
+
220
+ def default_data_dir() -> str:
221
+ """Return a per-OS user *data* directory (distinct from cache).
222
+
223
+ Used by ``subtitle setup-whisper`` to host the cloned whisper.cpp
224
+ source tree and its compiled ``whisper-cli`` binary so they survive
225
+ cache cleanup and are reused across invocations.
226
+
227
+ Resolution order:
228
+ 1. ``SUBTITLE_DATA_DIR`` environment variable, if set.
229
+ 2. Per-OS default:
230
+ * macOS: ``~/Library/Application Support/subtitle-generator``
231
+ * Windows: ``%LOCALAPPDATA%/subtitle-generator``
232
+ * Linux: ``$XDG_DATA_HOME/subtitle-generator`` (fallback to
233
+ ``~/.local/share/subtitle-generator``).
234
+ """
235
+ env_dir = os.environ.get(ENV_DATA_DIR)
236
+ if env_dir:
237
+ return os.path.abspath(os.path.expanduser(env_dir))
238
+
239
+ if sys.platform == "darwin":
240
+ return os.path.expanduser(
241
+ "~/Library/Application Support/subtitle-generator"
242
+ )
243
+ if sys.platform == "win32":
244
+ local_app = os.environ.get("LOCALAPPDATA") or os.path.expanduser(
245
+ "~/AppData/Local"
246
+ )
247
+ return os.path.join(local_app, "subtitle-generator")
248
+ xdg = os.environ.get("XDG_DATA_HOME")
249
+ if xdg:
250
+ return os.path.join(xdg, "subtitle-generator")
251
+ return os.path.expanduser("~/.local/share/subtitle-generator")
252
+
253
+
254
+ def installed_whisper_binary() -> Optional[str]:
255
+ """Return the path to the whisper-cli binary installed by
256
+ ``subtitle setup-whisper`` into the user data dir, or ``None`` if not
257
+ present. Used as a high-priority lookup in :func:`find_whisper_binary`.
258
+ """
259
+ bin_dir = os.path.join(default_data_dir(), "bin")
260
+ candidate = os.path.join(bin_dir, "whisper-cli")
261
+ if _is_executable_file(candidate):
262
+ return candidate
263
+ if sys.platform == "win32":
264
+ candidate_exe = candidate + ".exe"
265
+ if _is_executable_file(candidate_exe):
266
+ return candidate_exe
267
+ return None
268
+
269
+
270
+ def installed_whisper_binary_target() -> str:
271
+ """Return the absolute path where ``subtitle setup-whisper`` should
272
+ install the compiled whisper-cli binary. Always returns the same path
273
+ for the current OS; the file may or may not exist yet.
274
+ """
275
+ bin_dir = os.path.join(default_data_dir(), "bin")
276
+ name = "whisper-cli.exe" if sys.platform == "win32" else "whisper-cli"
277
+ return os.path.join(bin_dir, name)
@@ -0,0 +1,316 @@
1
+ """
2
+ Cross-platform builder for the project's bundled whisper.cpp fork.
3
+
4
+ Implements the ``subtitle setup-whisper`` workflow: clone (or update) the
5
+ project's whisper.cpp fork, build the ``whisper-cli`` binary with CMake,
6
+ and install it into the per-OS user data dir so subsequent
7
+ ``subtitle ...`` invocations can auto-discover it without any flags or
8
+ environment variables.
9
+
10
+ The fork pin is intentional: upstream whisper.cpp 1.8.x dropped the
11
+ ``-vi`` (video-input) flag and rejects ``.mp4`` directly, breaking this
12
+ project's "pass a video, get subtitles" UX. ``innovatorved/whisper.cpp``
13
+ preserves that flag.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import logging
19
+ import os
20
+ import shutil
21
+ import subprocess
22
+ import sys
23
+ from dataclasses import dataclass
24
+ from typing import Callable, List, Optional
25
+
26
+ from .exceptions import SubtitleError
27
+ from .paths import (
28
+ default_data_dir,
29
+ installed_whisper_binary_target,
30
+ )
31
+
32
+ logger = logging.getLogger(__name__)
33
+
34
+
35
+ # Pinned to the project's compatible fork. Override per-invocation with
36
+ # ``subtitle setup-whisper --repo <url> --ref <branch_or_tag>``.
37
+ DEFAULT_REPO_URL = "https://github.com/innovatorved/whisper.cpp.git"
38
+ DEFAULT_REF = "develop"
39
+
40
+
41
+ class WhisperSetupError(SubtitleError):
42
+ """Raised when the ``setup-whisper`` build pipeline fails."""
43
+
44
+
45
+ @dataclass
46
+ class WhisperSetupResult:
47
+ """Summary of a successful build/install run."""
48
+
49
+ binary_path: str
50
+ source_dir: str
51
+ repo_url: str
52
+ ref: str
53
+
54
+
55
+ def _check_dependency(name: str) -> str:
56
+ """Return the absolute path of ``name`` on PATH or raise.
57
+
58
+ All toolchain checks happen up-front so we fail before doing any
59
+ network or disk work — a clean error beats half-written state.
60
+ """
61
+ found = shutil.which(name)
62
+ if not found:
63
+ raise WhisperSetupError(
64
+ f"Required build dependency `{name}` was not found on PATH.",
65
+ details={"missing": name},
66
+ )
67
+ return found
68
+
69
+
70
+ def _check_cxx_compiler() -> str:
71
+ """Verify a C++ compiler is available; CMake will pick its own, but
72
+ we surface a friendlier error here than letting cmake fail mid-build.
73
+ """
74
+ for candidate in ("c++", "g++", "clang++", "cl"):
75
+ path = shutil.which(candidate)
76
+ if path:
77
+ return path
78
+ raise WhisperSetupError(
79
+ "No C++ compiler found on PATH (looked for c++, g++, clang++, cl).",
80
+ details={"hint": "Install Xcode CLI tools (macOS), build-essential "
81
+ "(Linux), or Visual Studio Build Tools (Windows)."},
82
+ )
83
+
84
+
85
+ def _run(
86
+ argv: List[str],
87
+ *,
88
+ cwd: Optional[str] = None,
89
+ env: Optional[dict] = None,
90
+ log_callback: Optional[Callable[[str], None]] = None,
91
+ ) -> None:
92
+ """Run a subprocess, streaming output through ``log_callback``.
93
+
94
+ Uses argv lists (never ``shell=True``) and raises
95
+ :class:`WhisperSetupError` on non-zero exit so callers don't have to
96
+ distinguish between :class:`FileNotFoundError` and
97
+ :class:`subprocess.CalledProcessError`.
98
+ """
99
+ pretty = " ".join(argv)
100
+ logger.info("$ %s%s", pretty, f" (cwd={cwd})" if cwd else "")
101
+ if log_callback:
102
+ log_callback(f"$ {pretty}")
103
+
104
+ try:
105
+ completed = subprocess.run(
106
+ argv,
107
+ cwd=cwd,
108
+ env=env,
109
+ check=False,
110
+ capture_output=True,
111
+ text=True,
112
+ )
113
+ except FileNotFoundError as e:
114
+ raise WhisperSetupError(
115
+ f"Could not invoke `{argv[0]}`: not found on PATH.",
116
+ details={"argv": argv},
117
+ cause=e,
118
+ )
119
+
120
+ if completed.stdout:
121
+ logger.debug(completed.stdout)
122
+ if completed.stderr:
123
+ logger.debug(completed.stderr)
124
+
125
+ if completed.returncode != 0:
126
+ # Surface the actual stderr so users can act on the failure
127
+ # (missing header, OpenMP not found, etc.) rather than a generic
128
+ # "build failed".
129
+ tail = (completed.stderr or completed.stdout or "").strip()
130
+ raise WhisperSetupError(
131
+ f"Command failed (exit {completed.returncode}): {pretty}",
132
+ details={
133
+ "argv": argv,
134
+ "cwd": cwd,
135
+ "stderr_tail": tail[-2000:] if tail else "",
136
+ },
137
+ )
138
+
139
+
140
+ def _git_already_at(src_dir: str, repo_url: str) -> bool:
141
+ """Return True iff ``src_dir`` is a git repo whose ``origin`` matches."""
142
+ git_dir = os.path.join(src_dir, ".git")
143
+ if not os.path.isdir(git_dir):
144
+ return False
145
+ try:
146
+ out = subprocess.check_output(
147
+ ["git", "config", "--get", "remote.origin.url"],
148
+ cwd=src_dir,
149
+ stderr=subprocess.DEVNULL,
150
+ text=True,
151
+ ).strip()
152
+ except (subprocess.CalledProcessError, FileNotFoundError):
153
+ return False
154
+ # Tolerate ssh-vs-https and trailing-.git differences.
155
+ norm_local = out.rstrip("/").removesuffix(".git").lower()
156
+ norm_repo = repo_url.rstrip("/").removesuffix(".git").lower()
157
+ return norm_local.endswith(norm_repo.split("github.com/")[-1])
158
+
159
+
160
+ def setup_whisper(
161
+ repo_url: str = DEFAULT_REPO_URL,
162
+ ref: str = DEFAULT_REF,
163
+ force: bool = False,
164
+ pull: bool = True,
165
+ log_callback: Optional[Callable[[str], None]] = None,
166
+ ) -> WhisperSetupResult:
167
+ """Clone, build, and install whisper.cpp into the user data dir.
168
+
169
+ Args:
170
+ repo_url: Git URL of the whisper.cpp source. Defaults to the
171
+ project's compatible fork.
172
+ ref: Branch, tag, or commit to check out.
173
+ force: If True, wipe any existing source tree and start clean.
174
+ pull: If False, skip ``git fetch / pull`` for an existing checkout
175
+ (useful for reproducible offline rebuilds).
176
+ log_callback: Optional callable for streaming human-readable
177
+ progress lines to the CLI.
178
+
179
+ Returns:
180
+ :class:`WhisperSetupResult` with the absolute binary path.
181
+
182
+ Raises:
183
+ WhisperSetupError: With actionable details if any step fails.
184
+ """
185
+ # 1. Toolchain pre-flight. Done before any network / disk work so we
186
+ # bail fast on missing deps without leaving half-built state.
187
+ git = _check_dependency("git")
188
+ cmake = _check_dependency("cmake")
189
+ _check_cxx_compiler()
190
+
191
+ data_dir = default_data_dir()
192
+ src_dir = os.path.join(data_dir, "whisper.cpp")
193
+ bin_target = installed_whisper_binary_target()
194
+ bin_dir = os.path.dirname(bin_target)
195
+ build_dir = os.path.join(src_dir, "build")
196
+
197
+ os.makedirs(data_dir, exist_ok=True)
198
+
199
+ if log_callback:
200
+ log_callback(f"[setup-whisper] data dir: {data_dir}")
201
+ log_callback(f"[setup-whisper] repo: {repo_url}@{ref}")
202
+
203
+ # 2. Clone (or refresh) the source tree.
204
+ if force and os.path.isdir(src_dir):
205
+ if log_callback:
206
+ log_callback("[setup-whisper] --force: removing existing checkout")
207
+ shutil.rmtree(src_dir)
208
+
209
+ if not os.path.isdir(src_dir):
210
+ if log_callback:
211
+ log_callback(f"[setup-whisper] cloning {repo_url}")
212
+ _run(
213
+ [git, "clone", "--depth", "1", "--branch", ref, repo_url, src_dir],
214
+ log_callback=log_callback,
215
+ )
216
+ else:
217
+ if not _git_already_at(src_dir, repo_url):
218
+ raise WhisperSetupError(
219
+ f"Existing checkout at {src_dir} points at a different "
220
+ f"remote. Re-run with --force to wipe and re-clone.",
221
+ details={"src_dir": src_dir, "expected_remote": repo_url},
222
+ )
223
+ if pull:
224
+ if log_callback:
225
+ log_callback(f"[setup-whisper] updating {src_dir} -> {ref}")
226
+ _run([git, "fetch", "--depth", "1", "origin", ref],
227
+ cwd=src_dir, log_callback=log_callback)
228
+ _run([git, "checkout", ref],
229
+ cwd=src_dir, log_callback=log_callback)
230
+ # Hard reset to remote ref so local edits never block a build.
231
+ _run([git, "reset", "--hard", f"origin/{ref}"],
232
+ cwd=src_dir, log_callback=log_callback)
233
+
234
+ # 3. Configure + build with CMake. CMake is more portable than the
235
+ # bare Makefile (it handles MSVC on Windows) and matches what
236
+ # upstream whisper.cpp recommends for >=1.7.x.
237
+ if log_callback:
238
+ log_callback("[setup-whisper] configuring with cmake")
239
+ _run(
240
+ [
241
+ cmake,
242
+ "-B", build_dir,
243
+ "-S", src_dir,
244
+ "-DCMAKE_BUILD_TYPE=Release",
245
+ # Keep examples (whisper-cli is one of them) on by default.
246
+ "-DBUILD_SHARED_LIBS=OFF",
247
+ "-DWHISPER_BUILD_EXAMPLES=ON",
248
+ "-DWHISPER_BUILD_TESTS=OFF",
249
+ ],
250
+ log_callback=log_callback,
251
+ )
252
+
253
+ if log_callback:
254
+ log_callback("[setup-whisper] building (this takes ~30-90s)")
255
+ build_argv = [cmake, "--build", build_dir, "--config", "Release"]
256
+ if sys.platform != "win32":
257
+ # CMake on Unix passes -j through to the underlying generator;
258
+ # on Windows MSBuild has its own /m flag and ignores -j.
259
+ build_argv.extend(["-j"])
260
+ _run(build_argv, log_callback=log_callback)
261
+
262
+ # 4. Locate the freshly-built binary. CMake puts examples in
263
+ # build/bin/<config>/ on multi-config generators (MSVC) and
264
+ # build/bin/ on single-config (Unix Makefiles, Ninja).
265
+ candidates = [
266
+ os.path.join(build_dir, "bin", "whisper-cli"),
267
+ os.path.join(build_dir, "bin", "whisper-cli.exe"),
268
+ os.path.join(build_dir, "bin", "Release", "whisper-cli.exe"),
269
+ os.path.join(build_dir, "bin", "Release", "whisper-cli"),
270
+ os.path.join(src_dir, "whisper-cli"), # legacy Makefile output
271
+ os.path.join(src_dir, "main"), # very old upstream name
272
+ ]
273
+ built = next(
274
+ (p for p in candidates if os.path.isfile(p) and os.access(p, os.X_OK)),
275
+ None,
276
+ )
277
+ if not built:
278
+ raise WhisperSetupError(
279
+ "Build succeeded but the whisper-cli binary could not be located.",
280
+ details={"searched": candidates, "build_dir": build_dir},
281
+ )
282
+
283
+ # 5. Install into the canonical user-data location. We copy (not
284
+ # symlink) so the binary is independent of a `--force`-driven
285
+ # rebuild that wipes ``src_dir``.
286
+ os.makedirs(bin_dir, exist_ok=True)
287
+ if os.path.exists(bin_target):
288
+ os.remove(bin_target)
289
+ shutil.copy2(built, bin_target)
290
+ os.chmod(bin_target, 0o755)
291
+
292
+ # 6. Smoke-test the installed binary so we don't return success on
293
+ # something that won't run (wrong glibc, broken signing, etc.).
294
+ try:
295
+ subprocess.run(
296
+ [bin_target, "-h"],
297
+ check=True,
298
+ capture_output=True,
299
+ timeout=15,
300
+ )
301
+ except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
302
+ raise WhisperSetupError(
303
+ f"Installed binary at {bin_target} did not pass `-h` smoke test.",
304
+ details={"binary": bin_target},
305
+ cause=e,
306
+ )
307
+
308
+ if log_callback:
309
+ log_callback(f"[setup-whisper] installed: {bin_target}")
310
+
311
+ return WhisperSetupResult(
312
+ binary_path=bin_target,
313
+ source_dir=src_dir,
314
+ repo_url=repo_url,
315
+ ref=ref,
316
+ )
@@ -32,4 +32,5 @@ subtitle_generator/utils/exceptions.py
32
32
  subtitle_generator/utils/file_handler.py
33
33
  subtitle_generator/utils/formatters.py
34
34
  subtitle_generator/utils/paths.py
35
- subtitle_generator/utils/validators.py
35
+ subtitle_generator/utils/validators.py
36
+ subtitle_generator/utils/whisper_setup.py