babelscribe 0.3.2__tar.gz → 0.4.0__tar.gz

{babelscribe-0.3.2 → babelscribe-0.4.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 babelscribe contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 babelscribe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{babelscribe-0.3.2 → babelscribe-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: babelscribe
-Version: 0.3.2
+Version: 0.4.0
 Summary: Transcribe any audio/video in 99 languages on any GPU (AMD, NVIDIA, Intel via Vulkan; NVIDIA via CUDA; Apple via Metal) or CPU — whisper.cpp with batteries included.
 License: MIT
 Project-URL: Homepage, https://github.com/phonology024/babelscribe
@@ -216,14 +216,20 @@ languages are the most valuable contribution.
 - **Long files that don't loop** — runs whisper with `--max-context 0`, which stops the classic "same sentence repeated forever" hallucination on long recordings.
 - **Hybrid mode for better spelling in your language** — community fine-tunes (e.g. Thai *Thonburian Whisper*) spell far better but often lose timestamps. `--text-model` takes the text from the fine-tune and the timing from `large-v3-turbo`, aligned character by character (works for languages without spaces), cut only at word boundaries, with the timing model filling any words the fine-tune skipped.
 - **`--accurate`** — slower, fewest errors: large-v3 with beam search, or for Thai and Hindi the best community fine-tune (hybrid). Chosen per language from the FLEURS benchmark above.
-- **Outputs** — `srt`, `vtt`, `txt`, `json` (segments with token timings).
+- **Custom vocabulary** — `--prompt "Pitakpong, babelscribe"` gives whisper an initial prompt that biases the spelling of names and jargon. In the MCP `transcribe` tool the same thing is the `vocabulary` argument. While a prompt is set, `--max-context 0` is not passed (whisper.cpp ignores the prompt otherwise).
+- **Translate to English** — `--translate` writes the transcript translated to English (whisper's translate task, any source language). It uses `large-v3` because turbo was not trained to translate, and cannot be combined with `--text-model`. In the MCP `transcribe` tool it is the `translate` argument.
+- **Outputs** — `srt`, `vtt`, `txt`, `json` (segments with token timings), `ass` (karaoke: each word highlights
+  as it is spoken, from the token timings — for short-form video and players that read ASS).
 
 ## Usage
 ```bash
 babelscribe talk.mp4 -f srt,vtt,txt,json          # all formats
+babelscribe reel.mp4 -f ass                        # karaoke subtitles, one highlight per word
 babelscribe podcast.mp3 -l en -m large-v3          # pick language and model
 babelscribe talk.mp4 -l hi --accurate              # slower, fewest errors (best model per language)
 babelscribe vo.wav -l th --text-model thai-thonburian   # hybrid: pick a Thai fine-tune yourself
+babelscribe talk.mp4 --prompt "Pitakpong, babelscribe"   # bias the spelling of names and terms
+babelscribe talk.mp4 --translate                   # subtitles translated to English
 babelscribe devices                                # GPUs whisper.cpp can see
 babelscribe models                                 # models and fine-tunes
 babelscribe talk.mp4 --bin /path/to/whisper-cli    # use your own whisper.cpp build
@@ -231,13 +237,16 @@ babelscribe talk.mp4 --bin /path/to/whisper-cli    # use your own whisper.cpp bu
 From Python:
 ```python
 from babelscribe.api import transcribe_file
-r = transcribe_file("talk.mp4", lang="auto", formats=["srt", "txt"])   # or accurate=True
+r = transcribe_file("talk.mp4", lang="auto", formats=["srt", "txt"])   # or accurate=True, prompt="names, terms"
 print(r["lang"], r["device"], r["files"]); print(r["text"][:200])
 ```
 Models download on first use to `~/.babelscribe/models` (`BABELSCRIBE_MODELS` to change). Hybrid fine-tunes are converted on your
 machine from their original Hugging Face repo — install `pip install "babelscribe[finetune]"` once; converted weights are never
 redistributed, so each fine-tune keeps its own licence. Thai word boundaries: `pip install "babelscribe[thai]"`.
 
+## Roadmap
+What's planned next (subtitle line wrapping, MCP progress for long files, folder batches, translate-to-English, more fine-tunes) is in [ROADMAP.md](ROADMAP.md) and the [open issues](https://github.com/phonology024/babelscribe/issues).
+
 ## Add a language fine-tune
 Add one entry to `FINETUNES` in `babelscribe/models.py` (Hugging Face repo, language code, whether it needs beam search) and open a PR.
 

{babelscribe-0.3.2 → babelscribe-0.4.0}/README.md

@@ -173,14 +173,20 @@ languages are the most valuable contribution.
 - **Long files that don't loop** — runs whisper with `--max-context 0`, which stops the classic "same sentence repeated forever" hallucination on long recordings.
 - **Hybrid mode for better spelling in your language** — community fine-tunes (e.g. Thai *Thonburian Whisper*) spell far better but often lose timestamps. `--text-model` takes the text from the fine-tune and the timing from `large-v3-turbo`, aligned character by character (works for languages without spaces), cut only at word boundaries, with the timing model filling any words the fine-tune skipped.
 - **`--accurate`** — slower, fewest errors: large-v3 with beam search, or for Thai and Hindi the best community fine-tune (hybrid). Chosen per language from the FLEURS benchmark above.
-- **Outputs** — `srt`, `vtt`, `txt`, `json` (segments with token timings).
+- **Custom vocabulary** — `--prompt "Pitakpong, babelscribe"` gives whisper an initial prompt that biases the spelling of names and jargon. In the MCP `transcribe` tool the same thing is the `vocabulary` argument. While a prompt is set, `--max-context 0` is not passed (whisper.cpp ignores the prompt otherwise).
+- **Translate to English** — `--translate` writes the transcript translated to English (whisper's translate task, any source language). It uses `large-v3` because turbo was not trained to translate, and cannot be combined with `--text-model`. In the MCP `transcribe` tool it is the `translate` argument.
+- **Outputs** — `srt`, `vtt`, `txt`, `json` (segments with token timings), `ass` (karaoke: each word highlights
+  as it is spoken, from the token timings — for short-form video and players that read ASS).
 
 ## Usage
 ```bash
 babelscribe talk.mp4 -f srt,vtt,txt,json          # all formats
+babelscribe reel.mp4 -f ass                        # karaoke subtitles, one highlight per word
 babelscribe podcast.mp3 -l en -m large-v3          # pick language and model
 babelscribe talk.mp4 -l hi --accurate              # slower, fewest errors (best model per language)
 babelscribe vo.wav -l th --text-model thai-thonburian   # hybrid: pick a Thai fine-tune yourself
+babelscribe talk.mp4 --prompt "Pitakpong, babelscribe"   # bias the spelling of names and terms
+babelscribe talk.mp4 --translate                   # subtitles translated to English
 babelscribe devices                                # GPUs whisper.cpp can see
 babelscribe models                                 # models and fine-tunes
 babelscribe talk.mp4 --bin /path/to/whisper-cli    # use your own whisper.cpp build
@@ -188,13 +194,16 @@ babelscribe talk.mp4 --bin /path/to/whisper-cli    # use your own whisper.cpp bu
 From Python:
 ```python
 from babelscribe.api import transcribe_file
-r = transcribe_file("talk.mp4", lang="auto", formats=["srt", "txt"])   # or accurate=True
+r = transcribe_file("talk.mp4", lang="auto", formats=["srt", "txt"])   # or accurate=True, prompt="names, terms"
 print(r["lang"], r["device"], r["files"]); print(r["text"][:200])
 ```
 Models download on first use to `~/.babelscribe/models` (`BABELSCRIBE_MODELS` to change). Hybrid fine-tunes are converted on your
 machine from their original Hugging Face repo — install `pip install "babelscribe[finetune]"` once; converted weights are never
 redistributed, so each fine-tune keeps its own licence. Thai word boundaries: `pip install "babelscribe[thai]"`.
 
+## Roadmap
+What's planned next (subtitle line wrapping, MCP progress for long files, folder batches, translate-to-English, more fine-tunes) is in [ROADMAP.md](ROADMAP.md) and the [open issues](https://github.com/phonology024/babelscribe/issues).
+
 ## Add a language fine-tune
 Add one entry to `FINETUNES` in `babelscribe/models.py` (Hugging Face repo, language code, whether it needs beam search) and open a PR.
 

{babelscribe-0.3.2 → babelscribe-0.4.0}/babelscribe/__init__.py

@@ -1,2 +1,2 @@
-"""babelscribe — any language, any GPU speech-to-text built on whisper.cpp."""
-__version__ = "0.3.2"
+"""babelscribe — any language, any GPU speech-to-text built on whisper.cpp."""
+__version__ = "0.4.0"

{babelscribe-0.3.2 → babelscribe-0.4.0}/babelscribe/__main__.py

@@ -1,3 +1,3 @@
-from .cli import main
-
-main()
+from .cli import main
+
+main()

babelscribe-0.4.0/babelscribe/api.py

@@ -0,0 +1,105 @@
+"""One function the CLI and the MCP server share: media file in -> subtitle/transcript files out."""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Callable
+
+from . import __version__, backend, hybrid, models, transcribe, writers
+
+
+def _quantizer(binary: Path) -> Path:
+    return binary.parent / ("whisper-quantize.exe" if binary.suffix == ".exe" else "whisper-quantize")
+
+
+def _device_id(device: str | int, found: list[dict]) -> int:
+    """Turn a user-supplied device into an id whisper.cpp actually reported.
+
+    `--device foo` used to escape as a bare ValueError from int(), and an id that is not in the list (5, -1)
+    was passed straight to whisper-cli. Both now fail here, before the run, with the ids that do exist."""
+    try:
+        dev = int(device)
+    except (TypeError, ValueError):
+        raise ValueError(f"device must be 'auto' or a GPU id, not {device!r}") from None
+    ids = [d["id"] for d in found]
+    if dev not in ids:
+        listed = ", ".join(f"{i} ({d['backend']} {d['name']})" for i, d in zip(ids, found)) or "none"
+        raise ValueError(f"no device {dev}; available: {listed}")
+    return dev
+
+
+def setup(model: str = "turbo", bin: str | None = None, flavor: str | None = None) -> tuple[Path, Path, list[dict]]:
+    """Find (or download) whisper-cli and the model, and list the devices it can use."""
+    binary = backend.find_binary(bin, flavor)
+    timing = models.ensure(model, _quantizer(binary))
+    binary, found = backend.probe_or_refetch(binary, timing, flavor)
+    return binary, timing, found
+
+
+def transcribe_file(
+    src: str | Path,
+    lang: str = "auto",
+    model: str = "turbo",
+    text_model: str | None = None,
+    accurate: bool = False,
+    formats: list[str] | None = None,
+    out: str | Path | None = None,
+    device: str | int = "auto",
+    bin: str | None = None,
+    flavor: str | None = None,
+    verbose: bool = False,
+    log: Callable[[str], None] = print,
+    max_line_chars: int | None = None,
+    prompt: str | None = None,
+    translate: bool = False,
+) -> dict:
+    """Transcribe one audio/video file. Returns a summary dict (files written, language, device, segments, text)."""
+    src = Path(src).expanduser()
+    if not src.is_file():
+        raise FileNotFoundError(f"no such file: {src}")
+    base = Path(out).expanduser() if out else src.with_suffix("")
+    # Before any download or inference: -o into a folder that does not exist used to fail at the very end with a
+    # bare "[Errno 2] ... .srt", throwing away a transcription that may have taken minutes.
+    base.parent.mkdir(parents=True, exist_ok=True)
+    if translate:
+        if text_model:
+            raise ValueError("translate cannot be combined with a text model (fine-tunes write the source language)")
+        if models.ALIASES.get(model, model) == "large-v3-turbo":   # turbo was not trained for translation
+            model = "large-v3"
+            log("translate: using large-v3 (turbo does not translate)")
+    binary, timing, found = setup(model, bin, flavor)
+    dev = backend.pick_device(found) if device in ("auto", None) else _device_id(device, found)
+    gpu = next((d for d in found if d["id"] == dev), found[0])
+    if lang == "auto":
+        lang = transcribe.detected_language(binary, timing, src, dev)
+        log(f"language: {lang}")
+    beam = 5 if translate and accurate else None
+    if accurate and not text_model and not translate:
+        if lang in models.ACCURATE:
+            text_model = models.ACCURATE[lang]          # fine-tune text + turbo timing
+        elif model == "turbo":
+            model, beam = "large-v3", 5
+            timing = models.ensure(model, _quantizer(binary))
+    t0 = time.time()
+    log(f"transcribing with {model} on {gpu['backend']} {gpu['name']} ...")
+    segs = transcribe.run(binary, timing, src, lang, dev, beam=beam, verbose=verbose, prompt=prompt, translate=translate)
+    meta = {"tool": f"babelscribe {__version__}", "model": model, "lang": lang, "device": f"{gpu['backend']} {gpu['name']}"}
+    if translate:
+        meta["translate"] = "en"
+    if text_model:
+        _, ft = models.resolve(text_model)
+        tm = models.ensure(text_model, _quantizer(binary))
+        log(f"text pass with {text_model} ...")
+        segs = hybrid.run(binary, tm, src, segs, ft["lang"] if ft else lang, dev, (ft or {}).get("beam"), verbose, prompt=prompt)
+        meta["text_model"] = text_model
+    files = writers.write(
+        segs,
+        base,
+        formats or ["srt", "json"],
+        meta,
+        max_line_chars=max_line_chars,
+    )
+    took = time.time() - t0
+    log(f"{len(segs)} segments in {took:.1f}s -> " + ", ".join(str(f) for f in files))
+    return {**meta, "files": [str(f) for f in files], "segments": len(segs), "seconds": round(took, 1),
+            "text": "\n".join(s["text"].strip() for s in segs)}

{babelscribe-0.3.2 → babelscribe-0.4.0}/babelscribe/backend.py

@@ -1,118 +1,118 @@
-"""Find or fetch a whisper.cpp `whisper-cli` build for this machine and list its GPU devices.
-
-Search order: --bin / BABELSCRIBE_WHISPER_BIN -> cached download -> `whisper-cli` on PATH -> download a prebuilt
-release asset for this OS (Vulkan on Windows/Linux = AMD + NVIDIA + Intel, Metal on macOS, CPU fallback)."""
-from __future__ import annotations
-
-import io
-import json
-import os
-import platform
-import re
-import shutil
-import subprocess
-import urllib.request
-import zipfile
-from pathlib import Path
-
-CACHE = Path(os.environ.get("BABELSCRIBE_HOME", Path.home() / ".babelscribe"))
-# Prebuilt binaries are produced by .github/workflows/build-binaries.yml and attached to a GitHub release.
-RELEASES = os.environ.get("BABELSCRIBE_RELEASES", "https://github.com/phonology024/babelscribe/releases/latest/download")
-EXE = "whisper-cli.exe" if os.name == "nt" else "whisper-cli"
-
-
-def asset_name(flavor: str | None = None) -> str:
-    system = {"Windows": "windows", "Linux": "linux", "Darwin": "macos"}[platform.system()]
-    arch = "arm64" if platform.machine().lower() in ("arm64", "aarch64") else "x64"
-    flavor = flavor or ("metal" if system == "macos" else "vulkan")
-    return f"whisper-cli-{system}-{arch}-{flavor}.zip"
-
-
-def find_binary(explicit: str | None = None, flavor: str | None = None, download: bool = True) -> Path:
-    for cand in (explicit, os.environ.get("BABELSCRIBE_WHISPER_BIN")):
-        if cand and Path(cand).is_file():
-            return Path(cand)
-    cached = next(iter(sorted((CACHE / "bin").rglob(EXE))), None) if (CACHE / "bin").exists() else None
-    if cached:
-        return cached
-    on_path = shutil.which("whisper-cli")
-    if on_path:
-        return Path(on_path)
-    if not download:
-        raise FileNotFoundError("whisper-cli not found; pass --bin or allow download")
-    return fetch_binary(flavor)
-
-
-def fetch_binary(flavor: str | None = None) -> Path:
-    name = asset_name(flavor)
-    dest = CACHE / "bin" / name[:-4]
-    print(f"downloading {name} ...")
-    data = urllib.request.urlopen(f"{RELEASES}/{name}").read()
-    zipfile.ZipFile(io.BytesIO(data)).extractall(dest)
-    exe = next(dest.rglob(EXE))
-    if os.name != "nt":
-        exe.chmod(0o755)
-    return exe
-
-
-def probe_or_refetch(binary: Path, model: Path, flavor: str | None = None) -> tuple[Path, list[dict]]:
-    """Probe devices; a cached binary that crashes with 'illegal instruction' is deleted and downloaded again once."""
-    try:
-        return binary, probe_devices(binary, model)
-    except IllegalInstruction:
-        cache = (CACHE / "bin").resolve()
-        if cache not in binary.resolve().parents:
-            raise SystemExit(f"{binary} crashed with 'illegal instruction': it was built for a newer CPU than this one.")
-        shutil.rmtree(binary.parent)
-        print("cached whisper-cli does not run on this CPU; downloading the current build ...")
-        binary = fetch_binary(flavor)
-        try:
-            return binary, probe_devices(binary, model)
-        except IllegalInstruction:
-            raise SystemExit("the prebuilt whisper-cli does not run on this CPU; build whisper.cpp yourself and pass --bin.")
-
-
-def devices(binary: Path) -> list[dict]:
-    """Ask whisper.cpp which GPUs it can see (it prints them while loading a model)."""
-    out = subprocess.run([str(binary), "--help"], capture_output=True, text=True, errors="replace")
-    text = out.stdout + out.stderr
-    found = []
-    for m in re.finditer(r"ggml_(vulkan|cuda|metal): *(\d+) = ([^|\n]+)", text):
-        found.append({"backend": m.group(1), "id": int(m.group(2)), "name": m.group(3).strip()})
-    return found
-
-
-class IllegalInstruction(RuntimeError):
-    """The binary was compiled for CPU features this machine lacks (e.g. an old AVX-512 build)."""
-
-
-def probe_devices(binary: Path, model: Path) -> list[dict]:
-    """Load a model on an empty clip to see the GPU list and which device whisper.cpp picks."""
-    import tempfile, wave
-    with tempfile.TemporaryDirectory() as d:
-        wav = Path(d) / "s.wav"
-        with wave.open(str(wav), "wb") as w:
-            w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000); w.writeframes(b"\0\0" * 16000)
-        # no -np: static builds route the GPU list through the same logger -np silences
-        out = subprocess.run([str(binary), "-m", str(model), "-f", str(wav)], capture_output=True, text=True, errors="replace")
-    if out.returncode in (0xC000001D, -4, 132):   # Windows STATUS_ILLEGAL_INSTRUCTION / SIGILL
-        raise IllegalInstruction(str(binary))
-    text = out.stdout + out.stderr
-    found = [{"backend": m.group(1), "id": int(m.group(2)), "name": m.group(3).strip(), "detail": m.group(4).strip()}
-             for m in re.finditer(r"ggml_(vulkan|cuda|metal): *(\d+) = ([^|\n]+)\|?([^\n]*)", text)]
-    if not found and "Metal" in text:
-        found.append({"backend": "metal", "id": 0, "name": "Apple GPU", "detail": ""})
-    return found or [{"backend": "cpu", "id": 0, "name": platform.processor() or "CPU", "detail": ""}]
-
-
-def pick_device(found: list[dict]) -> int:
-    """Prefer a discrete GPU: NVIDIA/AMD over integrated Intel/AMD APU (uma: 1)."""
-    gpus = [d for d in found if d["backend"] != "cpu"]
-    if not gpus:
-        return 0
-    discrete = [d for d in gpus if "uma: 0" in d.get("detail", "")] or gpus
-    return discrete[0]["id"]
-
-
-if __name__ == "__main__":
-    print(json.dumps({"asset": asset_name(), "binary": str(find_binary(download=False))}, indent=1))
+"""Find or fetch a whisper.cpp `whisper-cli` build for this machine and list its GPU devices.
+
+Search order: --bin / BABELSCRIBE_WHISPER_BIN -> cached download -> `whisper-cli` on PATH -> download a prebuilt
+release asset for this OS (Vulkan on Windows/Linux = AMD + NVIDIA + Intel, Metal on macOS, CPU fallback)."""
+from __future__ import annotations
+
+import io
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import urllib.request
+import zipfile
+from pathlib import Path
+
+CACHE = Path(os.environ.get("BABELSCRIBE_HOME", Path.home() / ".babelscribe"))
+# Prebuilt binaries are produced by .github/workflows/build-binaries.yml and attached to a GitHub release.
+RELEASES = os.environ.get("BABELSCRIBE_RELEASES", "https://github.com/phonology024/babelscribe/releases/latest/download")
+EXE = "whisper-cli.exe" if os.name == "nt" else "whisper-cli"
+
+
+def asset_name(flavor: str | None = None) -> str:
+    system = {"Windows": "windows", "Linux": "linux", "Darwin": "macos"}[platform.system()]
+    arch = "arm64" if platform.machine().lower() in ("arm64", "aarch64") else "x64"
+    flavor = flavor or ("metal" if system == "macos" else "vulkan")
+    return f"whisper-cli-{system}-{arch}-{flavor}.zip"
+
+
+def find_binary(explicit: str | None = None, flavor: str | None = None, download: bool = True) -> Path:
+    for cand in (explicit, os.environ.get("BABELSCRIBE_WHISPER_BIN")):
+        if cand and Path(cand).is_file():
+            return Path(cand)
+    cached = next(iter(sorted((CACHE / "bin").rglob(EXE))), None) if (CACHE / "bin").exists() else None
+    if cached:
+        return cached
+    on_path = shutil.which("whisper-cli")
+    if on_path:
+        return Path(on_path)
+    if not download:
+        raise FileNotFoundError("whisper-cli not found; pass --bin or allow download")
+    return fetch_binary(flavor)
+
+
+def fetch_binary(flavor: str | None = None) -> Path:
+    name = asset_name(flavor)
+    dest = CACHE / "bin" / name[:-4]
+    print(f"downloading {name} ...")
+    data = urllib.request.urlopen(f"{RELEASES}/{name}").read()
+    zipfile.ZipFile(io.BytesIO(data)).extractall(dest)
+    exe = next(dest.rglob(EXE))
+    if os.name != "nt":
+        exe.chmod(0o755)
+    return exe
+
+
+def probe_or_refetch(binary: Path, model: Path, flavor: str | None = None) -> tuple[Path, list[dict]]:
+    """Probe devices; a cached binary that crashes with 'illegal instruction' is deleted and downloaded again once."""
+    try:
+        return binary, probe_devices(binary, model)
+    except IllegalInstruction:
+        cache = (CACHE / "bin").resolve()
+        if cache not in binary.resolve().parents:
+            raise SystemExit(f"{binary} crashed with 'illegal instruction': it was built for a newer CPU than this one.")
+        shutil.rmtree(binary.parent)
+        print("cached whisper-cli does not run on this CPU; downloading the current build ...")
+        binary = fetch_binary(flavor)
+        try:
+            return binary, probe_devices(binary, model)
+        except IllegalInstruction:
+            raise SystemExit("the prebuilt whisper-cli does not run on this CPU; build whisper.cpp yourself and pass --bin.")
+
+
+def devices(binary: Path) -> list[dict]:
+    """Ask whisper.cpp which GPUs it can see (it prints them while loading a model)."""
+    out = subprocess.run([str(binary), "--help"], capture_output=True, text=True, errors="replace")
+    text = out.stdout + out.stderr
+    found = []
+    for m in re.finditer(r"ggml_(vulkan|cuda|metal): *(\d+) = ([^|\n]+)", text):
+        found.append({"backend": m.group(1), "id": int(m.group(2)), "name": m.group(3).strip()})
+    return found
+
+
+class IllegalInstruction(RuntimeError):
+    """The binary was compiled for CPU features this machine lacks (e.g. an old AVX-512 build)."""
+
+
+def probe_devices(binary: Path, model: Path) -> list[dict]:
+    """Load a model on an empty clip to see the GPU list and which device whisper.cpp picks."""
+    import tempfile, wave
+    with tempfile.TemporaryDirectory() as d:
+        wav = Path(d) / "s.wav"
+        with wave.open(str(wav), "wb") as w:
+            w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000); w.writeframes(b"\0\0" * 16000)
+        # no -np: static builds route the GPU list through the same logger -np silences
+        out = subprocess.run([str(binary), "-m", str(model), "-f", str(wav)], capture_output=True, text=True, errors="replace")
+    if out.returncode in (0xC000001D, -4, 132):   # Windows STATUS_ILLEGAL_INSTRUCTION / SIGILL
+        raise IllegalInstruction(str(binary))
+    text = out.stdout + out.stderr
+    found = [{"backend": m.group(1), "id": int(m.group(2)), "name": m.group(3).strip(), "detail": m.group(4).strip()}
+             for m in re.finditer(r"ggml_(vulkan|cuda|metal): *(\d+) = ([^|\n]+)\|?([^\n]*)", text)]
+    if not found and "Metal" in text:
+        found.append({"backend": "metal", "id": 0, "name": "Apple GPU", "detail": ""})
+    return found or [{"backend": "cpu", "id": 0, "name": platform.processor() or "CPU", "detail": ""}]
+
+
+def pick_device(found: list[dict]) -> int:
+    """Prefer a discrete GPU: NVIDIA/AMD over integrated Intel/AMD APU (uma: 1)."""
+    gpus = [d for d in found if d["backend"] != "cpu"]
+    if not gpus:
+        return 0
+    discrete = [d for d in gpus if "uma: 0" in d.get("detail", "")] or gpus
+    return discrete[0]["id"]
+
+
+if __name__ == "__main__":
+    print(json.dumps({"asset": asset_name(), "binary": str(find_binary(download=False))}, indent=1))

{babelscribe-0.3.2 → babelscribe-0.4.0}/babelscribe/cli.py

@@ -4,6 +4,7 @@ Vulkan, NVIDIA via CUDA, Apple via Metal) or the CPU.
   babelscribe talk.mp4                         # auto language, turbo model, best GPU -> talk.srt + talk.json
   babelscribe vo.wav -l th --text-model thai-thonburian   # hybrid: Thai fine-tune text + turbo timing
   babelscribe talk.mp4 --accurate              # slower, fewest errors: large-v3 + beam search, or the best fine-tune
+  babelscribe talk.mp4 --prompt "Pitakpong, babelscribe"   # bias spelling of names and terms
   babelscribe mcp                              # MCP server for AI apps (Claude, Codex, Gemini CLI, ...)
   babelscribe devices                          # list GPUs whisper.cpp can use
   babelscribe models                           # list models and fine-tunes"""
@@ -12,11 +13,14 @@ from __future__ import annotations
 import argparse
 import sys
 
-from . import __version__, api, backend, models
+from . import __version__, api, backend, doctor, models
 
 
 def main(argv: list[str] | None = None) -> None:
     argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["doctor"]:
+        doctor.main()
+        return
     if argv[:1] == ["mcp"]:                          # MCP server for AI apps (stdio)
         from .mcp_server import main as serve
         return serve()
@@ -32,7 +36,14 @@ def main(argv: list[str] | None = None) -> None:
     ap.add_argument("--text-model", help="language fine-tune for the text (hybrid mode), e.g. thai-thonburian")
     ap.add_argument("--accurate", action="store_true",
                     help="slower but fewest errors: large-v3 with beam search, or the language's best fine-tune (hybrid)")
-    ap.add_argument("-f", "--formats", default="srt,json", help="comma list: srt,vtt,txt,json")
+    ap.add_argument("--prompt", help='names and terms to spell correctly, e.g. --prompt "Pitakpong, babelscribe" (whisper initial prompt)')
+    ap.add_argument("--translate", action="store_true", help="translate the speech to English (uses large-v3; not with --text-model)")
+    ap.add_argument("-f", "--formats", default="srt,json", help="comma list: srt,vtt,txt,json,ass")
+    ap.add_argument(
+        "--max-line-chars",
+        type=int,
+        help="maximum characters per subtitle line (default: 42, smaller for CJK/Thai)",
+    )
     ap.add_argument("-o", "--out", help="output base path (default: next to the input)")
     ap.add_argument("--device", default="auto", help="GPU id from `babelscribe devices`, or auto")
     ap.add_argument("--bin", help="path to a whisper-cli you built yourself")
@@ -47,8 +58,22 @@ def main(argv: list[str] | None = None) -> None:
             print(f"  [{d['id']}] {d['backend']:6} {d['name']}  {d.get('detail', '')}")
         print(f"auto picks device {backend.pick_device(found)}"); return
     try:
-        api.transcribe_file(a.input, a.lang, a.model, a.text_model, a.accurate,
-                            [f.strip() for f in a.formats.split(",") if f.strip()], a.out, a.device, a.bin, a.flavor, a.verbose)
+        api.transcribe_file(
+            src=a.input,
+            lang=a.lang,
+            model=a.model,
+            text_model=a.text_model,
+            accurate=a.accurate,
+            formats=[f.strip() for f in a.formats.split(",") if f.strip()],
+            out=a.out,
+            device=a.device,
+            bin=a.bin,
+            flavor=a.flavor,
+            verbose=a.verbose,
+            max_line_chars=a.max_line_chars,
+            prompt=a.prompt,
+            translate=a.translate,
+        )
     except FileNotFoundError as e:
         raise SystemExit(str(e))