primocode 10.16.0 → 10.17.1

package/editor/helpers/transcribe.py

@@ -0,0 +1,734 @@
+# Adapted from browser-use/video-use (MIT, (c) 2026 Browser Use). See THIRD_PARTY_NOTICES.md.
+"""Word-level local transcription of one video (Contract 1).
+
+Pipeline:
+1. Decode the audio to 16 kHz mono (a mute or phase-cancelled channel is left out).
+2. Measure silences with the same auto threshold as speech_regions.py.
+3. Long silences (>= 2 s) are shortened to 1 s before Whisper sees the audio, so it
+   never gets a window of pure room noise (that is where it invents text). Times are
+   mapped back to the original file.
+4. Whisper in chunks of <= 28 s cut at pauses (spec cap: 300 s), each with the prompt:
+   mlx-whisper on Apple Silicon, faster-whisper (int8, CPU) elsewhere,
+   condition_on_previous_text=False and a short PT-BR prompt with fillers.
+5. Hallucination guards: drop words that lie entirely inside a measured silence >= 1 s,
+   repeated n-gram loops, and known subtitle-credit phrases sitting on silence.
+6. Word edges that fall inside a measured silence are moved to the speech edge
+   (Whisper tends to start the first word after a pause too early).
+7. Too few words for the measured voice (under POUCA_FALA_WPS words per second of speech) is
+   reported: on a clip copied out of a longer video that starts mid-sentence, Whisper returned the
+   fillers of the prompt ("E aí, olha só, sabe?") instead of 15 s of speech (29/09/2026).
+
+A file that is only in iCloud (macOS placeholder) is downloaded first or refused with a message:
+ffmpeg hangs on it without any error (helpers/icloud.py).
+
+Output: <edit_dir>/transcripts/<stem>.json, cached by source signature. Also writes
+<edit_dir>/regions/<stem>.json (auto threshold, 0.25 s) when it is missing or stale.
+
+Usage:
+    uv run python helpers/transcribe.py <video> [--edit-dir DIR] [--language pt]
+        [--model large-v3-turbo] [--force] [--prompt "Kiwify, Hubla"] [--no-prompt]
+"""
+
+from __future__ import annotations
+
+import argparse
+import bisect
+import os
+import platform
+import re
+import sys
+import time
+import unicodedata
+from pathlib import Path
+
+import numpy as np
+
+from common import file_signature, load_json, save_json
+from icloud import SoNaNuvem, garantir_local
+from speech_regions import (
+    SAMPLE_RATE,
+    AudioError,
+    complement,
+    detect_silences,
+    estimate_noise,
+    load_mono,
+    probe_media,
+    regions_path,
+    window_levels,
+)
+
+DEFAULT_MODEL = "large-v3-turbo"
+# Nudges Whisper toward verbatim PT-BR with punctuation. Tested on the sample clips:
+# identical words with and without it, better punctuation, no leak into silence.
+DEFAULT_PROMPT = "Ééé, hum, tipo, né, então... Aí, olha só, sabe?"
+MIN_SILENCE_S = 0.25      # same default as speech_regions.py
+LONG_GAP_S = 2.0          # silences at least this long get shortened before Whisper
+KEEP_GAP_S = 0.5          # silence kept on each side of a shortened gap
+CHUNK_TARGET_S = 28.0     # one Whisper window per chunk (spec cap is 300 s)
+CHUNK_MIN_S = 12.0
+GUARD_SILENCE_S = 1.0     # words entirely inside a silence this long are dropped
+EDGE_EPS = 0.02
+POUCA_FALA_WPS = 1.0      # fewer words than this per second of measured voice: Whisper likely returned the prompt
+POUCA_FALA_MIN_S = 4.0    # ... only judged with at least this much voice
+
+MLX_REPOS = {
+    "large-v3-turbo": "mlx-community/whisper-large-v3-turbo",
+    "turbo": "mlx-community/whisper-large-v3-turbo",
+    "large-v3": "mlx-community/whisper-large-v3-mlx",
+    "medium": "mlx-community/whisper-medium-mlx",
+    "small": "mlx-community/whisper-small-mlx",
+    "base": "mlx-community/whisper-base-mlx",
+    "tiny": "mlx-community/whisper-tiny-mlx",
+}
+
+# Whisper's classic inventions on silence (subtitle credits, YouTube outros).
+KNOWN_HALLUCINATIONS = (
+    "legendas pela comunidade amara org",
+    "legendas pela comunidade amaraorg",
+    "legenda adriana zanotto",
+    "legendas adriana zanotto",
+    "transcricao e legendas",
+    "obrigado por assistir",
+    "obrigada por assistir",
+    "inscreva se no canal",
+    "se inscreva no canal",
+    "ate o proximo video",
+    "ate a proxima",
+    "tchau tchau",
+    "e ai",
+    "subtitles by the amara org community",
+    "thanks for watching",
+)
+
+VIDEO_EXTS = (".mov", ".mp4", ".m4v", ".mkv", ".webm")
+
+
+class EngineError(RuntimeError):
+    pass
+
+
+class NameClashError(RuntimeError):
+    """Two different videos would share transcripts/<stem>.json (video.mov + video.mp4)."""
+
+
+def same_video(a: Path, b: Path) -> bool:
+    """Same file, or a copy of it (a symlink, or a copied folder: same size)."""
+    try:
+        return os.path.samefile(a, b) or os.stat(a).st_size == os.stat(b).st_size
+    except OSError:
+        return False
+
+
+def check_name_clash(out_path: Path, video: Path) -> None:
+    """Refuse to overwrite the transcript of ANOTHER video that has the same name without extension."""
+    data = load_json(out_path) if out_path.exists() else None
+    if not isinstance(data, dict) or not data.get("source"):
+        return
+    other = Path(data["source"])
+    if other == video or not other.exists() or same_video(other, video):
+        return
+    raise NameClashError(
+        f"{video.name} e {other.name} têm o mesmo nome sem a extensão e a transcrição de um apagaria a do outro "
+        f"({out_path.name}). Renomeie um deles (ex.: {video.stem}_2{video.suffix}) e rode de novo.")
+
+
+# ---------------------------------------------------------------- engines
+
+def default_engine() -> str:
+    return "mlx" if sys.platform == "darwin" and platform.machine() == "arm64" else "faster-whisper"
+
+
+def engine_label(engine: str, model: str) -> str:
+    name = Path(model).name if ("/" in model or os.sep in model) else model
+    return f"{'mlx-whisper' if engine == 'mlx' else 'faster-whisper'}/{name}"
+
+
+def _mlx_model_path(model: str) -> str:
+    if Path(model).exists():
+        return str(model)
+    repo = MLX_REPOS.get(model, model)
+    try:
+        from huggingface_hub import snapshot_download
+
+        return snapshot_download(repo, local_files_only=True)
+    except Exception:
+        print(f"baixando o modelo {repo} (só na primeira vez)...", file=sys.stderr, flush=True)
+        return repo
+
+
+def _run_mlx(audio: np.ndarray, model: str, language: str | None, prompt: str | None) -> tuple[list[dict], str | None]:
+    try:
+        import mlx_whisper
+    except ImportError as exc:
+        raise EngineError("mlx-whisper não está instalado. Rode: uv sync") from exc
+    result = mlx_whisper.transcribe(
+        audio,
+        path_or_hf_repo=_mlx_model_path(model),
+        language=language,
+        word_timestamps=True,
+        condition_on_previous_text=False,
+        initial_prompt=prompt,
+        verbose=None,
+    )
+    segments = []
+    for seg in result.get("segments", []):
+        words = [{"word": w.get("word", ""), "start": float(w["start"]), "end": float(w["end"]),
+                  "probability": float(w.get("probability", 0.0))} for w in seg.get("words", [])]
+        segments.append({"start": float(seg["start"]), "end": float(seg["end"]),
+                         "text": seg.get("text", ""), "words": words})
+    return segments, result.get("language")
+
+
+_FASTER_MODELS: dict[str, object] = {}
+
+
+def _run_faster(audio: np.ndarray, model: str, language: str | None, prompt: str | None) -> tuple[list[dict], str | None]:
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError as exc:
+        raise EngineError("faster-whisper não está instalado. Rode: uv sync") from exc
+    if model not in _FASTER_MODELS:
+        _FASTER_MODELS[model] = WhisperModel(model, device="cpu", compute_type="int8",
+                                             cpu_threads=os.cpu_count() or 4)
+    fw = _FASTER_MODELS[model]
+    seg_iter, info = fw.transcribe(
+        audio,
+        language=language,
+        word_timestamps=True,
+        condition_on_previous_text=False,
+        initial_prompt=prompt,
+        beam_size=5,
+        vad_filter=False,
+    )
+    segments = []
+    for seg in seg_iter:  # lazy generator: the work happens while iterating
+        words = [{"word": w.word, "start": float(w.start), "end": float(w.end),
+                  "probability": float(w.probability)} for w in (seg.words or [])]
+        segments.append({"start": float(seg.start), "end": float(seg.end), "text": seg.text, "words": words})
+    return segments, getattr(info, "language", None)
+
+
+def run_whisper(audio: np.ndarray, engine: str, model: str, language: str | None,
+                prompt: str | None) -> tuple[list[dict], str | None]:
+    if engine == "mlx":
+        return _run_mlx(audio, model, language, prompt)
+    return _run_faster(audio, model, language, prompt)
+
+
+# ---------------------------------------------------------------- long-gap compaction
+
+class TimeMap:
+    """Kept pieces of the original timeline, laid end to end in the compacted audio."""
+
+    def __init__(self, pieces: list[tuple[float, float]]):
+        self.orig = pieces
+        self.comp_starts: list[float] = []
+        t = 0.0
+        for s, e in pieces:
+            self.comp_starts.append(t)
+            t += e - s
+        self.length = t
+
+    def to_orig(self, t: float, side: str = "start") -> float:
+        if not self.orig:
+            return t
+        if side == "start":
+            i = bisect.bisect_right(self.comp_starts, t) - 1
+        else:
+            i = bisect.bisect_left(self.comp_starts, t) - 1
+        i = min(max(i, 0), len(self.orig) - 1)
+        s, e = self.orig[i]
+        return min(max(s + (t - self.comp_starts[i]), s), e)
+
+    def span_to_orig(self, cs: float, ce: float) -> tuple[float, float]:
+        """Map a word. A word that straddles a join (Whisper pulled its start back across a
+        removed gap) is kept inside the piece that holds most of it, ties going to the later one."""
+        if not self.orig:
+            return cs, ce
+        i = min(max(bisect.bisect_right(self.comp_starts, cs) - 1, 0), len(self.orig) - 1)
+        j = min(max(bisect.bisect_left(self.comp_starts, ce) - 1, 0), len(self.orig) - 1)
+        if j <= i:
+            return self.to_orig(cs, "start"), self.to_orig(ce, "end")
+        best, best_len = i, -1.0
+        for k in range(i, j + 1):
+            k0 = self.comp_starts[k]
+            k1 = k0 + (self.orig[k][1] - self.orig[k][0])
+            part = min(ce, k1) - max(cs, k0)
+            if part >= best_len:
+                best, best_len = k, part
+        k0 = self.comp_starts[best]
+        s, e = self.orig[best]
+        a = s + max(cs - k0, 0.0)
+        b = s + min(ce - k0, e - s)
+        return min(a, e), max(min(b, e), min(a, e))
+
+
+def plan_pieces(silences: list[list[float]], duration: float) -> list[tuple[float, float]]:
+    removed = []
+    for s, e in silences:
+        if e - s < LONG_GAP_S:
+            continue
+        rs = 0.0 if s <= EDGE_EPS else s + KEEP_GAP_S
+        re_ = duration if e >= duration - EDGE_EPS else e - KEEP_GAP_S
+        if re_ - rs > 0.05:
+            removed.append([rs, re_])
+    return [(s, e) for s, e in complement(removed, 0.0, duration) if e - s > 0.01]
+
+
+def plan_chunks(audio: np.ndarray, sr: int = SAMPLE_RATE, max_s: float = CHUNK_TARGET_S,
+                min_s: float = CHUNK_MIN_S) -> list[tuple[int, int]]:
+    """Sample ranges of <= max_s, each cut at a quiet point (a pause) after at least min_s.
+
+    Chunks fit one Whisper window, so the prompt applies to all of them: with
+    condition_on_previous_text=False Whisper only uses the prompt on the first window
+    of each call, and later windows came out without punctuation.
+    """
+    total = len(audio)
+    max_n = int(max_s * sr)
+    if total <= max_n:
+        return [(0, total)]
+    win = int(0.05 * sr)
+    rms_db, _ = window_levels(audio, sr)
+    smooth = np.convolve(rms_db, np.ones(5) / 5, mode="same") if len(rms_db) >= 5 else rms_db
+    bounds, start = [], 0
+    while total - start > max_n:
+        lo_w = (start + int(min_s * sr)) // win
+        hi_w = min((start + max_n) // win, len(smooth))
+        seg = smooth[lo_w:hi_w]
+        if len(seg) == 0:
+            cut = start + max_n
+        else:
+            quiet = np.where(seg <= seg.min() + 1.5)[0]
+            cut = (lo_w + int(quiet[-1])) * win + win // 2
+        cut = min(max(cut, start + win), total)
+        bounds.append((start, cut))
+        start = cut
+    if total > start:
+        if bounds and total - start < 3 * sr and total - bounds[-1][0] <= 30 * sr:
+            bounds[-1] = (bounds[-1][0], total)
+        else:
+            bounds.append((start, total))
+    return bounds
+
+
+# ---------------------------------------------------------------- word cleanup
+
+def _norm(text: str) -> str:
+    t = unicodedata.normalize("NFKD", text.lower())
+    t = "".join(c for c in t if not unicodedata.combining(c))
+    return re.sub(r"[^\w]+", "", t)
+
+
+def _has_letters(text: str) -> bool:
+    return any(c.isalnum() for c in text)
+
+
+def collect_words(segments: list[dict], offset: float, tmap: TimeMap, seg_base: int) -> list[dict]:
+    words: list[dict] = []
+    for si, seg in enumerate(segments):
+        first_in_seg = True
+        for w in seg["words"]:
+            raw = w.get("word") or ""
+            text = raw.strip()
+            if not text:
+                continue
+            s, e = tmap.span_to_orig(offset + w["start"], offset + max(w["end"], w["start"]))
+            same_seg = bool(words) and words[-1]["seg"] == seg_base + si
+            # Punctuation alone, or a piece with no leading space ("20" + ".8."), belongs to the previous word.
+            if same_seg and (not _has_letters(text) or (not first_in_seg and not raw[:1].isspace())):
+                prev = words[-1]
+                prev["text"] += text
+                prev["end"] = max(prev["end"], e)
+                prev["prob"] = min(prev["prob"], w["probability"])
+                continue
+            first_in_seg = False
+            if not _has_letters(text):
+                continue
+            words.append({"text": text, "start": s, "end": max(e, s), "prob": w["probability"], "seg": seg_base + si})
+    return words
+
+
+def _inside(w: dict, s: float, e: float) -> bool:
+    return w["start"] >= s - EDGE_EPS and w["end"] <= e + EDGE_EPS
+
+
+def silence_guard(words: list[dict], silences: list[list[float]]) -> tuple[list[dict], int]:
+    long_sil = [x for x in silences if x[1] - x[0] >= GUARD_SILENCE_S]
+    if not long_sil:
+        return words, 0
+    starts = [x[0] for x in long_sil]
+    kept = []
+    for w in words:
+        i = bisect.bisect_right(starts, w["start"] + EDGE_EPS) - 1
+        if i >= 0 and _inside(w, *long_sil[i]):
+            continue
+        kept.append(w)
+    return kept, len(words) - len(kept)
+
+
+def _speech_fraction(s: float, e: float, silences: list[list[float]]) -> float:
+    if e - s <= 0:
+        mid = s
+        return 0.0 if any(a <= mid <= b for a, b in silences) else 1.0
+    sil = sum(max(0.0, min(e, b) - max(s, a)) for a, b in silences)
+    return max(0.0, 1.0 - sil / (e - s))
+
+
+def loop_guard(words: list[dict], silences: list[list[float]]) -> tuple[list[dict], int]:
+    """Drop repeated n-gram loops (Whisper stuck repeating itself).
+
+    A run needs 5+ copies of one word, 4+ copies of 2-3 words or 3+ copies of longer
+    n-grams. Copies after the first are dropped only when they look invented: low
+    confidence, squeezed timing, or sitting mostly on silence. A real retake said three
+    times keeps all its copies.
+    """
+    toks = [_norm(w["text"]) for w in words]
+    drop = [False] * len(words)
+    # The same word twice on top of itself in time (a segment emitted twice) is never real speech.
+    for i in range(1, len(words)):
+        for j in range(max(0, i - 8), i):
+            if not drop[j] and toks[i] and toks[i] == toks[j] and words[i]["start"] < words[j]["end"] - 0.05:
+                drop[i] = True
+                break
+    words = [w for w, d in zip(words, drop) if not d]
+    n_overlap = sum(drop)
+    toks = [_norm(w["text"]) for w in words]
+    drop = [False] * len(words)
+    i, n_words = 0, len(words)
+    while i < n_words:
+        found = None
+        for n in range(1, 9):
+            if i + 2 * n > n_words:
+                break
+            pat = toks[i:i + n]
+            if not all(pat):
+                continue
+            k = 1
+            while toks[i + k * n:i + (k + 1) * n] == pat:
+                k += 1
+            need = 5 if n == 1 else 4 if n <= 3 else 3
+            if k >= need:
+                found = (n, k)
+                break
+        if not found:
+            i += 1
+            continue
+        n, k = found
+        for c in range(1, k):
+            copy = words[i + c * n:i + (c + 1) * n]
+            mean_prob = sum(w["prob"] for w in copy) / n
+            mean_dur = sum(w["end"] - w["start"] for w in copy) / n
+            speech = _speech_fraction(copy[0]["start"], copy[-1]["end"], silences)
+            if mean_prob < 0.6 or mean_dur < 0.08 or speech < 0.5:
+                for j in range(i + c * n, i + (c + 1) * n):
+                    drop[j] = True
+        i += k * n
+    kept = [w for w, d in zip(words, drop) if not d]
+    return kept, len(words) - len(kept) + n_overlap
+
+
+def known_phrase_guard(words: list[dict], silences: list[list[float]]) -> tuple[list[dict], int]:
+    """Drop whole segments that are a known subtitle-credit phrase sitting mostly on silence.
+
+    A creator can really say "obrigado por assistir", so the text alone is never enough.
+    """
+    by_seg: dict[int, list[int]] = {}
+    for idx, w in enumerate(words):
+        by_seg.setdefault(w["seg"], []).append(idx)
+    drop: set[int] = set()
+    for idxs in by_seg.values():
+        seg_words = [words[i] for i in idxs]
+        text = " ".join(_norm(w["text"]) for w in seg_words).strip()
+        if text not in KNOWN_HALLUCINATIONS:
+            continue
+        if _speech_fraction(seg_words[0]["start"], seg_words[-1]["end"], silences) < 0.5:
+            drop.update(idxs)
+    kept = [w for i, w in enumerate(words) if i not in drop]
+    return kept, len(words) - len(kept)
+
+
+_FINAL_PUNCT = re.compile(r"[.!?…]$")   # sentence end or ellipsis (not commas)
+EDGE_TAIL_S = 0.25                         # a speech island this short next to a sentence end is a neighbour's tail
+
+
+def refine_edges(words: list[dict], silences: list[list[float]]) -> int:
+    """Move word edges that fall inside a measured silence onto speech. In place.
+
+    The part of the word outside the pauses is split into speech islands:
+    - one island (the word starts or ends inside a pause): the word becomes that island;
+    - several islands (a pause inside the word): the longest island wins, after dropping a
+      short first island when the previous word ends a sentence (it is that word's tail) and
+      a short last island when this word ends a sentence or has "..." (the next word's head);
+    - no island (entirely inside a short pause): snap after the pause, or before it when the
+      word ends a sentence and the previous one does not.
+    """
+    if not silences or not words:
+        return 0
+    starts = [s for s, _ in silences]
+    changed = 0
+    for idx, w in enumerate(words):
+        ws, we = w["start"], w["end"]
+        j = bisect.bisect_right(starts, we) - 1
+        hits = []
+        while j >= 0 and silences[j][1] > ws:
+            if silences[j][0] < we:
+                hits.append(silences[j])
+            j -= 1
+        if not hits:
+            continue
+        hits.sort()
+        dur = we - ws
+        own_final = bool(_FINAL_PUNCT.search(w["text"]))
+        prev_final = idx > 0 and bool(_FINAL_PUNCT.search(words[idx - 1]["text"]))
+        islands = [i for i in complement([[max(a, ws), min(b, we)] for a, b in hits], ws, we) if i[1] - i[0] > 1e-3]
+        if not islands:
+            ss, se = hits[0]
+            if own_final and not prev_final:
+                ns, ne = max(ss - min(dur, 0.3), 0.0), ss
+            else:
+                ns, ne = se, se + min(dur, 0.3)
+        else:
+            cands = islands
+            if len(cands) > 1 and prev_final and cands[0][1] - cands[0][0] <= EDGE_TAIL_S:
+                cands = cands[1:]
+            if len(cands) > 1 and own_final and cands[-1][1] - cands[-1][0] <= EDGE_TAIL_S:
+                cands = cands[:-1]
+            ns, ne = max(cands, key=lambda i: (round(i[1] - i[0], 3), i[0]))
+        if ne - ns < 0.02:
+            ne = ns + min(max(dur, 0.02), 0.08)
+        if abs(ns - ws) > 1e-6 or abs(ne - we) > 1e-6:
+            w["start"], w["end"] = ns, ne
+            changed += 1
+    words.sort(key=lambda x: x["start"])
+    for a, b in zip(words, words[1:]):
+        if b["start"] < a["end"]:
+            a["end"] = max(a["start"], b["start"])
+    return changed
+
+
+def build_segments(words: list[dict]) -> list[dict]:
+    groups: dict[int, list[dict]] = {}
+    for w in words:
+        groups.setdefault(w["seg"], []).append(w)
+    segs = []
+    for ws in groups.values():
+        text = " ".join(w["text"] for w in ws)
+        segs.append({"start": round(ws[0]["start"], 3), "end": round(max(w["end"] for w in ws), 3), "text": text})
+    segs.sort(key=lambda s: s["start"])
+    return segs
+
+
+def aviso_pouca_fala(words: list[dict], speech_s: float, prompt: str | None) -> str | None:
+    """Warning when the transcript has far fewer words than the measured voice asks for.
+
+    Normal speech is 2 to 3 words per second. Under POUCA_FALA_WPS, Whisper most likely returned the prompt
+    (its fillers) or skipped a stretch: seen on a clip that started in the middle of a sentence.
+    """
+    if speech_s < POUCA_FALA_MIN_S:
+        return None
+    n = len(words)
+    wps = n / speech_s
+    if wps >= POUCA_FALA_WPS:
+        return None
+    vocab = {_norm(x) for x in re.findall(r"\w+", f"{DEFAULT_PROMPT} {prompt or ''}")} - {""}
+    eco = [w["text"] for w in words if _norm(w["text"]) in vocab]
+    msg = (f"só {n} palavra(s) para {speech_s:.0f} s de voz medida ({wps:.1f} por segundo; fala normal dá 2 a 3). ")
+    if n and len(eco) * 2 >= n:
+        msg += f"Quase tudo é o texto do prompt (\"{' '.join(eco[:8])}\"): o Whisper devolveu o prompt, não a fala. "
+    msg += ("Se o arquivo é um trecho copiado de um vídeo maior, copie de novo começando numa pausa (antes da "
+            "primeira palavra de uma frase) e transcreva de novo; senão rode com --no-prompt --force. Se o "
+            "trecho só tem música ou ruído, pode ignorar.")
+    return msg
+
+
+# ---------------------------------------------------------------- main entry
+
+def transcript_path(edit_dir: Path | str, video: Path | str) -> Path:
+    return Path(edit_dir) / "transcripts" / f"{Path(video).stem}.json"
+
+
+def build_prompt(extra: str | None, use_default: bool) -> str | None:
+    parts = []
+    if use_default:
+        parts.append(DEFAULT_PROMPT)
+    if extra and extra.strip():
+        parts.append(extra.strip())
+    return " ".join(parts) if parts else None
+
+
+def is_cached(out_path: Path, video: Path, engine: str, model: str, language: str | None, prompt: str | None) -> bool:
+    data = load_json(out_path)
+    if not isinstance(data, dict):
+        return False
+    if data.get("source_sig") != file_signature(video):
+        return False
+    if data.get("engine") != engine_label(engine, model):
+        return False
+    if language and data.get("language") != language:
+        return False
+    return data.get("prompt", DEFAULT_PROMPT) == prompt
+
+
+def transcribe_one(video: Path | str, edit_dir: Path | str | None = None, language: str | None = "pt",
+                   model: str = DEFAULT_MODEL, force: bool = False, prompt: str | None = DEFAULT_PROMPT,
+                   engine: str | None = None, verbose: bool = True) -> Path:
+    """Transcribe one video. Returns the transcript path (cached when the source did not change)."""
+    video = Path(video).absolute()
+    if not video.exists():
+        raise FileNotFoundError(f"vídeo não encontrado: {video}")
+    edit_dir = Path(edit_dir).absolute() if edit_dir else video.parent / "edit"
+    engine = engine or default_engine()
+    language = None if (language or "").lower() in ("", "auto") else language
+    out_path = transcript_path(edit_dir, video)
+    check_name_clash(out_path, video)
+
+    if not force and is_cached(out_path, video, engine, model, language, prompt):
+        if verbose:
+            data = load_json(out_path)
+            print(f"{video.stem}: em cache ({len(data.get('words', []))} palavras) · {out_path}")
+            if data.get("aviso"):
+                print(f"{video.stem}: AVISO: {data['aviso']}", flush=True)
+        return out_path
+
+    garantir_local([video], avisar=(print if verbose else (lambda *_: None)))
+    t0 = time.time()
+    info = probe_media(video)
+    duration = float(info.get("duration") or 0.0)
+    mono, audio_desc = load_mono(video)
+    if duration <= 0:
+        duration = len(mono) / SAMPLE_RATE
+    if verbose and audio_desc.get("reason"):
+        side = {"left": "esquerdo", "right": "direito"}.get(audio_desc["used"], audio_desc["used"])
+        print(f"{video.stem}: usando só o canal {side} ({audio_desc['reason']})", flush=True)
+
+    est = estimate_noise(mono)
+    audio_len = len(mono) / SAMPLE_RATE
+    silences = [[min(a, duration), min(b, duration)] for a, b in detect_silences(mono, est["threshold_db"], MIN_SILENCE_S)]
+    silences = [x for x in silences if x[1] > x[0]]
+    if silences and silences[-1][1] >= min(audio_len, duration) - EDGE_EPS:
+        silences[-1][1] = duration
+    t_audio = time.time() - t0
+
+    pieces = plan_pieces(silences, audio_len)
+    tmap = TimeMap(pieces)
+    comp = np.concatenate([mono[int(s * SAMPLE_RATE):int(e * SAMPLE_RATE)] for s, e in pieces]) if pieces else np.zeros(0, np.float32)
+    comp = np.ascontiguousarray(comp, dtype=np.float32)
+
+    t1 = time.time()
+    raw_words: list[dict] = []
+    detected_lang = language
+    seg_base = 0
+    speech_total = sum(e - s for s, e in complement(silences, 0.0, audio_len))
+    if len(comp) >= int(0.2 * SAMPLE_RATE) and speech_total >= 0.1:
+        for a, b in plan_chunks(comp):
+            chunk = comp[a:b]
+            if len(chunk) < int(0.2 * SAMPLE_RATE):
+                continue
+            segments, lang = run_whisper(chunk, engine, model, language, prompt)
+            detected_lang = detected_lang or lang
+            raw_words.extend(collect_words(segments, a / SAMPLE_RATE, tmap, seg_base))
+            seg_base += len(segments)
+    t_whisper = time.time() - t1
+
+    words = sorted(raw_words, key=lambda w: w["start"])
+    words, n_sil = silence_guard(words, silences)
+    words, n_loop = loop_guard(words, silences)
+    words, n_known = known_phrase_guard(words, silences)
+    n_refined = refine_edges(words, silences)
+
+    for w in words:
+        w["start"] = round(min(max(w["start"], 0.0), duration), 3)
+        w["end"] = round(min(max(w["end"], w["start"]), duration), 3)
+    segments = build_segments(words)
+    out_words = [{"text": w["text"], "start": w["start"], "end": w["end"], "prob": round(w["prob"], 3)} for w in words]
+    aviso = aviso_pouca_fala(out_words, speech_total, prompt)
+
+    elapsed = time.time() - t0
+    doc = {
+        "source": str(video),
+        "source_sig": file_signature(video),
+        "stem": video.stem,
+        "duration": round(duration, 3),
+        "language": detected_lang or language or "",
+        "engine": engine_label(engine, model),
+        "words": out_words,
+        "segments": segments,
+        "prompt": prompt,
+        "audio": {**audio_desc, "noise_db": est["threshold_db"], "shortened_gaps": len(pieces) - 1 if pieces else 0},
+        "guard": {"silence": n_sil, "loop": n_loop, "known_phrase": n_known, "refined_edges": n_refined},
+        "timing": {"audio_s": round(t_audio, 2), "whisper_s": round(t_whisper, 2), "total_s": round(elapsed, 2)},
+        "voz_s": round(speech_total, 2),
+    }
+    if aviso:
+        doc["aviso"] = aviso
+    save_json(out_path, doc)
+    _write_regions_if_stale(edit_dir, video, duration, est, silences, audio_desc)
+
+    if verbose:
+        per_min = elapsed / (duration / 60.0) if duration > 0 else 0.0
+        removed = n_sil + n_loop + n_known
+        extra = f" · {removed} palavras inventadas removidas" if removed else ""
+        print(f"{video.stem}: {len(out_words)} palavras, {duration:.1f}s de áudio, {elapsed:.1f}s "
+              f"({per_min:.1f}s por minuto){extra} · {out_path}", flush=True)
+        if aviso:
+            print(f"{video.stem}: AVISO: {aviso}", flush=True)
+    return out_path
+
+
+def _write_regions_if_stale(edit_dir: Path, video: Path, duration: float, est: dict,
+                            silences: list[list[float]], audio_desc: dict) -> None:
+    path = regions_path(edit_dir, video.stem)
+    cached = load_json(path)
+    if cached and cached.get("source_sig") == file_signature(video):
+        return
+    r = lambda x: round(float(x), 3)  # noqa: E731
+    save_json(path, {
+        "source": str(video),
+        "source_sig": file_signature(video),
+        "stem": video.stem,
+        "duration": r(duration),
+        "noise_db": est["threshold_db"],
+        "noise_mode": "auto",
+        "min_silence": MIN_SILENCE_S,
+        "speech": [[r(s), r(e)] for s, e in complement(silences, 0.0, duration)],
+        "silences": [[r(s), r(e)] for s, e in silences],
+        "audio": audio_desc,
+        "noise_estimate": est,
+    })
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Transcreve um vídeo palavra por palavra, localmente (Whisper).")
+    ap.add_argument("video", type=Path, help="arquivo de vídeo")
+    ap.add_argument("--edit-dir", type=Path, default=None, help="pasta edit (padrão: <pasta do vídeo>/edit)")
+    ap.add_argument("--language", default="pt", help="idioma falado (padrão pt; 'auto' detecta)")
+    ap.add_argument("--model", default=DEFAULT_MODEL, help="modelo Whisper (padrão large-v3-turbo)")
+    ap.add_argument("--force", action="store_true", help="transcreve de novo mesmo com cache")
+    ap.add_argument("--prompt", default=None,
+                    help="palavras que aparecem no vídeo, para o Whisper acertar a grafia (ex.: \"Kiwify, Hubla\")")
+    ap.add_argument("--no-prompt", action="store_true", help="não usa o prompt padrão com vícios de fala")
+    ap.add_argument("--engine", choices=("auto", "mlx", "faster-whisper"), default="auto",
+                    help="motor (padrão: mlx no Mac Apple Silicon, faster-whisper nos outros)")
+    args = ap.parse_args()
+
+    video = args.video.absolute()
+    if not video.exists():
+        sys.exit(f"vídeo não encontrado: {video}")
+    if video.is_dir():
+        sys.exit(f"isso é uma pasta, não um vídeo: {video}\nPara a pasta inteira use transcribe_batch.py")
+    try:
+        transcribe_one(
+            video,
+            edit_dir=args.edit_dir,
+            language=args.language,
+            model=args.model,
+            force=args.force,
+            prompt=build_prompt(args.prompt, not args.no_prompt),
+            engine=None if args.engine == "auto" else args.engine,
+        )
+    except (AudioError, EngineError, FileNotFoundError, NameClashError, SoNaNuvem) as exc:
+        sys.exit(str(exc))
+
+
+if __name__ == "__main__":
+    main()