primocode 10.16.0 → 10.17.1

package/editor/helpers/captions.py

@@ -0,0 +1,601 @@
+"""Caption cues on the cut timeline (Contract 7).
+
+Where the words come from (`--from`, default `auto`):
+  - sources: the word-level transcripts of the source videos (`transcripts/<stem>.json`, made with
+    the brand-name prompt and already read in Phase 1), mapped onto cut.mp4 through
+    `cut_timeline.json` (a word belongs to a segment when its middle falls inside the segment's
+    audio; it is shifted by audio_out_start - audio_src_start and kept inside that audio). No new
+    transcription is needed after a recut, and a word the cut chopped at a range edge is reported.
+  - cut: a transcript of cut.mp4 itself (`--transcript`, default `transcripts/cut.json`).
+  - auto: sources for every segment whose source transcript exists, cut.json for the rest.
+
+Then `--replace "errado=certo"` (repeatable; several words allowed on each side) fixes words, and
+the words are grouped into cues by measured width (with the chosen style's font), max words,
+punctuation and pauses. A cue never spans a cut boundary. Words keep their original case; the cue
+`text` is shown the way the style displays it (casing and punctuation), for the preview.
+
+captions.json also records `words_from`, `timeline_key` (a fingerprint of the cut positions: the
+composer refuses captions made for another cut), `duration`, `replacements`, `warnings` and
+`differences` ([{"time", "sources", "cut"}]: places where the source transcripts and
+transcripts/cut.json heard different words, printed as `confira:` lines so the agent picks the right
+one with --replace). A cut.json whose duration does not match cut_timeline.json is from another cut
+and is not used.
+
+Usage:
+    uv run python helpers/captions.py --edit-dir DIR [-o DIR/captions.json] [--style ID]
+        [--from auto|sources|cut] [--transcript DIR/transcripts/cut.json]
+        [--replace "errado=certo" ...] [--max-words 3] [--pause 0.35]
+    (the older form `--transcript edit/transcripts/cut.json -o edit/captions.json` still works and
+    finds the edit dir from the transcript path; with --from auto it still prefers the sources)
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import hashlib
+import re
+import sys
+import unicodedata
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import OUTPUT_FORMATS, fmt_time, load_json, load_style_catalog, now_iso, save_json  # noqa: E402
+import text_render as tr  # noqa: E402
+
+PAUSE_CLOSE = 0.35
+SENTENCE_END = (".", "!", "?", "…")
+CLAUSE_END = (",", ";", ":")
+MIN_WORD = 0.04
+MIN_ACTIVE = 0.07          # a word pushed to a cut still gets about 2 frames of highlight
+SHORT_CUE = 0.25           # one-word cues shorter than this join a neighbour
+WIDTH_TOLERANCE = 1.08      # up to 8% wider than the safe width: the renderer shrinks slightly
+WEAK_PAIR_TOLERANCE = 1.4   # "o acabamento", "as influenciadoras" stay together
+
+
+def _normalize_words(raw: list[dict]) -> list[dict]:
+    words = []
+    for w in raw or []:
+        text = str(w.get("text", "")).strip()
+        if not text:
+            continue
+        try:
+            start, end = float(w["start"]), float(w["end"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        words.append({"text": text, "start": start, "end": end})
+    words.sort(key=lambda w: w["start"])
+    for i, w in enumerate(words):
+        if i and w["start"] < words[i - 1]["end"]:
+            # overlapping whisper times: split the difference, keep order
+            mid = (w["start"] + words[i - 1]["end"]) / 2.0
+            words[i - 1]["end"] = max(words[i - 1]["start"] + MIN_WORD, mid)
+            w["start"] = max(w["start"], words[i - 1]["end"])
+        if w["end"] < w["start"] + MIN_WORD:
+            w["end"] = w["start"] + MIN_WORD
+    return words
+
+
+def timeline_key(timeline: dict | None) -> str | None:
+    """Fingerprint of where every segment sits in cut.mp4 and in its source. It changes when the
+    cut changes, and not when only the grade, gain or labels of the EDL change."""
+    if not timeline or not timeline.get("segments"):
+        return None
+    rows = []
+    for s in timeline.get("segments") or []:
+        try:
+            rows.append((str(s.get("source")), round(float(s.get("audio_src_start", s["src_start"])), 3),
+                         round(float(s["src_end"]), 3), round(float(s["out_start"]), 3), round(float(s["out_end"]), 3),
+                         round(float(s.get("audio_out_start", s["out_start"])), 3)))
+        except (KeyError, TypeError, ValueError):
+            continue
+    rows.sort(key=lambda r: r[3])
+    return hashlib.sha1(repr(rows).encode("utf-8")).hexdigest()[:16]
+
+
+def _timeline_segments(timeline: dict | None) -> list[dict]:
+    segs = []
+    for s in (timeline or {}).get("segments", []) or []:
+        try:
+            a, b = float(s["out_start"]), float(s["out_end"])
+            aa = min(a, float(s.get("audio_out_start", a)))
+            ab = float(s.get("audio_out_end", b))
+            src_a = float(s.get("audio_src_start", float(s["src_start"]) - (a - aa)))
+        except (KeyError, TypeError, ValueError):
+            continue
+        segs.append({"id": str(s.get("id") or ""), "source": str(s.get("source") or ""), "out_start": a, "out_end": b,
+                     "audio_out_start": aa, "audio_out_end": max(ab, b), "audio_src_start": src_a})
+    segs.sort(key=lambda s: s["out_start"])
+    return segs
+
+
+CHOP_KEEP = 0.6   # a word with less than this share of its time inside the range was chopped by the cut
+CUT_DURATION_TOLERANCE = 0.1   # s: a cut transcript whose duration differs more than this is from another cut
+MAX_DIFFERENCES = 12
+
+
+def load_cut_words(path: Path | None, timeline: dict | None) -> tuple[list[dict] | None, str | None]:
+    """Words of transcripts/cut.json, or (None, reason) when it is missing or was made for another cut
+    (its duration does not match cut_timeline.json)."""
+    data = load_json(path) if path and path.exists() else None
+    if not isinstance(data, dict) or not data.get("words"):
+        return None, None
+    dur, tl_dur = data.get("duration"), (timeline or {}).get("duration")
+    try:
+        if dur is not None and tl_dur is not None and abs(float(dur) - float(tl_dur)) > CUT_DURATION_TOLERANCE:
+            return None, (f"{path.name} é de outro corte ({float(dur):.2f}s e o corte tem {float(tl_dur):.2f}s): "
+                          f"não usei essa transcrição. Transcreva o cut.mp4 de novo se precisar dela")
+    except (TypeError, ValueError):
+        pass
+    return _normalize_words(data["words"]), None
+
+
+def transcript_differences(words: list[dict], cut_words: list[dict]) -> list[dict]:
+    """Places where the source transcripts and the cut transcript heard different words (swaps of up
+    to 3 words at about the same time). Either side may be the right one: the agent checks."""
+    a = [_norm_token(w["text"]) for w in words]
+    b = [_norm_token(w["text"]) for w in cut_words]
+    out = []
+    for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(a=a, b=b, autojunk=False).get_opcodes():
+        if tag != "replace" or i2 - i1 > 3 or j2 - j1 > 3 or any(w.get("replaced") for w in words[i1:i2]):
+            continue   # words fixed with --replace are already decided
+        if abs(words[i1]["start"] - cut_words[j1]["start"]) > 1.0:
+            continue
+        src = " ".join(w["text"].strip(".,;:!?…") for w in words[i1:i2])
+        cut = " ".join(w["text"].strip(".,;:!?…") for w in cut_words[j1:j2])
+        if _norm_token(src.replace(" ", "")) == _norm_token(cut.replace(" ", "")):
+            continue
+        out.append({"time": round(words[i1]["start"], 2), "sources": src, "cut": cut})
+    return out
+
+
+def words_from_sources(edit_dir: Path, timeline: dict, cut_transcript: Path | None, mode: str
+                       ) -> tuple[list[dict], str, list[str]]:
+    """Words on the cut timeline, each with its segment index ("seg").
+
+    -> (words, words_from, warnings). mode "sources" requires every source transcript; "auto" uses
+    the cut transcript for segments without one.
+    """
+    segs = _timeline_segments(timeline)
+    cache: dict[str, list[dict] | None] = {}
+    cut_words: list[dict] | None = None
+    cut_problem: str | None = None
+    words: list[dict] = []
+    warnings: list[str] = []
+    used = set()
+    for i, seg in enumerate(segs):
+        stem = seg["source"]
+        if stem not in cache:
+            data = load_json(edit_dir / "transcripts" / f"{stem}.json") if stem and stem != "cut" else None
+            cache[stem] = _normalize_words(data.get("words", [])) if isinstance(data, dict) and data.get("words") else None
+        src_words = cache[stem]
+        aa, ab = seg["audio_out_start"], seg["audio_out_end"]
+        if src_words is None:
+            if mode == "sources":
+                raise ValueError(f"falta a transcrição da fonte {stem!r} (transcripts/{stem}.json) do trecho {seg['id']}. "
+                                 f"Rode transcribe.py nessa fonte ou use --from auto")
+            if cut_words is None:
+                cut_words, cut_problem = load_cut_words(cut_transcript, timeline)
+                cut_words = cut_words or []
+                if cut_problem:
+                    warnings.append(cut_problem)
+            if not cut_words:
+                warnings.append(f"trecho {seg['id']} ({fmt_time(seg['out_start'])}) ficou sem legenda: não há transcrição "
+                                f"da fonte {stem!r} nem {'uma do corte atual' if cut_problem else 'do corte'}")
+                continue
+            used.add("cut")
+            for w in cut_words:
+                if aa <= (w["start"] + w["end"]) / 2.0 < ab:
+                    words.append(dict(w, seg=i))
+            continue
+        used.add("sources")
+        shift = aa - seg["audio_src_start"]
+        s0, s1 = seg["audio_src_start"], seg["audio_src_start"] + (ab - aa)
+        for w in src_words:
+            ws, we = w["start"], w["end"]
+            if we <= s0 or ws >= s1:
+                continue
+            # Whisper stretches a word back over the pause before it (the first word of a file starts
+            # at 0.0, the word after a pause starts where the previous one ended). A word crossing an
+            # edge is judged by a plausible length for its letters, ending where Whisper ends it.
+            plausible = 0.12 + 0.07 * max(1, len(re.sub(r"\W", "", w["text"])))
+            es, ee = ws, we
+            if ws < s0 or we > s1:
+                es = max(ws, we - plausible)
+            inside = max(0.0, min(ee, s1) - max(es, s0)) / max(1e-3, ee - es)
+            if inside < 0.5:
+                if inside > 1.0 - CHOP_KEEP:
+                    edge = "no começo" if es < s0 else "no fim"
+                    warnings.append(f"a palavra \"{w['text']}\" ficou quase toda fora do trecho {seg['id']} ({edge}, "
+                                    f"{fmt_time(aa if es < s0 else ab)}): confira a borda no EDL")
+                continue
+            if inside < CHOP_KEEP:
+                edge = "no começo" if es < s0 else "no fim"
+                warnings.append(f"a palavra \"{w['text']}\" foi cortada {edge} do trecho {seg['id']} "
+                                f"({fmt_time(aa if es < s0 else ab)}): confira a borda no EDL")
+            words.append({"text": w["text"], "start": min(max(aa, es + shift), ab - MIN_WORD),
+                          "end": max(min(ab, ee + shift), aa + MIN_WORD), "seg": i})
+    words.sort(key=lambda w: (w["start"], w["seg"]))
+    return words, "+".join(sorted(used, reverse=True)) or "nenhuma", warnings
+
+
+def _norm_token(text: str) -> str:
+    t = unicodedata.normalize("NFC", str(text)).lower()
+    return t.strip(".,;:!?…\"'“”‘’()[]{}«»-–—")
+
+
+def parse_replacements(values: list[str] | None) -> list[tuple[list[str], list[str], str]]:
+    out = []
+    for raw in values or []:
+        if "=" not in raw:
+            raise ValueError(f"--replace precisa ser \"errado=certo\" (recebi {raw!r})")
+        left, right = raw.split("=", 1)
+        src = [t for t in (_norm_token(x) for x in left.split()) if t]
+        if not src:
+            raise ValueError(f"--replace sem a palavra errada antes do '=' ({raw!r})")
+        out.append((src, right.split(), raw))
+    return out
+
+
+def apply_replacements(words: list[dict], reps: list[tuple[list[str], list[str], str]]) -> tuple[list[dict], list[dict]]:
+    """Swap word sequences (case and edge punctuation ignored when matching). The new words share
+    the time of the old ones, split by length; trailing punctuation of the last old word is kept."""
+    report = []
+    for src, dst, raw in reps:
+        count, i, out = 0, 0, []
+        n = len(src)
+        while i < len(words):
+            chunk = words[i:i + n]
+            if (len(chunk) == n and all(_norm_token(w["text"]) == t for w, t in zip(chunk, src))
+                    and len({w.get("seg") for w in chunk}) == 1):
+                count += 1
+                if dst:
+                    t0, t1 = chunk[0]["start"], chunk[-1]["end"]
+                    tail = re.search(r"[.,;:!?…]+$", chunk[-1]["text"])
+                    new = list(dst)
+                    if tail and not re.search(r"[.,;:!?…]$", new[-1]):
+                        new[-1] += tail.group(0)
+                    total = sum(len(x) for x in new) or 1
+                    t = t0
+                    for k, token in enumerate(new):
+                        t_end = t1 if k == len(new) - 1 else t + (t1 - t0) * len(token) / total
+                        out.append(dict(chunk[0], text=token, start=t, end=t_end, replaced=True))
+                        t = t_end
+                i += n
+                continue
+            out.append(words[i])
+            i += 1
+        words = out
+        report.append({"from": raw.split("=", 1)[0], "to": raw.split("=", 1)[1], "count": count})
+    return words, report
+
+
+def _segments_from_timeline(timeline: dict | None) -> list[tuple[float, float, float]]:
+    """(out_start, out_end, audio_out_start) per segment. With a J-cut the audio of a segment
+    starts a few frames before its picture, so words spoken in that lead belong to it."""
+    if not timeline:
+        return []
+    segs = []
+    for s in timeline.get("segments", []) or []:
+        try:
+            a, b = float(s["out_start"]), float(s["out_end"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        try:
+            aa = min(a, float(s.get("audio_out_start", a)))
+        except (TypeError, ValueError):
+            aa = a
+        segs.append((a, b, aa))
+    segs.sort()
+    return segs
+
+
+def _segment_index(t: float, segs: list[tuple[float, float, float]]) -> int:
+    """Index of the segment whose audio contains time t. Inside a J-cut lead (two segments'
+    audio overlap) the incoming segment wins. Nearest segment when t falls in a gap."""
+    if not segs:
+        return 0
+    for i in range(len(segs) - 1, -1, -1):
+        a, b, aa = segs[i]
+        if aa <= t < b:
+            return i
+    best, best_d = 0, None
+    for i, (a, b, _aa) in enumerate(segs):
+        d = min(abs(t - a), abs(t - b))
+        if best_d is None or d < best_d:
+            best, best_d = i, d
+    return best
+
+
+def _ends_with(text: str, marks: tuple[str, ...]) -> bool:
+    t = text.rstrip("\"'”’)]»")
+    return t.endswith(marks)
+
+
+def build_cues(words: list[dict], style_id: str, max_words: int, canvas: tuple[int, int],
+               segs: list[tuple[float, float]], pause: float = PAUSE_CLOSE) -> list[dict]:
+    info = tr.caption_style_info(style_id)
+    lines = max(1, int(info["lines"]))
+    limit = tr.caption_width_limit(style_id, canvas)
+    # multi-line styles fill up to `lines` lines; keep a margin so the balanced split fits
+    width_budget = limit if lines == 1 else limit * lines * 0.88
+
+    def fits(group: list[dict]) -> bool:
+        if len(group) <= 1 or info["one_word"]:
+            return True
+        width = tr.measure_caption_width([w["text"] for w in group], style_id, canvas)
+        if width <= width_budget * WIDTH_TOLERANCE:
+            return True
+        # a lone function word reads badly: keep it with the next word and let the renderer shrink
+        return len(group) == 2 and tr.is_weak_word(group[0]["text"]) and width <= width_budget * WEAK_PAIR_TOLERANCE
+
+    cues: list[list[dict]] = []
+    cur: list[dict] = []
+    for w in words:
+        if not isinstance(w.get("seg"), int) or not 0 <= w["seg"] < max(1, len(segs)):
+            w["seg"] = _segment_index((w["start"] + w["end"]) / 2.0, segs)
+        if cur:
+            prev = cur[-1]
+            # one-line styles breathe on every comma; subtitle-like styles only on longer clauses
+            clause = _ends_with(prev["text"], CLAUSE_END) and (lines == 1 or len(cur) >= 4)
+            hard = (w["start"] - prev["end"] >= pause or w["seg"] != prev["seg"]
+                    or _ends_with(prev["text"], SENTENCE_END) or clause)
+            if hard:
+                cues.append(cur)
+                cur = []
+            elif len(cur) >= max_words or not fits(cur + [w]):
+                # soft break: do not leave a function word hanging at the end of a cue
+                carry = []
+                if (len(cur) >= 2 and max_words >= 2 and tr.is_weak_word(cur[-1]["text"])
+                        and not tr.is_weak_word(cur[-2]["text"]) and fits([cur[-1], w])):
+                    carry = [cur.pop()]
+                cues.append(cur)
+                cur = carry
+        cur.append(w)
+    if cur:
+        cues.append(cur)
+
+    # an orphan word closing a sentence ("... na próxima | página.") pulls words from the cue before
+    for i in range(1, len(cues)):
+        prev, group = cues[i - 1], cues[i]
+        if len(group) != 1 or len(prev) < 3 or max_words < 2:
+            continue
+        if (group[0]["seg"] != prev[-1]["seg"] or group[0]["start"] - prev[-1]["end"] >= pause
+                or _ends_with(prev[-1]["text"], SENTENCE_END + CLAUSE_END)):
+            continue
+        moved = 0
+        while len(prev) > 2 and moved < 3 and len(group) < max_words:
+            trial = [prev[-1]] + group
+            if not fits(trial):
+                break
+            group.insert(0, prev.pop())
+            moved += 1
+            if not tr.is_weak_word(prev[-1]["text"]):
+                break
+
+    # a one-word cue shorter than SHORT_CUE ("ó,") flickers: join it to a neighbour in the same
+    # segment when that stays within max words and width
+    i = 0
+    while i < len(cues):
+        group = cues[i]
+        dur = group[-1]["end"] - group[0]["start"]
+        if len(group) == 1 and dur < SHORT_CUE and len(cues) > 1:
+            nxt = cues[i + 1] if i + 1 < len(cues) else None
+            prv = cues[i - 1] if i > 0 else None
+            if (nxt and nxt[0]["seg"] == group[0]["seg"] and nxt[0]["start"] - group[-1]["end"] < pause
+                    and len(nxt) < max(2, max_words) and fits(group + nxt)
+                    and not _ends_with(group[-1]["text"], SENTENCE_END)):
+                cues[i + 1] = group + nxt
+                del cues[i]
+                continue
+            if (prv and prv[-1]["seg"] == group[0]["seg"] and group[0]["start"] - prv[-1]["end"] < pause
+                    and len(prv) < max(2, max_words) and fits(prv + group)):
+                prv.extend(group)
+                del cues[i]
+                continue
+        i += 1
+
+    out = []
+    for group in cues:
+        start, end = group[0]["start"], group[-1]["end"]
+        if segs:
+            a, b, _aa = segs[group[0]["seg"]]
+            start, end = max(start, a), min(end, b)
+            if end <= start:
+                end = start + MIN_WORD
+        # words spoken in a J-cut lead start before the picture cut: keep them inside the cue and
+        # give each at least MIN_ACTIVE so the highlight still lands on it
+        timed = []
+        floor = start
+        for k, w in enumerate(group):
+            ws, we = w["start"], w["end"]
+            if ws < floor:
+                ws = floor
+                we = max(we, ws + MIN_ACTIVE)
+            elif we - ws < MIN_ACTIVE and k + 1 < len(group):
+                # a near zero-length word ("ó,") borrows the gap before the next word
+                we = max(we, min(ws + MIN_ACTIVE, group[k + 1]["start"]))
+            ws = min(ws, end)
+            we = min(max(we, ws + MIN_WORD), end)
+            timed.append({"text": w["text"], "start": round(ws, 3), "end": round(we, 3)})
+            floor = we
+        disp = tr.display_words([w["text"] for w in group], style_id)
+        out.append({
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "text": " ".join(disp),
+            "words": timed,
+        })
+    return out
+
+
+def drop_ja_legendado(cues: list[dict], tela: dict | None, cobertura: float = 0.45) -> tuple[list[dict], list[dict]]:
+    """Tira as falas que já aparecem escritas no vídeo (legenda gravada, motion que soletra a frase)."""
+    if not tela or not tela.get("legenda_existente"):
+        return cues, []
+    import texto_na_tela as tnt  # noqa: PLC0415
+
+    faixas = tela["legenda_existente"]
+    fica, sai = [], []
+    for cue in cues:
+        (sai if tnt.cobre(faixas, float(cue["start"]), float(cue["end"]), cobertura) else fica).append(cue)
+    return fica, sai
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Gera as legendas (captions.json) no tempo do corte, com as palavras das "
+                                             "transcrições das fontes (ou da transcrição do corte).")
+    ap.add_argument("--edit-dir", help="pasta edit da sessão (padrão: a pasta acima de transcripts/ do --transcript)")
+    ap.add_argument("--transcript", help="transcrição do cut.mp4, usada com --from cut ou nos trechos sem fonte "
+                                         "(padrão: edit/transcripts/cut.json)")
+    ap.add_argument("--from", dest="words_from", choices=("auto", "sources", "cut"), default="auto",
+                    help="de onde vêm as palavras: auto (fontes e, se faltar, o corte), sources ou cut (padrão auto)")
+    ap.add_argument("--replace", action="append", metavar="ERRADO=CERTO",
+                    help="troca palavra errada, ex: --replace 'Cacto=Cakto' (pode repetir; aceita várias palavras)")
+    ap.add_argument("-o", "--output", help="arquivo de saída (padrão: edit/captions.json)")
+    ap.add_argument("--style", help="estilo de legenda (padrão: o do catálogo)")
+    ap.add_argument("--max-words", type=int, help="máximo de palavras por legenda (padrão: o do estilo, 3 nos animados)")
+    ap.add_argument("--tela", help="mapa do que já está escrito na tela (padrão: edit/texto_na_tela.json, "
+                                   "gerado por texto_na_tela.py); use --tela nao para ignorar")
+    ap.add_argument("--pause", type=float, default=PAUSE_CLOSE, help="pausa (s) que fecha uma legenda (padrão 0.35)")
+    args = ap.parse_args(argv)
+
+    if not args.edit_dir and not args.transcript:
+        print("erro: passe --edit-dir (ou --transcript com a transcrição do corte)", file=sys.stderr)
+        return 2
+    tpath = Path(args.transcript).expanduser().resolve() if args.transcript else None
+    if args.edit_dir:
+        edit_dir = Path(args.edit_dir).expanduser().resolve()
+    else:
+        edit_dir = tpath.parent.parent if tpath.parent.name == "transcripts" else tpath.parent
+    if not edit_dir.is_dir():
+        print(f"erro: pasta de edição não encontrada: {edit_dir}", file=sys.stderr)
+        return 2
+    if tpath is None:
+        tpath = edit_dir / "transcripts" / "cut.json"
+    try:
+        reps = parse_replacements(args.replace)
+    except ValueError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 2
+
+    timeline = load_json(edit_dir / "cut_timeline.json")
+    segs = _segments_from_timeline(timeline)
+    warnings: list[str] = []
+    if args.words_from != "cut" and timeline and segs:
+        try:
+            words, words_from, warnings = words_from_sources(edit_dir, timeline, tpath, args.words_from)
+        except ValueError as e:
+            print(f"erro: {e}", file=sys.stderr)
+            return 2
+        for w in words:
+            if w["end"] < w["start"] + MIN_WORD:
+                w["end"] = w["start"] + MIN_WORD
+    elif args.words_from == "sources":
+        print(f"erro: --from sources precisa do cut_timeline.json em {edit_dir}. Renderize o corte primeiro.", file=sys.stderr)
+        return 2
+    else:
+        if not tpath.exists():
+            print(f"erro: transcrição não encontrada: {tpath}", file=sys.stderr)
+            return 2
+        words = _normalize_words((load_json(tpath) or {}).get("words", []))
+        words_from = "cut"
+        _, problem = load_cut_words(tpath, timeline)
+        if problem:
+            warnings.append(problem.replace("não usei essa transcrição", "as legendas podem ficar fora do tempo"))
+    if not words:
+        print(f"erro: não achei palavras com tempo para legendar ({'fontes do corte' if words_from != 'cut' else tpath})",
+              file=sys.stderr)
+        return 2
+    words, rep_report = apply_replacements(words, reps)
+    for r in rep_report:
+        if not r["count"]:
+            warnings.append(f"--replace '{r['from']}={r['to']}': não achei \"{r['from']}\" na fala")
+    differences: list[dict] = []
+    if "sources" in words_from:
+        cut_words, _ = load_cut_words(tpath, timeline)
+        if cut_words:
+            differences = transcript_differences(words, cut_words)
+
+    catalog = load_style_catalog()
+    style_id = args.style or (catalog.get("defaults") or {}).get("caption_style") or tr.caption_style_ids()[0]
+    try:
+        info = tr.caption_style_info(style_id)
+    except ValueError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 2
+    max_words = args.max_words if args.max_words else int(info["max_words"])
+    if info["one_word"] and not args.max_words:
+        max_words = 3   # the style shows one word at a time; cues still group phrases
+    if max_words < 1:
+        print("erro: --max-words precisa ser 1 ou mais", file=sys.stderr)
+        return 2
+
+    canvas = OUTPUT_FORMATS["vertical"]
+    if timeline and timeline.get("width") and timeline.get("height"):
+        canvas = (int(timeline["width"]), int(timeline["height"]))
+
+    cues = build_cues(words, style_id, max_words, canvas, segs, pause=args.pause)
+    tela = None
+    if (args.tela or "").lower() not in ("nao", "não", "no", "off"):
+        tela_path = Path(args.tela).expanduser().resolve() if args.tela else edit_dir / "texto_na_tela.json"
+        tela = load_json(tela_path) if tela_path.exists() else None
+        if tela and tela.get("video_sig") and timeline and timeline.get("video_sig") \
+                and tela["video_sig"] != timeline["video_sig"]:
+            warnings.append("texto_na_tela.json é de outro vídeo; rode texto_na_tela.py de novo")
+            tela = None
+    cues, ja_escritas = drop_ja_legendado(cues, tela)
+    boundaries = [round(seg[0], 3) for seg in segs[1:]]
+    out = {
+        "source": str((timeline or {}).get("video") or "cut.mp4"),
+        "style": style_id,
+        "max_words": max_words,
+        "canvas": list(canvas),
+        "words_from": words_from,
+        "timeline_key": timeline_key(timeline),
+        "duration": (timeline or {}).get("duration"),
+        "cut_boundaries": boundaries,
+        "replacements": rep_report,
+        "differences": differences,
+        "warnings": warnings,
+        "ja_escritas": [{"start": c["start"], "end": c["end"],
+                         "text": " ".join(w["text"] for w in c["words"])} for c in ja_escritas],
+        "created_at": now_iso(),
+        "cues": cues,
+    }
+    opath = Path(args.output).expanduser().resolve() if args.output else edit_dir / "captions.json"
+    save_json(opath, out)
+
+    state_path = edit_dir / "state.json"
+    if state_path.exists() and opath.parent == edit_dir:
+        state = load_json(state_path, default={}) or {}
+        state["captions"] = opath.name
+        state["updated_at"] = now_iso()
+        save_json(state_path, state)
+
+    n_words = sum(len(c["words"]) for c in cues)
+    avg = n_words / len(cues) if cues else 0
+    extra = f", respeitando {len(boundaries)} cortes" if segs else ""
+    origin = {"sources": "transcrições das fontes", "cut": "transcrição do corte",
+              "sources+cut": "transcrições das fontes e do corte"}.get(words_from, words_from)
+    for r in rep_report:
+        if r["count"]:
+            print(f"troca: \"{r['from']}\" -> \"{r['to']}\" ({r['count']}x)")
+    for msg in warnings:
+        print(f"aviso: {msg}")
+    for d in differences[:MAX_DIFFERENCES]:
+        print(f"confira: {fmt_time(d['time'])} fontes \"{d['sources']}\", transcrição do corte \"{d['cut']}\" "
+              f"(se o corte estiver certo: --replace '{d['sources']}={d['cut']}')")
+    if len(differences) > MAX_DIFFERENCES:
+        print(f"confira: e mais {len(differences) - MAX_DIFFERENCES} diferenças (differences no captions.json)")
+    if ja_escritas:
+        segundos = sum(c["end"] - c["start"] for c in ja_escritas)
+        print(f"pulei {len(ja_escritas)} legenda(s) ({segundos:.0f}s) onde o vídeo já mostra a frase escrita "
+              f"(texto_na_tela.json)")
+    print(f"ok: {len(cues)} legendas, {n_words} palavras (média {avg:.1f} por legenda), estilo {style_id}{extra}, "
+          f"palavras: {origin} -> {opath}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())