primocode 10.16.0 → 10.17.0

package/editor/helpers/texto_na_tela.py

@@ -0,0 +1,366 @@
+"""O que já está escrito ou desenhado na tela, para a legenda não repetir nem cobrir.
+
+Lê o vídeo de amostra em amostra (2 por segundo por padrão) e responde três coisas:
+
+  1. onde há texto/desenho na tela, por faixa de altura (para escolher onde a legenda cabe);
+  2. em que trechos já existe legenda gravada no vídeo (para não legendar duas vezes);
+  3. em que trechos a tela inteira é um gráfico claro (papel), onde a legenda branca sumiria.
+
+Dois motores de leitura:
+
+  vision       macOS com as ferramentas de linha de comando da Apple (`swiftc`): lê as palavras de
+               verdade (Vision). É o único que sabe dizer "isso aqui já é a legenda", porque compara o
+               que está escrito com o que está sendo falado.
+  heuristico   qualquer sistema, só com OpenCV: acha as manchas de texto sem ler. Serve para desviar,
+               e marca "já tem legenda" quando a mancha fica no lugar de legenda e troca junto com a
+               fala (uma placa de motion fica parada; legenda muda a cada segundo).
+
+Usage:
+    uv run python helpers/texto_na_tela.py --video cut.mp4 [--edit-dir DIR] [--transcript W.json]
+        [--fps 2] [--backend auto|vision|heuristico] [--force] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unicodedata
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import (edit_dir_for, file_signature, load_json, now_iso, probe_video,  # noqa: E402
+                    require_binary, run, save_json)
+
+VERSION = 1
+# Faixas candidatas, em fração da altura (centro da legenda no meio da faixa).
+BANDAS: list[tuple[str, float, float]] = [
+    ("legenda", 0.655, 0.760),   # padrão: altura do peito, abaixo do rosto
+    ("alta", 0.525, 0.630),
+    ("baixa", 0.780, 0.885),
+    ("rodape", 0.865, 0.960),
+]
+PAPEL_MIN = 0.72        # fração de pixel claro sem cor para a tela contar como gráfico claro
+TINTA_LIVRE = 0.02      # tinta máxima numa faixa de papel para caber legenda escura
+CONF_MIN = 0.45
+JANELA_FALA = 1.5       # segundos de folga ao comparar o escrito com o falado
+
+
+def utf8_console() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+        except (AttributeError, ValueError, OSError):
+            pass
+
+
+def _norm(texto: str) -> str:
+    return unicodedata.normalize("NFD", texto.lower()).encode("ascii", "ignore").decode()
+
+
+def _bin_dir() -> Path:
+    d = Path.home() / ".editor-video" / "bin"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def vision_disponivel() -> bool:
+    return sys.platform == "darwin" and shutil.which("swiftc") is not None
+
+
+def compilar_vision(fonte: Path | None = None) -> Path | None:
+    """Compila (uma vez) o leitor da Apple e devolve o caminho do binário."""
+    if not vision_disponivel():
+        return None
+    fonte = fonte or Path(__file__).resolve().parent / "assets_ocr" / "ocr_vision.swift"
+    if not fonte.exists():
+        return None
+    alvo = _bin_dir() / "ocr_vision"
+    if alvo.exists() and alvo.stat().st_mtime >= fonte.stat().st_mtime:
+        return alvo
+    try:
+        run(["swiftc", "-O", str(fonte), "-o", str(alvo)])
+    except (subprocess.CalledProcessError, OSError):
+        return None
+    return alvo if alvo.exists() else None
+
+
+def extrair_quadros(video: Path, destino: Path, fps: float, largura: int = 608) -> list[float]:
+    require_binary("ffmpeg")
+    run(["ffmpeg", "-y", "-loglevel", "error", "-i", str(video),
+         "-vf", f"fps={fps},scale={largura}:-2", "-q:v", "3", str(destino / "f_%05d.jpg")])
+    nomes = sorted(destino.glob("f_*.jpg"))
+    return [round(i / fps, 3) for i in range(len(nomes))]
+
+
+def _ler_vision(binario: Path, pasta: Path) -> dict[str, list[dict]]:
+    saida = pasta / "ocr.json"
+    run([str(binario), str(pasta), str(saida)])
+    return json.loads(saida.read_text())
+
+
+def _ler_heuristico(pasta: Path) -> dict[str, list[dict]]:
+    import cv2  # noqa: PLC0415 — só quando este motor é usado
+    import numpy as np  # noqa: PLC0415
+
+    out: dict[str, list[dict]] = {}
+    for arq in sorted(pasta.glob("f_*.jpg")):
+        img = cv2.imread(str(arq), cv2.IMREAD_GRAYSCALE)
+        if img is None:
+            continue
+        h, w = img.shape
+        grad = cv2.morphologyEx(img, cv2.MORPH_GRADIENT, cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3)))
+        _, bw = cv2.threshold(grad, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)
+        linha = cv2.morphologyEx(bw, cv2.MORPH_CLOSE, cv2.getStructuringElement(cv2.MORPH_RECT, (21, 3)))
+        cont, _ = cv2.findContours(linha, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        itens: list[dict] = []
+        for c in cont:
+            x, y, cw, ch = cv2.boundingRect(c)
+            if ch < h * 0.012 or ch > h * 0.12 or cw < ch * 1.2 or cw > w * 0.96:
+                continue
+            densidade = float(np.count_nonzero(bw[y:y + ch, x:x + cw])) / max(1, cw * ch)
+            if not 0.08 < densidade < 0.62:
+                continue
+            itens.append({"t": "", "c": 0.5, "x": x / w, "y": 1 - (y + ch) / h, "w": cw / w, "h": ch / h})
+        out[arq.name] = itens
+    return out
+
+
+def _papel_e_tinta(pasta: Path, nomes: list[str]) -> tuple[list[float], list[dict[str, float]]]:
+    from PIL import Image  # noqa: PLC0415
+    import numpy as np  # noqa: PLC0415
+
+    papel: list[float] = []
+    tinta: list[dict[str, float]] = []
+    for nome in nomes:
+        im = np.asarray(Image.open(pasta / nome).convert("RGB")).astype(int)
+        sat = im.max(2) - im.min(2)
+        claro = im.min(2)
+        papel.append(round(float(((claro > 205) & (sat < 40)).mean()), 3))
+        h = im.shape[0]
+        faixa: dict[str, float] = {}
+        for nome_faixa, a, b in BANDAS:
+            bloco = im[int(a * h):int(b * h)]
+            s = bloco.max(2) - bloco.min(2)
+            c = bloco.min(2)
+            faixa[nome_faixa] = round(float(((c < 200) | (s > 45)).mean()), 3)
+        tinta.append(faixa)
+    return papel, tinta
+
+
+def _intervalos(marcas: list[tuple[float, bool]], minimo: float = 0.6,
+                juntar: float = 2.5, dilatar: int = 1) -> list[list[float]]:
+    if dilatar:
+        vivos = [i for i, (_, v) in enumerate(marcas) if v]
+        marcas = [(t, any(abs(i - j) <= dilatar for j in vivos)) for i, (t, v) in enumerate(marcas)] \
+            if vivos else marcas
+    faixas: list[list[float]] = []
+    aberto: list[float] | None = None
+    for t, v in marcas:
+        if v and aberto is None:
+            aberto = [t, t]
+        elif v:
+            aberto[1] = t
+        elif aberto is not None:
+            faixas.append(aberto)
+            aberto = None
+    if aberto is not None:
+        faixas.append(aberto)
+    unidas: list[list[float]] = []
+    for f in faixas:
+        if unidas and f[0] - unidas[-1][1] <= juntar:
+            unidas[-1][1] = f[1]
+        else:
+            unidas.append(f)
+    return [f for f in unidas if f[1] - f[0] >= minimo]
+
+
+def _legenda_por_palavra(amostras: list[dict], palavras: list[dict]) -> list[tuple[float, bool]]:
+    """Já tem legenda quando o que está escrito bate com o que está sendo falado."""
+    marcas: list[tuple[float, bool]] = []
+    for am in amostras:
+        t = am["t"]
+        ditas = {_norm(re.sub(r"\W", "", w.get("word", w.get("text", ""))))
+                 for w in palavras
+                 if t - JANELA_FALA <= float(w.get("start", w.get("s", -9))) <= t + JANELA_FALA}
+        ditas = {p for p in ditas if len(p) >= 3}
+        achou = False
+        for it in am["itens"]:
+            escritas = {_norm(x) for x in re.findall(r"\w{3,}", it.get("texto", ""))}
+            if escritas & ditas:
+                achou = True
+                break
+        marcas.append((t, achou))
+    return marcas
+
+
+def _legenda_por_movimento(amostras: list[dict]) -> list[tuple[float, bool]]:
+    """Sem a fala para comparar: mancha no lugar de legenda que troca de tamanho a cada amostra.
+
+    Recebe as amostras já convertidas por `mapear` (centro_y medido do topo, centro_x, largura, altura), nos dois
+    motores. Antes lia as chaves cruas do leitor (x, y, w, h) e quebrava com KeyError 'y' (visto em 29/09/2026)."""
+    marcas: list[tuple[float, bool]] = []
+    anterior: tuple[float, float] | None = None
+    for am in amostras:
+        alvo = None
+        for it in am["itens"]:
+            if 0.55 <= it["centro_y"] <= 0.92 and 0.25 <= it["centro_x"] <= 0.75:
+                if alvo is None or it["largura"] > alvo[0]:
+                    alvo = (it["largura"], it["altura"])
+        troca = bool(alvo and anterior and abs(alvo[0] - anterior[0]) > 0.02)
+        marcas.append((am["t"], troca))
+        anterior = alvo
+    return marcas
+
+
+def mapear(video: Path, *, fps: float = 2.0, backend: str = "auto",
+           palavras: list[dict] | None = None) -> dict:
+    info = probe_video(video)
+    largura, altura = int(info["width"]), int(info["height"])
+    with tempfile.TemporaryDirectory(prefix="texto-na-tela-") as tmp:
+        pasta = Path(tmp)
+        tempos = extrair_quadros(video, pasta, fps)
+        nomes = [f"f_{i + 1:05d}.jpg" for i in range(len(tempos))]
+        binario = compilar_vision() if backend in ("auto", "vision") else None
+        if backend == "vision" and binario is None:
+            raise RuntimeError("motor vision indisponível (precisa de macOS com swiftc)")
+        usado = "vision" if binario else "heuristico"
+        bruto = _ler_vision(binario, pasta) if binario else _ler_heuristico(pasta)
+        papel, tinta = _papel_e_tinta(pasta, nomes)
+    amostras: list[dict] = []
+    for i, (t, nome) in enumerate(zip(tempos, nomes)):
+        itens = []
+        for it in bruto.get(nome, []):
+            if float(it.get("c", 1)) < CONF_MIN:
+                continue
+            texto = str(it.get("t", "")).strip()
+            centro = 1 - (it["y"] + it["h"] / 2)          # 0 no topo, 1 embaixo
+            itens.append({"texto": texto, "centro_y": round(centro, 4),
+                          "altura": round(it["h"], 4), "centro_x": round(it["x"] + it["w"] / 2, 4),
+                          "largura": round(it["w"], 4)})
+        amostras.append({"t": t, "itens": itens, "papel": papel[i], "tinta": tinta[i]})
+    if palavras:
+        marcas = _legenda_por_palavra(amostras, palavras)
+    else:
+        marcas = _legenda_por_movimento(amostras)
+    doc = {
+        "version": VERSION, "created_at": now_iso(), "video": video.name,
+        "video_sig": file_signature(video), "backend": usado, "fps": fps,
+        "width": largura, "height": altura, "duration": round(float(info["duration"]), 3),
+        "bandas": [{"nome": n, "a": a, "b": b} for n, a, b in BANDAS],
+        "amostras": amostras,
+        "legenda_existente": _intervalos(marcas),
+        "tela_cheia": _intervalos([(a["t"], a["papel"] >= PAPEL_MIN) for a in amostras], minimo=1.0),
+    }
+    doc["resumo"] = resumo(doc)
+    return doc
+
+
+def _amostras_entre(doc: dict, a: float, z: float) -> list[dict]:
+    return [s for s in doc["amostras"] if a - 0.3 <= s["t"] <= z + 0.3] or \
+           [min(doc["amostras"], key=lambda s: abs(s["t"] - (a + z) / 2))] if doc["amostras"] else []
+
+
+def cobre(faixas: list[list[float]], a: float, z: float, minimo: float = 0.45) -> bool:
+    if z <= a:
+        return False
+    sobra = sum(max(0.0, min(z, f[1]) - max(a, f[0])) for f in faixas)
+    return sobra > minimo * (z - a)
+
+
+def escolher_faixa(doc: dict, a: float, z: float, *, preferida: str | None = None,
+                   margem: float = 0.05) -> dict | None:
+    """Faixa livre para pôr a legenda entre `a` e `z` (None = não cabe em nenhuma)."""
+    ordem = [n for n, _, _ in BANDAS]
+    if preferida and preferida in ordem:
+        ordem = [ordem[0]] + ([preferida] if preferida != ordem[0] else []) + \
+                [n for n in ordem[1:] if n != preferida]
+    amostras = _amostras_entre(doc, a, z)
+    papel = bool(amostras) and all(s["papel"] >= PAPEL_MIN for s in amostras)
+    for nome in ordem:
+        faixa = next(f for f in BANDAS if f[0] == nome)
+        lo, hi = faixa[1] - margem, faixa[2] + margem
+        livre = True
+        for s in amostras:
+            if papel:
+                if s["tinta"].get(nome, 1.0) > TINTA_LIVRE:
+                    livre = False
+                    break
+            else:
+                for it in s["itens"]:
+                    if it["centro_y"] + it["altura"] / 2 > lo and it["centro_y"] - it["altura"] / 2 < hi:
+                        livre = False
+                        break
+            if not livre:
+                break
+        if livre:
+            return {"faixa": nome, "centro_y": round((faixa[1] + faixa[2]) / 2, 4),
+                    "papel": papel, "cor": "escura" if papel else "clara"}
+    return None
+
+
+def resumo(doc: dict) -> str:
+    n_leg = len(doc["legenda_existente"])
+    n_cheia = len(doc["tela_cheia"])
+    seg_leg = sum(b - a for a, b in doc["legenda_existente"])
+    seg_cheia = sum(b - a for a, b in doc["tela_cheia"])
+    motor = "leitura de texto (Vision)" if doc["backend"] == "vision" else "manchas de texto (OpenCV)"
+    partes = [f"{motor}",
+              f"{n_leg} trecho(s) já com legenda na tela ({seg_leg:.0f}s)",
+              f"{n_cheia} trecho(s) de gráfico em tela cheia ({seg_cheia:.0f}s)"]
+    if doc["backend"] != "vision":
+        partes.append("sem leitura de palavras: confira os trechos marcados antes de pular a legenda")
+    return "; ".join(partes) + "."
+
+
+def main(argv: list[str] | None = None) -> int:
+    utf8_console()
+    ap = argparse.ArgumentParser(description="O que já está escrito na tela (para a legenda desviar)")
+    ap.add_argument("--video", type=Path, required=True)
+    ap.add_argument("--edit-dir", type=Path)
+    ap.add_argument("--transcript", type=Path, help="JSON com as palavras faladas (start/word)")
+    ap.add_argument("--fps", type=float, default=2.0)
+    ap.add_argument("--backend", choices=["auto", "vision", "heuristico"], default="auto")
+    ap.add_argument("--force", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+    video = args.video.expanduser().absolute()
+    if not video.exists():
+        print(f"erro: não encontrei {video}", file=sys.stderr)
+        return 2
+    edit_dir = (args.edit_dir.expanduser().absolute() if args.edit_dir else edit_dir_for(video))
+    destino = edit_dir / "texto_na_tela.json"
+    palavras: list[dict] | None = None
+    if args.transcript and args.transcript.exists():
+        dados = load_json(args.transcript)
+        palavras = dados.get("words") if isinstance(dados, dict) else dados
+    if destino.exists() and not args.force:
+        antigo = load_json(destino)
+        if (antigo.get("video_sig") == file_signature(video) and antigo.get("version") == VERSION
+                and abs(float(antigo.get("fps", 0)) - args.fps) < 1e-6
+                and (palavras is None or antigo.get("backend") == "vision")):
+            print(antigo.get("resumo", "já estava pronto"))
+            if args.json:
+                print(json.dumps(antigo, ensure_ascii=False, indent=2))
+            return 0
+    try:
+        doc = mapear(video, fps=args.fps, backend=args.backend, palavras=palavras)
+    except RuntimeError as exc:
+        print(f"erro: {exc}", file=sys.stderr)
+        return 2
+    try:
+        save_json(destino, doc)
+    except OSError:
+        pass
+    print(doc["resumo"])
+    if args.json:
+        print(json.dumps(doc, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/editor/helpers/timeline_view.py

@@ -0,0 +1,292 @@
+# Adapted from browser-use/video-use (MIT, (c) 2026 Browser Use). See THIRD_PARTY_NOTICES.md.
+"""Filmstrip + waveform + words for one time range of a video, as a PNG.
+
+Usage:
+    uv run python helpers/timeline_view.py <video> <start> <end> [-o PNG] [--transcript JSON] [--frames N]
+
+- Waveform: peak envelope (light) and RMS (strong) of the audio in the range.
+- Silence bands (blue): from edit/regions/<stem>.json when present, else measured here
+  (RMS under -35 dBFS for at least 0.25 s).
+- Words: from --transcript, else edit/transcripts/<stem>.json (cut.mp4 -> transcripts/cut.json).
+- On a cut with a timeline next to it (cut_timeline.json): segment boundaries (yellow lines with
+  ids) and J-cut audio overlaps (orange bands, where the incoming audio starts early).
+Default output: edit/verify/timeline_<stem>_<start>-<end>.png
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageDraw
+
+from common import file_signature, fmt_time, load_json, probe_video
+from contact_sheet import (ACCENT, BG, DIM, FG, PANEL, abspath, default_verify_dir, extract_frames, find_timeline,
+                           parse_time, ui_font)
+
+WAVE_PEAK = (96, 128, 190)
+WAVE_RMS = (150, 190, 255)
+SILENCE = (40, 90, 170, 70)
+JCUT = (255, 140, 40, 90)
+ANALYSIS_SR = 16000
+
+
+def load_audio(video: Path, start: float, end: float) -> np.ndarray:
+    proc = subprocess.run(
+        ["ffmpeg", "-v", "error", "-nostdin", "-ss", f"{start:.4f}", "-i", str(video), "-t", f"{end - start:.4f}",
+         "-vn", "-ac", "1", "-ar", str(ANALYSIS_SR), "-f", "f32le", "-"], capture_output=True)
+    if proc.returncode != 0:
+        return np.zeros(0, dtype=np.float32)
+    return np.frombuffer(proc.stdout, dtype=np.float32)
+
+
+def measured_silences(pcm: np.ndarray, start: float, noise_db: float = -35.0, min_len: float = 0.25) -> list:
+    win = int(0.02 * ANALYSIS_SR)
+    if pcm.size < win:
+        return []
+    n = pcm.size // win
+    rms = np.sqrt(np.mean(pcm[: n * win].reshape(n, win) ** 2, axis=1))
+    quiet = 20 * np.log10(np.maximum(rms, 1e-9)) < noise_db
+    out, i = [], 0
+    while i < n:
+        if quiet[i]:
+            j = i
+            while j < n and quiet[j]:
+                j += 1
+            if (j - i) * 0.02 >= min_len:
+                out.append([start + i * 0.02, start + j * 0.02])
+            i = j
+        else:
+            i += 1
+    return out
+
+
+def resolve_transcript(video: Path, explicit: Path | None) -> Path | None:
+    if explicit:
+        return explicit if explicit.exists() else None
+    cands = []
+    if video.parent.name == "edit" or (video.parent / "transcripts").is_dir():
+        cands.append(video.parent / "transcripts" / f"{video.stem}.json")
+    cands.append(video.parent / "edit" / "transcripts" / f"{video.stem}.json")
+    return next((c for c in cands if c.exists()), None)
+
+
+def resolve_regions(video: Path) -> dict | None:
+    for c in (video.parent / "edit" / "regions" / f"{video.stem}.json", video.parent / "regions" / f"{video.stem}.json"):
+        data = load_json(c)
+        if isinstance(data, dict) and isinstance(data.get("silences"), list):
+            return data
+    return None
+
+
+def matches_video(data: dict, video: Path, duration: float) -> bool:
+    """A regions/transcript JSON describes this exact file (a re-rendered cut.mp4 keeps its name)."""
+    sig = data.get("source_sig")
+    if sig:
+        try:
+            return sig == file_signature(video)
+        except OSError:
+            return False
+    if data.get("duration") is not None and duration:
+        return abs(float(data["duration"]) - duration) <= 0.05
+    return True
+
+
+def nice_step(span: float, target_ticks: int = 10) -> float:
+    for step in (0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300):
+        if span / step <= target_ticks:
+            return step
+    return 600
+
+
+def render(video: Path, start: float, end: float, out: Path, transcript: Path | None, n_frames: int) -> Path:
+    info = probe_video(video)
+    dur = info.get("duration") or end
+    end = min(end, dur)
+    span = end - start
+    W = 1800
+    pad = 40
+    x0, x1 = pad, W - pad
+    inner = x1 - x0
+
+    def tx(t: float) -> float:
+        return x0 + (t - start) / span * inner
+
+    vertical = (info.get("display_height") or 0) > (info.get("display_width") or 0)
+    if n_frames <= 0:
+        n_frames = 12 if vertical else 7
+    gap = 6
+    tile_w = int((inner - gap * (n_frames - 1)) / n_frames)
+    tile_w -= tile_w % 2
+    times = [start + (i + 0.5) * span / n_frames for i in range(n_frames)]
+    frames = extract_frames(video, times, width=tile_w) if info.get("has_video") else []
+    tile_h = frames[0].size[1] if frames else 0
+
+    head, strip_y = 64, 64
+    wave_y = strip_y + tile_h + (34 if frames else 0) + 44
+    wave_h = 260
+    words_y = wave_y + wave_h + 14
+    ruler_y = words_y + 62
+    H = ruler_y + 70
+
+    canvas = Image.new("RGB", (W, H), BG)
+    d = ImageDraw.Draw(canvas, "RGBA")
+    f_head, f_lab, f_word, f_small = ui_font(26, bold=True), ui_font(15), ui_font(17), ui_font(14)
+    d.text((pad, 18), f"{video.name}  ·  {fmt_time(start)} a {fmt_time(end)}  ({span:.2f}s)", fill=FG, font=f_head)
+
+    for i, (img, t) in enumerate(zip(frames, times)):
+        x = x0 + i * (tile_w + gap)
+        canvas.paste(img, (x, strip_y))
+        d.rectangle((x, strip_y + tile_h, x + tile_w - 1, strip_y + tile_h + 28), fill=PANEL)
+        d.text((x + 6, strip_y + tile_h + 6), fmt_time(t), fill=DIM, font=f_small)
+
+    # waveform panel
+    d.rectangle((x0, wave_y, x1, wave_y + wave_h), fill=(28, 28, 34))
+    pcm = load_audio(video, start, end) if info.get("has_audio") else np.zeros(0, dtype=np.float32)
+
+    regions = resolve_regions(video)
+    stale_notes = []
+    if regions and not matches_video(regions, video, dur):
+        regions = None
+        stale_notes.append("regions desatualizado (o vídeo mudou)")
+    if regions:
+        silences = [[float(a), float(b)] for a, b in regions["silences"] if float(b) > start and float(a) < end]
+        sil_note = "silêncio medido (regions)"
+    else:
+        silences = measured_silences(pcm, start)
+        sil_note = "silêncio medido aqui (-35 dB, 0,25 s)"
+    for a, b in silences:
+        d.rectangle((tx(max(a, start)), wave_y, tx(min(b, end)), wave_y + wave_h), fill=SILENCE)
+
+    timeline = None
+    has_overlap = False
+    tl_path = find_timeline(video)
+    if tl_path and (video.parent / tl_path.name).exists():
+        timeline = load_json(tl_path)
+    if timeline:
+        for s in timeline.get("segments") or []:
+            a0, a1 = float(s.get("audio_out_start", s["out_start"])), float(s["out_start"])
+            if a1 - a0 > 1e-6 and a1 > start and a0 < end:
+                has_overlap = True
+                d.rectangle((tx(max(a0, start)), wave_y, tx(min(a1, end)), wave_y + wave_h), fill=JCUT)
+
+    mid = wave_y + wave_h / 2
+    amp = wave_h / 2 - 10
+    if pcm.size:
+        cols = inner
+        per = max(1, pcm.size // cols)
+        usable = (pcm.size // per) * per
+        blocks = pcm[:usable].reshape(-1, per)
+        peak = np.abs(blocks).max(axis=1)
+        rms = np.sqrt((blocks ** 2).mean(axis=1))
+        scale = max(float(peak.max()), 1e-4)
+        scale = max(scale, 0.25)   # keep quiet audio looking quiet
+        for i in range(blocks.shape[0]):
+            x = x0 + i * inner / blocks.shape[0]
+            hp = peak[i] / scale * amp
+            hr = rms[i] / scale * amp
+            d.line((x, mid - hp, x, mid + hp), fill=WAVE_PEAK)
+            d.line((x, mid - hr, x, mid + hr), fill=WAVE_RMS)
+    d.line((x0, mid, x1, mid), fill=(70, 70, 80))
+
+    if timeline:
+        for s in timeline.get("segments") or []:
+            t = float(s["out_start"])
+            if start <= t <= end:
+                d.line((tx(t), strip_y - 6, tx(t), words_y + 44), fill=ACCENT, width=2)
+                d.text((tx(t) + 5, wave_y + 6), f"{s['id']} {s.get('beat') or ''}".strip(), fill=ACCENT, font=f_lab)
+
+    # words: two alternating rows, skip labels that would collide
+    tr_path = resolve_transcript(video, transcript)
+    words = []
+    if tr_path:
+        data = load_json(tr_path) or {}
+        # An explicit --transcript of another file is trusted; one made from this path must match the file.
+        own = transcript is None or str(data.get("source") or "") == str(video)
+        if own and not matches_video(data, video, dur):
+            stale_notes.append("transcrição desatualizada (o vídeo mudou): transcreva de novo")
+            data = {}
+        words = [w for w in data.get("words", []) if w.get("end", 0) > start and w.get("start", 0) < end]
+    last_x = [-1e9, -1e9]
+    for w in words:
+        ws, we = max(float(w["start"]), start), min(float(w["end"]), end)
+        text = str(w.get("text", "")).strip()
+        if not text:
+            continue
+        xa, xb = tx(ws), tx(we)
+        d.line((xa, wave_y + wave_h, xa, wave_y + wave_h + 8), fill=DIM)
+        d.rectangle((xa, wave_y + wave_h - 4, max(xa + 1, xb), wave_y + wave_h - 1), fill=(200, 200, 210, 120))
+        tw = d.textlength(text, font=f_word)
+        row = 0 if xa > last_x[0] + 6 else 1 if xa > last_x[1] + 6 else None
+        if row is None:
+            continue
+        d.text((xa, words_y + row * 24), text, fill=FG, font=f_word)
+        last_x[row] = xa + tw
+
+    step = nice_step(span)
+    t = (int(start / step) + (1 if start % step > 1e-6 else 0)) * step
+    while t <= end + 1e-6:
+        x = tx(t)
+        d.line((x, ruler_y, x, ruler_y + 8), fill=DIM)
+        label = fmt_time(t)
+        lx = min(max(x - d.textlength(label, font=f_small) / 2, 4), W - 4 - d.textlength(label, font=f_small))
+        d.text((lx, ruler_y + 12), label, fill=DIM, font=f_small)
+        t += step
+    legend = f"azul = {sil_note}"
+    if timeline:
+        legend += "  ·  amarelo = início de trecho"
+    if has_overlap:
+        legend += "  ·  laranja = áudio do próximo trecho entrando antes (J-cut)"
+    if not words and not stale_notes:
+        legend += "  ·  sem transcrição"
+    for note in stale_notes:
+        legend += f"  ·  {note}"
+    d.text((pad, ruler_y + 40), legend, fill=DIM, font=f_small)
+    for note in stale_notes:
+        print(f"aviso: {note}", file=sys.stderr)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    canvas.save(out, "PNG", optimize=True)
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Tira de quadros + forma de onda + palavras de um trecho do vídeo (PNG).")
+    ap.add_argument("video", type=Path)
+    ap.add_argument("start", type=parse_time, help="início (segundos ou mm:ss.cc)")
+    ap.add_argument("end", type=parse_time, help="fim (segundos ou mm:ss.cc)")
+    ap.add_argument("-o", "--output", type=Path, help="PNG de saída (padrão: edit/verify/timeline_<nome>_<ini>-<fim>.png)")
+    ap.add_argument("--transcript", type=Path, help="transcrição JSON (padrão: edit/transcripts/<nome>.json)")
+    ap.add_argument("--frames", type=int, default=0, help="quantos quadros na tira (padrão automático)")
+    args = ap.parse_args()
+
+    video = abspath(args.video)
+    if not video.exists():
+        print(f"erro: vídeo não encontrado: {video}", file=sys.stderr)
+        return 2
+    if args.end <= args.start:
+        print("erro: o fim precisa ser maior que o início", file=sys.stderr)
+        return 2
+    try:
+        info = probe_video(video)
+    except Exception as exc:  # noqa: BLE001
+        print(f"erro: não consegui ler {video.name}: {exc}", file=sys.stderr)
+        return 2
+    if args.start >= (info.get("duration") or 0):
+        print(f"erro: início {args.start:.2f}s passa do fim do vídeo ({info.get('duration', 0):.2f}s)", file=sys.stderr)
+        return 2
+    out = args.output or default_verify_dir(video) / f"timeline_{video.stem}_{args.start:.2f}-{args.end:.2f}.png"
+    try:
+        path = render(video, args.start, args.end, abspath(out), args.transcript, args.frames)
+    except RuntimeError as exc:
+        print(f"erro: {exc}", file=sys.stderr)
+        return 1
+    print(f"imagem salva: {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())