subtitle-generator 3.0.2__tar.gz → 3.0.4__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.4}/PKG-INFO +42 -15
  2. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/PYPI_README.md +41 -14
  3. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/pyproject.toml +1 -1
  4. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/__init__.py +1 -1
  5. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/cli/commands.py +165 -13
  6. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/subtitle_gen.py +49 -16
  7. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/paths.py +101 -23
  8. subtitle_generator-3.0.4/subtitle_generator/utils/whisper_setup.py +316 -0
  9. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator.egg-info/SOURCES.txt +2 -1
  10. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/CONTRIBUTING.md +0 -0
  11. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/LICENSE +0 -0
  12. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/MANIFEST.in +0 -0
  13. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/README.md +0 -0
  14. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/config/default.yaml +0 -0
  15. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/docs/API.md +0 -0
  16. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/docs/PACKAGING.md +0 -0
  17. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/docs/TROUBLESHOOTING.md +0 -0
  18. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/docs/example.md +0 -0
  19. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/environment.yml +0 -0
  20. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/requirements.txt +0 -0
  21. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/setup.cfg +0 -0
  22. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/setup.py +0 -0
  23. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/cli/__init__.py +0 -0
  24. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/config/__init__.py +0 -0
  25. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/config/config_loader.py +0 -0
  26. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/config/settings.py +0 -0
  27. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/__init__.py +0 -0
  28. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/async_processor.py +0 -0
  29. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/batch_processor.py +0 -0
  30. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/transcriber.py +0 -0
  31. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/core/video_processor.py +0 -0
  32. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/models/__init__.py +0 -0
  33. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/models/model_manager.py +0 -0
  34. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/__init__.py +0 -0
  35. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/downloader.py +0 -0
  36. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/exceptions.py +0 -0
  37. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/file_handler.py +0 -0
  38. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/subtitle_generator/utils/formatters.py +0 -0
  39. {subtitle_generator-3.0.2 → subtitle_generator-3.0.4}/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.4
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,31 +83,49 @@ 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
+
89
+ ```bash
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
+
87
100
  ```bash
88
- # macOS (recommended — also adds the binary to your PATH)
89
- brew install whisper-cpp
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
 
109
127
  ```bash
110
- # Generate subtitles (VTT format)
128
+ # Generate subtitles (VTT format) into the current directory
111
129
  subtitle video.mp4
112
130
 
113
131
  # Generate SRT format
@@ -118,8 +136,14 @@ subtitle video.mp4 --merge
118
136
 
119
137
  # Use a larger model for better accuracy
120
138
  subtitle video.mp4 --model large
139
+
140
+ # Route output somewhere other than the current directory
141
+ subtitle /path/to/video.mp4 --output-dir ~/subs
121
142
  ```
122
143
 
144
+ > Output lands in the directory you ran the command from (or `--output-dir`
145
+ > if you pass it), regardless of where the input video lives.
146
+
123
147
  ## CLI Commands
124
148
 
125
149
  | Command | Description |
@@ -135,9 +159,12 @@ subtitle video.mp4 --model large
135
159
  | Option | Description |
136
160
  |--------|-------------|
137
161
  | `--model`, `-m` | Model to use: tiny, base, small, medium, large |
138
- | `--format`, `-f` | Output format: vtt, srt, txt, json, lrc, ass, ttml |
162
+ | `--format`, `-f` | Output format: vtt, srt, txt, json, lrc |
139
163
  | `--merge` | Embed subtitles into the video file |
164
+ | `--output-dir`, `-o` | Where to write the subtitle (default: current dir) |
140
165
  | `--threads`, `-t` | Number of processing threads |
166
+ | `--whisper-binary` | Override the auto-discovered whisper-cli path |
167
+ | `--models-dir` | Override the model cache directory |
141
168
  | `--verbose`, `-v` | Enable verbose output |
142
169
 
143
170
  ## Python API
@@ -38,31 +38,49 @@ 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
+
44
+ ```bash
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
+
42
55
  ```bash
43
- # macOS (recommended — also adds the binary to your PATH)
44
- brew install whisper-cpp
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
 
64
82
  ```bash
65
- # Generate subtitles (VTT format)
83
+ # Generate subtitles (VTT format) into the current directory
66
84
  subtitle video.mp4
67
85
 
68
86
  # Generate SRT format
@@ -73,8 +91,14 @@ subtitle video.mp4 --merge
73
91
 
74
92
  # Use a larger model for better accuracy
75
93
  subtitle video.mp4 --model large
94
+
95
+ # Route output somewhere other than the current directory
96
+ subtitle /path/to/video.mp4 --output-dir ~/subs
76
97
  ```
77
98
 
99
+ > Output lands in the directory you ran the command from (or `--output-dir`
100
+ > if you pass it), regardless of where the input video lives.
101
+
78
102
  ## CLI Commands
79
103
 
80
104
  | Command | Description |
@@ -90,9 +114,12 @@ subtitle video.mp4 --model large
90
114
  | Option | Description |
91
115
  |--------|-------------|
92
116
  | `--model`, `-m` | Model to use: tiny, base, small, medium, large |
93
- | `--format`, `-f` | Output format: vtt, srt, txt, json, lrc, ass, ttml |
117
+ | `--format`, `-f` | Output format: vtt, srt, txt, json, lrc |
94
118
  | `--merge` | Embed subtitles into the video file |
119
+ | `--output-dir`, `-o` | Where to write the subtitle (default: current dir) |
95
120
  | `--threads`, `-t` | Number of processing threads |
121
+ | `--whisper-binary` | Override the auto-discovered whisper-cli path |
122
+ | `--models-dir` | Override the model cache directory |
96
123
  | `--verbose`, `-v` | Enable verbose output |
97
124
 
98
125
  ## Python API
@@ -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.4"
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.4"
@@ -7,6 +7,7 @@ with progress callbacks and rich output.
7
7
 
8
8
  import argparse
9
9
  import logging
10
+ import os
10
11
  import sys
11
12
  from abc import ABC, abstractmethod
12
13
  from typing import Optional
@@ -188,11 +189,15 @@ class SubtitleCLI:
188
189
  self.observer.on_error(f"Download failed: {e}")
189
190
  return 1
190
191
 
191
- # Sanitize filename if needed
192
+ # Sanitize filename if needed. (Note: this still mutates the
193
+ # user's source file path. With argv-based subprocess invocation
194
+ # in 3.0.2+ it is no longer strictly necessary to do this for
195
+ # whisper-cli to accept the path, but we keep it to match the
196
+ # historical behaviour of moving the renamed file forward
197
+ # through validation.)
192
198
  if " " in filepath:
193
199
  new_path = sanitize_filename(filepath)
194
200
  if new_path != filepath:
195
- import os
196
201
  os.rename(filepath, new_path)
197
202
  filepath = new_path
198
203
 
@@ -230,36 +235,53 @@ class SubtitleCLI:
230
235
  def progress_callback(stage: str, progress: float):
231
236
  self.observer.on_progress(stage, progress)
232
237
 
238
+ # Where the final subtitle file lands. Default = current working
239
+ # directory; an absolute or relative path may be supplied via
240
+ # ``--output-dir``. We use the input's *basename* so that
241
+ # ``subtitle /Users/me/videos/foo.mp4`` produces ``./foo.srt`` in
242
+ # the user's CWD, never scribbling next to the input video.
243
+ target_dir = os.path.abspath(args.output_dir) if args.output_dir else os.getcwd()
244
+ os.makedirs(target_dir, exist_ok=True)
245
+ input_basename = os.path.splitext(os.path.basename(filepath))[0]
246
+ final_subtitle_path = os.path.join(
247
+ target_dir, f"{input_basename}.{output_format}"
248
+ )
249
+
233
250
  subtitle_path, success = generator.generate_and_rename(
234
251
  input_path=filepath,
235
252
  model_name=model,
236
253
  output_format=output_format,
237
254
  output_dir=default_output_dir(),
255
+ output_path=final_subtitle_path,
238
256
  progress_callback=progress_callback,
239
257
  )
240
-
258
+
241
259
  if not success:
242
260
  self.observer.on_error("Transcription failed")
243
261
  return 1
244
-
245
- # Merge subtitles into video if requested
262
+
246
263
  if merge:
247
264
  self.observer.on_progress("merging", 0.0)
248
265
  processor = VideoProcessor()
249
-
250
- import os
251
- base, ext = os.path.splitext(filepath)
252
- output_path = f"{base}_subtitled{ext}"
253
-
254
- if processor.merge_subtitles(filepath, subtitle_path, output_path):
266
+
267
+ # Mirror the subtitle's "land in CWD" behaviour for the
268
+ # merged video too: a user who ran the command from ~/work
269
+ # expects ~/work/video_subtitled.mp4, not the input video's
270
+ # neighbour.
271
+ input_ext = os.path.splitext(filepath)[1] or ".mp4"
272
+ merged_output_path = os.path.join(
273
+ target_dir, f"{input_basename}_subtitled{input_ext}"
274
+ )
275
+
276
+ if processor.merge_subtitles(filepath, subtitle_path, merged_output_path):
255
277
  self.observer.on_progress("merging", 1.0)
256
- self.observer.on_complete(True, output_path)
278
+ self.observer.on_complete(True, merged_output_path)
257
279
  else:
258
280
  self.observer.on_error("Failed to merge subtitles")
259
281
  return 1
260
282
  else:
261
283
  self.observer.on_complete(True, subtitle_path)
262
-
284
+
263
285
  return 0
264
286
 
265
287
  def _handle_models_command(self, args: argparse.Namespace) -> int:
@@ -396,6 +418,9 @@ def create_main_parser() -> argparse.ArgumentParser:
396
418
  description="Generate subtitles for video files using Whisper",
397
419
  formatter_class=argparse.RawDescriptionHelpFormatter,
398
420
  epilog="""
421
+ First-time setup (one-time):
422
+ subtitle setup-whisper Build the whisper-cli binary
423
+
399
424
  Examples:
400
425
  subtitle video.mp4 Generate VTT subtitles
401
426
  subtitle video.mp4 --merge Generate and embed subtitles
@@ -448,6 +473,19 @@ Examples:
448
473
  action="store_true",
449
474
  help="Verbose output",
450
475
  )
476
+ parser.add_argument(
477
+ "--output-dir", "-o",
478
+ type=str,
479
+ default=None,
480
+ metavar="DIR",
481
+ help=(
482
+ "Directory to write the subtitle file (and, with --merge, the "
483
+ "embedded video). Defaults to the current working directory, "
484
+ "which is usually what you want — running `subtitle "
485
+ "/some/elsewhere/video.mp4` no longer scribbles into "
486
+ "/some/elsewhere/."
487
+ ),
488
+ )
451
489
  parser.add_argument(
452
490
  "--whisper-binary",
453
491
  type=str,
@@ -500,6 +538,62 @@ def create_models_parser() -> argparse.ArgumentParser:
500
538
  return parser
501
539
 
502
540
 
541
+ def create_setup_whisper_parser() -> argparse.ArgumentParser:
542
+ """Create parser for the `setup-whisper` subcommand.
543
+
544
+ The subcommand builds whisper.cpp from source into the user data
545
+ directory so the rest of the CLI can auto-discover the binary on
546
+ every subsequent invocation, without manual env vars or PATH
547
+ manipulation.
548
+ """
549
+ parser = argparse.ArgumentParser(
550
+ prog="subtitle setup-whisper",
551
+ description=(
552
+ "Clone, build, and install the whisper.cpp CLI into your "
553
+ "per-OS user data dir. One-time setup; auto-discovered "
554
+ "afterwards."
555
+ ),
556
+ formatter_class=argparse.RawDescriptionHelpFormatter,
557
+ epilog="""
558
+ Examples:
559
+ subtitle setup-whisper Build the default fork (recommended)
560
+ subtitle setup-whisper --force Wipe existing checkout and rebuild
561
+ subtitle setup-whisper --no-pull Rebuild offline from current sources
562
+ subtitle setup-whisper --ref v1.7.4 Pin to a specific tag/branch/commit
563
+
564
+ Requires git, cmake, and a C++ compiler on PATH.
565
+ """,
566
+ )
567
+ parser.add_argument(
568
+ "--repo",
569
+ type=str,
570
+ default=None,
571
+ metavar="URL",
572
+ help=(
573
+ "Git URL of the whisper.cpp source. Defaults to the project's "
574
+ "compatible fork (innovatorved/whisper.cpp)."
575
+ ),
576
+ )
577
+ parser.add_argument(
578
+ "--ref",
579
+ type=str,
580
+ default=None,
581
+ metavar="REF",
582
+ help="Branch, tag, or commit to check out (default: develop).",
583
+ )
584
+ parser.add_argument(
585
+ "--force",
586
+ action="store_true",
587
+ help="Wipe any existing checkout and re-clone from scratch.",
588
+ )
589
+ parser.add_argument(
590
+ "--no-pull",
591
+ action="store_true",
592
+ help="Skip `git fetch / pull` on an existing checkout (offline rebuild).",
593
+ )
594
+ return parser
595
+
596
+
503
597
  def create_batch_parser() -> argparse.ArgumentParser:
504
598
  """Create parser for batch subcommand."""
505
599
  parser = argparse.ArgumentParser(
@@ -571,6 +665,59 @@ Examples:
571
665
  return parser
572
666
 
573
667
 
668
+ def _handle_setup_whisper_command(args: argparse.Namespace) -> int:
669
+ """Handle the ``subtitle setup-whisper`` subcommand.
670
+
671
+ Kept at module scope (rather than as a method on ``SubtitleCLI``) so
672
+ that triggering the build doesn't require constructing a
673
+ ``ModelManager`` — useful when the user is running ``setup-whisper``
674
+ precisely because nothing works yet.
675
+ """
676
+ # Local import: keeps the heavy build logic out of CLI startup time
677
+ # for the 99% of invocations that aren't `setup-whisper`.
678
+ from ..utils.whisper_setup import (
679
+ DEFAULT_REF,
680
+ DEFAULT_REPO_URL,
681
+ WhisperSetupError,
682
+ setup_whisper,
683
+ )
684
+
685
+ repo = args.repo or DEFAULT_REPO_URL
686
+ ref = args.ref or DEFAULT_REF
687
+ force = bool(args.force)
688
+ pull = not bool(getattr(args, "no_pull", False))
689
+
690
+ print(f"[setup-whisper] repo={repo} ref={ref} force={force} pull={pull}")
691
+
692
+ def _stream(line: str) -> None:
693
+ print(line, flush=True)
694
+
695
+ try:
696
+ result = setup_whisper(
697
+ repo_url=repo,
698
+ ref=ref,
699
+ force=force,
700
+ pull=pull,
701
+ log_callback=_stream,
702
+ )
703
+ except WhisperSetupError as e:
704
+ print(f"\n[ERROR] setup-whisper failed: {e}", file=sys.stderr)
705
+ return 1
706
+ except KeyboardInterrupt:
707
+ print("\n\nOperation cancelled.", file=sys.stderr)
708
+ return 130
709
+
710
+ print(
711
+ "\n[DONE] whisper-cli installed.\n"
712
+ f" binary: {result.binary_path}\n"
713
+ f" source: {result.source_dir}\n"
714
+ f" ref: {result.ref}\n"
715
+ "You can now run `subtitle <video>` from anywhere — the binary "
716
+ "will be auto-discovered."
717
+ )
718
+ return 0
719
+
720
+
574
721
  def main(args: Optional[list[str]] = None) -> int:
575
722
  """Main entry point for CLI."""
576
723
  if args is None:
@@ -589,6 +736,11 @@ def main(args: Optional[list[str]] = None) -> int:
589
736
  cli = SubtitleCLI()
590
737
  return cli._handle_formats_command()
591
738
 
739
+ if args and args[0] == "setup-whisper":
740
+ parser = create_setup_whisper_parser()
741
+ parsed_args = parser.parse_args(args[1:])
742
+ return _handle_setup_whisper_command(parsed_args)
743
+
592
744
  if args and args[0] == "batch":
593
745
  parser = create_batch_parser()
594
746
  parsed_args = parser.parse_args(args[1:])
@@ -7,6 +7,7 @@ using the transcriber strategy and handling the overall workflow.
7
7
 
8
8
  import logging
9
9
  import os
10
+ import shutil
10
11
  from typing import Optional, Callable
11
12
 
12
13
  from .transcriber import TranscriberStrategy, TranscriptionResult
@@ -103,21 +104,33 @@ class SubtitleGenerator:
103
104
  model_name: str = "base",
104
105
  output_format: str = "vtt",
105
106
  output_dir: str = "data",
107
+ output_path: Optional[str] = None,
106
108
  progress_callback: Optional[Callable[[str, float], None]] = None,
107
109
  ) -> tuple[str, bool]:
108
110
  """
109
- Generate subtitles and rename output to match input filename.
111
+ Generate subtitles and move the result to a final location.
110
112
 
111
113
  Args:
112
- input_path: Path to input audio/video file
113
- model_name: Name of the model to use
114
- output_format: Output subtitle format
115
- output_dir: Directory for the transient transcription output
116
- (the file is renamed next to ``input_path`` afterwards).
117
- progress_callback: Optional callback for progress updates
114
+ input_path: Path to input audio/video file.
115
+ model_name: Name of the model to use.
116
+ output_format: Output subtitle format.
117
+ output_dir: Directory for the transient transcription output.
118
+ Whisper.cpp writes a UUID-prefixed file here; it is then
119
+ moved to the final target. Use a temp-style dir to keep
120
+ this from polluting the user's CWD.
121
+ output_path: Optional explicit destination (an absolute or
122
+ relative file path including extension). When ``None``
123
+ (the historic default), the result is renamed to sit
124
+ next to ``input_path`` as ``<input>.<output_format>``.
125
+ CLI callers pass an explicit value so the user gets the
126
+ output in the directory they ran the command from,
127
+ regardless of where the input video lives.
128
+ progress_callback: Optional callback for progress updates.
118
129
 
119
130
  Returns:
120
- Tuple of (output_path, success)
131
+ Tuple of (final_output_path, success). On rename failure the
132
+ transient path is returned with ``success=True`` so callers
133
+ can still surface the file to the user.
121
134
  """
122
135
  result = self.generate(
123
136
  input_path=input_path,
@@ -126,21 +139,41 @@ class SubtitleGenerator:
126
139
  output_dir=output_dir,
127
140
  progress_callback=progress_callback,
128
141
  )
129
-
142
+
130
143
  if not result.success:
131
144
  return ("", False)
132
-
133
- # Rename to match input file
134
- base, _ = os.path.splitext(input_path)
135
- final_output_path = f"{base}.{output_format}"
136
-
145
+
146
+ if output_path:
147
+ final_output_path = output_path
148
+ else:
149
+ base, _ = os.path.splitext(input_path)
150
+ final_output_path = f"{base}.{output_format}"
151
+
137
152
  try:
138
153
  if os.path.exists(result.output_path):
139
- os.rename(result.output_path, final_output_path)
154
+ # Make sure the destination directory exists before moving;
155
+ # callers may legitimately point at a path under a CWD that
156
+ # only has the file's parent, not the file.
157
+ final_dir = os.path.dirname(final_output_path)
158
+ if final_dir:
159
+ os.makedirs(final_dir, exist_ok=True)
160
+ # If the destination already exists (re-run, --force-style
161
+ # repeat) remove it first, since `shutil.move` on most
162
+ # platforms refuses to overwrite an existing regular file.
163
+ if os.path.isfile(final_output_path):
164
+ os.remove(final_output_path)
165
+ # `shutil.move` falls back to copy-then-delete when the
166
+ # source and destination are on different filesystems
167
+ # (common when /tmp is a tmpfs or a separate Docker
168
+ # volume), unlike `os.rename` which raises EXDEV.
169
+ shutil.move(result.output_path, final_output_path)
140
170
  logger.info(f"Renamed output to: {final_output_path}")
141
171
  return (final_output_path, True)
142
172
  except OSError as e:
173
+ # Cross-device rename or non-writable parent dir. Surface the
174
+ # transient path so the user can still copy it manually
175
+ # rather than losing a successful transcription.
143
176
  logger.error(f"Failed to rename output: {e}")
144
177
  return (result.output_path, True)
145
-
178
+
146
179
  return (result.output_path, True)
@@ -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