primocode 10.16.0 → 10.17.0

package/editor/helpers/compose_final.py

@@ -0,0 +1,3555 @@
+"""Phase 2 composer: edit_data.json -> final.mp4 (Contract 8).
+
+Pipeline (all layers frame-accurate on the output frame grid):
+  1. Camera on the base (cut.mp4): per timeline segment zoom level (hard change on the cut
+     frame) anchored at focus_y, optional eased push-in. Done with ffmpeg `perspective`
+     (sub-pixel sampling, so a slow push-in has no integer-crop jitter).
+  2. Inserts: every window is pre-rendered once to renders/inserts/ (images: eased Ken Burns in
+     PIL with sub-pixel affine sampling; videos: loop from frame 0). Split windows re-frame the
+     speaker in the remaining band; `full` covers; `pip` is a rounded white card with a shadow.
+  3. Overlays: inserts -> mid track (pip card + hook) -> captions (text_render track, seam
+     aware) -> top track (disclaimer, CTA, flashes). Text tracks are PNG states played by the
+     concat demuxer (`option framerate`), each overlay limited with enable windows on `n`.
+  4. Audio: base + SFX placed in samples + music (loudness matched, sidechain ducked, faded)
+     -> loudnorm two-pass -> length pinned to the video.
+  5. H.264 High CRF 18 (preview: 540 wide, CRF 26), yuv420p, bt709/tv, AAC 192k 48k, faststart.
+     Writes edit/verify/final_report.json and updates state.json.
+
+Usage:
+    uv run python helpers/compose_final.py edit/edit_data.json [-o final.mp4] [--preview] [--keep-temp]
+
+Defaults and optional keys beyond SPEC Contract 8 (all optional):
+  - a missing section is off (no camera move, no hook, ...); `loudness` defaults to -14 / -1.
+  - inserts[].sfx: effect name or a sound file; null = none. Names: whoosh, pop, click, tick, rise, cash, coin,
+    notification, success, error, count, keyboard, snap, mouse_click, bass_drop, metal_hit, synth_hit, flash,
+    charge, metal_riser, wind, rewind, gears, data, or the Portuguese label / alias of one of them from
+    assets/sfx/sfx.json ("grave", "notificacao", "estalo de dedo"...; accents, case and spaces do not matter).
+    inserts[].corner (pip only): "top_right" (default) or "top_left".
+  - hook.sfx (default "pop"), transitions[].sfx (default "click"), cta.sfx (default none).
+  - Built-in effects come from assets/sfx/sfx.json (make_sfx.builtin_sfx): each has an anchor (`anchor_s`,
+    the moment it hits full strength) that lands on the event frame, so the sound starts anchor_s earlier
+    (the CTA "rise" peaks when the CTA appears). A start before 0 is clamped to 0, with a warning when the
+    anchor then misses its frame. A sound file keeps anchor 0: it starts on the event frame (2 frames
+    early on an insert), exactly as before.
+  - sfx.events: [{"at": seconds, "name": effect or file, "volume": 0.0-2.0, "anchor_s": seconds}] sounds at
+    a chosen time, not tied to a hook, insert, flash or CTA (e.g. "cash" when the speech talks about a sale).
+    The anchor lands on the frame of `at`; `volume` multiplies sfx.volume; `anchor_s` (optional, >= 0)
+    replaces the anchor (a file's default is 0). A negative or non-numeric `at` or `anchor_s` is an error;
+    an `at` past the end is dropped with a warning, and a sound that loses more than 10% of its energy to
+    the video end plays cut with a warning. Only plays when sfx is on.
+  - camera.focus_y, hook.center_y, captions.center_y, cta.center_y, disclaimer.center_y: a number
+    (focus: fraction of the height; centers: pixels on the output canvas) or omitted / "auto".
+    Auto uses the speaker's face found by face_layout.py (edit/face_layout.json, made on the fly):
+    the zoom anchors on the eyes of each segment, splits frame each segment's face, and every text
+    goes to the free spot closest to its usual place (hook 430, captions 1400, CTA 1110 / 1180,
+    disclaimer 1548 on 1080x1920; horizontal and square canvases have their own table), never on
+    the face and never on a text shown at the same time. Manual numbers are kept as they are
+    (captions.center_y moves the captions for the whole video; split seams still win).
+  - Text layers on screen together never overlap: priority CTA > hook > captions > disclaimer. The
+    lower one moves (when auto) or hides while they would touch. Every move and hide is listed in
+    verify/final_report.json "adjustments"; text still over a face goes to "face_checks" and to
+    an `aviso:` line with a suggested center_y.
+  - captions.json made for another cut (timeline_key, cut boundaries or length that do not match
+    cut_timeline.json) is refused: run captions.py again.
+  - Inserts that overlap: the one later in the list is drawn on top. An HEIC/HEIF photo is converted
+    to JPG once with `sips` on macOS (renders/heic/); elsewhere it is refused with a hint.
+  - music.volume_db is relative to the voice loudness (the track is measured first). Default -15
+    (MUSIC_VOLUME_DB): with continuous speech the duck takes about 4 dB more off, so the bed sits about
+    19 LU under the voice; the old -22 left it about 26 LU under, nearly inaudible (measured 16/09/2026 on
+    two real cuts with a pop and a piano bed; the owner approved about -15 on a real ad).
+  - music.mood (instead of music.file): a mood of the personal library (helpers/trilhas.py). The choice
+    recorded in assets/trilhas_escolhidas.json is reused while its file is intact; otherwise the favorite of
+    the mood, else the best fit for the cut, is copied to assets/trilha_<mood>.<ext> and recorded.
+    music.track pins a library track id. When music.file is given it wins and mood is ignored. Without
+    mood the audio is exactly the one of a plain music.file.
+  - audio.denoise: "off" (default), "leve" or "forte" removes background noise from the voice (see
+    helpers/denoise.py). The voice is rebuilt from the sources range by range (cut_timeline.json) with
+    each source's own noise profile, placed on the same samples as in cut.mp4, loudnormed like
+    render_cut and used instead of cut.mp4's audio; cut.mp4 is not touched. Absent or "off": the audio
+    graph is exactly the one without this option. The report gets "denoise" (mode, noise floor before and
+    after, warnings) and the log one "ruído de fundo: ..." line.
+  - --preview writes final_preview.mp4 (540 px short side, CRF 26) unless -o is given.
+  - "edit_type": "tela_verde" + "tela_verde": {...}: the speaker cut out over images, videos or a color
+    (helpers/matte.py + helpers/tela_verde.py, SPEC Contract 13). The person matte of each cut range is made
+    once and cached in renders/matte/; the tela verde clip replaces cut.mp4 as the base (the camera zoom goes
+    into the person layer), faces and bodies are placed where the person lands and texts avoid them. Any
+    other edit_type, or none, renders exactly as before.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter, ImageOps
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import (  # noqa: E402
+    ffprobe_json,
+    file_signature,
+    fmt_time,
+    hex_to_rgb,
+    load_json,
+    load_style_catalog,
+    now_iso,
+    output_fps_for,
+    require_binary,
+    save_json,
+)
+import captions as captions_mod  # noqa: E402
+import denoise as denoise_mod  # noqa: E402
+import face_layout  # noqa: E402
+import make_sfx  # noqa: E402
+import text_render as tr  # noqa: E402
+
+RENDER_VERSION = "c2"          # bump to invalidate cached insert clips / overlay PNGs
+IMAGE_EXT = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".tif", ".tiff"}
+HEIC_EXT = {".heic", ".heif", ".hif"}
+VIDEO_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".gif", ".mts"}
+INSERT_TYPES = ("split_top", "split_bottom", "full", "pip")
+SFX_FILE_EXT = (".wav", ".mp3", ".m4a", ".aac", ".ogg", ".flac")
+SFX_EVENT_MAX_VOLUME = 2.0
+SFX_EVENT_MIN_KEPT = 0.9       # an sfx.events sound with less of its energy before the video end gets a warning
+SFX_TRIM_FADE = 0.08           # s: fade at the end of a sound cut to its "length" (animation cues)
+SR = 48000
+MUSIC_VOLUME_DB = -15.0        # music.volume_db default: about 19 LU under continuous speech once ducked
+KB_DRIFT = 0.06                # Ken Burns scale drift (SPEC: at most 6%)
+PREVIEW_SHORT_SIDE = 540
+
+DEFAULT_DISCLAIMER = "Resultado individual. Depende de execução. Não é promessa de ganho."
+DEFAULT_CTA = "Toque em Saiba Mais"
+
+
+class ComposeError(Exception):
+    def __init__(self, message: str, code: int = 1):
+        super().__init__(message)
+        self.code = code
+
+
+def log(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def even(v: float) -> int:
+    return max(2, int(round(v / 2.0)) * 2)
+
+
+def ease_in_out(p: float) -> float:
+    p = min(1.0, max(0.0, p))
+    return 0.5 - 0.5 * math.cos(math.pi * p)
+
+
+def short_hash(obj) -> str:
+    return hashlib.sha1(repr(obj).encode("utf-8")).hexdigest()[:16]
+
+
+def ffmpeg_cmd(args: list, what: str) -> subprocess.CompletedProcess:
+    proc = subprocess.run(["ffmpeg", "-hide_banner", "-nostdin", *[str(a) for a in args]],
+                          capture_output=True, text=True)
+    if proc.returncode != 0:
+        tail = "\n".join((proc.stderr or "").strip().splitlines()[-12:])
+        raise ComposeError(f"o ffmpeg falhou ao {what}:\n{tail}")
+    return proc
+
+
+_FF_MAJOR: int | None = None
+
+
+def ffmpeg_major() -> int:
+    global _FF_MAJOR
+    if _FF_MAJOR is None:
+        out = subprocess.run(["ffmpeg", "-version"], capture_output=True, text=True).stdout
+        m = re.search(r"ffmpeg version n?(\d+)", out)
+        _FF_MAJOR = int(m.group(1)) if m else 7
+    return _FF_MAJOR
+
+
+def graph_args(script: Path) -> list[str]:
+    return ["-/filter_complex", str(script)] if ffmpeg_major() >= 7 else ["-filter_complex_script", str(script)]
+
+
+# ============================================================== plan
+
+@dataclass
+class Insert:
+    idx: int
+    type: str
+    src: Path
+    kind: str                  # image | video
+    f0: int
+    f1: int
+    ken_burns: bool
+    split: float
+    sfx: str | None
+    content: tuple[int, int, int, int] = (0, 0, 0, 0)      # x, y, w, h of the picture
+    speaker: tuple[int, int, int, int] | None = None       # x, y, w, h of the speaker band
+    speaker_src_y: int = 0
+    speaker_pieces: list[tuple[int, int, int]] = field(default_factory=list)   # (f0, f1, source row) per camera segment
+    seam_y: int | None = None
+    card: tuple[int, int, int, int] | None = None          # pip outer card
+    clip: Path | None = None
+    to_bg: bool = False        # tela verde: a split_top / split_bottom insert shown as the background (no panel)
+    item: dict | None = None   # the raw edit_data item (tela verde reads escurecer / desfocar / encaixe / corner)
+
+
+@dataclass
+class Plan:
+    edit_dir: Path
+    edit_data_path: Path
+    data: dict
+    base: Path
+    out_path: Path
+    preview: bool
+    full_w: int
+    full_h: int
+    W: int
+    H: int
+    fps: int
+    base_fps: float
+    base_w: int
+    base_h: int
+    nf: int
+    has_audio: bool
+    segments: list[tuple[int, int]]
+    accent: str
+    renders: Path
+    warnings: list[str] = field(default_factory=list)
+    layers: list[dict] = field(default_factory=list)
+    timeline: dict | None = None
+    faces: dict | None = None                                  # face_layout.json
+    cam_segs: list[dict] = field(default_factory=list)         # per segment: f0, f1, zoom, zoom_max, focus_y, face
+    zones: list[tuple] = field(default_factory=list)           # (f0, f1, face zones, face cores) in render px
+    obstacles: list[tuple] = field(default_factory=list)       # (f0, f1, (x0, y0, x1, y1)): pip cards texts avoid
+    adjustments: list[dict] = field(default_factory=list)
+    face_checks: list[dict] = field(default_factory=list)
+    music_choice: dict | None = None                           # music.mood resolved through the library
+    tv: dict | None = None                                     # edit_type "tela_verde" (prepare_tela_verde)
+    person_zones: list[tuple] = field(default_factory=list)    # (f0, f1, body rects) in render px, tela verde only
+    image_zones: list[tuple] = field(default_factory=list)     # (f0, f1, rect) main area of a whole background picture
+
+    @property
+    def duration(self) -> float:
+        return self.nf / self.fps
+
+    @property
+    def s(self) -> float:          # render scale vs the full output canvas
+        return self.W / self.full_w
+
+    def fr(self, t, default: int = 0) -> int:
+        if t is None:
+            return default
+        return max(0, min(self.nf, int(round(float(t) * self.fps + 1e-6))))
+
+    def rel(self, p: Path) -> str:
+        try:
+            return str(p.resolve().relative_to(self.edit_dir))
+        except ValueError:
+            return str(p.resolve())
+
+
+def _section(data: dict, key: str) -> dict:
+    v = data.get(key)
+    return v if isinstance(v, dict) else {}
+
+
+def _enabled(sec: dict) -> bool:
+    return bool(sec) and bool(sec.get("enabled", True))
+
+
+def _resolve(edit_dir: Path, value: str, what: str) -> Path:
+    if not value or not str(value).strip():
+        raise ComposeError(f"{what}: caminho vazio", 2)
+    p = Path(str(value)).expanduser()
+    if not p.is_absolute():
+        p = edit_dir / p
+    p = p.resolve()
+    if not p.exists():
+        raise ComposeError(f"{what}: arquivo não encontrado: {p}", 2)
+    return p
+
+
+def _base_facts(base: Path) -> dict:
+    try:
+        info = ffprobe_json(base)
+    except Exception:
+        raise ComposeError(f"não consegui ler o vídeo base: {base}", 2)
+    streams = info.get("streams", [])
+    v = next((s for s in streams if s.get("codec_type") == "video"), None)
+    if v is None:
+        raise ComposeError(f"o vídeo base não tem imagem: {base}", 2)
+    from fractions import Fraction
+    rate = v.get("avg_frame_rate") or v.get("r_frame_rate") or "30/1"
+    try:
+        fps = float(Fraction(rate))
+    except (ValueError, ZeroDivisionError):
+        fps = 30.0
+    if fps <= 0:
+        fps = 30.0
+    dur = float(v.get("duration") or (info.get("format") or {}).get("duration") or 0.0)
+    nb = int(v.get("nb_frames") or 0)
+    if nb <= 0:
+        proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_packets",
+                               "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", str(base)],
+                              capture_output=True, text=True)
+        try:
+            nb = int(proc.stdout.strip().split(",")[0])
+        except ValueError:
+            nb = int(round(dur * fps))
+    rot = 0
+    for sd in v.get("side_data_list", []) or []:
+        if "rotation" in sd:
+            rot = abs(int(round(float(sd["rotation"])))) % 180
+    w, h = int(v.get("width", 0)), int(v.get("height", 0))
+    if rot == 90:
+        w, h = h, w
+    return {"fps": fps, "duration": dur, "frames": nb, "width": w, "height": h,
+            "has_audio": any(s.get("codec_type") == "audio" for s in streams)}
+
+
+def build_plan(edit_data_path: Path, out: str | None, preview: bool) -> Plan:
+    if not edit_data_path.exists():
+        raise ComposeError(f"edit_data.json não encontrado: {edit_data_path}", 2)
+    try:
+        data = json.loads(edit_data_path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as e:
+        raise ComposeError(f"edit_data.json inválido ({e})", 2)
+    if not isinstance(data, dict):
+        raise ComposeError("edit_data.json precisa ser um objeto JSON", 2)
+    edit_dir = edit_data_path.parent.resolve()
+    base = _resolve(edit_dir, data.get("base") or "cut.mp4", "base")
+    facts = _base_facts(base)
+
+    timeline_path = edit_dir / (data.get("timeline") or "cut_timeline.json")
+    timeline = load_json(timeline_path) if timeline_path.exists() else None
+
+    outcfg = _section(data, "output")
+    full_w = int(outcfg.get("width") or (timeline or {}).get("width") or facts["width"])
+    full_h = int(outcfg.get("height") or (timeline or {}).get("height") or facts["height"])
+    fps_val = outcfg.get("fps") or (timeline or {}).get("fps") or output_fps_for(facts["fps"])
+    fps = int(round(float(fps_val)))
+    if fps <= 0 or full_w < 16 or full_h < 16:
+        raise ComposeError("output inválido em edit_data.json (width/height/fps)", 2)
+    if preview:
+        k = min(1.0, PREVIEW_SHORT_SIDE / min(full_w, full_h))
+        W, H = even(full_w * k), even(full_h * k)
+    else:
+        W, H = even(full_w), even(full_h)
+
+    if abs(facts["fps"] - fps) < 0.01:
+        nf = facts["frames"]
+    else:
+        nf = int(round(facts["duration"] * fps))
+    if nf <= 0:
+        raise ComposeError("o vídeo base não tem quadros", 2)
+
+    accent = str(data.get("accent") or (load_style_catalog().get("defaults") or {}).get("accent") or "#FFC400")
+    try:
+        hex_to_rgb(accent)
+    except ValueError:
+        raise ComposeError(f"cor de destaque inválida: {accent!r} (use #RRGGBB)", 2)
+
+    if out:
+        out_path = Path(out).expanduser()
+        if not out_path.is_absolute():
+            out_path = (Path.cwd() / out_path)
+    else:
+        out_path = edit_dir / ("final_preview.mp4" if preview else "final.mp4")
+    out_path = out_path.resolve()
+
+    plan = Plan(edit_dir=edit_dir, edit_data_path=edit_data_path.resolve(), data=data, base=base,
+                out_path=out_path, preview=preview, full_w=full_w, full_h=full_h, W=W, H=H, fps=fps,
+                base_fps=facts["fps"], base_w=facts["width"], base_h=facts["height"], nf=nf,
+                has_audio=facts["has_audio"], segments=[], accent=accent,
+                renders=edit_dir / "renders" / ("preview" if preview else "full"), timeline=timeline)
+
+    # timeline segments on the output frame grid
+    segs = []
+    for s in (timeline or {}).get("segments", []) or []:
+        try:
+            segs.append(plan.fr(float(s["out_start"])))
+        except (KeyError, TypeError, ValueError):
+            continue
+    starts = sorted({f for f in segs if 0 < f < nf})
+    bounds = [0] + starts + [nf]
+    plan.segments = [(a, b) for a, b in zip(bounds, bounds[1:]) if b > a]
+    music = _section(data, "music")
+    if _enabled(music) and music.get("file"):
+        _resolve(edit_dir, music.get("file"), "music.file")
+    elif _enabled(music) and music.get("mood") not in (None, ""):
+        resolve_music_mood(plan, music)
+    elif _enabled(music):
+        raise ComposeError("music está ligado mas sem 'file' nem 'mood' (ex: \"file\": \"assets/trilha.mp3\" "
+                           "ou \"mood\": \"triste\")", 2)
+    if timeline is None:
+        plan.warnings.append("cut_timeline.json não encontrado: o vídeo inteiro conta como um trecho só")
+    if timeline and abs(float(timeline.get("duration") or 0) - nf / fps) > 1.5 / fps:
+        plan.warnings.append(f"cut_timeline.json diz {timeline.get('duration')}s, mas o vídeo base tem {nf / fps:.3f}s")
+    return plan
+
+
+def resolve_music_mood(plan: Plan, music: dict) -> None:
+    """music.mood without music.file: pick the track from the personal library (helpers/trilhas.py).
+
+    The chosen file goes to assets/ and into plan.data["music"]["file"] (in memory only), so the audio graph is
+    the one of a plain music.file; plan.music_choice keeps the track id and why for the report."""
+    import trilhas
+
+    mood, track = music.get("mood"), music.get("track")
+    if not isinstance(mood, str) or not mood.strip():
+        raise ComposeError("music.mood precisa ser o nome de um humor, ex.: \"triste\"", 2)
+    if track is not None and (not isinstance(track, str) or not track.strip()):
+        raise ComposeError("music.track precisa ser o id de uma trilha da biblioteca, ex.: \"triste-2\"", 2)
+    try:
+        choice = trilhas.resolve_for_edit(plan.edit_dir, mood.strip(), plan.duration,
+                                          track.strip() if track else None)
+    except trilhas.TrilhaError as e:
+        raise ComposeError(f"music.mood: {e}", 2)
+    _resolve(plan.edit_dir, choice["file"], "music.file")
+    plan.data["music"] = {**music, "file": choice["file"]}
+    plan.music_choice = choice
+    if choice.get("warning"):
+        plan.warnings.append(choice["warning"])
+
+
+def _plain_number(value) -> float | None:
+    """A finite number (or numeric text); None for bools, text that is not a number, NaN and inf."""
+    if isinstance(value, bool):
+        return None
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return None
+    return v if math.isfinite(v) else None
+
+
+def _as_json(value) -> str:
+    """A value the way it is written in edit_data.json (null, true, "texto"), for error messages."""
+    try:
+        text = json.dumps(value, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return repr(value)
+    if isinstance(value, str) and "," in value and _plain_number(value.replace(",", ".")) is not None:
+        text += ", use ponto no lugar da vírgula"
+    return text
+
+
+def plan_sfx_events(plan: Plan) -> list[dict]:
+    """sfx.events: effects at a chosen time on the cut, not tied to a hook, insert, flash or CTA.
+
+    Checked before anything renders. Returns events in the same shape build_tracks gives run_audio
+    ({name, frame, lead_frames 0, why "efeito"}) plus at, event (index), and volume and anchor_s when given.
+    """
+    sec = _section(plan.data, "sfx")
+    if not _enabled(sec) or sec.get("events") is None:
+        return []
+    raw = sec.get("events")
+    example = '{"at": 5.07, "name": "cash"}'
+    if not isinstance(raw, list):
+        raise ComposeError(f"sfx.events precisa ser uma lista (ex: [{example}])", 2)
+    out: list[dict] = []
+    for i, item in enumerate(raw):
+        where = f"sfx.events[{i}]"
+        if not isinstance(item, dict):
+            raise ComposeError(f"{where} precisa ser um objeto (ex: {example})", 2)
+        at = _plain_number(item.get("at"))
+        if at is None or at < 0:
+            if "at" not in item:
+                raise ComposeError(f"{where} precisa de \"at\": o segundo do corte em que o som toca (ex: {example})", 2)
+            raise ComposeError(f"{where}.at precisa ser um número de segundos, 0 ou mais (veio {_as_json(item.get('at'))})", 2)
+        name = item.get("name")
+        if not isinstance(name, str) or not name.strip():
+            raise ComposeError(f"{where} precisa de \"name\": um efeito ({', '.join(make_sfx.NAMES)}, ou o nome em "
+                               f"português, ex.: \"grave\") ou um arquivo (ex: \"assets/meu_som.wav\")", 2)
+        name = name.strip()
+        ev: dict = {"name": name, "frame": 0, "lead_frames": 0, "why": "efeito", "at": round(at, 4), "event": i}
+        if item.get("volume") is not None:
+            vol = _plain_number(item.get("volume"))
+            if vol is None or vol < 0:
+                raise ComposeError(f"{where}.volume precisa ser um número de 0.0 a {SFX_EVENT_MAX_VOLUME:.1f} "
+                                   f"(veio {_as_json(item.get('volume'))})", 2)
+            if vol > SFX_EVENT_MAX_VOLUME:
+                plan.warnings.append(f"{where}.volume {vol:g} passou do máximo e ficou em {SFX_EVENT_MAX_VOLUME:.1f}")
+                vol = SFX_EVENT_MAX_VOLUME
+            ev["volume"] = vol
+        if item.get("anchor_s") is not None:
+            anchor = _plain_number(item.get("anchor_s"))
+            if anchor is None or anchor < 0:
+                raise ComposeError(f"{where}.anchor_s precisa ser um número de segundos, 0 ou mais: onde fica o ponto "
+                                   f"forte dentro do som (veio {_as_json(item.get('anchor_s'))})", 2)
+            ev["anchor_s"] = round(anchor, 4)
+        if Path(name).suffix.lower() in SFX_FILE_EXT:
+            _resolve(plan.edit_dir, name, f"{where}.name")
+        if at * plan.fps >= plan.nf - 1e-6:
+            plan.warnings.append(f"{where} ('{name}' em {fmt_time(at)}) passa do fim do vídeo (o vídeo acaba em "
+                                 f"{fmt_time(plan.duration)} e o último quadro começa em "
+                                 f"{fmt_time((plan.nf - 1) / plan.fps)}) e foi ignorado")
+            continue
+        # same rounding as the other events (Plan.fr); a time in the last half frame stays on the last frame
+        ev["frame"] = min(plan.fr(at), plan.nf - 1)
+        out.append(ev)
+    return out
+
+
+def plan_denoise(plan: Plan) -> str:
+    """audio.denoise: "off" | "leve" | "forte" (a missing section or "enabled": false is off). Checked before rendering."""
+    raw = plan.data.get("audio")
+    if raw is None:
+        return "off"
+    if not isinstance(raw, dict):
+        raise ComposeError('audio precisa ser um objeto (ex: "audio": {"denoise": "leve"})', 2)
+    if raw.get("enabled", True) is False:
+        return "off"
+    try:
+        return denoise_mod.normalize_mode(raw.get("denoise"))
+    except ValueError as e:
+        raise ComposeError(str(e), 2)
+
+
+def run_denoise(plan: Plan, mode: str, keep_temp: bool) -> tuple[Path | None, dict]:
+    """The cleaned voice for run_audio (None keeps cut.mp4's audio). A failure never stops the render."""
+    if mode == "off":
+        return None, {"mode": "off", "applied": "off"}
+    if not plan.has_audio:
+        msg = "o vídeo base não tem áudio: não há ruído para limpar"
+        plan.warnings.append(msg)
+        return None, {"mode": mode, "applied": "off", "warnings": [msg]}
+    work = plan.edit_dir / "renders" / "denoise"
+    try:
+        res = denoise_mod.build_voice(plan.edit_dir, plan.base, plan.timeline, plan.fps, plan.nf * SR // plan.fps, mode,
+                                      work, keep_temp=keep_temp)
+    except Exception as e:  # noqa: BLE001  (the cleaning is optional: the render goes on with the cut's audio)
+        msg = f"a limpeza de ruído falhou ({e}). O vídeo sai com o som original"
+        plan.warnings.append(msg)
+        return None, {"mode": mode, "applied": "off", "warnings": [msg]}
+    plan.warnings.extend(res.warnings)
+    return res.path, res.report
+
+
+def denoise_line(rep: dict) -> str | None:
+    """One PT-BR log line about the background-noise removal (None when it is off)."""
+    mode = rep.get("mode") or "off"
+    if mode == "off":
+        return None
+    applied = rep.get("applied") or "off"
+    if applied == "off":
+        return f"ruído de fundo: sem limpeza (pedido {denoise_mod.LABEL[mode]}, veja o aviso)"
+    if applied == "misto":
+        lighter = [e["source"] for e in rep.get("sources") or [] if e.get("applied") == "leve"]
+        what = f"{denoise_mod.LABEL[mode]}, leve em {', '.join(lighter)}"
+    elif applied != mode:
+        what = f"{denoise_mod.LABEL[applied]} no lugar de {denoise_mod.LABEL[mode]}"
+    else:
+        what = denoise_mod.LABEL[applied]
+    if rep.get("method") == "corte":
+        what += ", no som do corte"
+    before, after = rep.get("noise_floor_before_db"), rep.get("noise_floor_after_db")
+    if before is not None and after is not None:
+        return f"ruído de fundo: {what} (fundo de {before:.0f} dB para {after:.0f} dB)"
+    return f"ruído de fundo: {what}"
+
+
+# ============================================================== camera
+
+def _is_auto(value) -> bool:
+    return value is None or (isinstance(value, str) and value.strip().lower() == "auto")
+
+
+def load_faces(plan: Plan) -> None:
+    """Face per timeline segment (face_layout.json, detected on the first compose and cached)."""
+    try:
+        plan.faces = face_layout.build(plan.edit_dir, plan.base, timeline=plan.timeline)
+    except face_layout.FaceLayoutError as e:
+        plan.warnings.append(f"não consegui procurar o rosto ({e}): textos e zoom nas posições padrão")
+    except Exception as e:  # noqa: BLE001  (a detector failure must not stop the render)
+        plan.warnings.append(f"a detecção de rosto falhou ({e.__class__.__name__}): textos e zoom nas posições padrão")
+
+
+def camera_segments(plan: Plan, levels: list[float], zoom_cuts: bool, push_in: bool, amount: float) -> list[dict]:
+    cam = _section(plan.data, "camera")
+    manual = None
+    if not _is_auto(cam.get("focus_y")):
+        try:
+            manual = min(0.9, max(0.1, float(cam.get("focus_y"))))
+        except (TypeError, ValueError):
+            raise ComposeError("camera.focus_y precisa ser um número entre 0.1 e 0.9 ou \"auto\"", 2)
+    face_segs = [f for f in ((plan.faces or {}).get("segments") or []) if isinstance(f, dict)]
+    found = any(f.get("face") for f in face_segs)
+    fallback = ((plan.faces or {}).get("recommended") or {}).get("camera", {}).get("focus_y") if found else None
+    fallback = float(fallback) if fallback is not None else 0.40
+    out = []
+    for i, (a, b) in enumerate(plan.segments):
+        z = levels[i % len(levels)] if zoom_cuts else 1.0
+        t0, t1 = a / plan.fps, b / plan.fps
+        best, best_ov = None, 0.0
+        for f in face_segs:
+            ov = min(t1, float(f.get("end", 0))) - max(t0, float(f.get("start", 0)))
+            if ov > best_ov:
+                best, best_ov = f, ov
+        face = best if best and best.get("face") else None
+        fy = manual if manual is not None else (float(face["focus_y"]) if face and face.get("focus_y") is not None else fallback)
+        out.append({"f0": a, "f1": b, "zoom": z, "zoom_max": z * (1 + amount) if push_in else z,
+                    "focus_y": min(0.9, max(0.1, fy)), "face": face, "manual_focus": manual is not None})
+    return out
+
+
+def camera_filter(plan: Plan) -> str | None:
+    cam = _section(plan.data, "camera")
+    zoom_cuts = bool(cam.get("zoom_cuts", False))
+    push_in = bool(cam.get("push_in", False))
+    levels = cam.get("zoom_levels") or [1.0, 1.14]
+    try:
+        levels = [min(1.6, max(1.0, float(z))) for z in levels] or [1.0]
+    except (TypeError, ValueError):
+        raise ComposeError("camera.zoom_levels precisa ser uma lista de números (ex: [1.0, 1.14])", 2)
+    amount = min(0.25, max(0.0, float(cam.get("push_in_amount", 0.05) or 0.0)))
+    plan.cam_segs = camera_segments(plan, levels, zoom_cuts, push_in and amount > 0, amount)
+    segs_info = []
+    parts = []
+    for cs in plan.cam_segs:
+        a, b, z = cs["f0"], cs["f1"], cs["zoom"]
+        n = b - a
+        if push_in and amount > 0 and n > 1:
+            expr = f"{z:.5f}*(1+{amount:.5f}*(0.5-0.5*cos(PI*clip((in-1-{a})/{n - 1},0,1))))"
+        else:
+            expr = f"{z:.5f}"
+        parts.append((b, expr, cs["focus_y"]))
+        segs_info.append({"start": round(a / plan.fps, 3), "end": round(b / plan.fps, 3), "zoom": z,
+                          "push_in": amount if push_in else 0.0, "focus_y": round(cs["focus_y"], 4),
+                          "face": bool(cs["face"])})
+    manual = next((cs["focus_y"] for cs in plan.cam_segs if cs["manual_focus"]), None)
+    plan.layers.append({"type": "camera", "zoom_cuts": zoom_cuts, "push_in": push_in,
+                        "focus_y": manual if manual is not None else "auto", "segments": segs_info})
+    if not push_in and all(abs(info["zoom"] - 1.0) < 1e-6 for info in segs_info):
+        return None
+
+    def piecewise(fn) -> str:
+        expr = fn(parts[-1])
+        for part in reversed(parts[:-1]):
+            expr = f"if(lt(in-1,{part[0]}),{fn(part)},{expr})"
+        return f"({expr})"
+
+    Z = piecewise(lambda p: p[1])
+    # each segment's crop keeps its own eye line still (focus_y per segment)
+    T = piecewise(lambda p: f"{p[2]:.5f}*(1-1/({p[1]}))")
+    left = f"W*0.5*(1-1/{Z})"
+    top = f"H*{T}"
+    right = f"W*0.5*(1-1/{Z})+W/{Z}"
+    bottom = f"H*{T}+H/{Z}"
+    return (f"perspective=x0='{left}':y0='{top}':x1='{right}':y1='{top}':"
+            f"x2='{left}':y2='{bottom}':x3='{right}':y3='{bottom}':interpolation=cubic:eval=frame")
+
+
+def segment_for(plan: Plan, f0: int, f1: int) -> dict | None:
+    """Camera segment covering most of [f0, f1)."""
+    best, best_ov = None, 0
+    for cs in plan.cam_segs:
+        ov = min(f1, cs["f1"]) - max(f0, cs["f0"])
+        if ov > best_ov:
+            best, best_ov = cs, ov
+    return best
+
+
+# ============================================================== inserts
+
+def plan_inserts(plan: Plan, tela_verde: bool = False) -> list[Insert]:
+    """tela_verde: split_top / split_bottom items become background items (to_bg, no panel, no seam)."""
+    raw = plan.data.get("inserts") or []
+    if not isinstance(raw, list):
+        raise ComposeError("inserts precisa ser uma lista", 2)
+    sfx_on = _enabled(_section(plan.data, "sfx"))
+    W, H, s = plan.W, plan.H, plan.s
+    lay = tr.layout_defaults((W, H))
+    safe_top, safe_bottom = lay["top"], lay["bottom"]
+    out: list[Insert] = []
+    seam_reach = (0.0, 0.0)          # (above, below) px the captions reach from a split seam
+    cap = _section(plan.data, "captions")
+    if _enabled(cap) and not tela_verde and any(isinstance(it, dict) and it.get("type") in ("split_top", "split_bottom")
+                                                for it in raw):
+        style = cap.get("style")
+        if not style:   # the same fallback build_tracks uses: the style captions.json was grouped for
+            try:
+                cues = load_json(plan.edit_dir / str(cap.get("file") or "captions.json"))
+            except (ValueError, OSError):
+                cues = None
+            style = (cues.get("style") if isinstance(cues, dict) else None) \
+                or (load_style_catalog().get("defaults") or {}).get("caption_style") or "impacto"
+        try:
+            seam_reach = tr.caption_extent([], style, (W, H), float(cap.get("font_scale", 1.0) or 1.0), plan.fps)
+        except (ValueError, TypeError):
+            seam_reach = (0.0, 0.0)   # unknown style: build_tracks reports it
+    for i, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise ComposeError(f"inserts[{i}] precisa ser um objeto", 2)
+        typ = item.get("type")
+        if typ not in INSERT_TYPES:
+            raise ComposeError(f"inserts[{i}].type inválido: {typ!r}. Use {', '.join(INSERT_TYPES)}", 2)
+        src = _resolve(plan.edit_dir, item.get("src"), f"inserts[{i}].src")
+        ext = src.suffix.lower()
+        if ext in HEIC_EXT:
+            src, ext = heic_to_jpg(plan, src, i), ".jpg"
+        kind = "image" if ext in IMAGE_EXT else "video" if ext in VIDEO_EXT else None
+        if kind is None:
+            try:
+                Image.open(src).close()
+                kind = "image"
+            except Exception:
+                kind = "video"
+        try:
+            t0, t1 = float(item["start"]), float(item["end"])
+        except (KeyError, TypeError, ValueError):
+            raise ComposeError(f"inserts[{i}] precisa de start e end em segundos", 2)
+        f0, f1 = plan.fr(t0), plan.fr(t1)
+        if f0 >= plan.nf:
+            plan.warnings.append(f"insert {i + 1} começa depois do fim do vídeo e foi ignorado")
+            continue
+        if t1 * plan.fps > plan.nf + 0.5:
+            plan.warnings.append(f"insert {i + 1} passava do fim do vídeo e foi cortado em {fmt_time(plan.duration)}")
+        if f1 - f0 < 2:
+            plan.warnings.append(f"insert {i + 1} dura menos de 2 quadros e foi ignorado")
+            continue
+        kb_default = kind == "image"
+        split = item.get("split", 0.46)
+        try:
+            split = min(0.75, max(0.25, float(split if split is not None else 0.46)))
+        except (TypeError, ValueError):
+            raise ComposeError(f"inserts[{i}].split precisa ser um número entre 0.25 e 0.75", 2)
+        sfx_name = item.get("sfx", "whoosh")
+        if sfx_name in (None, False, "", "none"):
+            sfx_name = None
+        ins = Insert(idx=i, type=typ, src=src, kind=kind, f0=f0, f1=f1,
+                     ken_burns=bool(item.get("ken_burns", kb_default)), split=split,
+                     sfx=str(sfx_name) if (sfx_name and sfx_on) else None)
+        if tela_verde:
+            ins.item = item
+        if tela_verde and typ in ("split_top", "split_bottom"):
+            ins.to_bg = True            # its "split" does not apply: it is the background of [f0, f1)
+            ins.content = (0, 0, W, H)
+        elif typ in ("split_top", "split_bottom"):
+            hb = even(split * H)
+            hs = H - hb
+            # eyes of the segment under this window, where the camera left them (focus_y is the eye line)
+            seg = segment_for(plan, f0, min(f1, plan.nf))
+            face = (seg["focus_y"] if seg else 0.40) * H
+            if typ == "split_top":
+                ins.content = (0, 0, W, hb)
+                ins.speaker = (0, hb, W, hs)
+                ins.seam_y = hb
+            else:
+                ins.content = (0, hs, W, hb)
+                ins.speaker = (0, 0, W, hs)
+                ins.seam_y = hs
+            ins.speaker_src_y = face_layout.speaker_src_y(typ, hb / H, face, W, H, safe_top, safe_bottom)
+            # the face can sit at another height in each take the window covers: re-frame per segment
+            pieces: list[tuple[int, int, int]] = []
+            for cs in plan.cam_segs:
+                a, b = max(f0, cs["f0"]), min(f1, cs["f1"])
+                if b <= a:
+                    continue
+                core = None
+                if cs.get("face") and cs["face"].get("core"):
+                    rects = [face_layout.zoom_rect(cs["face"]["core"], z, cs["focus_y"]) for z in {cs["zoom"], cs["zoom_max"]}]
+                    core = (min(r["y0"] for r in rects) * H, max(r["y1"] for r in rects) * H)
+                reach = seam_reach[0] if typ == "split_bottom" else seam_reach[1]
+                y = face_layout.speaker_src_y(typ, hb / H, cs["focus_y"] * H, W, H, safe_top, safe_bottom,
+                                              core=core, clear=reach + GAP_FACE * H if reach else 0.0)
+                if pieces and pieces[-1][2] == y and pieces[-1][1] == a:
+                    pieces[-1] = (pieces[-1][0], b, y)
+                else:
+                    pieces.append((a, b, y))
+            ins.speaker_pieces = pieces or [(f0, f1, ins.speaker_src_y)]
+            ins.speaker_src_y = max(ins.speaker_pieces, key=lambda p: p[1] - p[0])[2]
+        elif typ == "full":
+            ins.content = (0, 0, W, H)
+        else:  # pip
+            aspect = 1.0
+            if kind == "image":
+                with Image.open(src) as im:
+                    im = ImageOps.exif_transpose(im)
+                    aspect = im.width / max(1, im.height)
+            else:
+                try:
+                    info = ffprobe_json(src)
+                    v = next(st for st in info.get("streams", []) if st.get("codec_type") == "video")
+                    aspect = int(v["width"]) / max(1, int(v["height"]))
+                except Exception:
+                    aspect = 1.0
+            aspect = min(1.25, max(0.8, aspect))
+            border = max(2, int(round(10 * s)))
+            cw = even(380 * s)
+            ch = even(cw / aspect)
+            ow, oh = cw + 2 * border, ch + 2 * border
+            corner = str(item.get("corner") or "top_right")
+            if corner not in ("top_right", "top_left"):
+                raise ComposeError(f"inserts[{i}].corner inválido: {corner!r}. Use top_right ou top_left", 2)
+            margin_x = int(round(48 * s))
+            ox = W - margin_x - ow if corner == "top_right" else margin_x
+            oy = int(round(safe_top + 26 * s))
+            ins.card = (ox, oy, ow, oh)
+            ins.content = (ox + border, oy + border, cw, ch)
+        out.append(ins)
+    for k, a in enumerate(out):
+        for b in out[k + 1:]:
+            if b.f0 < a.f1 and a.f0 < b.f1 and a.to_bg == b.to_bg:
+                plan.warnings.append(f"inserts {a.idx + 1} e {b.idx + 1} se sobrepõem ({fmt_time(max(a.f0, b.f0) / plan.fps)}): "
+                                     f"o {b.idx + 1}, que vem depois na lista, fica por cima")
+    return out   # list order = drawing order (a later insert is drawn over an earlier one)
+
+
+def heic_to_jpg(plan: Plan, src: Path, i: int, where: str | None = None) -> Path:
+    """iPhone photos (HEIC/HEIF) -> JPG once, with macOS `sips` (cached by the file signature)."""
+    where = where or f"inserts[{i}].src"
+    sips = shutil.which("sips") if sys.platform == "darwin" else None
+    if not sips:
+        raise ComposeError(f"{where} é uma foto HEIC do iPhone ({src.name}), que não abre aqui. "
+                           f"Converta para JPG (no iPhone: Ajustes > Câmera > Formatos > Mais Compatível; ou abra e "
+                           f"exporte como JPG) e use o arquivo .jpg", 2)
+    out_dir = plan.edit_dir / "renders" / "heic"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / f"{src.stem}_{short_hash((str(src), file_signature(src)))[:10]}.jpg"
+    if out.exists() and out.stat().st_size > 0:
+        return out
+    tmp = out.with_name(".tmp-" + out.name)
+    proc = subprocess.run([sips, "-s", "format", "jpeg", "-s", "formatOptions", "93", str(src), "--out", str(tmp)],
+                          capture_output=True, text=True)
+    if proc.returncode != 0 or not tmp.exists():
+        raise ComposeError(f"não consegui converter a foto HEIC {where} ({src.name}) para JPG. "
+                           f"Exporte a foto como JPG e use o arquivo .jpg", 2)
+    os.replace(tmp, out)
+    return out
+
+
+# ============================================================== tela verde (SPEC Contract 13)
+
+EDIT_TYPES = ("clean", "split_top", "split_bottom", "tela_verde")
+
+
+def resolve_media(plan: Plan, value, where: str) -> tuple[Path, str]:
+    """An image or video file of the edit -> (path, "image" | "video"), HEIC converted like the inserts."""
+    if not isinstance(value, str):
+        raise ComposeError(f"{where} precisa ser o caminho de um arquivo (ex: \"assets/foto.jpg\")", 2)
+    src = _resolve(plan.edit_dir, value, where)
+    ext = src.suffix.lower()
+    if ext in HEIC_EXT:
+        src, ext = heic_to_jpg(plan, src, 0, where), ".jpg"
+    kind = "image" if ext in IMAGE_EXT else "video" if ext in VIDEO_EXT else None
+    if kind is None:
+        try:
+            Image.open(src).close()
+            kind = "image"
+        except Exception:
+            kind = "video"
+    return src, kind
+
+
+def plan_tela_verde(plan: Plan):
+    """edit_type "tela_verde": check the section before anything renders (exit 2). None for the other types."""
+    et = plan.data.get("edit_type")
+    if et is None or et in EDIT_TYPES[:3]:
+        if plan.data.get("tela_verde") is not None:
+            plan.warnings.append("a seção tela_verde ficou de fora: para usar, ponha \"edit_type\": \"tela_verde\"")
+        return None
+    if et != "tela_verde":
+        raise ComposeError(f"edit_type {_as_json(et)} não existe. Use {', '.join(EDIT_TYPES)}", 2)
+    import matte as MT
+    import tela_verde as TV
+
+    try:
+        cfg = TV.parse_config(plan.data.get("tela_verde"), plan.fps, plan.nf,
+                              lambda value, where: resolve_media(plan, value, where), plan.fr,
+                              screen=(plan.full_w, plan.full_h))
+        MT.default_engine_ready()
+    except TV.TelaVerdeError as e:
+        raise ComposeError(str(e), e.code)
+    except MT.MatteError as e:
+        raise ComposeError(str(e), e.code)
+    return cfg      # its warnings go to the report after the split inserts join it (insert_backgrounds)
+
+
+def insert_backgrounds(plan: Plan, cfg, inserts: list[Insert]) -> None:
+    """Tela verde: the split_top / split_bottom inserts become background items (they win over tela_verde.fundo
+    during their own frames); then the warnings of the section go to the report."""
+    import tela_verde as TV
+
+    moved = [i for i in inserts if i.to_bg]
+    try:
+        TV.add_insert_backgrounds(cfg, [{"insert": i.idx + 1, "type": i.type, "src": i.src, "kind": i.kind,
+                                         "f0": i.f0, "f1": i.f1, "ken_burns": i.ken_burns, "item": i.item}
+                                        for i in moved], plan.nf, plan.fps)
+    except TV.TelaVerdeError as e:
+        raise ComposeError(str(e), e.code)
+    for ins in inserts:
+        bad = [k for k in ("escurecer", "desfocar", "encaixe") if ins.item and k in ins.item and not ins.to_bg]
+        if bad:
+            plan.warnings.append(f"inserts[{ins.idx}].{bad[0]} só vale para imagem em cima ou embaixo na tela verde "
+                                 f"(que vira fundo): no {ins.type} ficou de fora")
+    plan.warnings.extend(cfg.warnings)
+    if moved:
+        names = ", ".join(str(i.idx + 1) for i in moved)
+        kinds = sorted({TV.SPLIT_LABEL[i.type] for i in moved})
+        log(f"tela verde: {'o insert' if len(moved) == 1 else 'os inserts'} {names} ({' e '.join(kinds)}) "
+            f"{'vai' if len(moved) == 1 else 'vão'} para o fundo, atrás de você (sem tela dividida)")
+
+
+def prepare_tela_verde(plan: Plan, cfg) -> None:
+    """Person segments, their mattes (computed now when not cached), placement, and the face and body of each
+    segment where they land on the screen (cam_segs switch to screen coordinates without zoom)."""
+    import matte as MT
+    import tela_verde as TV
+
+    t0 = time.time()
+    segs = []
+    for cs in plan.cam_segs:
+        has_face = bool(cs.get("face"))
+        mode = "pessoa" if (has_face or cfg.no_face == "recorte" or plan.faces is None) else "original"
+        push = cs["zoom_max"] / cs["zoom"] - 1.0 if cs["zoom_max"] > cs["zoom"] + 1e-9 else 0.0
+        segs.append(TV.Segment(f0=cs["f0"], f1=cs["f1"], mode=mode, zoom=cs["zoom"], push=push,
+                               focus_y=cs["focus_y"], face=cs.get("face") if has_face else None))
+    people = [i for i, sg in enumerate(segs) if sg.mode == "pessoa"]
+    mset = None
+    mattes: dict[int, object] = {}
+    if people:
+        try:
+            mset = MT.ensure(plan.edit_dir, plan.base, [(segs[i].f0, segs[i].f1) for i in people], plan.fps,
+                             (plan.full_w, plan.full_h), plan.timeline, progress=log,
+                             base_fps=plan.base_fps, base_size=(plan.base_w, plan.base_h))
+        except MT.MatteError as e:
+            raise ComposeError(f"recorte da pessoa: {e}", e.code)
+        plan.warnings.extend(mset.warnings)
+        for i, job in zip(people, mset.jobs):
+            mattes[i] = job
+            segs[i].stats = job.meta.get("stats") or {}
+            if cfg.mirror:           # the person segments are drawn flipped: place them as they will be seen
+                segs[i].stats = TV.mirror_stats(segs[i].stats)
+                segs[i].face = TV.mirror_face(segs[i].face)
+    TV.plan_segments(cfg, segs)
+    for sg in segs:
+        if sg.note:
+            plan.warnings.append(f"tela verde, trecho {fmt_time(sg.f0 / plan.fps)}-{fmt_time(sg.f1 / plan.fps)}: {sg.note}")
+    filled = merge_windows([(sg.f0, sg.f1) for sg in segs if sg.fill])
+    if filled:
+        spans = ", ".join(f"{fmt_time(a / plan.fps)}-{fmt_time(b / plan.fps)}" for a, b in filled)
+        plan.warnings.append(f"tela verde: em {spans} a câmera corta os dois lados do seu corpo, então ali você "
+                             f"ocupa a largura toda da tela (um pouco mais baixo), para o corte não aparecer no meio "
+                             f"da tela")
+    inner = TV.inner_cut(cfg, segs, plan.W, plan.H)
+    if inner:
+        plan.warnings.append(inner["aviso"])
+    for cs, sg in zip(plan.cam_segs, segs):
+        cs["tv_zoom"], cs["tv_zoom_max"], cs["tv_mode"] = cs["zoom"], cs["zoom_max"], sg.mode
+        if sg.mode == "pessoa":
+            z = TV.screen_zones(cfg, sg, plan.W, plan.H)
+            face = z["face"]
+            cs["face"] = ({"zone": face["zone"], "core": face["core"], "face": {"eyes_y": face["eyes_y"]}}
+                          if face else None)
+            if face:
+                cs["focus_y"] = min(0.9, max(0.1, face["eyes_y"]))
+            cs["person"] = z["person"]
+            cs["zoom"] = cs["zoom_max"] = 1.0      # the zoom is already in the person layer
+    for b in cfg.backgrounds:        # the main area of a still picture shown whole (its empty margin may be covered)
+        if b.fit == "inteiro" and b.kind == "image" and b.size:
+            try:
+                b.content = TV.content_box(TV.read_image(b.src))
+            except Exception as e:  # noqa: BLE001
+                raise ComposeError(f"não consegui abrir a imagem do fundo ({b.name}): {b.src} ({e})", 2)
+        elif b.kind == "video" and b.src is not None:
+            # empty frames at its start and end; shown whole: its main area over the clip and a plain border
+            try:
+                info = TV.scan_video(b.src, plan.fps, plan.renders / "telaverde")
+            except Exception as e:  # noqa: BLE001
+                raise ComposeError(f"não consegui ler o vídeo do fundo ({b.name}): {b.src} ({e})", 1)
+            b.pass_frames, b.lead, b.tail = int(info["frames"]), int(info["lead"]), int(info["tail"])
+            if b.fit == "inteiro" and b.size:
+                b.content = tuple(float(v) for v in info["content"])
+                b.quiet = bool(info["quiet"])
+    TV.plan_stages(cfg, segs, plan.W, plan.H, caption_room(plan))
+    plan.image_zones = TV.image_zones(cfg, segs, plan.W, plan.H)
+    plates, plate_rows = room_plates(plan, mattes)
+    plan.tv = {"cfg": cfg, "segments": segs, "mattes": mattes, "mset": mset, "inner_cut": inner,
+               "plates": plates, "plate_rows": plate_rows,
+               "matte_seconds": round(mset.seconds, 2) if mset else 0.0, "prepare_seconds": round(time.time() - t0, 2)}
+    cam = next((layer for layer in plan.layers if layer["type"] == "camera"), None)
+    if cam is not None:
+        cam["applied_to"] = "tela_verde"
+
+
+def room_plates(plan: Plan, mattes: dict) -> tuple[dict, list[dict]]:
+    """Tela verde: the room plate of each take (the ranges of one source video with the same framing), so the
+    render can take out the room a matte keeps. -> ({segment index: plate}, report rows)."""
+    import matte as MT
+    import tela_verde as TV
+
+    if not mattes or not plan.timeline or os.environ.get(TV.PLATE_ENV, "1") == "0":
+        return {}, []
+    groups: dict[str, list] = {}
+    names: dict[str, str] = {}
+    for i, job in mattes.items():
+        tseg = MT._timeline_segment(plan.timeline, job.f0, job.f1, plan.fps)
+        if not tseg or tseg.get("source") is None:
+            continue
+        cam = str(tseg.get("imagem_de") or tseg.get("source"))   # the camera the picture came from
+        g = json.dumps([cam, tseg.get("crop")], sort_keys=True, ensure_ascii=False)
+        groups.setdefault(g, []).append((i, job))
+        names[g] = cam
+    if not groups:
+        return {}, []
+    try:
+        found, notes = TV.room_plates(plan.base, _matte_pre(plan), plan.base_fps, plan.fps,
+                                      (plan.full_w, plan.full_h),
+                                      {g: [(j.f0, j.f1, j) for _, j in parts] for g, parts in groups.items()},
+                                      plan.edit_dir / MT.CACHE_DIR, progress=log)
+    except (OSError, ValueError, MT.MatteError) as e:
+        plan.warnings.append(f"tela verde: não consegui aprender o fundo do cenário ({e}); o recorte ficou como o "
+                             f"modelo fez")
+        return {}, []
+    plates, rows = {}, []
+    for g, parts in groups.items():
+        plate = found.get(g)
+        for i, _ in parts:
+            if plate is not None:
+                plates[i] = plate
+        rows.append({"tomada": names[g], "trechos": len(parts), "usado": plate is not None,
+                     "conhece": plate.known if plate is not None else None,
+                     "motivo": None if plate is not None else (notes.get(g) or None)})
+    return plates, rows
+
+
+def compute_person_zones(plan: Plan, inserts: list[Insert]) -> None:
+    """plan.person_zones: where the cut-out body is on the screen, per frame interval (tela verde only)."""
+    if not plan.tv:
+        return
+    W, H = plan.W, plan.H
+    pieces = []
+    for cs in plan.cam_segs:
+        r = cs.get("person")
+        rects = [(r["x0"] * W, r["y0"] * H, r["x1"] * W, r["y1"] * H)] if r else []
+        pieces.append((cs["f0"], cs["f1"], rects))
+    cuts = sorted({0, plan.nf} | {p[0] for p in pieces} | {p[1] for p in pieces}
+                  | {min(plan.nf, i.f0) for i in inserts} | {min(plan.nf, i.f1) for i in inserts})
+    out: list[tuple] = []
+    for a, b in zip(cuts, cuts[1:]):
+        if b <= a:
+            continue
+        base = next((p for p in pieces if p[0] <= a < p[1]), None)
+        rects = base[2] if base else []
+        top = None
+        for ins in inserts:
+            if ins.type != "pip" and ins.f0 <= a and b <= ins.f1:
+                top = ins
+        if top is not None and top.type == "full":
+            rects = []
+        elif top is not None and top.speaker is not None:
+            _, band_y, _, hs = top.speaker
+            src_y = next((y for p0, p1, y in top.speaker_pieces if p0 <= a < p1), top.speaker_src_y)
+            moved = []
+            for r in rects:
+                y0, y1 = max(band_y, r[1] - src_y + band_y), min(band_y + hs, r[3] - src_y + band_y)
+                if y1 > y0:
+                    moved.append((r[0], y0, r[2], y1))
+            rects = moved
+        if out and out[-1][1] == a and out[-1][2] == rects:
+            out[-1] = (out[-1][0], b, rects)
+        else:
+            out.append((a, b, rects))
+    plan.person_zones = out
+
+
+def person_bands(plan: Plan, f0: int, f1: int, gap: float = 0.0,
+                 skip: list[tuple[int, int]] | tuple = ()) -> list[tuple[float, float]]:
+    """Vertical bands taken by the cut-out body during [f0, f1) (empty unless tela verde)."""
+    out = []
+    for a, b, rects in plan.person_zones:
+        if b <= f0 or a >= f1:
+            continue
+        lo_f, hi_f = max(a, f0), min(b, f1)
+        if any(h0 <= lo_f and hi_f <= h1 for h0, h1 in skip):
+            continue
+        for r in rects:
+            out.append((r[1] - gap, r[3] + gap))
+    return out
+
+
+def image_bands(plan: Plan, f0: int, f1: int, gap: float = 0.0,
+                skip: list[tuple[int, int]] | tuple = ()) -> list[tuple[float, float]]:
+    """Vertical bands taken by the main area of a whole background picture during [f0, f1) (tela verde only)."""
+    out = []
+    for a, b, r in plan.image_zones:
+        if b <= f0 or a >= f1:
+            continue
+        lo_f, hi_f = max(a, f0), min(b, f1)
+        if any(h0 <= lo_f and hi_f <= h1 for h0, h1 in skip):
+            continue
+        out.append((r[1] - gap, r[3] + gap))
+    return out
+
+
+def caption_room(plan: Plan):
+    """Tela verde: the height auto captions need between a whole background picture and the head, for the frame
+    spans of that picture (0 when the captions are off, manual or silent there)."""
+    cap = _section(plan.data, "captions")
+    if not _enabled(cap):
+        return None
+    try:
+        manual = None if _is_auto(cap.get("center_y")) else float(cap.get("center_y")) * plan.s
+        cues = load_json(plan.edit_dir / str(cap.get("file") or "captions.json")) or {}
+        style = cap.get("style") or (cues.get("style") if isinstance(cues, dict) else None) \
+            or (load_style_catalog().get("defaults") or {}).get("caption_style") or "impacto"
+        above, below = tr.caption_extent(cues, style, (plan.W, plan.H), float(cap.get("font_scale", 1.0) or 1.0),
+                                         plan.fps)
+    except (ValueError, TypeError, OSError, AttributeError):
+        return None                 # build_tracks reports what is wrong with the captions
+    if manual is not None:
+        # a height written by hand keeps its place unless it lands on the face (then it is placed like auto)
+        gap = GAP_FACE * plan.H
+        faces = [(cs["face"]["zone"]["y0"] * plan.H - gap, cs["face"]["zone"]["y1"] * plan.H + gap)
+                 for cs in plan.cam_segs if cs.get("tv_mode") == "pessoa" and (cs.get("face") or {}).get("zone")]
+        if not any(manual - above < b and a < manual + below for a, b in faces):
+            return None
+    spans = []
+    for cue in (cues.get("cues") if isinstance(cues, dict) else cues) or []:
+        try:
+            spans.append((plan.fr(float(cue["start"])), plan.fr(float(cue["end"]))))
+        except (KeyError, TypeError, ValueError):
+            continue
+    need = above + below + GAP_FACE * plan.H
+
+    def room(item_spans: list[tuple[int, int]]) -> float:
+        heard = any(a < f1 and f0 < b for f0, f1 in item_spans for a, b in spans)
+        return need if heard else 0.0
+    return room
+
+
+def place_pips_tela_verde(plan: Plan, inserts: list[Insert]) -> None:
+    """Tela verde: a pip card goes to the top corner away from the person (the one asked, when it is free of the
+    face), and to the other corner when the face would be under it."""
+    cfg = plan.tv["cfg"]
+    W, s = plan.W, plan.s
+    for ins in inserts:
+        if ins.type != "pip" or not ins.card:
+            continue
+        ox, oy, ow, oh = ins.card
+        margin_x = int(round(48 * s))
+        corners = {"top_right": W - margin_x - ow, "top_left": margin_x}
+        asked = (ins.item or {}).get("corner")
+        away = "top_left" if cfg.position == "direita" else "top_right"
+        order = [asked, "top_right" if asked == "top_left" else "top_left"] if asked else \
+            [away, "top_right" if away == "top_left" else "top_left"]
+        faces = []
+        for cs in plan.cam_segs:
+            face = cs.get("face")
+            if cs.get("tv_mode") != "pessoa" or not face or not face.get("zone") or cs["f1"] <= ins.f0 or cs["f0"] >= ins.f1:
+                continue
+            z = face["zone"]
+            faces.append((z["x0"] * W, z["y0"] * plan.H, z["x1"] * W, z["y1"] * plan.H))
+        pad = GAP_FACE * plan.H
+        chosen = None
+        for corner in order:
+            rect = (corners[corner] - pad, oy - pad, corners[corner] + ow + pad, oy + oh + pad)
+            if not any(boxes_hit(rect, f) for f in faces):
+                chosen = corner
+                break
+        if chosen is None:
+            chosen = order[0]
+            plan.warnings.append(f"o cartão do insert {ins.idx + 1} (pip) encosta no rosto nos dois cantos de cima: "
+                                 f"mude o tempo dele ou use a tela verde em outra posição")
+        elif asked and chosen != asked:
+            plan.adjustments.append({"layer": f"insert {ins.idx + 1}", "action": "moved", "start": round(ins.f0 / plan.fps, 3),
+                                     "end": round(ins.f1 / plan.fps, 3), "because": "rosto (tela verde)",
+                                     "corner_asked": asked, "corner": chosen})
+            plan.warnings.append(f"o cartão do insert {ins.idx + 1} (pip) foi para o canto "
+                                 f"{'esquerdo' if chosen == 'top_left' else 'direito'} para não cobrir o rosto")
+        x = corners[chosen]
+        border = ins.content[0] - ox
+        ins.card = (x, oy, ow, oh)
+        ins.content = (x + border, ins.content[1], ins.content[2], ins.content[3])
+
+
+def render_tela_verde(plan: Plan) -> dict:
+    import tela_verde as TV
+
+    tv = plan.tv
+    job = TV.Job(cfg=tv["cfg"], segments=tv["segments"], mattes=tv["mattes"], base=plan.base,
+                 base_pre=_matte_pre(plan), base_fps=plan.base_fps, fps=plan.fps, size=(plan.W, plan.H),
+                 full_size=(plan.full_w, plan.full_h), nf=plan.nf, out_dir=plan.renders / "telaverde",
+                 plates=tv.get("plates") or {})
+    try:
+        return TV.render(job, progress=log)
+    except TV.TelaVerdeError as e:
+        raise ComposeError(str(e), e.code)
+
+
+def _matte_pre(plan: Plan) -> list[str]:
+    import matte as MT
+    return MT.base_pre_filters(plan.base_fps, (plan.base_w, plan.base_h), plan.fps, (plan.full_w, plan.full_h))
+
+
+def tela_verde_layer(plan: Plan, clip: dict) -> dict:
+    import tela_verde as TV
+
+    tv = plan.tv
+    cfg = tv["cfg"]
+    fps = plan.fps
+    fundo = TV.report_backgrounds(cfg, fps, plan.W, plan.H, 1.0 / plan.s, plan.rel)
+    moved = [{"insert": b.insert, "type": b.insert_type, "src": plan.rel(b.src), "kind": b.kind,
+              "start": round(b.f0 / fps, 3), "end": round(b.f1 / fps, 3), "encaixe": b.fit,
+              "encaixe_pedido": b.fit_asked, "ken_burns": b.ken_burns, "escurecer": b.darken, "desfocar": b.blur,
+              "rect": [int(round(v / plan.s)) for v in b.place] if b.place else None,
+              "stage": [int(round(v / plan.s)) for v in b.stage] if b.stage else None}
+             for b in cfg.from_inserts]
+    mset = tv["mset"]
+    return {"type": "tela_verde", "posicao": cfg.position, "altura": cfg.height,
+            "contorno": ({"cor": "#%02X%02X%02X" % tuple(cfg.outline[0]), "largura": cfg.outline[1]}
+                         if cfg.outline else None),
+            "sombra": cfg.shadow, "fundo_original_desfocado": cfg.blurred_original, "sem_rosto": cfg.no_face,
+            "espelhar": cfg.mirror,
+            "corte_dentro": ({k: v for k, v in tv["inner_cut"].items() if k != "aviso"} if tv.get("inner_cut") else None),
+            "fundo": fundo, "inserts_no_fundo": moved,
+            "segments": TV.report_segments(cfg, tv["segments"], fps, plan.W, plan.H, 1.0 / plan.s),
+            "matte": mset.report(plan.rel) if mset else None,
+            "fundo_do_cenario": tv.get("plate_rows") or [],
+            "clip": plan.rel(Path(clip["file"])), "cached": bool(clip.get("cached")),
+            "seconds": {"matte": tv["matte_seconds"], "compose": clip.get("render_seconds", 0.0)}}
+
+
+def _kb_path(ins: Insert, n: int, pw: float, ph: float, cw: int, ch: int):
+    """Per-frame (window_w, window_h, center_x, center_y) in prescaled source pixels."""
+    zoom_in = ins.idx % 2 == 0
+    z0, z1 = (1.0, 1.0 + KB_DRIFT) if zoom_in else (1.0 + KB_DRIFT, 1.0)
+    base_w, base_h = cw * (1.0 + KB_DRIFT), ch * (1.0 + KB_DRIFT)
+    dirs = [(1, -0.5), (-1, 0.5), (0.6, 1), (-0.6, -1)]
+    dx, dy = dirs[ins.idx % 4]
+    frames = []
+    for j in range(n):
+        p = ease_in_out(j / max(1, n - 1))
+        z = z0 + (z1 - z0) * p
+        ww, wh = base_w / z, base_h / z
+        # pan inside whatever room the window leaves (at most 3% of the window)
+        room_x = max(0.0, (pw - base_w) / 2.0) + (base_w - ww) / 2.0
+        room_y = max(0.0, (ph - base_h) / 2.0) + (base_h - wh) / 2.0
+        span_x = min(room_x, 0.03 * ww) * dx
+        span_y = min(room_y, 0.03 * wh) * dy
+        cx = pw / 2.0 + span_x * (2 * p - 1)
+        cy = ph / 2.0 + span_y * (2 * p - 1)
+        cx = min(max(cx, ww / 2.0), pw - ww / 2.0)
+        cy = min(max(cy, wh / 2.0), ph - wh / 2.0)
+        frames.append((ww, wh, cx, cy))
+    return frames
+
+
+def _encoder(out_tmp: Path, w: int, h: int, fps: int, n: int) -> subprocess.Popen:
+    return subprocess.Popen(
+        ["ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
+         "-s", f"{w}x{h}", "-framerate", str(fps), "-i", "-",
+         "-vf", "scale=out_color_matrix=bt709:out_range=tv,format=yuv420p",
+         "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-g", str(fps),
+         "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-color_range", "tv",
+         "-frames:v", str(n), "-f", "mp4", str(out_tmp)],
+        stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+
+
+def render_insert_clip(plan: Plan, ins: Insert) -> Path:
+    cw, ch = ins.content[2], ins.content[3]
+    n = ins.f1 - ins.f0
+    st = ins.src.stat()
+    key = short_hash((RENDER_VERSION, str(ins.src), st.st_size, st.st_mtime_ns, ins.kind, cw, ch, n, plan.fps,
+                      ins.ken_burns, ins.idx % 4))
+    out_dir = plan.renders / "inserts"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / f"ins_{key}.mp4"
+    if out.exists() and out.stat().st_size > 0:
+        return out
+    tmp = out.with_name(".tmp-" + out.name)
+    margin = 1.0 + KB_DRIFT if ins.ken_burns else 1.0
+
+    if ins.kind == "video" and not ins.ken_burns:
+        ffmpeg_cmd(["-v", "error", "-y", "-stream_loop", "-1", "-i", ins.src, "-an",
+                    "-vf", (f"fps={plan.fps},scale={cw}:{ch}:force_original_aspect_ratio=increase:flags=lanczos,"
+                            f"crop={cw}:{ch},setsar=1,scale=out_color_matrix=bt709:out_range=tv,format=yuv420p"),
+                    "-c:v", "libx264", "-preset", "veryfast", "-crf", "12", "-g", str(plan.fps),
+                    "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-color_range", "tv",
+                    "-frames:v", n, "-f", "mp4", tmp], f"preparar o vídeo do insert {ins.idx + 1}")
+        os.replace(tmp, out)
+        return out
+
+    pw_target, ph_target = cw * margin, ch * margin
+    if ins.kind == "image":
+        with Image.open(ins.src) as im:
+            im = ImageOps.exif_transpose(im)
+            if im.mode in ("RGBA", "LA", "P"):
+                rgba = im.convert("RGBA")
+                bg = Image.new("RGB", rgba.size, (18, 18, 18))
+                bg.paste(rgba, mask=rgba.getchannel("A"))
+                src_img = bg
+            else:
+                src_img = im.convert("RGB")
+        sc = max(pw_target / src_img.width, ph_target / src_img.height)
+        pw, ph = max(cw, int(math.ceil(src_img.width * sc))), max(ch, int(math.ceil(src_img.height * sc)))
+        pre = src_img.resize((pw, ph), Image.LANCZOS)
+
+        def frames_iter():
+            while True:
+                yield pre
+    else:
+        pw, ph = int(math.ceil(pw_target)), int(math.ceil(ph_target))
+        dec = subprocess.Popen(
+            ["ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-stream_loop", "-1", "-i", str(ins.src), "-an",
+             "-vf", f"fps={plan.fps},scale={pw}:{ph}:force_original_aspect_ratio=increase:flags=lanczos,crop={pw}:{ph},format=rgb24",
+             "-frames:v", str(n), "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+
+        def frames_iter():
+            size = pw * ph * 3
+            last = None
+            while True:
+                buf = dec.stdout.read(size) if dec.stdout else b""
+                if len(buf) == size:
+                    last = Image.frombuffer("RGB", (pw, ph), buf, "raw", "RGB", 0, 1)
+                if last is None:
+                    raise ComposeError(f"não consegui ler o vídeo do insert {ins.idx + 1}: {ins.src}")
+                yield last
+
+    enc = _encoder(tmp, cw, ch, plan.fps, n)
+    try:
+        path = _kb_path(ins, n, pw, ph, cw, ch) if ins.ken_burns else None
+        it = frames_iter()
+        for j in range(n):
+            frame = next(it)
+            if path is None:
+                x0, y0 = (frame.width - cw) // 2, (frame.height - ch) // 2
+                img = frame.crop((x0, y0, x0 + cw, y0 + ch))
+            else:
+                ww, wh, cx, cy = path[j]
+                qx, qy = ww / cw, wh / ch
+                img = frame.transform((cw, ch), Image.AFFINE,
+                                      (qx, 0.0, cx - ww / 2.0, 0.0, qy, cy - wh / 2.0),
+                                      resample=Image.BICUBIC)
+            enc.stdin.write(img.tobytes())
+        enc.stdin.close()
+        err = enc.stderr.read().decode("utf-8", "replace") if enc.stderr else ""
+        if enc.wait() != 0:
+            raise ComposeError(f"falha ao codificar o insert {ins.idx + 1}: {err[-500:]}")
+    except BrokenPipeError:
+        err = enc.stderr.read().decode("utf-8", "replace") if enc.stderr else ""
+        raise ComposeError(f"falha ao codificar o insert {ins.idx + 1}: {err[-500:]}")
+    finally:
+        if ins.kind == "video":
+            try:
+                dec.kill()  # type: ignore[possibly-undefined]
+            except Exception:
+                pass
+    os.replace(tmp, out)
+    return out
+
+
+# ============================================================== motion (animated texts and numbers, SPEC Contract 12)
+
+MOTION_KEYS = ("template", "start", "end", "duration", "params", "region", "sfx", "enabled", "id", "note")
+MOTION_REGIONS = {"auto": None, "top": "topo", "middle": "centro", "center": "centro", "bottom": "baixo",
+                  "topo": "topo", "centro": "centro", "baixo": "baixo", "faixa_topo": "faixa_topo", "tela": "tela"}
+MOTION_EXAMPLE = '{"template": "checklist", "start": 12.3, "end": 15.0, "params": {"items": ["Acesso na hora"]}}'
+MOTION_CAPTION_SHIFT = 150.0   # design px: an auto item steps aside from the captions only when that moves it this little
+MOTION_GAP = 23.0              # design px between an auto item and a face or a text above it in priority
+
+
+def _of_names(names: list[str]) -> str:
+    """['chamada', 'gancho', 'animação 2'] -> 'da chamada, do gancho e da animação 2' (each name once)."""
+    seen = list(dict.fromkeys(names))
+    parts = [("do " if n == "gancho" else "da ") + n for n in seen]
+    return parts[0] if len(parts) == 1 else ", ".join(parts[:-1]) + " e " + parts[-1]
+
+
+@dataclass
+class Motion:
+    idx: int                   # 1-based position in the list (as the report and the warnings call it)
+    template: str
+    item: object               # motion.render.MotionItem
+    f0: int
+    f1: int
+    auto: bool                 # region "auto": the template's place, slid off faces and texts
+    sfx: bool
+    region_asked: object
+    clip: dict | None = None
+    ink: tuple | None = None   # render px on the output canvas (what the clip really draws)
+    shown: list = field(default_factory=list)
+    cues: list = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return f"animação {self.idx} ({self.template})"
+
+
+def _motion_items(data: dict) -> list | None:
+    """The list under "motion": a list, or {"enabled": bool, "items": [...]}. None when it is off or absent."""
+    raw = data.get("motion")
+    if raw is None:
+        return None
+    if isinstance(raw, dict):
+        if raw.get("enabled", True) is False:
+            return None
+        extra = sorted(set(raw) - {"enabled", "items", "tema", "quantidade"})
+        if extra:
+            raise ComposeError(f"motion tem campos desconhecidos: {', '.join(extra)} (use \"items\", \"enabled\", "
+                               f"\"tema\" e \"quantidade\")", 2)
+        raw = raw.get("items", [])
+    if not isinstance(raw, list):
+        raise ComposeError(f"motion precisa ser uma lista de animações (ex: \"motion\": [{MOTION_EXAMPLE}])", 2)
+    return raw
+
+
+def _motion_region(value, where: str):
+    """(region spec for the engine or None for the template's own place, auto?)"""
+    if value is None:
+        return None, True
+    if isinstance(value, str):
+        key = value.strip().lower()
+        if key not in MOTION_REGIONS:
+            import difflib
+            near = difflib.get_close_matches(key, list(MOTION_REGIONS), n=1, cutoff=0.6)
+            hint = f" Você quis dizer \"{near[0]}\"?" if near else ""
+            raise ComposeError(f"{where}.region \"{value}\" não existe.{hint} Use \"auto\", \"top\", \"middle\", \"bottom\" "
+                               f"ou {{\"x\", \"y\", \"w\", \"h\"}} em pixels da tela 1080x1920", 2)
+        spec = MOTION_REGIONS[key]
+        return spec, spec is None
+    box = None
+    if isinstance(value, dict) and set(value) == {"x", "y", "w", "h"}:
+        box = [value["x"], value["y"], value["w"], value["h"]]
+    elif isinstance(value, list) and len(value) == 4:
+        box = value
+    nums = [_plain_number(v) for v in box] if box is not None else None
+    if not nums or any(v is None for v in nums) or nums[2] < 20 or nums[3] < 20:
+        raise ComposeError(f"{where}.region precisa ser \"auto\", \"top\", \"middle\", \"bottom\" ou {{\"x\": 140, \"y\": 1000, "
+                           f"\"w\": 800, \"h\": 520}} (pixels da tela 1080x1920, largura e altura de pelo menos 20) "
+                           f"(veio {_as_json(value)})", 2)
+    return nums, False
+
+
+def _motion_theme(data: dict) -> str | None:
+    """The look chosen for all the animations ("motion": {"tema": "papelaria"}), or None."""
+    raw = data.get("motion")
+    tema = raw.get("tema") if isinstance(raw, dict) else None
+    if tema is None:
+        return None
+    from motion import engine as ME
+    if tema not in ME.THEME_NAMES:
+        raise ComposeError(f"motion.tema \"{tema}\" não existe (use {', '.join(ME.THEME_NAMES)})", 2)
+    return str(tema)
+
+
+def plan_motion(plan: Plan) -> list[Motion]:
+    """edit_data "motion": check every item and decide its frames before anything renders (exit 2 on a mistake)."""
+    raw = _motion_items(plan.data)
+    if not raw:
+        return []
+    from motion import engine as ME
+    from motion import registry as MRg
+    from motion import render as MR
+
+    out: list[Motion] = []
+    for i, entry in enumerate(raw):
+        where = f"motion[{i}]"
+        n = i + 1
+        if not isinstance(entry, dict):
+            raise ComposeError(f"{where} precisa ser um objeto (ex: {MOTION_EXAMPLE})", 2)
+        if entry.get("enabled", True) is False:
+            continue
+        unknown = [k for k in entry if k not in MOTION_KEYS]
+        if unknown:
+            import difflib
+            near = difflib.get_close_matches(str(unknown[0]), list(MOTION_KEYS), n=1, cutoff=0.6)
+            hint = f" Você quis dizer \"{near[0]}\"?" if near else ""
+            raise ComposeError(f"{where}.{unknown[0]} não existe.{hint} Campos: {', '.join(MOTION_KEYS[:7])}", 2)
+        tid = entry.get("template")
+        if not isinstance(tid, str) or not tid.strip():
+            names = ", ".join(sorted(MRg.templates()))
+            raise ComposeError(f"{where} precisa de \"template\": o modelo da animação ({names})", 2)
+        tid = tid.strip()
+        start = _plain_number(entry.get("start"))
+        if start is None or start < 0:
+            if "start" not in entry:
+                raise ComposeError(f"{where} precisa de \"start\": o segundo do corte em que a animação começa "
+                                   f"(ex: {MOTION_EXAMPLE})", 2)
+            raise ComposeError(f"{where}.start precisa ser um número de segundos, 0 ou mais "
+                               f"(veio {_as_json(entry.get('start'))})", 2)
+        end = dur = None
+        if entry.get("end") is not None and entry.get("duration") is not None:
+            raise ComposeError(f"{where}: use \"end\" ou \"duration\", não os dois", 2)
+        if entry.get("end") is not None:
+            end = _plain_number(entry.get("end"))
+            if end is None or end <= start:
+                raise ComposeError(f"{where}.end precisa ser um número de segundos maior que o start ({start:g}) "
+                                   f"(veio {_as_json(entry.get('end'))})", 2)
+        if entry.get("duration") is not None:
+            dur = _plain_number(entry.get("duration"))
+            if dur is None or dur <= 0:
+                raise ComposeError(f"{where}.duration precisa ser um número de segundos maior que 0 "
+                                   f"(veio {_as_json(entry.get('duration'))})", 2)
+        params = entry.get("params")
+        if params is None:
+            params = {}
+        tema = _motion_theme(plan.data)
+        if tema and isinstance(params, dict) and "tema" not in params:
+            params = {**params, "tema": tema}      # "motion": {"tema": ...} is the look of every item
+        if not isinstance(params, dict):
+            raise ComposeError(f"{where}.params precisa ser um objeto com os parâmetros do modelo "
+                               f"(ex: {{\"items\": [\"Acesso na hora\"]}}; veja motion_render.py --describe {tid})", 2)
+        spec, auto = _motion_region(entry.get("region", "auto"), where)
+        sfx_on = entry.get("sfx", True)
+        if not isinstance(sfx_on, bool):
+            raise ComposeError(f"{where}.sfx precisa ser true ou false (veio {_as_json(sfx_on)})", 2)
+        try:
+            tpl = MRg.get(tid)
+            f0 = plan.fr(start)
+            if f0 >= plan.nf:
+                plan.warnings.append(f"animação {n} ('{tid}' em {fmt_time(start)}) começa depois do fim do vídeo "
+                                     f"({fmt_time(plan.duration)}) e foi ignorada")
+                continue
+            if end is not None:
+                f1 = plan.fr(end)
+                if end * plan.fps > plan.nf + 0.5:
+                    plan.warnings.append(f"animação {n} ('{tid}') passava do fim do vídeo e foi cortada em "
+                                         f"{fmt_time(plan.duration)}")
+            else:
+                secs = dur if dur is not None else tpl.suggested_duration(MRg.resolve_params(tpl, params))
+                f1 = f0 + ME.frame_of(secs, plan.fps)
+                if f1 > plan.nf:
+                    plan.warnings.append(f"animação {n} ('{tid}') passava do fim do vídeo e foi cortada em "
+                                         f"{fmt_time(plan.duration)}: comece antes ou use uma duration menor")
+            f1 = min(f1, plan.nf)
+            if f1 - f0 < 2:
+                plan.warnings.append(f"animação {n} ('{tid}' em {fmt_time(start)}) dura menos de 2 quadros e foi ignorada")
+                continue
+            item = MR.plan_item(tid, params, fps=plan.fps, canvas=(plan.W, plan.H), region=spec, frames=f1 - f0,
+                                accent=plan.accent)
+            MR.sfx_cues(item)
+            MR.render_frame(item, 0)     # a mistake only the drawing sees (a target off the screen) stops here too
+        except ME.MotionError as e:
+            raise ComposeError(f"{where}: {e}", 2 if e.code == 2 else 1)
+        for w in item.warnings:
+            plan.warnings.append(f"animação {n}: {w}")
+        item.warnings.clear()
+        settle = tpl.settle(item.params, plan.fps)
+        if settle is not None:
+            # an end earlier than the drawing: the last items would never show (or never get their check / cross)
+            frames = f1 - f0
+            exit_frames = min(MR.EXIT_FRAMES, frames // 3) if tpl.exit == "fade" else 0
+            need = settle + exit_frames / plan.fps
+            if need * plan.fps > frames + 1:
+                plan.warnings.append(f"animação {n} ('{tid}' em {fmt_time(start)}) acaba antes de terminar o desenho: "
+                                     f"ela precisa de {ME.format_number(need, 1)} s e ficou com "
+                                     f"{ME.format_number(frames / plan.fps, 1)} s. Aumente o end ou tire o end para usar "
+                                     f"a duração sugerida ({ME.format_number(tpl.suggested_duration(item.params), 1)} s)")
+        out.append(Motion(idx=n, template=tid, item=item, f0=f0, f1=f1, auto=auto, sfx=sfx_on,
+                          region_asked=entry.get("region", "auto")))
+    for k, a in enumerate(out):
+        for b in out[k + 1:]:
+            if b.f0 < a.f1 and a.f0 < b.f1:
+                plan.warnings.append(f"as animações {a.idx} e {b.idx} aparecem juntas ({fmt_time(max(a.f0, b.f0) / plan.fps)}): "
+                                     f"deixe uma animação por vez na tela")
+    return out
+
+
+def place_motion(plan: Plan, motions: list[Motion], highs: list[tuple[str, int, int, tuple]],
+                 caption_bands) -> None:
+    """Auto items slide off the faces, the CTA, the hook and the animations before them (and off the captions
+    when that costs little); the others stay where they were asked. Then every clip is rendered."""
+    if not motions:
+        return
+    from motion import render as MR
+
+    k = min(plan.W, plan.H) / 1080.0
+    fps = plan.fps
+    for m in motions:
+        item = m.item
+        if not (m.auto and item.template.movable):
+            continue
+        faces: list[tuple[str, tuple[float, float]]] = []          # (why, band in design px)
+        faces += [("rosto", (a / k, b / k)) for a, b in face_bands(plan, m.f0, m.f1)]
+        texts = []
+        for why, h0, h1, band in highs:
+            if h0 < m.f1 and m.f0 < h1:
+                texts.append((why, (band[0] / k, band[1] / k)))
+        others = []
+        for other in motions:
+            if other.idx >= m.idx or other.item.ink is None or not (other.f0 < m.f1 and m.f0 < other.f1):
+                continue
+            ob = other.item.box
+            others.append((f"animação {other.idx}", (ob.y + other.item.ink[1], ob.y + other.item.ink[3])))
+        # no place free of everything: the face still wins. First give up the other animations (they only share a
+        # moment), then the CTA and the hook (they win anyway: the animation is hidden where it touches them).
+        # Tela verde: off the whole cut-out body first, when there is room
+        levels = [faces + texts + others, faces + texts, faces]
+        gave = [[], others, texts + others]
+        body = [("pessoa", (a / k, b / k)) for a, b in person_bands(plan, m.f0, m.f1)]
+        if body:
+            levels = [faces + body + texts + others] + levels
+            gave = [[]] + gave
+        dy, named, relaxed = None, levels[0], 0
+        for lvl, cand in enumerate(levels):
+            if lvl and len(cand) == len(levels[lvl - 1]):
+                continue
+            dy = MR.free_offset(item, [band for _, band in cand], MOTION_GAP)
+            if dy is not None:
+                named, relaxed = cand, lvl
+                break
+        bands = [band for _, band in named]
+        caps = [(a / k, b / k) for a, b in caption_bands(m.f0, m.f1)]
+        if caps:
+            around = MR.free_offset(item, bands + caps, MOTION_GAP)
+            if around is not None and (dy is None or abs(around - dy) <= MOTION_CAPTION_SHIFT):
+                dy = around
+                named += [("legenda", band) for band in caps]
+        if dy is None:
+            plan.warnings.append(f"a {m.name} não achou lugar livre do rosto e dos textos entre "
+                                 f"{fmt_time(m.f0 / fps)} e {fmt_time(m.f1 / fps)}: ficou no lugar padrão. "
+                                 f"Use outra region ou mude o tempo")
+            continue
+        given_up = [name for name, _ in gave[relaxed]]
+        if given_up:
+            plan.warnings.append(f"a {m.name} não achou lugar livre de tudo entre {fmt_time(m.f0 / fps)} e "
+                                 f"{fmt_time(m.f1 / fps)}: ficou fora do rosto, mas perto {_of_names(given_up)}. "
+                                 f"Mude o tempo para ela não dividir a tela")
+        if abs(dy) >= 0.5:
+            ink = item.ink
+            before = (item.box.y + (ink[1] + ink[3]) / 2.0) if ink else item.box.y
+            top, bottom = (item.box.y + ink[1], item.box.y + ink[3]) if ink else (item.box.y, item.box.y + item.box.h)
+            why = []
+            for name, (b0, b1) in named:        # what the item touched where it was asked
+                if b0 - MOTION_GAP < bottom and top < b1 + MOTION_GAP and name not in why:
+                    why.append(name)
+            MR.move_item(item, dy)
+            ko = min(plan.full_w, plan.full_h) / 1080.0          # design px -> px of the full output
+            plan.adjustments.append({"layer": f"motion {m.idx}", "action": "moved", "start": round(m.f0 / fps, 3),
+                                     "end": round(m.f1 / fps, 3), "because": " e ".join(why) or "rosto ou texto",
+                                     "from_center_y": int(round(before * ko)),
+                                     "center_y": int(round((before + dy) * ko))})
+
+    out_dir = plan.renders / "motion"
+    workers = max(1, min(4, len(motions), os.cpu_count() or 2))
+
+    def work(m: Motion) -> dict:
+        return MR.render_clip(m.item, out_dir)
+
+    try:
+        with ThreadPoolExecutor(max_workers=workers) as ex:
+            clips = list(ex.map(work, motions))
+    except Exception as e:  # noqa: BLE001
+        from motion.engine import MotionError
+        if isinstance(e, MotionError):
+            raise ComposeError(f"falha ao desenhar uma animação: {e}", 2 if e.code == 2 else 1)
+        raise
+    for m, clip in zip(motions, clips):
+        m.clip = clip
+        m.ink = tuple(clip["ink"]) if clip.get("ink") else None
+        if m.ink is None:
+            plan.warnings.append(f"a {m.name} não desenhou nada e foi ignorada")
+
+
+# ============================================================== overlay tracks (PNG states)
+
+class Track:
+    """Frame-grid layer states composited in PIL, played through an ffconcat playlist."""
+
+    def __init__(self, plan: Plan, name: str):
+        self.plan = plan
+        self.name = name
+        self.images: dict[str, Image.Image] = {}
+        self.bboxes: dict[str, tuple | None] = {}
+        self.content: dict[str, str] = {}
+        self.states: list[tuple[int, int, int, tuple]] = []   # f0, f1, z, recipe
+        self.z = 0
+
+    def add_image(self, key: str, img: Image.Image) -> None:
+        self.images[key] = img
+        self.bboxes[key] = img.getchannel("A").getbbox()
+        # content hash: cached PNG names must change whenever the art changes
+        self.content[key] = hashlib.sha1(img.tobytes()).hexdigest()[:16]
+
+    def add(self, f0: int, f1: int, recipe: tuple, z: int | None = None) -> None:
+        f0, f1 = max(0, f0), min(self.plan.nf, f1)
+        if f1 > f0:
+            self.states.append((f0, f1, self.z if z is None else z, recipe))
+
+    def next_z(self) -> int:
+        self.z += 1
+        return self.z
+
+    def _transformed(self, key: str, scale: float, alpha: float, dy: float) -> Image.Image | None:
+        img = self.images[key]
+        bbox = self.bboxes[key]
+        if bbox is None or alpha <= 0.001:
+            return None
+        if abs(scale - 1.0) < 1e-4 and alpha >= 0.999 and abs(dy) < 0.5:
+            return img
+        W, H = img.size
+        x0, y0, x1, y1 = bbox
+        part = img.crop(bbox)
+        if abs(scale - 1.0) >= 1e-4:
+            nw, nh = max(1, int(round(part.width * scale))), max(1, int(round(part.height * scale)))
+            part = part.resize((nw, nh), Image.BICUBIC)
+        if alpha < 0.999:
+            part.putalpha(part.getchannel("A").point(lambda v, a=alpha: int(v * a)))
+        cx, cy = (x0 + x1) / 2.0, (y0 + y1) / 2.0 + dy
+        canvas = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+        tr._alpha_paste(canvas, part, int(round(cx - part.width / 2.0)), int(round(cy - part.height / 2.0)))
+        return canvas
+
+    def build(self, out_dir: Path) -> tuple[Path | None, list[dict], list[tuple[int, int]]]:
+        plan = self.plan
+        if not self.states:
+            return None, [], []
+        cuts = sorted({f for a, b, _, _ in self.states for f in (a, b)})
+        intervals = []
+        for u, v in zip(cuts, cuts[1:]):
+            active = sorted((z, r) for a, b, z, r in self.states if a <= u and v <= b)
+            if not active:
+                continue
+            key = tuple(r for _, r in active)
+            if intervals and intervals[-1][1] == u and intervals[-1][2] == key:
+                intervals[-1][1] = v
+            else:
+                intervals.append([u, v, key])
+        out_dir.mkdir(parents=True, exist_ok=True)
+        jobs = {}
+        entries = []
+        for u, v, key in intervals:
+            ids = tuple(self.content.get(r[1], "") if r[0] == "img" else "" for r in key)
+            name = f"{self.name}_{short_hash((RENDER_VERSION, plan.W, plan.H, key, ids))}.png"
+            jobs.setdefault(name, key)
+            entries.append({"file": str(out_dir / name), "start": u / plan.fps, "end": v / plan.fps})
+
+        def work(item):
+            name, key = item
+            path = out_dir / name
+            if path.exists():
+                return
+            canvas = Image.new("RGBA", (plan.W, plan.H), (0, 0, 0, 0))
+            for recipe in key:
+                if recipe[0] == "flash":
+                    canvas.alpha_composite(Image.new("RGBA", (plan.W, plan.H), (255, 255, 255, int(round(255 * recipe[1])))))
+                    continue
+                _, img_key, scale, alpha, dy = recipe
+                layer = self._transformed(img_key, scale, alpha, dy)
+                if layer is not None:
+                    canvas.alpha_composite(layer)
+            tmp = path.with_name(".tmp-" + path.name)
+            canvas.save(tmp, "PNG", compress_level=1)
+            os.replace(tmp, path)
+
+        with ThreadPoolExecutor(max_workers=min(8, os.cpu_count() or 4)) as ex:
+            list(ex.map(work, jobs.items()))
+        ff = out_dir / f"{self.name}.ffconcat"
+        tr.write_ffconcat(entries, str(ff), total_duration=plan.duration,
+                          blank_png=str(out_dir / f"blank_{plan.W}x{plan.H}.png"), fps=plan.fps)
+        windows = merge_windows([(plan.fr(e["start"]), plan.fr(e["end"])) for e in entries])
+        return ff, entries, windows
+
+
+def merge_windows(spans: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    out: list[list[int]] = []
+    for a, b in sorted(spans):
+        if out and a <= out[-1][1]:
+            out[-1][1] = max(out[-1][1], b)
+        else:
+            out.append([a, b])
+    return [(a, b) for a, b in out]
+
+
+def enable_expr(windows: list[tuple[int, int]], nf: int) -> str | None:
+    if not windows:
+        return None
+    if len(windows) == 1 and windows[0][0] <= 0 and windows[0][1] >= nf:
+        return None
+    if len(windows) > 120:
+        return None
+    return "+".join(f"between(n,{a},{b - 1})" for a, b in windows)
+
+
+def seam_shadow(plan: Plan, ins: Insert) -> Image.Image:
+    """Soft shadow the picture band casts on the speaker band, so the split reads as layers."""
+    W, H, s = plan.W, plan.H, plan.s
+    depth = max(4, int(round(34 * s)))
+    canvas = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+    ramp = Image.new("L", (1, depth))
+    for y in range(depth):
+        ramp.putpixel((0, y), int(round(255 * 0.42 * (1.0 - y / depth) ** 2)))
+    ramp = ramp.resize((W, depth))
+    band = Image.new("RGBA", (W, depth), (0, 0, 0, 255))
+    seam = int(ins.seam_y or 0)
+    if ins.type == "split_top":        # speaker below the seam
+        band.putalpha(ramp)
+        canvas.alpha_composite(band, (0, min(H - depth, seam)))
+    else:                              # speaker above the seam
+        band.putalpha(ramp.transpose(Image.FLIP_TOP_BOTTOM))
+        canvas.alpha_composite(band, (0, max(0, seam - depth)))
+    return canvas
+
+
+def pip_decoration(plan: Plan, ins: Insert) -> Image.Image:
+    W, H, s = plan.W, plan.H, plan.s
+    ox, oy, ow, oh = ins.card  # type: ignore[misc]
+    border = ins.content[0] - ox
+    radius = border * 2.8
+    ss = 3
+    canvas = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+    # soft shadow below the card (never inside it: the card content sits under this layer)
+    pad = int(round(60 * s))
+    sw, sh = ow + 2 * pad, oh + 2 * pad
+    mask = Image.new("L", (sw, sh), 0)
+    off = int(round(12 * s))
+    ImageDraw.Draw(mask).rounded_rectangle((pad, pad + off, pad + ow, pad + oh + off), radius=radius, fill=int(255 * 0.55))
+    mask = mask.filter(ImageFilter.GaussianBlur(20 * s))
+    card_mask = Image.new("L", (sw * ss, sh * ss), 0)
+    ImageDraw.Draw(card_mask).rounded_rectangle((pad * ss, pad * ss, (pad + ow) * ss - 1, (pad + oh) * ss - 1),
+                                                radius=radius * ss, fill=255)
+    card_mask = card_mask.resize((sw, sh), Image.LANCZOS)
+    mask = Image.composite(Image.new("L", (sw, sh), 0), mask, card_mask)
+    shadow = Image.new("RGBA", (sw, sh), (0, 0, 0, 255))
+    shadow.putalpha(mask)
+    tr._alpha_paste(canvas, shadow, ox - pad, oy - pad)
+    # white ring: outer rounded rect minus inner rounded rect (covers the content corners)
+    ring = Image.new("L", (ow * ss, oh * ss), 0)
+    d = ImageDraw.Draw(ring)
+    d.rounded_rectangle((0, 0, ow * ss - 1, oh * ss - 1), radius=radius * ss, fill=255)
+    d.rounded_rectangle((border * ss, border * ss, (ow - border) * ss - 1, (oh - border) * ss - 1),
+                        radius=max(1.0, (radius - border)) * ss, fill=0)
+    ring = ring.resize((ow, oh), Image.LANCZOS)
+    white = Image.new("RGBA", (ow, oh), (255, 255, 255, 255))
+    white.putalpha(ring)
+    tr._alpha_paste(canvas, white, ox, oy)
+    return canvas
+
+
+HOOK_IN = [(0.80, 0.55), (0.95, 0.92), (1.045, 1.0), (1.015, 1.0)]   # (scale, alpha) per frame
+HOOK_OUT = [0.66, 0.33]
+HOOK_MAX_SCALE = 1.05
+CTA_IN = [(0.90, 0.3, 60), (0.94, 0.6, 34), (0.98, 0.85, 14), (1.015, 1.0, 4), (1.02, 1.0, 0), (1.005, 1.0, 0)]
+CTA_MAX_SCALE = 1.03           # entrance and pulse
+CTA_SLIDE = 14                 # px (1080 wide) the CTA still sits lower on its first solid entrance frame
+SFX_CALIBRATION = make_sfx.SFX_CALIBRATION   # 1.4: gain at sfx.volume 1.0 (levels per effect in assets/sfx/sfx.json)
+AAC_TP_HEADROOM = 1.0          # AAC encoding adds inter-sample peaks: normalize a bit under the target
+FLASH = [(-1, 0.35), (0, 0.9), (1, 0.6), (2, 0.32), (3, 0.12)]
+
+# text placement (fractions of the canvas height)
+GAP_FACE = 0.012               # room between a text and a face
+GAP_TEXT = 0.005               # room between two texts
+SOFT_SHIFT = 60 / 1920         # captions may move this much so the disclaimer keeps its usual place
+FACE_COVER_WARN = 0.05         # share of the face (brows to lower lip) a text may cover before a warning
+PRIORITY = ("cta", "hook", "motion", "captions", "disclaimer")   # motion = the animations of edit_data "motion"
+TEXT_LAYERS = ("cta", "hook", "captions", "disclaimer")
+LABELS = {"cta": "a chamada", "hook": "o gancho", "captions": "a legenda", "disclaimer": "o aviso",
+          "motion": "a animação"}
+OF_LABELS = {"cta": "da chamada", "hook": "do gancho", "captions": "da legenda", "disclaimer": "do aviso",
+             "motion": "da animação"}
+MIN_PIECE = {"hook": 0.3, "motion": 0.5, "captions": 0.13, "disclaimer": 1.0}   # s: shorter leftovers of a hidden layer are hidden too
+DISCLAIMER_HIDDEN_WARN = 0.2   # share of its time the disclaimer may lose to other texts before a warning
+CENTER_KEYS = {"cta": "cta.center_y", "hook": "hook.center_y", "captions": "captions.center_y",
+               "disclaimer": "disclaimer.center_y"}
+
+
+def clamp_cue_words(cues):
+    """Copy of the cues with word times kept inside their cue (a cue clamped to a cut must not
+    start its first word a frame before that cut)."""
+    if not isinstance(cues, dict):
+        return cues
+    out = dict(cues)
+    fixed = []
+    for cue in cues.get("cues") or []:
+        try:
+            c0, c1 = float(cue["start"]), float(cue["end"])
+        except (KeyError, TypeError, ValueError):
+            fixed.append(cue)
+            continue
+        c = dict(cue)
+        words = []
+        for w in cue.get("words") or []:
+            try:
+                ws, we = float(w["start"]), float(w["end"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            ws = min(max(ws, c0), c1)
+            words.append(dict(w, start=ws, end=min(max(we, ws), c1)))
+        c["words"] = words
+        fixed.append(c)
+    out["cues"] = fixed
+    return out
+
+
+def check_captions_cut(plan: Plan, cues, cap_file: Path) -> None:
+    """Refuse captions made for another cut: every caption after a changed cut would be out of sync."""
+    if not isinstance(cues, dict):
+        return
+    name = plan.rel(cap_file)
+    hint = "Rode captions.py de novo para este corte."
+    tl = plan.timeline
+    if tl:
+        key, current = cues.get("timeline_key"), captions_mod.timeline_key(tl)
+        if key and current and key != current:
+            raise ComposeError(f"{name} é de outro corte: o cut_timeline.json mudou depois das legendas. {hint}", 2)
+        bounds = cues.get("cut_boundaries")
+        if isinstance(bounds, list):
+            starts = []
+            for seg in tl.get("segments") or []:
+                try:
+                    starts.append(float(seg["out_start"]))
+                except (KeyError, TypeError, ValueError):
+                    continue
+            want = sorted(starts)[1:]
+            try:
+                got = sorted(float(b) for b in bounds)
+            except (TypeError, ValueError):
+                got = []
+            if len(want) != len(got) or any(abs(a - b) > 0.02 for a, b in zip(want, got)):
+                show = lambda xs: ", ".join(f"{x:.2f}" for x in xs[:5]) + (" ..." if len(xs) > 5 else "")  # noqa: E731
+                raise ComposeError(f"{name} é de outro corte: as legendas têm cortes em {show(got) or 'nenhum'} s e o corte "
+                                   f"atual em {show(want) or 'nenhum'} s. {hint}", 2)
+    ends = []
+    for cue in cues.get("cues") or []:
+        try:
+            ends.append(float(cue["end"]))
+        except (KeyError, TypeError, ValueError):
+            continue
+    if ends and max(ends) > plan.duration + 0.5:
+        raise ComposeError(f"{name} é de outro corte: a última legenda termina em {fmt_time(max(ends))} e o vídeo tem "
+                           f"{fmt_time(plan.duration)}. {hint}", 2)
+
+
+def _center_value(sec: dict, key: str, what: str) -> float | None:
+    v = sec.get(key)
+    if _is_auto(v):
+        return None
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        raise ComposeError(f"{what} precisa ser um número (pixels na tela de saída) ou \"auto\"", 2)
+
+
+def grow_box(bb, scale: float = 1.0, extra_below: float = 0.0):
+    if not bb:
+        return None
+    cx, cy = (bb[0] + bb[2]) / 2.0, (bb[1] + bb[3]) / 2.0
+    hw, hh = (bb[2] - bb[0]) / 2.0 * scale, (bb[3] - bb[1]) / 2.0 * scale
+    return (cx - hw, cy - hh, cx + hw, cy + hh + extra_below)
+
+
+def boxes_hit(a, b) -> bool:
+    return bool(a) and bool(b) and a[0] < b[2] and b[0] < a[2] and a[1] < b[3] and b[1] < a[3]
+
+
+def cover_share(box, zone) -> float:
+    if not box or not zone:
+        return 0.0
+    w = min(box[2], zone[2]) - max(box[0], zone[0])
+    h = min(box[3], zone[3]) - max(box[1], zone[1])
+    if w <= 0 or h <= 0:
+        return 0.0
+    return w * h / max(1e-6, (zone[2] - zone[0]) * (zone[3] - zone[1]))
+
+
+def subtract_windows(spans: list[tuple], windows: list[tuple[int, int]]) -> list[tuple]:
+    """(f0, f1, *payload) spans minus frame windows."""
+    out = []
+    for f0, f1, *rest in spans:
+        pieces = [(f0, f1)]
+        for a, b in windows:
+            nxt = []
+            for p0, p1 in pieces:
+                if b <= p0 or a >= p1:
+                    nxt.append((p0, p1))
+                    continue
+                if p0 < a:
+                    nxt.append((p0, a))
+                if b < p1:
+                    nxt.append((b, p1))
+            pieces = nxt
+        out += [(p0, p1, *rest) for p0, p1 in pieces if p1 > p0]
+    return out
+
+
+def compute_face_zones(plan: Plan, inserts: list[Insert]) -> None:
+    """Face zones as drawn in the output (after the camera and the inserts), per frame interval."""
+    W, H = plan.W, plan.H
+    pieces = []
+    for cs in plan.cam_segs:
+        zones, cores = [], []
+        face = cs.get("face")
+        if face and face.get("zone"):
+            for key, dst in (("zone", zones), ("core", cores)):
+                if not face.get(key):
+                    continue
+                rects = [face_layout.zoom_rect(face[key], z, cs["focus_y"]) for z in {cs["zoom"], cs["zoom_max"]}]
+                dst.append((min(r["x0"] for r in rects) * W, min(r["y0"] for r in rects) * H,
+                            max(r["x1"] for r in rects) * W, max(r["y1"] for r in rects) * H))
+        pieces.append((cs["f0"], cs["f1"], zones, cores))
+    cuts = sorted({0, plan.nf} | {p[0] for p in pieces} | {p[1] for p in pieces}
+                  | {min(plan.nf, i.f0) for i in inserts} | {min(plan.nf, i.f1) for i in inserts})
+    out: list[tuple] = []
+    for a, b in zip(cuts, cuts[1:]):
+        if b <= a:
+            continue
+        base = next((p for p in pieces if p[0] <= a < p[1]), None)
+        zones, cores = (base[2], base[3]) if base else ([], [])
+        top = None
+        for ins in inserts:                      # list order: the last one covering is drawn on top
+            if ins.type != "pip" and ins.f0 <= a and b <= ins.f1:
+                top = ins
+        if top is not None and top.type == "full":
+            zones, cores = [], []
+        elif top is not None and top.speaker is not None:
+            _, band_y, _, hs = top.speaker
+            src_y = next((y for p0, p1, y in top.speaker_pieces if p0 <= a < p1), top.speaker_src_y)
+
+            def moved(r, src_y=src_y, band_y=band_y, hs=hs):
+                y0 = max(band_y, r[1] - src_y + band_y)
+                y1 = min(band_y + hs, r[3] - src_y + band_y)
+                return (r[0], y0, r[2], y1) if y1 > y0 else None
+
+            zones = [m for m in map(moved, zones) if m]
+            cores = [m for m in map(moved, cores) if m]
+        if out and out[-1][1] == a and out[-1][2] == zones and out[-1][3] == cores:
+            out[-1] = (out[-1][0], b, zones, cores)
+        else:
+            out.append((a, b, zones, cores))
+    plan.zones = out
+    pad = 12 * plan.s
+    plan.obstacles = [(i.f0, i.f1, (i.card[0] - pad, i.card[1] - pad, i.card[0] + i.card[2] + pad, i.card[1] + i.card[3] + pad))
+                      for i in inserts if i.type == "pip" and i.card]
+    plan.obstacles += tela_obstacles(plan)
+
+
+def tela_obstacles(plan: Plan) -> list[tuple[int, int, tuple[float, float, float, float]]]:
+    """Texto/desenho que já está no vídeo (edit/texto_na_tela.json) vira obstáculo: os textos desviam dele."""
+    doc = load_json(plan.edit_dir / "texto_na_tela.json")
+    if not isinstance(doc, dict) or not doc.get("amostras"):
+        return []
+    passo = 1.0 / float(doc.get("fps") or 2.0)
+    pad = 10 * plan.s
+    out: list[tuple[int, int, tuple[float, float, float, float]]] = []
+    for am in doc["amostras"]:
+        itens = am.get("itens") or []
+        if not itens:
+            continue
+        f0 = int(round(float(am["t"]) * plan.fps))
+        f1 = int(round((float(am["t"]) + passo) * plan.fps))
+        for it in itens:
+            centro = float(it.get("centro_y", 0.5)) * plan.H
+            meia = max(6.0, float(it.get("altura", 0.02)) * plan.H / 2)
+            cx = float(it.get("centro_x", 0.5)) * plan.W
+            meia_x = max(20.0, float(it.get("largura", 0.4)) * plan.W / 2)
+            out.append((f0, f1, (cx - meia_x - pad, centro - meia - pad, cx + meia_x + pad, centro + meia + pad)))
+    # junta amostras seguidas com a mesma caixa, para a lista não explodir
+    out.sort(key=lambda o: (round(o[2][1]), round(o[2][3]), o[0]))
+    juntos: list[tuple[int, int, tuple[float, float, float, float]]] = []
+    for f0, f1, r in out:
+        if juntos and juntos[-1][2] == r and f0 - juntos[-1][1] <= plan.fps * 0.6:
+            juntos[-1] = (juntos[-1][0], f1, r)
+        else:
+            juntos.append((f0, f1, r))
+    return juntos
+
+
+def face_bands(plan: Plan, f0: int, f1: int, core: bool = False, gap: float = 0.0,
+               skip: list[tuple[int, int]] | tuple = ()) -> list[tuple[float, float]]:
+    """Vertical bands taken by faces (and pip cards) during [f0, f1), minus intervals fully inside `skip` windows."""
+    out = []
+    for a, b, zones, cores in plan.zones:
+        if b <= f0 or a >= f1:
+            continue
+        lo_f, hi_f = max(a, f0), min(b, f1)
+        if any(h0 <= lo_f and hi_f <= h1 for h0, h1 in skip):
+            continue
+        for r in (cores if core else zones):
+            out.append((r[1] - gap, r[3] + gap))
+    for a, b, r in plan.obstacles:
+        if a < f1 and f0 < b:
+            out.append((r[1], r[3]))
+    return out
+
+
+def layout_spans(plan: Plan) -> list[tuple[int, int]]:
+    """The frame spans the captions are placed in when one height does not fit the whole video: the face zone
+    pieces, split where a whole background picture comes or goes (tela verde)."""
+    spans = [(a, b) for a, b, _, _ in plan.zones]
+    if not plan.image_zones:
+        return spans
+    cuts = sorted({p for a, b, _ in plan.image_zones for p in (a, b)})
+    out = []
+    for a, b in spans:
+        pts = [a] + [c for c in cuts if a < c < b] + [b]
+        out += list(zip(pts, pts[1:]))
+    return out
+
+
+def manual_off_face(plan: Plan, layer: str, manual: float, above: float, below: float, f0: int, f1: int,
+                    lo: float, hi: float, to_out) -> float:
+    """Tela verde: a hook or CTA height written by hand stays where it is free of the (moved) face, else it goes to
+    the free height closest to it, with a warning."""
+    c = pick_center([manual], above, below, face_bands(plan, f0, f1, gap=GAP_FACE * plan.H), lo, hi, manual)
+    if c is None or abs(c - manual) <= 0.5:
+        return manual
+    plan.adjustments.append({"layer": layer, "action": "moved", "start": round(f0 / plan.fps, 3),
+                             "end": round(f1 / plan.fps, 3), "because": "rosto (tela verde)",
+                             "from_center_y": to_out(manual), "center_y": to_out(c)})
+    plan.warnings.append(f"{CENTER_KEYS[layer]} {to_out(manual)} cairia no rosto na tela verde (você mudou de lugar): "
+                         f"{LABELS[layer]} foi para {to_out(c)}. Tire o center_y para ela se ajustar sozinha")
+    return c
+
+
+def pick_center(prefs: list, above: float, below: float, blocked: list[tuple[float, float]], lo: float, hi: float,
+                fallback: float | None = None) -> float | None:
+    """First preference that is free as it is, else the free center closest to `fallback` (or prefs[0])."""
+    prefs = [p for p in prefs if p is not None]
+    for p in prefs:
+        if face_layout.free_center(p, above, below, blocked, lo, hi) == p:
+            return p
+    target = fallback if fallback is not None else (prefs[0] if prefs else (lo + hi) / 2.0)
+    return face_layout.free_center(target, above, below, blocked, lo, hi)
+
+
+def layout_pieces(windows: list[dict], fps: int, f0: int, f1: int, default_cy: float) -> list[tuple[int, int, float]]:
+    """Caption center per frame interval, with the rule text_render applies to `layout` windows
+    (the window that starts later wins)."""
+    def fr(t):
+        return int(round(float(t) * fps + 1e-6))
+
+    lay = sorted(((fr(w["start"]), fr(w["end"]), float(w["center_y"])) for w in windows), key=lambda x: x[0])
+    cuts = sorted({f0, f1} | {p for a, b, _ in lay for p in (a, b) if f0 < p < f1})
+    out: list[tuple[int, int, float]] = []
+    for a, b in zip(cuts, cuts[1:]):
+        cy = default_cy
+        for l0, l1, lcy in lay:
+            if l0 <= a and b <= l1:
+                cy = lcy
+        if out and out[-1][1] == a and out[-1][2] == cy:
+            out[-1] = (out[-1][0], b, cy)
+        else:
+            out.append((a, b, cy))
+    return out
+
+
+def add_decorations(plan: Plan, mid: "Track", inserts: list[Insert]) -> None:
+    """Pip cards and split seam shadows, left out while an insert later in the list covers them."""
+    W, H, s = plan.W, plan.H, plan.s
+    for ins in inserts:
+        if ins.type == "pip":
+            cx, cy_, cw, ch = ins.card  # type: ignore[misc]
+            key, rect = f"pip{ins.idx}", (cx, cy_, cx + cw, cy_ + ch)
+            mid.add_image(key, pip_decoration(plan, ins))
+        elif ins.seam_y is not None:
+            key = f"seam{ins.type}{ins.seam_y}"
+            depth = max(4, int(round(34 * s)))
+            rect = (0, max(0, ins.seam_y - depth), W, min(H, ins.seam_y + depth))
+            if key not in mid.images:
+                mid.add_image(key, seam_shadow(plan, ins))
+        else:
+            continue
+        covered = []
+        for other in inserts:
+            if other.idx <= ins.idx or other.f1 <= ins.f0 or other.f0 >= ins.f1:
+                continue
+            ocard = other.card if other.type == "pip" else None
+            if other.type != "pip" or boxes_hit(rect, (ocard[0], ocard[1], ocard[0] + ocard[2], ocard[1] + ocard[3])):
+                covered.append((max(ins.f0, other.f0), min(ins.f1, other.f1)))
+        z = mid.next_z()
+        for a, b in subtract_windows([(ins.f0, ins.f1)], merge_windows(covered)):
+            mid.add(a, b, ("img", key, 1.0, 1.0, 0.0), z=z)
+        if covered:
+            plan.adjustments.append({"layer": f"insert {ins.idx + 1}", "action": "decoration_hidden",
+                                     "windows": [[round(a / plan.fps, 3), round(b / plan.fps, 3)] for a, b in merge_windows(covered)],
+                                     "because": "um insert depois na lista fica por cima"})
+
+
+def build_tracks(plan: Plan, inserts: list[Insert], motions: list[Motion] | None = None) -> dict:
+    s = plan.s
+    W, H, fps, nf = plan.W, plan.H, plan.fps, plan.nf
+    data = plan.data
+    motions = list(motions or [])
+    catalog_defaults = load_style_catalog().get("defaults") or {}
+    result: dict = {"mid": None, "captions": None, "top": None, "sfx_events": [], "motion": []}
+    sfx_on = _enabled(_section(data, "sfx"))
+    lay = tr.layout_defaults((W, H))
+    lo, hi = lay["top"], lay["bottom"]
+    disc_hi = min(H - 8.0 * H / 1920.0, lay["bottom"] + 0.035 * H)
+    g_face, g_text = GAP_FACE * H, GAP_TEXT * H
+    out_dir = plan.renders / "overlays"
+
+    def to_out(px):
+        return None if px is None else int(round(px / s))
+
+    def overlaps(a0, a1, b0, b1):
+        return a0 < b1 and b0 < a1
+
+    # ---------------- settings of each text layer
+    hook = _section(data, "hook")
+    hk = None
+    if _enabled(hook) and str(hook.get("text") or "").strip():
+        style = hook.get("style") or catalog_defaults.get("hook_style") or "manchete"
+        if style not in tr.HOOK_STYLES:
+            raise ComposeError(f"estilo de gancho '{style}' não existe. Opções: {', '.join(tr.HOOK_STYLES)}", 2)
+        h0 = plan.fr(hook.get("start", 0.0))
+        h1 = plan.fr(hook.get("end"), default=min(nf, plan.fr(3.0)))
+        if h1 - h0 < 2:
+            plan.warnings.append("gancho com menos de 2 quadros foi ignorado")
+        else:
+            text = str(hook["text"])
+            maxw = int(round(900 * s))
+            fit = tr.hook_fit(text, style, (W, H), max_width=maxw)
+            if fit["too_long"]:
+                plan.warnings.append(f"gancho longo demais, a letra ficou pequena ({fit['size']}px). Encurte o texto.")
+            plan.warnings.extend(tr.text_issues("hook", text, style))
+            manual = _center_value(hook, "center_y", "hook.center_y")
+            hk = {"style": style, "text": text, "f0": h0, "f1": h1, "fit": fit, "maxw": maxw,
+                  "manual": manual * s if manual is not None else None}
+
+    cap = _section(data, "captions")
+    cp = None
+    if _enabled(cap):
+        cap_file = _resolve(plan.edit_dir, cap.get("file") or "captions.json", "captions.file")
+        try:
+            cues = load_json(cap_file) or {}
+        except ValueError as e:
+            raise ComposeError(f"captions.json inválido ({e})", 2)
+        check_captions_cut(plan, cues, cap_file)
+        cues = clamp_cue_words(cues)
+        has_cues = bool(cues.get("cues") if isinstance(cues, dict) else cues)
+        if not has_cues:
+            plan.warnings.append("captions.json não tem legendas")
+        style = cap.get("style") or (cues.get("style") if isinstance(cues, dict) else None) \
+            or catalog_defaults.get("caption_style") or "impacto"
+        try:
+            tr.caption_style_info(style)
+        except ValueError as e:
+            raise ComposeError(str(e), 2)
+        if isinstance(cues, dict) and cues.get("style") and cues.get("style") != style:
+            plan.warnings.append(f"captions.json foi agrupado para '{cues.get('style')}' e o vídeo usa '{style}'. "
+                                 f"Se ficar estranho, rode captions.py --style {style}")
+        font_scale = float(cap.get("font_scale", 1.0) or 1.0)
+        manual = _center_value(cap, "center_y", "captions.center_y")
+        hide = [(hk["f0"], hk["f1"])] if hk and cap.get("hide_during_hook", True) else []
+        seams = [{"start": i.f0 / fps, "end": i.f1 / fps, "center_y": float(i.seam_y)} for i in inserts if i.seam_y is not None]
+        cp = {"file": cap_file, "cues": cues, "style": style, "font_scale": font_scale, "has_cues": has_cues,
+              "manual": manual * s if manual is not None else None, "hide": hide, "seams": seams, "moves": [],
+              "base": [], "ext": tr.caption_extent(cues, style, (W, H), font_scale, fps)}
+
+    disc = _section(data, "disclaimer")
+    dc = None
+    if _enabled(disc):
+        text = str(disc.get("text") or DEFAULT_DISCLAIMER)
+        d0 = plan.fr(disc.get("start", 0.0))
+        d1 = plan.fr(disc.get("end"), default=nf)
+        if d1 > d0:
+            plan.warnings.extend(tr.text_issues("disclaimer", text))
+            manual = _center_value(disc, "center_y", "disclaimer.center_y")
+            bb = tr.ink_bbox(tr.render_disclaimer(text, canvas=(W, H), center_y=lay["disclaimer"]))
+            dc = {"text": text, "f0": d0, "f1": d1, "manual": manual * s if manual is not None else None,
+                  "ext": (lay["disclaimer"] - bb[1], bb[3] - lay["disclaimer"]) if bb else (0.0, 0.0)}
+
+    cta = _section(data, "cta")
+    ct = None
+    if _enabled(cta):
+        text = str(cta.get("text") or DEFAULT_CTA)
+        dur = float(cta.get("duration", 2.5) or 2.5)
+        c1 = nf
+        c0 = plan.fr(cta.get("start")) if cta.get("start") is not None else max(0, nf - plan.fr(dur))
+        if cta.get("start") is not None:
+            c1 = min(nf, c0 + plan.fr(dur))
+        if c1 - c0 >= 2:
+            sub = cta.get("sub")
+            plan.warnings.extend(tr.text_issues("cta", text) + tr.text_issues("cta_sub", str(sub or "")))
+            manual = _center_value(cta, "center_y", "cta.center_y")
+            pref = lay["cta"] if cp and cp["has_cues"] else lay["cta_alone"]
+            bb = tr.ink_bbox(tr.render_cta(text, sub, plan.accent, canvas=(W, H), center_y=pref))
+            ext = (((pref - bb[1]) * CTA_MAX_SCALE, (bb[3] - pref) * CTA_MAX_SCALE + CTA_SLIDE * s) if bb else (0.0, 0.0))
+            ct = {"text": text, "sub": sub, "f0": c0, "f1": c1, "pref": pref, "ext": ext,
+                  "manual": manual * s if manual is not None else None}
+
+    for ins in inserts:
+        if hk and overlaps(ins.f0, ins.f1, hk["f0"], hk["f1"]):
+            plan.warnings.append(f"insert {ins.idx + 1} aparece junto com o gancho ({fmt_time(max(ins.f0, hk['f0']) / fps)} a "
+                                 f"{fmt_time(min(ins.f1, hk['f1']) / fps)}): comece o insert depois do fim do gancho")
+        if ct and overlaps(ins.f0, ins.f1, ct["f0"], ct["f1"]):
+            plan.warnings.append(f"insert {ins.idx + 1} aparece junto com a chamada ({fmt_time(max(ins.f0, ct['f0']) / fps)} a "
+                                 f"{fmt_time(min(ins.f1, ct['f1']) / fps)}): termine o insert antes da chamada")
+
+    for m in motions:
+        if hk and overlaps(m.f0, m.f1, hk["f0"], hk["f1"]):
+            plan.warnings.append(f"a {m.name} aparece junto com o gancho ({fmt_time(max(m.f0, hk['f0']) / fps)} a "
+                                 f"{fmt_time(min(m.f1, hk['f1']) / fps)}): comece a animação depois do fim do gancho")
+        if ct and overlaps(m.f0, m.f1, ct["f0"], ct["f1"]):
+            plan.warnings.append(f"a {m.name} aparece junto com a chamada ({fmt_time(max(m.f0, ct['f0']) / fps)} a "
+                                 f"{fmt_time(min(m.f1, ct['f1']) / fps)}): termine a animação antes da chamada")
+
+    def caption_windows() -> list[dict]:
+        return ([{"start": a / fps, "end": b / fps, "center_y": cy} for a, b, cy in cp["base"]] + cp["seams"] + cp["moves"])
+
+    def caption_pieces(f0, f1):
+        return [(a, b, cy) for a, b, cy in layout_pieces(caption_windows(), fps, f0, f1, lay["caption"])
+                if not any(h0 <= a and b <= h1 for h0, h1 in cp["hide"])]
+
+    def caption_bands(f0, f1):
+        return [(cy - cp["ext"][0] - g_text, cy + cp["ext"][1] + g_text) for _, _, cy in caption_pieces(f0, f1)]
+
+    # ---------------- 1. captions: base height, off the faces (and, if it is cheap, off the disclaimer)
+    if cp:
+        above, below = cp["ext"]
+        # tela verde: a height written by hand for the recording may land on the face, which moved; there it goes
+        # to the free height closest to it
+        tv_manual = cp["manual"] is not None and plan.tv is not None
+        if cp["manual"] is not None and not tv_manual:
+            cp["base"] = [(0, nf, cp["manual"])]
+        else:
+            pref = lay["caption"] if not tv_manual else cp["manual"]
+            soft = []
+            if dc and not tv_manual:
+                dcy = dc["manual"] if dc["manual"] is not None else lay["disclaimer"]
+                soft = [(dcy - dc["ext"][0] - g_text, dcy + dc["ext"][1] + g_text)]
+
+            def choose_caption(f0, f1, prev=None, whole=False):
+                faces = face_bands(plan, f0, f1, gap=g_face, skip=cp["hide"])
+                if tv_manual and face_layout.free_center(pref, above, below, faces, lo, hi) == pref:
+                    return pref      # the height written by hand is free of the face here: it stays
+                body = person_bands(plan, f0, f1, gap=g_face, skip=cp["hide"])
+                if body:   # tela verde: the captions go off the cut-out body (above it) when there is room
+                    # and off the main area of a whole background picture (between it and the head)
+                    imgs = image_bands(plan, f0, f1, gap=g_face, skip=cp["hide"])
+                    c = pick_center([prev, pref], above, below, faces + body + imgs, lo, hi, pref)
+                    if c is not None:
+                        return c
+                    if imgs and whole:
+                        return None      # one height for the whole video only when it is free of everything
+                    if imgs:             # else below the face, before covering the picture
+                        c = pick_center([prev, pref], above, below, faces + imgs, lo, hi, pref)
+                        if c is not None:
+                            return c
+                    c = pick_center([prev, pref], above, below, faces + body, lo, hi, pref)
+                    if c is not None:
+                        return c
+                if soft:
+                    c = pick_center([prev, pref], above, below, faces + soft, lo, hi, pref)
+                    if c is not None and abs(c - pref) <= SOFT_SHIFT * H:
+                        return c
+                return pick_center([prev, pref], above, below, faces, lo, hi, pref)
+
+            c = choose_caption(0, nf, whole=True)
+            if c is not None:
+                cp["base"] = [(0, nf, c)]
+            else:
+                prev = None
+                no_room = []
+                for a, b in layout_spans(plan):
+                    c = choose_caption(a, b, prev)
+                    if c is None:
+                        c = pref
+                        no_room.append((a, b))
+                    if cp["base"] and cp["base"][-1][1] == a and cp["base"][-1][2] == c:
+                        cp["base"][-1] = (cp["base"][-1][0], b, c)
+                    else:
+                        cp["base"].append((a, b, c))
+                    prev = c
+                if no_room:
+                    total = sum(b - a for a, b in no_room) / fps
+                    plan.warnings.append(f"a legenda não achou lugar livre do rosto em {len(no_room)} trecho(s) "
+                                         f"({total:.1f}s, o primeiro em {fmt_time(no_room[0][0] / fps)}): ficou na altura padrão")
+            if tv_manual:
+                moved = [(a, b, c) for a, b, c in cp["base"] if abs(c - cp["manual"]) > 0.5]
+                for a, b, c in moved:
+                    plan.adjustments.append({"layer": "captions", "action": "moved", "start": round(a / fps, 3),
+                                             "end": round(b / fps, 3), "because": "rosto (tela verde)",
+                                             "from_center_y": to_out(cp["manual"]), "center_y": to_out(c)})
+                if moved:
+                    total = sum(b - a for a, b, _ in moved) / fps
+                    plan.warnings.append(f"captions.center_y {to_out(cp['manual'])} cairia no rosto na tela verde (você "
+                                         f"mudou de lugar): em {total:.1f}s a legenda foi para a altura livre mais perto "
+                                         f"({to_out(moved[0][2])}). Tire o center_y para ela se ajustar sozinha")
+
+    # ---------------- 2. CTA: off the faces, and off the captions when there is room
+    if ct:
+        above, below = ct["ext"]
+        if ct["manual"] is not None:
+            ct["cy"] = ct["manual"]
+            if plan.tv is not None:
+                ct["cy"] = manual_off_face(plan, "cta", ct["manual"], above, below, ct["f0"], ct["f1"], lo, hi, to_out)
+        else:
+            faces = face_bands(plan, ct["f0"], ct["f1"], gap=g_face)
+            caps = caption_bands(ct["f0"], ct["f1"]) if cp and cp["has_cues"] else []
+            body = person_bands(plan, ct["f0"], ct["f1"], gap=g_face)
+            c = None
+            imgs = image_bands(plan, ct["f0"], ct["f1"], gap=g_face) if body else []
+            if imgs:
+                c = pick_center([ct["pref"]], above, below, faces + body + imgs + caps, lo, hi) if caps else None
+                if c is None:
+                    c = pick_center([ct["pref"]], above, below, faces + body + imgs, lo, hi)
+            if body and c is None:
+                c = pick_center([ct["pref"]], above, below, faces + body + caps, lo, hi) if caps else None
+                if c is None:
+                    c = pick_center([ct["pref"]], above, below, faces + body, lo, hi)
+            if c is None:
+                c = pick_center([ct["pref"]], above, below, faces + caps, lo, hi) if caps else None
+            if c is None:
+                c = pick_center([ct["pref"]], above, below, faces, lo, hi)
+            if c is None:
+                c = ct["pref"]
+                plan.warnings.append("a chamada não achou lugar livre do rosto: ficou na posição padrão")
+            ct["cy"] = c
+        ct["img"] = tr.render_cta(ct["text"], ct["sub"], plan.accent, canvas=(W, H), center_y=ct["cy"])
+        ct["band"] = (ct["cy"] - above, ct["cy"] + below)
+
+    # ---------------- 3. hook: off the faces and the CTA
+    if hk:
+        img0 = tr.render_hook(hk["text"], hk["style"], plan.accent, canvas=(W, H), center_y=int(round(lay["hook"])),
+                              max_width=hk["maxw"])
+        bb = tr.ink_bbox(img0)
+        above, below = ((lay["hook"] - bb[1]) * HOOK_MAX_SCALE, (bb[3] - lay["hook"]) * HOOK_MAX_SCALE) if bb else (0.0, 0.0)
+        if hk["manual"] is not None:
+            cy = hk["manual"]
+            if plan.tv is not None:
+                cy = manual_off_face(plan, "hook", hk["manual"], above, below, hk["f0"], hk["f1"], lo, hi, to_out)
+        else:
+            faces = face_bands(plan, hk["f0"], hk["f1"], gap=g_face)
+            highs = [(ct["band"][0] - g_text, ct["band"][1] + g_text)] if ct and overlaps(hk["f0"], hk["f1"], ct["f0"], ct["f1"]) else []
+            caps = caption_bands(hk["f0"], hk["f1"]) if cp and cp["has_cues"] else []
+            body = person_bands(plan, hk["f0"], hk["f1"], gap=g_face)
+            cy = None
+            imgs = image_bands(plan, hk["f0"], hk["f1"], gap=g_face) if body else []
+            if imgs:
+                cy = pick_center([lay["hook"]], above, below, faces + body + imgs + highs + caps, lo, hi) if caps else None
+                if cy is None:
+                    cy = pick_center([lay["hook"]], above, below, faces + body + imgs + highs, lo, hi)
+            if body and cy is None:
+                cy = pick_center([lay["hook"]], above, below, faces + body + highs + caps, lo, hi) if caps else None
+                if cy is None:
+                    cy = pick_center([lay["hook"]], above, below, faces + body + highs, lo, hi)
+            if cy is None:
+                cy = pick_center([lay["hook"]], above, below, faces + highs + caps, lo, hi) if caps else None
+            if cy is None:
+                cy = pick_center([lay["hook"]], above, below, faces + highs, lo, hi)
+            if cy is None:
+                cy = lay["hook"]
+                plan.warnings.append("o gancho não achou lugar livre do rosto: ficou na posição padrão")
+        hk["cy"] = cy
+        hk["img"] = img0 if int(round(cy)) == int(round(lay["hook"])) else tr.render_hook(
+            hk["text"], hk["style"], plan.accent, canvas=(W, H), center_y=int(round(cy)), max_width=hk["maxw"])
+        hk["band"] = (cy - above, cy + below)
+
+    # ---------------- 3b. animations: off the faces, the CTA and the hook (and the captions when it is cheap)
+    if motions:
+        t_mo = time.time()
+        highs_mo = [(why, cfg["f0"], cfg["f1"], (cfg["band"][0] - g_text, cfg["band"][1] + g_text))
+                    for why, cfg in (("chamada", ct), ("gancho", hk)) if cfg]
+        place_motion(plan, motions, highs_mo,
+                     lambda a, b: caption_bands(a, b) if cp and cp["has_cues"] else [])
+        cached = sum(1 for m in motions if m.clip and m.clip.get("cached"))
+        log(f"animações prontas ({len(motions)}{f', {cached} do cache' if cached else ''}) em {time.time() - t_mo:.1f}s")
+        motions = [m for m in motions if m.ink is not None]
+        above_motion = []
+        if ct:
+            above_motion.append(("cta", ct["f0"], ct["f1"],
+                                 grow_box(tr.ink_bbox(ct["img"]), CTA_MAX_SCALE, CTA_SLIDE * s)))
+        if hk:
+            above_motion.append(("hook", hk["f0"], hk["f1"], grow_box(tr.ink_bbox(hk["img"]), HOOK_MAX_SCALE)))
+        resolve_motion_windows(plan, motions, above_motion)
+
+    # ---------------- 4. captions step aside (auto) or hide (manual, or no room) for the CTA, the hook and the animations
+    if cp and cp["has_cues"]:
+        above, below = cp["ext"]
+        highs = []
+        if ct:
+            highs.append(("cta", ct["f0"], ct["f1"], ct["band"]))
+        if hk:
+            highs.append(("hook", hk["f0"], hk["f1"], hk["band"]))
+        for m in motions:
+            highs += [("motion", a, b, (m.ink[1], m.ink[3])) for a, b in m.shown]
+        for name, f0, f1, band in highs:
+            for a, b, cyc in caption_pieces(f0, f1):
+                if cyc + below + g_text <= band[0] or cyc - above - g_text >= band[1]:
+                    continue
+                new = None
+                if cp["manual"] is None:
+                    blocked = face_bands(plan, a, b, gap=g_face) + [
+                        (hb[0] - g_text, hb[1] + g_text) for _, x0, x1, hb in highs if overlaps(a, b, x0, x1)]
+                    body = person_bands(plan, a, b, gap=g_face)
+                    if body:
+                        new = pick_center([cyc], above, below, blocked + body, lo, hi)
+                    if new is None:
+                        new = pick_center([cyc], above, below, blocked, lo, hi)
+                if new is not None:
+                    cp["moves"].append({"start": a / fps, "end": b / fps, "center_y": new})
+                    plan.adjustments.append({"layer": "captions", "action": "moved", "start": round(a / fps, 3),
+                                             "end": round(b / fps, 3), "because": name, "from_center_y": to_out(cyc),
+                                             "center_y": to_out(new)})
+                else:
+                    cp["hide"].append((a, b))
+                    plan.adjustments.append({"layer": "captions", "action": "hidden", "start": round(a / fps, 3),
+                                             "end": round(b / fps, 3), "because": name})
+
+    # ---------------- 5. disclaimer: off the faces and every text on screen with it
+    if dc:
+        above, below = dc["ext"]
+        spans: list[tuple[int, int, float]] = []
+        if dc["manual"] is not None:
+            spans = [(dc["f0"], dc["f1"], dc["manual"])]
+        else:
+            pref = lay["disclaimer"]
+            top_anchor = lo + above + g_text
+
+            def text_bands(a, b):
+                out = []
+                for cfg in (hk, ct):
+                    if cfg and overlaps(a, b, cfg["f0"], cfg["f1"]):
+                        out.append((cfg["band"][0] - g_text, cfg["band"][1] + g_text))
+                for m in motions:
+                    if any(overlaps(a, b, x0, x1) for x0, x1 in m.shown):
+                        out.append((m.ink[1] - g_text, m.ink[3] + g_text))
+                if cp and cp["has_cues"]:
+                    out += caption_bands(a, b)
+                return out
+
+            def choose_disc(a, b, prev=None):
+                txt = text_bands(a, b)
+                body = person_bands(plan, a, b, gap=g_face)
+                c = None
+                if body:
+                    c = pick_center([prev, pref, top_anchor], above, below,
+                                    face_bands(plan, a, b, gap=g_face) + body + txt, lo, disc_hi, pref)
+                if c is None:
+                    c = pick_center([prev, pref, top_anchor], above, below, face_bands(plan, a, b, gap=g_face) + txt,
+                                    lo, disc_hi, pref)
+                if c is None:   # small print may sit on the chin or the forehead, never on the eyes or the mouth
+                    c = pick_center([prev, pref, top_anchor], above, below,
+                                    face_bands(plan, a, b, core=True, gap=3 * g_face) + txt, lo, disc_hi, pref)
+                return c
+
+            c = choose_disc(dc["f0"], dc["f1"])
+            if c is not None:
+                spans = [(dc["f0"], dc["f1"], c)]
+            else:
+                cuts = {dc["f0"], dc["f1"]}
+                for a, b, _, _ in plan.zones:
+                    cuts |= {a, b}
+                for cfg in (hk, ct):
+                    if cfg:
+                        cuts |= {cfg["f0"], cfg["f1"]}
+                for m in motions:
+                    for x0, x1 in m.shown:
+                        cuts |= {x0, x1}
+                if cp:
+                    for a, b, _ in layout_pieces(caption_windows(), fps, 0, nf, lay["caption"]):
+                        cuts |= {a, b}
+                    for a, b in cp["hide"]:
+                        cuts |= {a, b}
+                points = sorted(f for f in cuts if dc["f0"] <= f <= dc["f1"])
+                prev = None
+                for a, b in zip(points, points[1:]):
+                    if b <= a:
+                        continue
+                    c = choose_disc(a, b, prev)
+                    if c is None:
+                        plan.adjustments.append({"layer": "disclaimer", "action": "hidden", "start": round(a / fps, 3),
+                                                 "end": round(b / fps, 3), "because": "sem lugar livre"})
+                        prev = None
+                        continue
+                    if spans and spans[-1][1] == a and spans[-1][2] == c:
+                        spans[-1] = (spans[-1][0], b, c)
+                    else:
+                        spans.append((a, b, c))
+                    prev = c
+            for a, b, c in spans:
+                if abs(c - pref) > 0.5:
+                    plan.adjustments.append({"layer": "disclaimer", "action": "moved", "start": round(a / fps, 3),
+                                             "end": round(b / fps, 3), "because": "rosto ou outro texto",
+                                             "from_center_y": to_out(pref), "center_y": to_out(c)})
+        dc["imgs"] = {}
+        for _, _, c in spans:
+            key = f"disc{int(round(c))}"
+            if key not in dc["imgs"]:
+                dc["imgs"][key] = (c, tr.render_disclaimer(dc["text"], canvas=(W, H), center_y=c))
+        dc["spans"] = [(a, b, f"disc{int(round(c))}") for a, b, c in spans]
+
+    # ---------------- 6. caption track at the chosen heights
+    states: list[dict] = []
+    if cp:
+        layout = caption_windows()
+        hide_s = [[a / fps, b / fps] for a, b in merge_windows(cp["hide"])]
+        cap_dir = plan.renders / f"captions_{cp['style']}_{W}x{H}"
+        states = tr.render_caption_track(cp["cues"], cp["style"], plan.accent, str(cap_dir), canvas=(W, H), fps=fps,
+                                         layout=layout or None, hide=hide_s or None, font_scale=cp["font_scale"])
+        states = [st for st in states if st["start"] < plan.duration]
+
+    # ---------------- 7. what is really drawn: overlapping texts resolved by priority
+    drawn: dict[str, list[tuple]] = {"cta": [], "hook": [], "motion": [], "captions": [], "disclaimer": []}
+    if ct:
+        drawn["cta"] = [(ct["f0"], ct["f1"], grow_box(tr.ink_bbox(ct["img"]), CTA_MAX_SCALE, CTA_SLIDE * s), None)]
+    if hk:
+        drawn["hook"] = [(hk["f0"], hk["f1"], grow_box(tr.ink_bbox(hk["img"]), HOOK_MAX_SCALE), None)]
+    drawn["motion"] = [(a, b, m.ink, m.idx) for m in motions for a, b in m.shown]   # resolved in 3b
+    if cp:
+        drawn["captions"] = [(plan.fr(st["start"]), plan.fr(st["end"]), tuple(st["bbox"]) if st.get("bbox") else None,
+                              st["file"]) for st in states]
+    if dc:
+        boxes = {k: tr.ink_bbox(img) for k, (_, img) in dc["imgs"].items()}
+        drawn["disclaimer"] = [(a, b, boxes[k], k) for a, b, k in dc["spans"]]
+    for i, low in enumerate(PRIORITY):
+        if low == "motion":
+            continue
+        hits: dict[str, list[tuple[int, int]]] = {}
+        for high in PRIORITY[:i]:
+            for h0, h1, hbox, _ in drawn[high]:
+                for l0, l1, lbox, _ in drawn[low]:
+                    a, b = max(h0, l0), min(h1, l1)
+                    if b > a and boxes_hit(hbox, lbox):
+                        hits.setdefault(high, []).append((a, b))
+        if hits:
+            windows = merge_windows([w for ws in hits.values() for w in ws])
+            min_f = max(1, int(round(MIN_PIECE.get(low, 0.0) * fps)))
+            before = sum(span[1] - span[0] for span in drawn[low])
+            kept = []
+            for span in drawn[low]:
+                for piece in subtract_windows([span], windows):
+                    if (piece[0], piece[1]) != (span[0], span[1]) and piece[1] - piece[0] < min_f:
+                        # a sliver left between two hides would blink on screen: hide it with its neighbour
+                        high = next((h for h, ws in hits.items() for a, b in ws if b == piece[0] or a == piece[1]),
+                                    next(iter(hits)))
+                        hits[high].append((piece[0], piece[1]))
+                    else:
+                        kept.append(piece)
+            drawn[low] = kept
+            for high, ws in hits.items():
+                for a, b in merge_windows(ws):
+                    plan.adjustments.append({"layer": low, "action": "hidden", "start": round(a / fps, 3),
+                                             "end": round(b / fps, 3), "because": high})
+            hidden_share = 1.0 - sum(span[1] - span[0] for span in kept) / max(1, before)
+            if low == "disclaimer" and hidden_share > DISCLAIMER_HIDDEN_WARN:
+                names = [OF_LABELS[h] for h in PRIORITY if h in hits]
+                behind = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " e " + names[-1]
+                plan.warnings.append(f"o aviso ficou escondido em {round(hidden_share * 100)}% do tempo para não ficar em cima "
+                                     f"{behind}. Deixe disclaimer.center_y em \"auto\" ou escolha outra altura")
+
+    # ---------------- 8. text still over a face (manual heights, or no free spot)
+    face_report(plan, drawn, {"cta": ct, "hook": hk, "captions": cp, "disclaimer": dc}, lay, disc_hi)
+    motion_face_report(plan, motions)
+
+    # ---------------- 9. tracks
+    for m in motions:
+        if not m.shown:
+            plan.warnings.append(f"a {m.name} ficou escondida o tempo todo e não entrou no vídeo")
+            continue
+        result["motion"].append((m.clip, m.f0, m.shown))
+        m.cues = motion_cues(m)
+        for cue in m.cues:
+            if m.sfx and sfx_on and any(a <= cue["frame"] < b for a, b in m.shown):
+                result["sfx_events"].append(cue)
+    mid = Track(plan, "mid")
+    add_decorations(plan, mid, inserts)
+    if hk:
+        mid.add_image("hook", hk["img"])
+        z = mid.next_z()
+        shown = drawn["hook"]
+        h0, h1 = hk["f0"], hk["f1"]
+        n = h1 - h0
+        animate = n >= len(HOOK_IN) + len(HOOK_OUT) + 2
+        for j in range(n):
+            f = h0 + j
+            if not any(a <= f < b for a, b, _, _ in shown):
+                continue
+            sc, al = 1.0, 1.0
+            if animate and j < len(HOOK_IN):
+                sc, al = HOOK_IN[j]
+            elif animate and j >= n - len(HOOK_OUT):
+                al = HOOK_OUT[j - (n - len(HOOK_OUT))]
+            mid.add(f, f + 1, ("img", "hook", sc, al, 0.0), z=z)
+        plan.layers.append({"type": "hook", "style": hk["style"], "text": hk["text"], "start": h0 / fps, "end": h1 / fps,
+                            "frames": [h0, h1], "lines": hk["fit"]["lines"], "center_y": to_out(hk["cy"]),
+                            "auto": hk["manual"] is None})
+        snd = hook.get("sfx", "pop")
+        if sfx_on and snd:
+            result["sfx_events"].append({"name": str(snd), "frame": h0, "lead_frames": 0, "why": "gancho"})
+    result["mid"] = mid.build(out_dir)
+
+    if cp:
+        by_file = {}
+        final_states = []
+        for a, b, bbox, file in drawn["captions"]:
+            final_states.append({"file": file, "start": round(a / fps, 6), "end": round(b / fps, 6),
+                                 "bbox": list(bbox) if bbox else None})
+            by_file[file] = True
+        cap_dir = plan.renders / f"captions_{cp['style']}_{W}x{H}"
+        ff = tr.write_ffconcat(final_states, str(cap_dir / "captions.ffconcat"), total_duration=plan.duration,
+                               blank_png=str(cap_dir / "blank.png"), fps=fps)
+        windows = merge_windows([(plan.fr(st["start"]), plan.fr(st["end"])) for st in final_states])
+        result["captions"] = (ff, final_states, windows)
+        plan.layers.append({"type": "captions", "style": cp["style"], "file": plan.rel(cp["file"]),
+                            "words_from": cp["cues"].get("words_from") if isinstance(cp["cues"], dict) else None,
+                            "states": len(final_states), "png_files": len(by_file),
+                            "start": round(final_states[0]["start"], 3) if final_states else None,
+                            "end": round(final_states[-1]["end"], 3) if final_states else None,
+                            "hide": [[round(a / fps, 3), round(b / fps, 3)] for a, b in merge_windows(cp["hide"])],
+                            "layout": [{"start": round(w["start"], 3), "end": round(w["end"], 3),
+                                        "center_y": to_out(w["center_y"])} for w in caption_windows()],
+                            "auto": cp["manual"] is None, "font_scale": cp["font_scale"]})
+
+    top = Track(plan, "top")
+    if dc and dc["spans"]:
+        for key, (_, img) in dc["imgs"].items():
+            top.add_image(key, img)
+        z = top.next_z()
+        d0 = dc["f0"]
+        for a, b, _, key in drawn["disclaimer"]:
+            fade = 4 if (a == d0 and d0 > 0) else 0
+            for j in range(min(fade, b - a)):
+                top.add(a + j, a + j + 1, ("img", key, 1.0, round((j + 1) / (fade + 1), 3), 0.0), z=z)
+            top.add(a + min(fade, b - a), b, ("img", key, 1.0, 1.0, 0.0), z=z)
+        centers = sorted({to_out(c) for c, _ in dc["imgs"].values()})
+        plan.layers.append({"type": "disclaimer", "text": dc["text"], "start": dc["f0"] / fps, "end": dc["f1"] / fps,
+                            "frames": [dc["f0"], dc["f1"]], "center_y": centers[0] if len(centers) == 1 else centers,
+                            "auto": dc["manual"] is None,
+                            "shown": [[round(a / fps, 3), round(b / fps, 3)] for a, b in
+                                      merge_windows([(a, b) for a, b, _, _ in drawn["disclaimer"]])]})
+    if ct:
+        top.add_image("cta", ct["img"])
+        z = top.next_z()
+        c0, c1 = ct["f0"], ct["f1"]
+        n_in = min(len(CTA_IN), c1 - c0)
+        for j in range(n_in):
+            sc, al, dy = CTA_IN[j]
+            top.add(c0 + j, c0 + j + 1, ("img", "cta", sc, al, round(dy * s, 1)), z=z)
+        # gentle pulse after the entrance (quantized so PNGs repeat)
+        for f in range(c0 + n_in, c1):
+            tt = (f - c0 - n_in) / fps
+            sc = 1.0 + 0.028 * (0.5 - 0.5 * math.cos(2 * math.pi * tt / 1.1))
+            sc = round(round(sc / 0.004) * 0.004, 3)
+            top.add(f, f + 1, ("img", "cta", sc, 1.0, 0.0), z=z)
+        plan.layers.append({"type": "cta", "text": ct["text"], "sub": ct["sub"], "start": c0 / fps, "end": c1 / fps,
+                            "frames": [c0, c1], "center_y": to_out(ct["cy"]), "auto": ct["manual"] is None})
+        snd = cta.get("sfx")
+        if sfx_on and snd:
+            result["sfx_events"].append({"name": str(snd), "frame": c0, "lead_frames": 0, "why": "chamada"})
+    for k, trn in enumerate(data.get("transitions") or []):
+        if not isinstance(trn, dict):
+            continue
+        if (trn.get("type") or "flash") != "flash":
+            plan.warnings.append(f"transição '{trn.get('type')}' não existe (só 'flash') e foi ignorada")
+            continue
+        try:
+            f = plan.fr(float(trn["at"]))
+        except (KeyError, TypeError, ValueError):
+            plan.warnings.append(f"transitions[{k}] sem 'at' válido foi ignorada")
+            continue
+        z = top.next_z()
+        for off, al in FLASH:
+            top.add(f + off, f + off + 1, ("flash", al), z=z)
+        plan.layers.append({"type": "flash", "at": f / fps, "frame": f,
+                            "frames": [max(0, f - 1), min(nf, f + 4)]})
+        snd = trn.get("sfx", "click")
+        if sfx_on and snd:
+            result["sfx_events"].append({"name": str(snd), "frame": f, "lead_frames": 0, "why": "flash"})
+    result["top"] = top.build(out_dir)
+    return result
+
+
+def face_report(plan: Plan, drawn: dict, cfgs: dict, lay: dict, disc_hi: float) -> None:
+    """List texts still covering the eyes, nose or mouth, with a center_y that would free them."""
+    fps, H = plan.fps, plan.H
+    g_face = GAP_FACE * H
+    for layer in TEXT_LAYERS:
+        hits = []
+        for f0, f1, box, _ in drawn[layer]:
+            for a, b, _, cores in plan.zones:
+                lo_f, hi_f = max(f0, a), min(f1, b)
+                if hi_f <= lo_f:
+                    continue
+                share = max([cover_share(box, core) for core in cores] or [0.0])
+                if share > FACE_COVER_WARN:
+                    hits.append((lo_f, hi_f, share))
+        if not hits:
+            continue
+        hits.sort()
+        merged: list[list] = []
+        for a, b, share in hits:
+            if merged and a <= merged[-1][1] + 1:
+                merged[-1][1] = max(merged[-1][1], b)
+                merged[-1][2] = max(merged[-1][2], share)
+            else:
+                merged.append([a, b, share])
+        cfg = cfgs.get(layer) or {}
+        worst = max(merged, key=lambda m: m[2])
+        pref = {"cta": cfg.get("pref"), "hook": lay["hook"], "captions": lay["caption"], "disclaimer": lay["disclaimer"]}[layer]
+        ext = cfg.get("ext")
+        if layer == "hook" and cfg.get("band") and cfg.get("cy") is not None:
+            ext = (cfg["cy"] - cfg["band"][0], cfg["band"][1] - cfg["cy"])
+        suggest = None
+        if ext:
+            hi = disc_hi if layer == "disclaimer" else lay["bottom"]
+            c = pick_center([pref], ext[0], ext[1], face_bands(plan, worst[0], worst[1], gap=g_face), lay["top"], hi)
+            suggest = int(round(c / plan.s)) if c is not None else None
+        for a, b, share in merged[:20]:
+            plan.face_checks.append({"layer": layer, "start": round(a / fps, 3), "end": round(b / fps, 3),
+                                     "cover": round(share, 3), "suggest_center_y": suggest})
+        where = (f"em {fmt_time(worst[0] / fps)}" if worst[1] - worst[0] <= fps
+                 else f"entre {fmt_time(worst[0] / fps)} e {fmt_time(worst[1] / fps)}")
+        on_seam = layer == "captions" and any(
+            plan.fr(sm["start"]) < worst[1] and worst[0] < plan.fr(sm["end"]) for sm in cfg.get("seams") or [])
+        if on_seam:
+            tip = ("Nesse trecho a legenda fica na divisão da tela dividida: troque split_top por split_bottom (ou o "
+                   "contrário) ou mude o split desse insert")
+        elif cfg.get("manual") is None:
+            tip = ("Não sobrou lugar livre do rosto com os outros textos desse trecho: encurte um texto ou tire um "
+                   "deles desse trecho")
+        elif suggest is not None:
+            tip = f"Use {CENTER_KEYS[layer]} perto de {suggest} (ou \"auto\")"
+        else:
+            tip = "Não há lugar livre do rosto: encurte o texto ou use tela dividida"
+        plan.warnings.append(f"{LABELS[layer]} cobre o rosto {where} ({round(worst[2] * 100)}%). {tip}")
+
+
+def motion_cues(m: Motion) -> list[dict]:
+    """The template's sound cues on the output frames, in the sfx.events shape (why "animação N")."""
+    out = []
+    for cue in m.clip.get("sfx") or []:
+        ev = {"name": str(cue["name"]), "frame": m.f0 + int(cue["frame"]), "lead_frames": 0,
+              "why": f"animação {m.idx}", "motion": m.idx, "volume": float(cue.get("volume", 1.0))}
+        if cue.get("length"):
+            ev["length"] = float(cue["length"])
+        out.append(ev)
+    return out
+
+
+def resolve_motion_windows(plan: Plan, motions: list[Motion], highs: list[tuple]) -> None:
+    """m.shown: where each animation really shows. The CTA and the hook (above it in PRIORITY) hide it where their
+    boxes touch it, and a leftover shorter than MIN_PIECE["motion"] is hidden with its neighbour. Done before the
+    captions and the disclaimer are placed, so they only give way to what is really on screen."""
+    fps = plan.fps
+    min_f = max(1, int(round(MIN_PIECE["motion"] * fps)))
+    for m in motions:
+        hits: dict[str, list[tuple[int, int]]] = {}
+        for name, h0, h1, hbox in highs:
+            a, b = max(h0, m.f0), min(h1, m.f1)
+            if b > a and boxes_hit(hbox, m.ink):
+                hits.setdefault(name, []).append((a, b))
+        if not hits:
+            m.shown = [(m.f0, m.f1)]
+            continue
+        kept = []
+        for p0, p1 in subtract_windows([(m.f0, m.f1)], merge_windows([w for ws in hits.values() for w in ws])):
+            if p1 - p0 < min_f:
+                # a sliver left between two hides would blink on screen: hide it with its neighbour
+                high = next((h for h, ws in hits.items() for a, b in ws if b == p0 or a == p1), next(iter(hits)))
+                hits[high].append((p0, p1))
+            else:
+                kept.append((p0, p1))
+        m.shown = kept
+        for high in PRIORITY:
+            for a, b in merge_windows(hits.get(high, [])):
+                plan.adjustments.append({"layer": f"motion {m.idx}", "action": "hidden", "start": round(a / fps, 3),
+                                         "end": round(b / fps, 3), "because": high})
+                plan.warnings.append(f"a {m.name} ficou escondida de {fmt_time(a / fps)} a {fmt_time(b / fps)} "
+                                     f"para não ficar em cima {OF_LABELS[high]}. Mude o start, o end ou a region")
+
+
+def motion_face_report(plan: Plan, motions: list[Motion]) -> None:
+    """An animation still over the eyes, nose or mouth goes to face_checks and to a warning."""
+    fps = plan.fps
+    for m in motions:
+        hits = []
+        for a, b, _, cores in plan.zones:
+            for w0, w1 in m.shown:
+                lo_f, hi_f = max(a, w0), min(b, w1)
+                if hi_f <= lo_f:
+                    continue
+                share = max([cover_share(m.ink, core) for core in cores] or [0.0])
+                if share > FACE_COVER_WARN:
+                    hits.append((lo_f, hi_f, share))
+        if not hits:
+            continue
+        hits.sort()
+        worst = max(hits, key=lambda h: h[2])
+        for a, b, share in hits[:20]:
+            plan.face_checks.append({"layer": f"motion {m.idx}", "start": round(a / fps, 3), "end": round(b / fps, 3),
+                                     "cover": round(share, 3), "suggest_center_y": None,
+                                     "suggest_region": "auto" if not m.auto else None})
+        if not m.item.template.movable:
+            tip = "Esse modelo fica sempre no mesmo lugar: mude o tempo ou use num trecho sem o rosto ali"
+        elif m.auto:
+            tip = "Não sobrou lugar livre do rosto: use menos itens, outra region ou outro trecho"
+        else:
+            tip = "Use \"region\": \"auto\" para ela fugir do rosto"
+        plan.warnings.append(f"a {m.name} cobre o rosto entre {fmt_time(hits[0][0] / fps)} e {fmt_time(hits[-1][1] / fps)} "
+                             f"({round(worst[2] * 100)}%). {tip}")
+
+
+def motion_layers(plan: Plan, motions: list[Motion]) -> None:
+    """layers[type=motion] of the report."""
+    fps = plan.fps
+    ko = min(plan.full_w, plan.full_h) / 1080.0
+    for m in motions:
+        if m.clip is None:
+            continue
+        item = m.item
+        asked = m.region_asked
+        layer = {"type": "motion", "index": m.idx, "template": m.template, "label": item.template.label,
+                 "start": m.f0 / fps, "end": m.f1 / fps, "frames": [m.f0, m.f1],
+                 "shown": [[round(a / fps, 3), round(b / fps, 3)] for a, b in m.shown],
+                 "region_asked": asked if asked is not None else "auto", "auto": m.auto,
+                 "region": [int(round(v * ko)) for v in item.region], "moved_by": int(round(item.moved_by * ko)),
+                 "rect": [m.clip["x"], m.clip["y"], m.clip["w"], m.clip["h"]],
+                 "ink": list(m.ink) if m.ink else None,
+                 "clip": plan.rel(Path(m.clip["file"])), "cached": bool(m.clip.get("cached")),
+                 "params": item.params, "sfx_on": m.sfx,
+                 "sfx": [{"name": c["name"], "frame": c["frame"], "time": round(c["frame"] / fps, 3),
+                          "volume": c["volume"]} for c in m.cues]}
+        plan.layers.append(layer)
+
+
+# ============================================================== video graph
+
+def run_video(plan: Plan, inserts: list[Insert], tracks: dict, cam: str | None, tmp_video: Path,
+              base_clip: Path | None = None) -> None:
+    """base_clip: the tela verde clip, already on the output grid and size, used in place of the base."""
+    W, H, fps, nf = plan.W, plan.H, plan.fps, plan.nf
+    inputs: list[str] = ["-i", str(base_clip or plan.base)]
+    chains: list[str] = []
+    n_in = 1
+
+    pre = []
+    if base_clip is None and abs(plan.base_fps - fps) > 0.01:
+        pre.append(f"fps={fps}")
+    if base_clip is None and (plan.base_w, plan.base_h) != (W, H):
+        pre.append(f"scale={W}:{H}:force_original_aspect_ratio=increase:flags=bicubic,crop={W}:{H},setsar=1")
+    pre += [f"settb=1/{fps}", "setpts=N", "format=yuv420p"]
+    if cam:
+        pre.append(cam)
+    splits = [i for i in inserts if i.speaker is not None]
+    if splits:
+        labels = "[cur0]" + "".join(f"[spk{i.idx}]" for i in splits)
+        chains.append(f"[0:v]{','.join(pre)},split={len(splits) + 1}{labels}")
+    else:
+        chains.append(f"[0:v]{','.join(pre)}[cur0]")
+    cur = "cur0"
+    step = 0
+
+    def nxt() -> str:
+        nonlocal step
+        step += 1
+        return f"cur{step}"
+
+    for ins in inserts:
+        en = f"between(n,{ins.f0},{ins.f1 - 1})"
+        if ins.speaker is not None:
+            _, sy, sw, sh = ins.speaker
+            lab = nxt()
+            pieces = ins.speaker_pieces or [(ins.f0, ins.f1, ins.speaker_src_y)]
+            ypos = str(pieces[-1][2])
+            for p0, p1, y in reversed(pieces[:-1]):      # crop evaluates y on every frame (n = frame of the base)
+                ypos = f"if(lt(n,{p1}),{y},{ypos})"
+            chains.append(f"[spk{ins.idx}]crop={sw}:{sh}:0:'{ypos}'[spkc{ins.idx}]")
+            chains.append(f"[{cur}][spkc{ins.idx}]overlay=x=0:y={sy}:enable='{en}'[{lab}]")
+            cur = lab
+        inputs += ["-i", str(ins.clip)]
+        x, y = ins.content[0], ins.content[1]
+        lab = nxt()
+        chains.append(f"[{n_in}:v]settb=1/{fps},setpts=N+{ins.f0},format=yuv420p[ins{ins.idx}]")
+        chains.append(f"[{cur}][ins{ins.idx}]overlay=x={x}:y={y}:eof_action=pass:enable='{en}'[{lab}]")
+        cur = lab
+        n_in += 1
+
+    motion_tracks = tracks.get("motion") or []
+    if motion_tracks:
+        from motion import render as MR
+        for clip, f0, windows in motion_tracks:
+            inputs += ["-i", str(clip["file"])]
+            lab = nxt()
+            chains.extend(MR.overlay_filters(clip, n_in, cur, lab, f0, windows))
+            cur = lab
+            n_in += 1
+
+    for name in ("mid", "captions", "top"):
+        track = tracks.get(name)
+        if not track or not track[0] or not track[1]:
+            continue
+        ff, _, windows = track
+        inputs += ["-f", "concat", "-safe", "0", "-i", str(ff)]
+        en = enable_expr(windows, nf)
+        lab = nxt()
+        chains.append(f"[{n_in}:v]format=rgba,scale=out_color_matrix=bt709:out_range=tv,format=yuva420p[t{name}]")
+        opt = f":enable='{en}'" if en else ""
+        chains.append(f"[{cur}][t{name}]overlay=0:0:eof_action=pass:format=auto{opt}[{lab}]")
+        cur = lab
+        n_in += 1
+    chains.append(f"[{cur}]format=yuv420p[vout]")
+
+    script = plan.renders / "final_graph.txt"
+    script.write_text(";\n".join(chains) + "\n", encoding="utf-8")
+    crf, preset = ("26", "veryfast") if plan.preview else ("18", "medium")
+    args = ["-v", "error", "-y", *inputs, *graph_args(script), "-map", "[vout]",
+            "-frames:v", str(nf), "-fps_mode", "cfr", "-r", str(fps),
+            "-c:v", "libx264", "-preset", preset, "-crf", crf, "-profile:v", "high", "-pix_fmt", "yuv420p",
+            "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-color_range", "tv",
+            "-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709",
+            "-an", "-f", "mp4", str(tmp_video)]
+    ffmpeg_cmd(args, "montar o vídeo final")
+
+
+# ============================================================== audio
+
+def loudnorm_measure(path: Path, extra: list[str] | None = None, i=-14.0, tp=-1.0, lra=11.0) -> dict | None:
+    proc = subprocess.run(["ffmpeg", "-hide_banner", "-nostdin", "-v", "info", *(extra or []), "-i", str(path),
+                           "-vn", "-af", f"loudnorm=I={i}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"],
+                          capture_output=True, text=True)
+    m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr or "", re.S)
+    if not m:
+        return None
+    try:
+        d = json.loads(m.group(0))
+        vals = {k: float(d[k]) for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}
+    except (ValueError, KeyError):
+        return None
+    if not all(math.isfinite(v) for v in vals.values()):
+        return None
+    return vals
+
+
+def _sound_share_kept(path: Path, n_keep: int) -> tuple[float, float] | None:
+    """(share of the sound's energy inside its first n_keep samples at SR, its length in seconds).
+
+    None when the file cannot be read or is silent."""
+    proc = subprocess.run(["ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-i", str(path), "-vn", "-ac", "1",
+                           "-ar", str(SR), "-f", "f32le", "-"], capture_output=True)
+    if proc.returncode != 0 or not proc.stdout:
+        return None
+    x = np.frombuffer(proc.stdout[: len(proc.stdout) // 4 * 4], dtype="<f4").astype(np.float64)
+    whole = float(np.sum(x * x))
+    if whole <= 0:
+        return None
+    return float(np.sum(x[: max(0, n_keep)] ** 2)) / whole, len(x) / SR
+
+
+SFX_WHY_LABELS = {"gancho": "do gancho", "chamada": "da chamada", "flash": "do flash"}
+
+
+def _anchor_warning(e: dict, anchor: float, late: int, fps: int) -> str:
+    """Warning for an anchored effect that had to start at 0 and so hits after its frame."""
+    if e["why"] == "efeito":
+        label = f"sfx.events[{e['event']}] ('{e['name']}' em {fmt_time(e['at'])})"
+    else:
+        of = SFX_WHY_LABELS.get(e["why"]) or (("da " if e["why"].startswith("animação") else "do ") + e["why"])
+        label = f"efeito '{e['name']}' {of} em {fmt_time(e['frame'] / fps)}"
+    return (f"{label}: o ponto forte fica {anchor:.2f} s depois do começo do som, então ele teria que começar antes "
+            f"do vídeo. Começou no início e o ponto forte chega {late / SR:.2f} s atrasado")
+
+
+def run_audio(plan: Plan, inserts: list[Insert], sfx_events: list[dict], out_wav: Path, report: dict,
+              voice: Path | None = None) -> None:
+    """voice: a cleaned voice track (audio.denoise) used instead of the base's audio; None = the base's audio."""
+    data = plan.data
+    fps, total = plan.fps, plan.nf * SR // plan.fps
+    loud = _section(data, "loudness")
+    target_i = float(loud.get("i", -14))
+    target_tp = float(loud.get("tp", -1.0))
+    target_lra = float(loud.get("lra", 11))
+    work = plan.renders / "audio"
+    work.mkdir(parents=True, exist_ok=True)
+    voice_in = voice if voice is not None else plan.base
+
+    voice_i = None
+    if plan.has_audio:
+        m = loudnorm_measure(voice_in)
+        voice_i = m["input_i"] if m else None
+    ref_i = voice_i if voice_i is not None else target_i
+
+    inputs: list[str] = []
+    chains: list[str] = []
+    if plan.has_audio:
+        inputs += ["-i", str(voice_in)]
+        voice_src = "[0:a]"
+    else:
+        inputs += ["-f", "lavfi", "-t", f"{plan.duration:.6f}", "-i", f"anullsrc=r={SR}:cl=stereo"]
+        voice_src = "[0:a]"
+    n_in = 1
+    music = _section(data, "music")
+    music_on = _enabled(music) and music.get("file")
+    duck = bool(music.get("duck", True)) if music_on else False
+    chains.append(f"{voice_src}aresample={SR},aformat=sample_fmts=fltp:channel_layouts=stereo,"
+                  f"apad=whole_len={total},atrim=end_sample={total},asetpts=N/SR/TB[voice]")
+    mix_inputs = []
+    if duck:
+        chains.append("[voice]asplit=2[vmix][vkey]")
+        mix_inputs.append("[vmix]")
+    else:
+        mix_inputs.append("[voice]")
+
+    # SFX: gain calibrated for a voice at the target loudness
+    sfx_sec = _section(data, "sfx")
+    placed = []
+    if _enabled(sfx_sec):
+        vol = float(sfx_sec.get("volume", 0.6) or 0.0)
+        adj_db = max(-10.0, min(10.0, ref_i - target_i))
+        gain = vol * SFX_CALIBRATION * (10 ** (adj_db / 20.0))
+        events = list(sfx_events)
+        for ins in inserts:
+            if ins.sfx:
+                events.append({"name": ins.sfx, "frame": ins.f0, "lead_frames": 2, "why": f"insert {ins.idx + 1}"})
+        names = {e["name"] for e in events}
+        custom = {}
+        for nm in names:
+            p = Path(nm)
+            if p.suffix.lower() in SFX_FILE_EXT:
+                custom[nm] = _resolve(plan.edit_dir, nm, "sfx")
+        # a category of the effects library ("transicao", "humor") or one of its takes ("humor-012"): a category
+        # hands out a different take to every event, in a fixed order per edit. A category name wins over a
+        # built-in alias that happens to match it ("impacto" is also an alias of metal_hit)
+        import efeitos
+        library = efeitos.resolve([nm for nm in names if nm not in custom], seed=plan.edit_dir.name)
+        builtin = make_sfx.builtin_sfx([nm for nm in names if nm not in custom and nm not in library])
+        manifest = make_sfx.load_manifest()
+        handed: dict[str, int] = {}
+        for e in sorted(events, key=lambda e: e["frame"]):
+            known = builtin.get(e["name"])
+            if known is None and e["name"] in library:
+                pool = library[e["name"]]["takes"]
+                k = handed.get(e["name"], 0)
+                handed[e["name"]] = k + 1
+                known = pool[k % len(pool)]
+            path = custom.get(e["name"]) or (known["path"] if known else None)
+            if path is None:
+                if make_sfx.resolve_name(e["name"], manifest) is not None or e["name"] in make_sfx.NAMES:
+                    plan.warnings.append(f"o arquivo do efeito sonoro '{e['name']}' está faltando na pasta assets/sfx da "
+                                         f"skill e ele não tocou. Instale a skill de novo")
+                else:
+                    plan.warnings.append(f"efeito sonoro '{e['name']}' não existe (use {', '.join(make_sfx.NAMES)}, o nome "
+                                         f"em português de um deles, como grave ou notificacao, uma categoria da "
+                                         f"biblioteca de efeitos ({', '.join(efeitos.CATEGORIES)}), um som dela como "
+                                         f"humor-012, ou um arquivo)")
+                continue
+            ev_gain = gain * float(e.get("volume", 1.0))      # sfx.events can carry their own multiplier
+            anchor = e.get("anchor_s")
+            if anchor is None and known:
+                anchor = known["anchor_s"]
+            late = 0
+            if anchor is None:
+                # a sound file with no anchor: its t=0 on the event frame (lead_frames early), as always
+                start = max(0, (e["frame"] - e["lead_frames"]) * SR // fps)
+            else:
+                # the anchor (the moment the sound hits full strength) lands on the event frame
+                start = e["frame"] * SR // fps - int(round(anchor * SR))
+                if start < 0:
+                    late, start = -start, 0
+            if start >= total or ev_gain <= 0:
+                continue
+            kept = _sound_share_kept(path, total - start) if "event" in e else None
+            # an anchor_s past the end of the sound gets its own warning below, not a "late" one
+            past_end = kept is not None and e.get("anchor_s") is not None and e["anchor_s"] > kept[1]
+            if late and anchor >= (e["frame"] + 1) / fps and not past_end:
+                plan.warnings.append(_anchor_warning(e, anchor, late, fps))
+            inputs += ["-i", str(path)]
+            lab = f"sfx{n_in}"
+            trim = ""
+            if e.get("length"):
+                # a cue that lasts as long as its animation (typing): cut the sound after its strong point + length
+                cut = (anchor or 0.0) + float(e["length"])
+                trim = f"atrim=end={cut:.4f},afade=t=out:st={max(0.0, cut - SFX_TRIM_FADE):.4f}:d={SFX_TRIM_FADE:.3f},"
+            chains.append(f"[{n_in}:a]aresample={SR},aformat=sample_fmts=fltp:channel_layouts=stereo,"
+                          f"{trim}volume={ev_gain:.4f},adelay=delays={start}S:all=1[{lab}]")
+            mix_inputs.append(f"[{lab}]")
+            entry = {"name": e["name"], "why": e["why"], "sample": start, "time": round(start / SR, 4),
+                     "file": str(path)}
+            if known and known.get("id") and known["id"] != e["name"]:
+                entry["effect"] = known["id"]           # a Portuguese name: the sfx.json id it played
+            for key in ("at", "volume", "event", "motion", "length"):
+                if key in e:
+                    entry[key] = e[key]
+            if anchor:
+                entry["anchor_s"] = anchor
+            if late:
+                entry["late_s"] = round(late / SR, 4)
+            if "event" in e:
+                if kept is not None and kept[0] < SFX_EVENT_MIN_KEPT:
+                    plan.warnings.append(f"sfx.events[{e['event']}] ('{e['name']}' em {fmt_time(e['at'])}) é cortado "
+                                         f"pelo fim do vídeo: toca só {(total - start) / SR:.2f} s dos "
+                                         f"{kept[1]:.2f} s do som. Adiante o \"at\" para ouvir o som inteiro")
+                if past_end:
+                    plan.warnings.append(f"sfx.events[{e['event']}].anchor_s {e['anchor_s']:g} passa do fim do som "
+                                         f"({kept[1]:.2f} s): o som inteiro tocou antes de {fmt_time(e['at'])}")
+            placed.append(entry)
+            n_in += 1
+    report["sfx"] = placed
+
+    if music_on:
+        mpath = _resolve(plan.edit_dir, music.get("file"), "music.file")
+        mm = loudnorm_measure(mpath, extra=["-t", f"{plan.duration + 1:.3f}"])
+        vol_db = float(music.get("volume_db", MUSIC_VOLUME_DB))
+        if mm:
+            gain_db = (ref_i - mm["input_i"]) + vol_db
+        else:
+            gain_db = vol_db
+            plan.warnings.append("não consegui medir o volume da trilha; usei volume_db direto")
+        gain_db = max(-60.0, min(12.0, gain_db))
+        fade = max(0.0, min(plan.duration, float(music.get("fade_out", 1.5) or 0.0)))
+        inputs += ["-stream_loop", "-1", "-i", str(mpath)]
+        chains.append(f"[{n_in}:a]aresample={SR},aformat=sample_fmts=fltp:channel_layouts=stereo,"
+                      f"atrim=end_sample={total},asetpts=N/SR/TB,volume={gain_db:.2f}dB,afade=t=in:d=0.35[mus0]")
+        cur = "mus0"
+        if duck:
+            # sidechaincompress ends when either input ends, even with samples of the other still waiting, and
+            # ffmpeg 8 feeds the inputs from their own threads: endless silence after both, cut at total after
+            chains.append("[mus0]apad[mus0p]")
+            chains.append("[vkey]apad[vkeyp]")
+            chains.append(f"[mus0p][vkeyp]sidechaincompress=threshold=0.1:ratio=3:attack=20:release=300:knee=3:"
+                          f"makeup=1,atrim=end_sample={total}[mus1]")
+            cur = "mus1"
+        if fade > 0:
+            chains.append(f"[{cur}]afade=t=out:st={plan.duration - fade:.4f}:d={fade:.4f}[mus]")
+        else:
+            chains.append(f"[{cur}]anull[mus]")
+        mix_inputs.append("[mus]")
+        report["music"] = {"file": plan.rel(mpath), "measured_i": mm["input_i"] if mm else None,
+                           "volume_db": vol_db, "gain_db": round(gain_db, 2), "duck": duck, "fade_out": fade}
+        layer = {"type": "music", "file": plan.rel(mpath), "gain_db": round(gain_db, 2), "duck": duck,
+                 "fade_out": fade}
+        choice = plan.music_choice
+        if choice:
+            picked = {"mood": choice.get("mood"), "track_id": choice.get("track_id"), "title": choice.get("title"),
+                      "chosen_from": choice.get("from"), "why": choice.get("why"), "source": choice.get("source"),
+                      "license": choice.get("license"), "sha256": choice.get("sha256")}
+            report["music"].update(picked)
+            layer.update({"mood": picked["mood"], "track_id": picked["track_id"]})
+        elif music.get("mood") not in (None, ""):
+            report["music"]["mood_ignored"] = music.get("mood")      # music.file wins over music.mood
+        plan.layers.append(layer)
+        n_in += 1
+
+    if len(mix_inputs) > 1:
+        # every input exactly total samples long: where amix stops never depends on which input arrived first
+        fitted = []
+        for k, lab in enumerate(mix_inputs):
+            chains.append(f"{lab}apad=whole_len={total},atrim=end_sample={total}[fit{k}]")
+            fitted.append(f"[fit{k}]")
+        chains.append(f"{''.join(fitted)}amix=inputs={len(fitted)}:normalize=0:duration=longest:"
+                      f"dropout_transition=0[mixraw]")
+    else:
+        chains.append(f"{mix_inputs[0]}anull[mixraw]")
+    chains.append(f"[mixraw]apad=whole_len={total},atrim=end_sample={total}[aout]")
+    script = work / "audio_graph.txt"
+    script.write_text(";\n".join(chains) + "\n", encoding="utf-8")
+    mix = work / "mix.wav"
+    ffmpeg_cmd(["-v", "error", "-y", *inputs, *graph_args(script), "-map", "[aout]", "-c:a", "pcm_f32le",
+                "-ar", SR, "-ac", 2, str(mix)], "mixar o áudio")
+
+    norm_tp = target_tp - AAC_TP_HEADROOM
+    if not plan.has_audio and not music_on:
+        # no voice and no music: only effects. Normalizing them to -14 LUFS would make them blast.
+        measured = None
+        os.replace(mix, out_wav)
+        plan.warnings.append("o vídeo base não tem áudio: só os efeitos entram, sem normalizar o volume")
+    else:
+        measured = loudnorm_measure(mix, i=target_i, tp=norm_tp, lra=target_lra)
+        if measured:
+            af = (f"loudnorm=I={target_i}:TP={norm_tp}:LRA={target_lra}:measured_I={measured['input_i']}:"
+                  f"measured_TP={measured['input_tp']}:measured_LRA={measured['input_lra']}:"
+                  f"measured_thresh={measured['input_thresh']}:offset={measured['target_offset']}:linear=true")
+        else:
+            af = f"loudnorm=I={target_i}:TP={norm_tp}:LRA={target_lra}"
+            plan.warnings.append("medição de loudness falhou (áudio mudo?); normalização em uma passada")
+        ffmpeg_cmd(["-v", "error", "-y", "-i", mix, "-af",
+                    f"{af},aresample={SR},apad=whole_len={total},atrim=end_sample={total}",
+                    "-c:a", "pcm_f32le", "-ar", SR, "-ac", 2, str(out_wav)], "normalizar o volume")
+    report["loudnorm_input"] = measured
+    report["voice_i"] = voice_i
+    if not plan.data.get("_keep_temp") and mix.exists():
+        try:
+            mix.unlink()
+        except OSError:
+            pass
+
+
+# ============================================================== main
+
+def probe_output(path: Path) -> dict:
+    info = ffprobe_json(path)
+    v = next((s for s in info.get("streams", []) if s.get("codec_type") == "video"), {})
+    a = next((s for s in info.get("streams", []) if s.get("codec_type") == "audio"), {})
+    from fractions import Fraction
+    try:
+        fps = float(Fraction(v.get("avg_frame_rate") or "0/1"))
+    except (ValueError, ZeroDivisionError):
+        fps = 0.0
+    return {"duration": float((info.get("format") or {}).get("duration") or 0), "width": int(v.get("width") or 0),
+            "height": int(v.get("height") or 0), "fps": round(fps, 3), "frames": int(v.get("nb_frames") or 0),
+            "video_codec": v.get("codec_name"), "profile": v.get("profile"), "pix_fmt": v.get("pix_fmt"),
+            "color_space": v.get("color_space"), "color_primaries": v.get("color_primaries"),
+            "color_transfer": v.get("color_transfer"), "color_range": v.get("color_range"),
+            "audio_codec": a.get("codec_name"), "sample_rate": int(a.get("sample_rate") or 0),
+            "channels": int(a.get("channels") or 0), "audio_duration": float(a.get("duration") or 0)}
+
+
+def update_state(plan: Plan) -> None:
+    state_path = plan.edit_dir / "state.json"
+    state = load_json(state_path, default={}) or {}
+    if not isinstance(state, dict):
+        state = {}
+    if plan.preview:
+        # The low-res preview is for the agent to check frames; it never asks the person to approve.
+        state.update({
+            "phase": "final",
+            "awaiting": None,
+            "edit_data": plan.rel(plan.edit_data_path),
+            "message": "Montando o vídeo final...",
+            "updated_at": now_iso(),
+        })
+    else:
+        state.update({
+            "phase": "final",
+            "awaiting": "approval_final",
+            "final_video": plan.rel(plan.out_path),
+            "edit_data": plan.rel(plan.edit_data_path),
+            "message": "Vídeo final pronto. Assista e aprove ou marque o que mudar.",
+            "updated_at": now_iso(),
+        })
+    save_json(state_path, state)
+
+
+def compose(edit_data_path: Path, out: str | None, preview: bool, keep_temp: bool = False) -> int:
+    t_start = time.time()
+    require_binary("ffmpeg")
+    require_binary("ffprobe")
+    plan = build_plan(edit_data_path, out, preview)
+    timed_sfx = plan_sfx_events(plan)
+    denoise = plan_denoise(plan)
+    motions = plan_motion(plan)
+    tv_cfg = plan_tela_verde(plan)
+    if keep_temp:
+        plan.data["_keep_temp"] = True
+    plan.renders.mkdir(parents=True, exist_ok=True)
+    log(f"compondo {plan.rel(plan.out_path)}: {plan.W}x{plan.H} {plan.fps}fps, {plan.nf} quadros "
+        f"({fmt_time(plan.duration)}){' · prévia' if preview else ''}")
+    if plan.music_choice:
+        c = plan.music_choice
+        why = "a mesma da última montagem desta edição" if c.get("from") == "escolha anterior" else c.get("why")
+        log(f"trilha do humor {c.get('mood')}: {c.get('track_id')} \"{c.get('title')}\" em {c.get('file')} ({why})")
+
+    load_faces(plan)
+    cam = camera_filter(plan)
+    if tv_cfg is not None:
+        # the inserts first: a wrong one stops before the cut-out; split_top / split_bottom become the background
+        inserts = plan_inserts(plan, tela_verde=True)
+        insert_backgrounds(plan, tv_cfg, inserts)
+        prepare_tela_verde(plan, tv_cfg)
+        place_pips_tela_verde(plan, inserts)
+        cam = None
+    else:
+        inserts = plan_inserts(plan)
+    drawn = [i for i in inserts if not i.to_bg]         # every insert when the edit is not tela verde
+    compute_face_zones(plan, drawn)
+    compute_person_zones(plan, drawn)
+    if plan.image_zones:
+        covered = [(i.f0, i.f1) for i in drawn if i.type == "full"]
+        plan.image_zones = subtract_windows(plan.image_zones, merge_windows(covered)) if covered else plan.image_zones
+    audio_report: dict = {}
+    denoise_report: dict = {"mode": "off", "applied": "off"}
+    audio_wav = plan.renders / "audio" / "final_audio.wav"
+    audio_error: list[BaseException] = []
+
+    t0 = time.time()
+    tv_clip = None
+    with ThreadPoolExecutor(max_workers=3) as ex:
+        tv_job = ex.submit(render_tela_verde, plan) if plan.tv else None
+        clips = list(ex.map(lambda i: render_insert_clip(plan, i), drawn))
+        if tv_job is not None:
+            tv_clip = tv_job.result()
+            plan.tv["compose_seconds"] = tv_clip.get("render_seconds", 0.0)
+            layer = tela_verde_layer(plan, tv_clip)
+            plan.layers.insert(0, layer)
+            log(f"tela verde pronta{' (do cache)' if tv_clip.get('cached') else ''}: recorte {plan.tv['matte_seconds']:.1f}s, "
+                f"montagem {tv_clip.get('render_seconds', 0.0):.1f}s ({plan.nf} quadros)")
+    for ins, clip in zip(drawn, clips):
+        ins.clip = clip
+    bg_rows = {b.insert: b for b in plan.tv["cfg"].from_inserts} if plan.tv else {}
+    for ins in inserts:
+        if ins.to_bg:
+            b = bg_rows.get(ins.idx + 1)
+            plan.layers.append({"type": "insert", "insert_type": ins.type, "as": "fundo", "src": plan.rel(ins.src),
+                                "kind": ins.kind, "start": ins.f0 / plan.fps, "end": ins.f1 / plan.fps,
+                                "frames": [ins.f0, ins.f1], "ken_burns": ins.ken_burns,
+                                "encaixe": b.fit if b else None,
+                                "rect": ([int(round(v / plan.s)) for v in b.place] if b and b.place
+                                         else [0, 0, plan.full_w, plan.full_h]),
+                                "speaker_rect": None, "speaker_offsets": None, "seam_y": None, "sfx": ins.sfx})
+            continue
+        plan.layers.append({"type": "insert", "insert_type": ins.type, "src": plan.rel(ins.src), "kind": ins.kind,
+                            "start": ins.f0 / plan.fps, "end": ins.f1 / plan.fps, "frames": [ins.f0, ins.f1],
+                            "ken_burns": ins.ken_burns, "rect": list(ins.content),
+                            "speaker_rect": list(ins.speaker) if ins.speaker else None,
+                            "speaker_offsets": ([{"start": round(p0 / plan.fps, 3), "end": round(p1 / plan.fps, 3),
+                                                  "src_y": int(round(y / plan.s))} for p0, p1, y in ins.speaker_pieces]
+                                                if ins.speaker else None),
+                            "seam_y": ins.seam_y, "sfx": ins.sfx})
+    if drawn:
+        log(f"inserts prontos ({len(drawn)}) em {time.time() - t0:.1f}s")
+
+    t0 = time.time()
+    tracks = build_tracks(plan, drawn, motions)
+    motion_layers(plan, motions)
+    log(f"camadas de texto prontas em {time.time() - t0:.1f}s")
+
+    def audio_job():
+        try:
+            voice = None
+            if denoise != "off":
+                t_dn = time.time()
+                voice, rep = run_denoise(plan, denoise, keep_temp)
+                denoise_report.clear()
+                denoise_report.update(rep)
+                denoise_report["seconds"] = round(time.time() - t_dn, 2)
+            run_audio(plan, inserts, tracks["sfx_events"] + timed_sfx, audio_wav, audio_report, voice=voice)
+        except BaseException as e:  # noqa: BLE001
+            audio_error.append(e)
+
+    th = threading.Thread(target=audio_job, daemon=True)
+    th.start()
+
+    t0 = time.time()
+    tmp_video = plan.renders / "final_video_only.mp4"
+    run_video(plan, drawn, tracks, cam, tmp_video, Path(tv_clip["file"]) if tv_clip else None)
+    log(f"vídeo codificado em {time.time() - t0:.1f}s")
+    th.join()
+    if audio_error:
+        err = audio_error[0]
+        raise err if isinstance(err, ComposeError) else ComposeError(f"falha no áudio: {err}")
+
+    plan.out_path.parent.mkdir(parents=True, exist_ok=True)
+    loud = _section(plan.data, "loudness")
+    target_i, target_tp = float(loud.get("i", -14)), float(loud.get("tp", -1.0))
+    tmp_out = plan.out_path.with_name(".tmp-" + plan.out_path.name)
+
+    def mux(gain_db: float) -> None:
+        af = ["-af", f"volume={gain_db:.2f}dB"] if abs(gain_db) > 0.001 else []
+        ffmpeg_cmd(["-v", "error", "-y", "-i", tmp_video, "-i", audio_wav, "-map", "0:v:0", "-map", "1:a:0",
+                    "-c:v", "copy", *af, "-c:a", "aac", "-b:a", "192k", "-ar", SR, "-ac", 2,
+                    "-t", f"{plan.duration:.6f}", "-movflags", "+faststart", "-f", "mp4", tmp_out],
+                   "juntar vídeo e áudio")
+
+    mux(0.0)
+    final_loud = loudnorm_measure(tmp_out, i=target_i, tp=target_tp)
+    if final_loud and final_loud["input_tp"] > target_tp + 0.05:
+        # the AAC encoder pushed a true peak over the target: trim the gain just enough and encode again
+        mux(target_tp - final_loud["input_tp"] - 0.1)
+        final_loud = loudnorm_measure(tmp_out, i=target_i, tp=target_tp)
+    os.replace(tmp_out, plan.out_path)
+    for p in (tmp_video, audio_wav):
+        if keep_temp:
+            break
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+    facts = probe_output(plan.out_path)
+    elapsed = time.time() - t_start
+    for e in audio_report.get("sfx", []):
+        layer = {"type": "sfx", "name": e["name"], "why": e["why"], "time": e["time"], "sample": e["sample"]}
+        for key in ("effect", "at", "volume", "event", "motion", "length", "anchor_s", "late_s"):
+            if key in e:
+                layer[key] = e[key]
+        plan.layers.append(layer)
+    report = {
+        "output": plan.rel(plan.out_path),
+        "edit_data": plan.rel(plan.edit_data_path),
+        "base": plan.rel(plan.base),
+        "preview": plan.preview,
+        "duration": round(plan.duration, 6),
+        "frames": plan.nf,
+        "fps": plan.fps,
+        "width": plan.W,
+        "height": plan.H,
+        "probe": facts,
+        "loudness": {
+            "target_i": target_i, "target_tp": target_tp,
+            "i": final_loud["input_i"] if final_loud else None,
+            "tp": final_loud["input_tp"] if final_loud else None,
+            "lra": final_loud["input_lra"] if final_loud else None,
+            "voice_before_i": audio_report.get("voice_i"),
+        },
+        "music": audio_report.get("music"),
+        "denoise": denoise_report,
+        "layers": plan.layers,
+        "faces": {"file": "face_layout.json" if plan.faces else None,
+                  "segments_with_face": sum(1 for cs in plan.cam_segs if cs.get("face")),
+                  "segments": len(plan.cam_segs)},
+        "adjustments": plan.adjustments,
+        "face_checks": plan.face_checks,
+        "warnings": plan.warnings,
+        "render_seconds": round(elapsed, 2),
+        "realtime_factor": round(elapsed / max(plan.duration, 1e-6), 3),
+        "created_at": now_iso(),
+    }
+    report_path = plan.edit_dir / "verify" / "final_report.json"
+    save_json(report_path, report)
+    update_state(plan)
+
+    counts = {}
+    for layer in plan.layers:
+        counts[layer["type"]] = counts.get(layer["type"], 0) + 1
+    parts = [f"{v} {k}" for k, v in counts.items() if k != "camera"]
+    cam_layer = next((layer for layer in plan.layers if layer["type"] == "camera"), {})
+    if cam_layer.get("zoom_cuts"):
+        parts.append("zoom nos cortes")
+    if cam_layer.get("push_in"):
+        parts.append("aproximação lenta")
+    log(f"camadas: {', '.join(parts) if parts else 'nenhuma além da base'}")
+    moved = [a for a in plan.adjustments if a.get("action") == "moved"]
+    hidden = [a for a in plan.adjustments if a.get("action") == "hidden"]
+    if moved or hidden:
+        names = {"captions": ("legenda", "escondida"), "disclaimer": ("aviso", "escondido"), "hook": ("gancho", "escondido"),
+                 "cta": ("chamada", "escondida")}
+        for a in moved + hidden:
+            if a["layer"].startswith("motion ") and a["layer"] not in names:
+                names[a["layer"]] = (a["layer"].replace("motion", "animação"), "escondida")
+        bits = [f"{names.get(a['layer'], (a['layer'], 'escondido'))[0]} "
+                f"{'mudou de altura' if a['action'] == 'moved' else names.get(a['layer'], ('', 'escondido'))[1]} "
+                f"{fmt_time(a['start'])}-{fmt_time(a['end'])}" for a in (moved + hidden)[:6]]
+        more = f" e mais {len(moved) + len(hidden) - 6}" if len(moved) + len(hidden) > 6 else ""
+        log(f"ajustes para não sobrepor textos: {'; '.join(bits)}{more} (detalhes em adjustments no relatório)")
+    if final_loud:
+        log(f"volume final: {final_loud['input_i']:.1f} LUFS, pico {final_loud['input_tp']:.1f} dBTP")
+    line = denoise_line(denoise_report)
+    if line:
+        log(line)
+    for w in plan.warnings:
+        log(f"aviso: {w}")
+    log(f"ok: {plan.out_path} ({facts['width']}x{facts['height']}, {facts['fps']:g}fps, {facts['duration']:.2f}s)")
+    log(f"relatório: {report_path}")
+    log(f"tempo total de render: {elapsed:.1f}s ({elapsed / max(plan.duration, 1e-6):.2f}x a duração do vídeo)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Monta o vídeo final a partir do edit_data.json (zoom, inserts, textos, efeitos, trilha).")
+    ap.add_argument("edit_data", help="caminho do edit_data.json (fica na pasta edit)")
+    ap.add_argument("-o", "--output", help="arquivo de saída (padrão: final.mp4 na pasta edit; com --preview, final_preview.mp4)")
+    ap.add_argument("--preview", action="store_true", help="prévia rápida em 540 de largura, CRF 26")
+    ap.add_argument("--keep-temp", action="store_true", help="mantém os arquivos intermediários em renders/ (para investigar)")
+    args = ap.parse_args(argv)
+    try:
+        return compose(Path(args.edit_data).expanduser().resolve(), args.output, args.preview, args.keep_temp)
+    except ComposeError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return e.code
+    except ValueError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("interrompido", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())