babelscribe 0.2.0__py3-none-any.whl

babelscribe/__init__.py

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

babelscribe/__main__.py

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

babelscribe/align.py

@@ -0,0 +1,111 @@
+"""Hybrid mode: accurate TEXT from a language fine-tune (often without usable timestamps) + accurate TIMING from a
+general model. Both transcripts are aligned character by character (spaces/punctuation ignored, works for languages
+without spaces such as Thai, Chinese, Japanese); every character of the accurate text gets a time, and the text is
+re-segmented on the timing model's segment boundaries."""
+from __future__ import annotations
+
+import difflib
+import re
+import unicodedata
+
+_SKIP = re.compile(r"[\s\W_]", re.UNICODE)
+
+
+def _chars_with_times(segs: list[dict]) -> tuple[str, list[float]]:
+    chars, times = [], []
+    for s in segs:
+        toks = s.get("words") or [[s["text"], s["start"], s["end"]]]
+        for text, t0, t1 in toks:
+            clean = [c for c in unicodedata.normalize("NFC", text) if not _SKIP.match(c)]
+            for i, c in enumerate(clean):
+                chars.append(c)
+                times.append(t0 + (t1 - t0) * (i + .5) / max(1, len(clean)))
+    return "".join(chars), times
+
+
+def _word_breaks(text: str) -> set[int]:
+    """Positions where a new word starts. Spaces everywhere; for Thai/Lao/Khmer/Burmese use pythainlp if installed."""
+    br = {i for i, c in enumerate(text) if i and (text[i - 1].isspace() or c.isspace())}
+    if any('฀' <= c <= '๿' for c in text):
+        try:
+            from pythainlp.tokenize import word_tokenize
+            pos = 0
+            for w in word_tokenize(text, keep_whitespace=True):
+                br.add(pos); pos += len(w)
+        except ImportError:
+            pass
+    return br
+
+
+def hybrid(text_segs: list[dict], time_segs: list[dict]) -> list[dict]:
+    full = " ".join(s["text"] for s in text_segs)
+    full = unicodedata.normalize("NFC", full)
+    ref, ref_t = _chars_with_times(time_segs)
+    keep = [(i, c) for i, c in enumerate(full) if not _SKIP.match(c)]
+    hyp = "".join(c for _, c in keep)
+    sm = difflib.SequenceMatcher(None, hyp, ref, autojunk=False)
+    t_of = [None] * len(hyp)
+    for a, b, n in sm.get_matching_blocks():
+        for k in range(n):
+            t_of[a + k] = ref_t[b + k]
+    # fill gaps by linear interpolation between matched neighbours
+    known = [i for i, t in enumerate(t_of) if t is not None]
+    if not known:
+        return time_segs
+    for i in range(len(t_of)):
+        if t_of[i] is None:
+            lo = max((k for k in known if k < i), default=None)
+            hi = min((k for k in known if k > i), default=None)
+            if lo is None:
+                t_of[i] = t_of[hi]
+            elif hi is None:
+                t_of[i] = t_of[lo]
+            else:
+                t_of[i] = t_of[lo] + (t_of[hi] - t_of[lo]) * (i - lo) / (hi - lo)
+    char_time = {}
+    for (pos, _), t in zip(keep, t_of):
+        char_time[pos] = t
+    # cut the accurate text at the timing model's segment ends
+    bounds = [s["end"] for s in time_segs]
+    out, cur, cur_t0, bi = [], [], None, 0
+    last_t = 0.0
+    breaks = _word_breaks(full)
+    hold = False
+    for pos, ch in enumerate(full):
+        t = char_time.get(pos, last_t)
+        last_t = t
+        # never cut inside a word: if we are mid-word, keep filling the current segment until the next word break
+        hold = bool(cur) and pos not in breaks and pos - (max((b for b in breaks if b <= pos), default=0)) < 14
+        while not hold and bi < len(bounds) - 1 and t > bounds[bi]:
+            if cur and "".join(cur).strip():
+                out.append({"start": cur_t0, "end": bounds[bi], "text": "".join(cur).strip(), "words": []})
+            cur, cur_t0 = [], None
+            bi += 1
+        if cur_t0 is None and not ch.isspace():
+            cur_t0 = t
+        cur.append(ch)
+    if cur and "".join(cur).strip():
+        out.append({"start": cur_t0, "end": time_segs[-1]["end"], "text": "".join(cur).strip(), "words": []})
+    return _fill_uncovered(out, time_segs, sm, ref, ref_t)
+
+
+def _fill_uncovered(out: list[dict], time_segs: list[dict], sm: difflib.SequenceMatcher, ref: str, ref_t: list[float]) -> list[dict]:
+    """Text models often skip the first/last words of a clip. Where the timing transcript has speech that the
+    accurate text never matched (head or tail), keep the timing model's words there instead of losing them."""
+    blocks = [b for b in sm.get_matching_blocks() if b.size >= 3]   # ignore stray 1–2 char matches
+    if not blocks or not ref:
+        return out
+    first_ref, last_ref = blocks[0].b, blocks[-1].b + blocks[-1].size - 1
+    def words_between(t0: float, t1: float) -> str:
+        ws = [w for s in time_segs for w in (s.get("words") or [[s["text"], s["start"], s["end"]]]) if t0 < (w[1] + w[2]) / 2 <= t1]
+        return "".join(w[0] for w in ws).strip()
+    if len(ref) - 1 - last_ref > 2:
+        tail = words_between(ref_t[last_ref], time_segs[-1]["end"] + 1)
+        tail = tail.lstrip("".join(chr(c) for c in range(0x0e31, 0x0e4f) if unicodedata.category(chr(c)) == "Mn"))   # no orphan vowel/tone marks
+        if tail and out:
+            out[-1]["text"] = (out[-1]["text"] + " " + tail).strip(); out[-1]["end"] = time_segs[-1]["end"]
+    if first_ref > 2:
+        head = words_between(time_segs[0]["start"] - 1, ref_t[first_ref] - .01)
+        if head and out:
+            out[0]["text"] = (head + " " + out[0]["text"]).strip(); out[0]["start"] = time_segs[0]["start"]
+    return out

babelscribe/backend.py

@@ -0,0 +1,94 @@
+"""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 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
+
+
+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)
+        out = subprocess.run([str(binary), "-m", str(model), "-f", str(wav), "-np"], capture_output=True, text=True, errors="replace")
+    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/cli.py

@@ -0,0 +1,80 @@
+"""babelscribe — transcribe any audio/video, in any language Whisper knows, on any GPU (AMD / NVIDIA / Intel via
+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 devices                          # list GPUs whisper.cpp can use
+  babelscribe models                           # list models and fine-tunes"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from . import __version__, backend, hybrid, models, transcribe, writers
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["models"]:
+        print("general (99 languages):"); [print(f"  {k:16} {v}") for k, v in models.GENERAL.items()]
+        print("fine-tunes (text quality for one language, use with --text-model):")
+        [print(f"  {k:16} [{v['lang']}] {v['note']}") for k, v in models.FINETUNES.items()]
+        return
+    ap = argparse.ArgumentParser(prog="babelscribe", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", help="audio or video file, or 'devices'")
+    ap.add_argument("-l", "--lang", default="auto", help="language code (th, en, ja, ...) or auto")
+    ap.add_argument("-m", "--model", default="turbo", help="timing/general model (default turbo = large-v3-turbo)")
+    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("-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")
+    ap.add_argument("--flavor", help="prebuilt flavour to download: vulkan | cuda | metal | cpu")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    ap.add_argument("--version", action="version", version=__version__)
+    a = ap.parse_args(argv)
+
+    binary = backend.find_binary(a.bin, a.flavor)
+    timing = models.ensure(a.model, binary.parent / ("whisper-quantize.exe" if binary.suffix == ".exe" else "whisper-quantize"))
+    found = backend.probe_devices(binary, timing)
+    if a.input == "devices":
+        for d in found:
+            print(f"  [{d['id']}] {d['backend']:6} {d['name']}  {d.get('detail', '')}")
+        print(f"auto picks device {backend.pick_device(found)}"); return
+    dev = backend.pick_device(found) if a.device == "auto" else int(a.device)
+    gpu = next((d for d in found if d["id"] == dev), found[0])
+    src = Path(a.input)
+    if not src.exists():
+        raise SystemExit(f"no such file: {src}")
+    lang = a.lang
+    if lang == "auto":
+        lang = transcribe.detected_language(binary, timing, src, dev); print(f"language: {lang}")
+    beam = None
+    if a.accurate:
+        if not a.text_model and lang in models.ACCURATE:
+            a.text_model = models.ACCURATE[lang]          # fine-tune text + turbo timing
+        elif not a.text_model and a.model == "turbo":
+            a.model, beam = "large-v3", 5
+            timing = models.ensure(a.model)
+    t0 = time.time()
+    print(f"transcribing with {a.model} on {gpu['backend']} {gpu['name']} ...")
+    segs = transcribe.run(binary, timing, src, lang, dev, beam=beam, verbose=a.verbose)
+    meta = {"tool": f"babelscribe {__version__}", "model": a.model, "lang": lang, "device": f"{gpu['backend']} {gpu['name']}"}
+    if a.text_model:
+        _, ft = models.resolve(a.text_model)
+        tm = models.ensure(a.text_model, binary.parent / ("whisper-quantize.exe" if binary.suffix == ".exe" else "whisper-quantize"))
+        print(f"text pass with {a.text_model} ...")
+        segs = hybrid.run(binary, tm, src, segs, ft["lang"] if ft else lang, dev, (ft or {}).get("beam"), a.verbose)
+        meta["text_model"] = a.text_model
+    base = Path(a.out) if a.out else src.with_suffix("")
+    files = writers.write(segs, base, [f.strip() for f in a.formats.split(",") if f.strip()], meta)
+    print(f"{len(segs)} segments in {time.time() - t0:.1f}s -> " + ", ".join(str(f) for f in files))
+
+
+if __name__ == "__main__":
+    main()

babelscribe/hybrid.py

@@ -0,0 +1,51 @@
+"""Hybrid pass done safely: language fine-tunes without timestamps drop words at whisper's 30 s window seams.
+So we cut the audio into short chunks (<= max_len s) at the timing model's segment boundaries (natural pauses),
+transcribe every chunk with the text model in ONE whisper-cli run (model loaded once), and align each chunk's
+accurate text to the timing segments inside that chunk."""
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+from . import align
+from .transcribe import to_wav16k
+
+
+def chunks(time_segs: list[dict], max_len: float = 24.0) -> list[tuple[float, float, list[dict]]]:
+    out, cur = [], []
+    for s in time_segs:
+        if cur and s["end"] - cur[0]["start"] > max_len:
+            out.append(cur); cur = []
+        cur.append(s)
+    if cur:
+        out.append(cur)
+    return [(c[0]["start"], c[-1]["end"], c) for c in out]
+
+
+def run(binary: Path, text_model: Path, media: Path, time_segs: list[dict], lang: str, device: int, beam: int | None,
+        verbose: bool = False, pad: float = .25) -> list[dict]:
+    parts = chunks(time_segs)
+    with tempfile.TemporaryDirectory() as d:
+        wavs = []
+        for i, (a, b, _) in enumerate(parts):
+            w = Path(d) / f"c{i:04d}.wav"; to_wav16k(media, w, max(0.0, a - pad), b + pad, tail_silence=1.5); wavs.append(w)
+        cmd = [str(binary), "-m", str(text_model), "-l", lang, "-oj", "-mc", "0", "-dev", str(device), "-np"]
+        if beam:
+            cmd += ["-bs", str(beam)]
+        for w in wavs:
+            cmd += ["-f", str(w)]
+        p = subprocess.run(cmd, capture_output=not verbose, text=True, errors="replace")
+        if p.returncode:
+            raise RuntimeError(f"whisper-cli failed ({p.returncode}):\n{(p.stderr or '')[-2000:]}")
+        texts = []
+        for w in wavs:
+            j = json.loads(Path(str(w) + ".json").read_text(encoding="utf-8", errors="replace"))
+            texts.append(" ".join(s["text"].strip() for s in j.get("transcription", [])))
+    out = []
+    for (a, b, segs), text in zip(parts, texts):
+        if not text.strip():
+            out.extend(segs); continue
+        out.extend(align.hybrid([{"start": a, "end": b, "text": text, "words": []}], segs))
+    return out

babelscribe/models.py

@@ -0,0 +1,94 @@
+"""Model registry + download.
+
+General models are the official whisper.cpp ggml files (99 languages). Language fine-tunes are listed by their
+Hugging Face repo and converted on the user's machine (we never redistribute converted weights — each fine-tune
+keeps its own licence). Fine-tunes often lose timestamp prediction, so they are used for TEXT and a general model
+gives the TIMING (see align.py)."""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from .backend import CACHE
+
+GGML = "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-{name}.bin"
+GENERAL = {   # name -> size (approx) ; 'turbo' is the best speed/quality default
+    "tiny": "75 MB", "base": "142 MB", "small": "466 MB", "medium": "1.5 GB",
+    "large-v3": "3.1 GB", "large-v3-turbo": "1.6 GB",
+}
+ALIASES = {"turbo": "large-v3-turbo", "large": "large-v3"}
+# Community fine-tunes: add a line to support a new language better. 'beam' = needs beam search (greedy loops).
+FINETUNES = {
+    "thai-thonburian": {"repo": "biodatlab/whisper-th-large-v3-combined", "lang": "th", "beam": 5, "timestamps": False,
+                        "note": "Thonburian Whisper (Thai) — strong Thai spelling; pair with turbo for timing"},
+    "thai-pathumma": {"repo": "nectec/Pathumma-whisper-th-large-v3", "lang": "th", "beam": 5, "timestamps": False,
+                      "note": "Pathumma Whisper by NECTEC (Thai) — lowest Thai CER on FLEURS"},
+    "hindi-vasista": {"repo": "vasista22/whisper-hindi-large-v2", "lang": "hi", "beam": 5, "timestamps": False,
+                      "note": "Hindi fine-tune of large-v2 (Speech Lab, IIT Madras) — halves Hindi WER on FLEURS"},
+}
+# --accurate: per language, the model that scored best on FLEURS (bench/fleurs.py). Languages not listed use large-v3
+# with beam search, which beat every public fine-tune we tried for vi / ar.
+ACCURATE = {"th": "thai-pathumma", "hi": "hindi-vasista"}
+MODELS = Path(os.environ.get("BABELSCRIBE_MODELS", CACHE / "models"))
+
+
+def resolve(name: str) -> tuple[str, dict | None]:
+    name = ALIASES.get(name, name)
+    if name in GENERAL:
+        return name, None
+    if name in FINETUNES:
+        return name, FINETUNES[name]
+    raise SystemExit(f"unknown model '{name}'. General: {', '.join(GENERAL)}; fine-tunes: {', '.join(FINETUNES)}")
+
+
+def path_for(name: str) -> Path:
+    name, ft = resolve(name)
+    return MODELS / (f"ggml-{name}-q8_0.bin" if ft else f"ggml-{name}.bin")
+
+
+def ensure(name: str, quantizer: Path | None = None) -> Path:
+    name, ft = resolve(name)
+    p = path_for(name)
+    if p.exists():
+        return p
+    MODELS.mkdir(parents=True, exist_ok=True)
+    if not ft:
+        print(f"downloading model {name} ({GENERAL[name]}) ...")
+        tmp = p.with_suffix(".part")
+        urllib.request.urlretrieve(GGML.format(name=name), tmp)
+        tmp.replace(p)
+        return p
+    return convert_finetune(name, ft, p, quantizer)
+
+
+def convert_finetune(name: str, ft: dict, out: Path, quantizer: Path | None) -> Path:
+    """HF transformers checkpoint -> ggml (whisper.cpp convert-h5-to-ggml.py) -> q8_0. Needs: pip install babelscribe[finetune]."""
+    try:
+        import torch, transformers  # noqa: F401
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        raise SystemExit("fine-tune conversion needs extras: pip install \"babelscribe[finetune]\"")
+    work = MODELS / f"_{name}"
+    work.mkdir(parents=True, exist_ok=True)
+    hf = snapshot_download(ft["repo"], local_dir=work / "hf")
+    oa = work / "openai-whisper"
+    if not oa.exists():
+        subprocess.run(["git", "clone", "-q", "--depth", "1", "https://github.com/openai/whisper.git", str(oa)], check=True)
+    script = work / "convert-h5-to-ggml.py"
+    if not script.exists():
+        urllib.request.urlretrieve("https://raw.githubusercontent.com/ggml-org/whisper.cpp/master/models/convert-h5-to-ggml.py", script)
+    # some fine-tunes ship bf16 weights, which the converter cannot export -> load them as float32
+    src = script.read_text(encoding="utf-8").replace("WhisperForConditionalGeneration.from_pretrained(dir_model)\n",
+                                                     "WhisperForConditionalGeneration.from_pretrained(dir_model).float()\n")
+    script.write_text(src, encoding="utf-8")
+    subprocess.run([sys.executable, str(script), hf, str(oa), str(work)], check=True)
+    f32 = work / "ggml-model.bin"
+    if quantizer and quantizer.exists():
+        subprocess.run([str(quantizer), str(f32), str(out), "q8_0"], check=True)
+        f32.unlink()
+    else:
+        f32.replace(out)
+    return out

babelscribe/transcribe.py

@@ -0,0 +1,69 @@
+"""Run whisper.cpp on any audio/video file and return segments [{start, end, text, words: [[text, t0, t1], ...]}]."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def ffmpeg() -> str:
+    exe = shutil.which("ffmpeg")
+    if exe:
+        return exe
+    try:
+        import imageio_ffmpeg
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except ImportError:
+        raise SystemExit("ffmpeg not found: install it or `pip install imageio-ffmpeg`")
+
+
+def to_wav16k(src: Path, dst: Path, start: float | None = None, end: float | None = None, tail_silence: float = 0) -> None:
+    cmd = [ffmpeg(), "-v", "error", "-y"]
+    if start is not None:
+        cmd += ["-ss", str(start)]
+    if end is not None:
+        cmd += ["-to", str(end)]
+    cmd += ["-i", str(src), "-vn", "-ac", "1", "-ar", "16000"]
+    if tail_silence:   # whisper tends to drop the last words when audio stops abruptly
+        cmd += ["-af", f"apad=pad_dur={tail_silence}"]
+    cmd += ["-c:a", "pcm_s16le", str(dst)]
+    subprocess.run(cmd, check=True)
+
+
+def run(binary: Path, model: Path, media: Path, lang: str = "auto", device: int = 0, beam: int | None = None,
+        threads: int | None = None, extra: list[str] | None = None, verbose: bool = False) -> list[dict]:
+    with tempfile.TemporaryDirectory() as d:
+        wav = Path(d) / "in.wav"
+        to_wav16k(media, wav)
+        out = Path(d) / "out"
+        # -mc 0: never feed previous text back as a prompt — stops the repeat-loop hallucination on long files
+        cmd = [str(binary), "-m", str(model), "-f", str(wav), "-l", lang, "-ojf", "-of", str(out), "-mc", "0", "-dev", str(device)]
+        if beam:
+            cmd += ["-bs", str(beam)]
+        if threads:
+            cmd += ["-t", str(threads)]
+        cmd += extra or []
+        p = subprocess.run(cmd, capture_output=not verbose, text=True, errors="replace")
+        if p.returncode:
+            raise RuntimeError(f"whisper-cli failed ({p.returncode}):\n{(p.stderr or '')[-2000:]}")
+        data = json.loads(Path(str(out) + ".json").read_text(encoding="utf-8", errors="replace"))
+    segs = []
+    for s in data.get("transcription", []):
+        words = [[t["text"], t["offsets"]["from"] / 1000, t["offsets"]["to"] / 1000] for t in s.get("tokens", [])
+                 if not t["text"].startswith("[_") and t["text"].strip()]
+        segs.append({"start": s["offsets"]["from"] / 1000, "end": s["offsets"]["to"] / 1000, "text": s["text"].strip(), "words": words})
+    return [s for s in segs if s["text"]]
+
+
+def detected_language(binary: Path, model: Path, media: Path, device: int = 0) -> str:
+    with tempfile.TemporaryDirectory() as d:
+        wav = Path(d) / "in.wav"
+        to_wav16k(media, wav, 0, 30)
+        p = subprocess.run([str(binary), "-m", str(model), "-f", str(wav), "-l", "auto", "-dl", "-dev", str(device)],
+                           capture_output=True, text=True, errors="replace")
+    import re
+    m = re.search(r"auto-detected language: (\w+)", p.stdout + p.stderr)
+    return m.group(1) if m else "auto"

babelscribe/writers.py

@@ -0,0 +1,29 @@
+"""Output formats: srt, vtt, txt, json."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _ts(t: float, sep: str) -> str:
+    ms = int(round(max(0.0, t) * 1000))
+    h, ms = divmod(ms, 3600000); m, ms = divmod(ms, 60000); s, ms = divmod(ms, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d}{sep}{ms:03d}"
+
+
+def write(segs: list[dict], base: Path, formats: list[str], meta: dict) -> list[Path]:
+    out = []
+    for f in formats:
+        p = base.with_suffix("." + f)
+        if f == "srt":
+            p.write_text("".join(f"{i}\n{_ts(s['start'], ',')} --> {_ts(s['end'], ',')}\n{s['text']}\n\n" for i, s in enumerate(segs, 1)), encoding="utf-8")
+        elif f == "vtt":
+            p.write_text("WEBVTT\n\n" + "".join(f"{_ts(s['start'], '.')} --> {_ts(s['end'], '.')}\n{s['text']}\n\n" for s in segs), encoding="utf-8")
+        elif f == "txt":
+            p.write_text("\n".join(s["text"] for s in segs) + "\n", encoding="utf-8")
+        elif f == "json":
+            p.write_text(json.dumps({"meta": meta, "segments": segs}, ensure_ascii=False, indent=1), encoding="utf-8")
+        else:
+            raise SystemExit(f"unknown format {f}")
+        out.append(p)
+    return out

babelscribe-0.2.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: babelscribe
+Version: 0.2.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
+Project-URL: Issues, https://github.com/phonology024/babelscribe/issues
+Keywords: whisper,speech-to-text,transcription,subtitles,vulkan,amd,gpu,thai
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: imageio-ffmpeg>=0.5
+Provides-Extra: finetune
+Requires-Dist: torch; extra == "finetune"
+Requires-Dist: transformers; extra == "finetune"
+Requires-Dist: huggingface_hub; extra == "finetune"
+Requires-Dist: numpy; extra == "finetune"
+Provides-Extra: thai
+Requires-Dist: pythainlp; extra == "thai"
+Dynamic: license-file
+
+# babelscribe
+
+**Transcribe any audio or video, in any of Whisper's 99 languages, on any GPU — AMD, NVIDIA, Intel or Apple — or just the CPU.**
+One command, no CUDA required, subtitles out.
+
+```bash
+pip install babelscribe          # Python 3.9+
+babelscribe interview.mp4                 # auto-detects language, picks your best GPU -> interview.srt + interview.json
+```
+
+babelscribe is a thin, friendly layer on top of [whisper.cpp](https://github.com/ggml-org/whisper.cpp). It exists because
+getting fast Whisper on a non-NVIDIA card (e.g. an AMD Radeon on Windows) still means building whisper.cpp with the
+Vulkan SDK yourself. babelscribe downloads a prebuilt `whisper-cli` for your system and handles the rest.
+
+| Your hardware | Backend used | Prebuilt asset |
+|---|---|---|
+| AMD / NVIDIA / Intel GPU on Windows | Vulkan | `windows-x64-vulkan` |
+| NVIDIA on Windows | Vulkan (same build) | `windows-x64-vulkan` |
+| NVIDIA on Linux (alternative) | CUDA | `linux-x64-cuda` (`--flavor cuda`) |
+| AMD / NVIDIA / Intel GPU on Linux | Vulkan | `linux-x64-vulkan` |
+| Apple Silicon | Metal | `macos-arm64-metal` |
+| No usable GPU | CPU | `*-cpu` (`--flavor cpu`) |
+
+A 19-minute English TED talk transcribes in 48 seconds on an AMD Radeon RX 9070 XT with 1.5% word error — see the benchmark below.
+
+## Benchmark: real talks, human captions as the answer key
+Four TED / TEDx talks, scored against the **human-made captions in the spoken language** (`bench/bench.py`, reproducible).
+Error = word error rate (WER) for space-separated languages, character error rate (CER) for Japanese and Thai.
+GPU: AMD Radeon RX 9070 XT via Vulkan. *default* = `large-v3-turbo`; *accurate* = `--accurate` (see the FLEURS section).
+
+| Language | Talk | Length | default: time / error | `--accurate`: time / error |
+|---|---|---|---|---|
+| English | [Matt Walker — Sleep Is Your Superpower (TED)](https://youtu.be/5MuIMqhT8DM) | 19.3 min | 48 s (24x) · WER **1.5%** | 107 s (11x) · WER **1.5%** |
+| Japanese | [Kazunari Taguchi (TEDxHimi)](https://youtu.be/cjtmDEG-B7U) | 16.2 min | 47 s (20x) · CER 4.7% | 115 s (8x) · CER **4.2%** |
+| Spanish | [Adrià Solà Pastor — Cómo hablar (TEDxESIC University)](https://youtu.be/XUqrvbsTfck) | 19.9 min | 56 s (21x) · WER 13.8% | 134 s (9x) · WER 13.5% |
+| Thai | [นิติ ชัยชิตาทร — โปรดเรียกฉันด้วยนามอันแท้จริง (TEDxBangkok)](https://youtu.be/48A9SU6_bQ8) | 14.1 min | 74 s (12x) · CER 22.7% | 565 s (2x) · CER **16.4%** |
+
+How to read it: TED captions are edited for reading (fillers dropped, light rewording), so these numbers are an upper bound —
+most of the Spanish "errors" are the speaker's actual words versus the tidied caption. Thai is genuinely harder: fast,
+casual speech with slang; `--accurate` (Pathumma Whisper text + turbo timing) cuts its error by more than a quarter.
+Talks are used only to measure accuracy; their transcripts are not redistributed (TED content is CC BY-NC-ND).
+
+## Benchmark: 16 languages on FLEURS
+[Google FLEURS](https://huggingface.co/datasets/google/fleurs) test set, 50 utterances per language, human-verified
+verbatim transcripts (`bench/fleurs.py`, reproducible). Same normaliser for every language (Whisper's rule: lower-case,
+drop punctuation and non-spacing marks, numbers spelled out). WER for space-separated languages, CER for ja / zh / ko / th.
+
+| Language | default (turbo) | `--accurate` | model `--accurate` uses | `--accurate`, edge-trimmed* |
+|---|---|---|---|---|
+| English | 6.1% | 5.7% | large-v3, beam 5 | 5.6% |
+| Spanish | 4.1% | 4.2% | large-v3, beam 5 | **2.6%** |
+| French | 7.4% | 7.3% | large-v3, beam 5 | 7.2% |
+| German | 4.3% | 4.0% | large-v3, beam 5 | **3.3%** |
+| Portuguese | 8.5% | 7.7% | large-v3, beam 5 | 5.3% |
+| Italian | 6.7% | 6.5% | large-v3, beam 5 | **3.8%** |
+| Russian | 6.8% | 5.8% | large-v3, beam 5 | 5.6% |
+| Arabic | 11.0% | 10.6% | large-v3, beam 5 | 9.7% |
+| Hindi | 28.4% | **12.6%** | [vasista22/whisper-hindi-large-v2](https://huggingface.co/vasista22/whisper-hindi-large-v2) + turbo timing | 11.1% |
+| Indonesian | 9.8% | 7.8% | large-v3, beam 5 | 5.6% |
+| Vietnamese | 10.8% | 9.1% | large-v3, beam 5 | 9.1% |
+| Turkish | 6.2% | 6.7% | large-v3, beam 5 | 5.8% |
+| Japanese (CER) | 6.4% | 5.7% | large-v3, beam 5 | **4.6%** |
+| Chinese (CER) | 6.3% | 5.3% | large-v3, beam 5 | **4.8%** |
+| Korean (CER) | 4.1% | 3.9% | large-v3, beam 5 | **3.1%** |
+| Thai (CER) | 15.9% | **8.9%** | [Pathumma Whisper](https://huggingface.co/nectec/Pathumma-whisper-th-large-v3) (NECTEC) + turbo timing | 8.8% |
+
+\* Some FLEURS clips contain more speech than their reference transcript, so a correct model is charged for words the
+reference leaves out. *Edge-trimmed* ignores extra words before the first / after the last reference word; both numbers
+are stored by `bench/fleurs.py`. 50 utterances per language means differences under ~0.5 points are noise.
+
+Also measured and **not** used, because large-v3 was as good or better: large-v2 (all languages),
+PhoWhisper-large (vi 19.0%), whisper-large-v3 dialectal / code-switching Arabic fine-tunes (12.2% / 15.2%),
+Typhoon Whisper (th 11.9%), Thonburian Whisper (th 9.1% — kept as an option), Vaani Hindi (16.5%).
+
+## Why babelscribe (vs. what already exists)
+| | GPU on AMD / Intel | Windows, no build step | Video in, subtitles out | Long files don't loop | Better text for your language |
+|---|---|---|---|---|---|
+| **babelscribe** | ✅ Vulkan | ✅ prebuilt `whisper-cli` downloaded for you | ✅ ffmpeg bundled | ✅ `--max-context 0` by default | ✅ hybrid fine-tune text + turbo timing |
+| whisper.cpp (raw) | ✅ Vulkan — if you compile it | ❌ official releases ship no Windows Vulkan build | ❌ WAV 16 kHz only | ⚠️ you must know the flag | ❌ |
+| faster-whisper / WhisperX | ❌ GPU = NVIDIA CUDA only | ✅ pip | ✅ | ⚠️ | ⚠️ manual |
+| Cloud APIs | n/a (cloud) | ✅ | ✅ | ✅ | ❌ — and your audio leaves your machine, paid per minute |
+
+babelscribe does **not** replace those projects — it stands on whisper.cpp and simply removes the hard parts:
+compiling for your GPU, converting media, picking the right device, avoiding the long-file repeat bug, and combining
+a language-specific fine-tune with accurate timestamps.
+
+## Languages
+All 99 languages Whisper was trained on, auto-detected or forced with `-l`:
+af am ar as az ba be bg bn bo br bs ca cs cy da de el en es et eu fa fi fo fr gl gu ha haw he hi hr ht hu hy id is it ja jw ka kk km kn ko la lb ln lo lt lv mg mi mk ml mn mr ms mt my ne nl nn no oc pa pl ps pt ro ru sa sd si sk sl sn so sq sr su sv sw ta te tg th tk tl tr tt uk ur uz vi yi yo yue zh
+
+Accuracy follows Whisper's own training data: excellent for high-resource languages (English, Spanish, Japanese, …),
+weaker for low-resource ones. That is what hybrid mode is for — a community fine-tune for one language can be plugged in
+with one line in `babelscribe/models.py` (Thai and Hindi so far). PRs adding fine-tunes for other
+languages are the most valuable contribution.
+
+## Limitations (honest)
+- Tested end to end so far on an AMD Radeon RX 9070 XT (Windows, Vulkan). CUDA, Linux and macOS builds are produced by CI; reports from those machines are welcome.
+- Hybrid mode runs two models, so it is slower (≈1 min per minute of audio with a large fine-tune on that GPU).
+- Proper nouns can still be misspelled — check names before publishing subtitles.
+
+## Features
+- **Any input** — mp4, mkv, mov, mp3, wav, m4a… (ffmpeg is bundled through `imageio-ffmpeg`).
+- **Any language** — `-l auto` detects it; or pass `-l th`, `-l ja`, `-l es`…
+- **Picks the right GPU** — prefers a discrete card over an integrated one; `babelscribe devices` lists them, `--device N` overrides.
+- **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).
+
+## Usage
+```bash
+babelscribe talk.mp4 -f srt,vtt,txt,json          # all formats
+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 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
+```
+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]"`.
+
+## 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.
+
+## Prebuilt binaries
+`.github/workflows/build-binaries.yml` builds `whisper-cli` + `whisper-quantize` for every row of the table above and attaches
+them to each `v*` release. Point `BABELSCRIBE_RELEASES` at another URL to self-host.
+
+## ภาษาไทย
+ถอดเสียงจากไฟล์เสียงหรือวิดีโอได้ทุกภาษา บนการ์ดจอทุกยี่ห้อ (AMD / NVIDIA / Intel ผ่าน Vulkan, Apple ผ่าน Metal) หรือ CPU
+ภาษาไทยแนะนำ `babelscribe ไฟล์.mp4 -l th --accurate` — ข้อความจาก Pathumma Whisper (NECTEC) ที่ผิดน้อยที่สุดใน FLEURS (CER 8.9% เทียบ turbo 15.9%) + เวลาจาก large-v3-turbo
+หรือเลือก Thonburian Whisper เอง: `--text-model thai-thonburian`
+
+## Credits & licence
+MIT. Built on [whisper.cpp](https://github.com/ggml-org/whisper.cpp) (MIT) and OpenAI Whisper models (MIT).
+Fine-tunes belong to their authors: [Pathumma Whisper](https://huggingface.co/nectec/Pathumma-whisper-th-large-v3) by NECTEC,
+[Thonburian Whisper](https://huggingface.co/biodatlab/whisper-th-large-v3-combined) by biodatlab,
+[whisper-hindi-large-v2](https://huggingface.co/vasista22/whisper-hindi-large-v2) by vasista22 (Speech Lab, IIT Madras).

babelscribe-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+babelscribe/__init__.py,sha256=VGezPdaYYtL55ILTeVGmlhe-iqS4YFLXY7nraKeCdbY,103
+babelscribe/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+babelscribe/align.py,sha256=ih6Z51NhNb56ZdgRVvHalV61YQhczZSPZJ5L2arF-IY,5448
+babelscribe/backend.py,sha256=nK_XfB1ks-rzxV7NsoguuZGaeavLh9tHlTet7UvXEFQ,4173
+babelscribe/cli.py,sha256=-rPXUO1LYZpOLah14LHo4cHFdcZRfzKUzrCyIC-NPbA,4831
+babelscribe/hybrid.py,sha256=p4_8Tff7TX44SA2nuk7Fep6oUy0DaZAe9kuFTVs6uwY,2313
+babelscribe/models.py,sha256=ZJlP8FmFSACXAK9BQqmGtHDiJo_c69zzipdLgOK3UTs,4748
+babelscribe/transcribe.py,sha256=P6PHvlgXV4qQoXlxQgx0NOzqZVRkdBWD9EDxWg80CW0,3180
+babelscribe/writers.py,sha256=KgBgU8ffo4ZivfKB1nYUoLvyKFN0_KS8URGq73fnE9g,1206
+babelscribe-0.2.0.dist-info/licenses/LICENSE,sha256=3ZK_oMT5HxgxqJMijLqNWomKlKvxrPgyQfMOHpg-X-s,1081
+babelscribe-0.2.0.dist-info/METADATA,sha256=_RpYsw7J7ac9hLfZ2lRyLuu8jQolMjjYC_OCyW37cEM,12200
+babelscribe-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+babelscribe-0.2.0.dist-info/entry_points.txt,sha256=y2Qve_Z8e-VqQI3YfjnTfT8gXaQ5xKFAJk3KyVBBRh4,53
+babelscribe-0.2.0.dist-info/top_level.txt,sha256=hv5KCl8pcQP8PT6r1d63GdGfprcubJlOZBZipJYP-fc,12
+babelscribe-0.2.0.dist-info/RECORD,,

babelscribe-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

babelscribe-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+babelscribe = babelscribe.cli:main

babelscribe-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +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.

babelscribe-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+babelscribe