primocode 10.16.0 → 10.17.0

package/editor/helpers/face_layout.py

@@ -0,0 +1,570 @@
+"""Where the speaker's face is in the cut, and where text fits without covering it.
+
+Runs OpenCV's YuNet face detector (assets/models/face_detection_yunet_2023mar.onnx, MIT) on
+several frames of every cut_timeline.json segment (one decoding pass) and writes
+edit/face_layout.json. A segment keeps its face when at least one sampled frame finds it; the
+protected zone is the union of the boxes found in that segment, so a face that moves inside a
+take stays covered.
+
+face_layout.json (coordinates: fractions of the video size; centers: pixels on the cut canvas):
+    {"version": 1, "video": "cut.mp4", "video_sig": "...", "segments_key": "...", "width": 1080,
+     "height": 1920, "fps": 30, "duration": 25.77, "model": "face_detection_yunet_2023mar.onnx",
+     "assumed_zoom": 1.15,
+     "segments": [{"id": "r1", "start": 0.0, "end": 2.8, "samples": 7, "detected": 7,
+                   "face": {"x0", "y0", "x1", "y1", "eyes_y", "mouth_y", "score"} | null,
+                   "zone": {"x0", "y0", "x1", "y1"} | null,     # never put text here
+                   "core": {"x0", "y0", "x1", "y1"} | null,     # eyes to lower lip
+                   "focus_y": 0.61,
+                   "recommended": {"hook_center_y", "captions_center_y", "cta_center_y",
+                                   "disclaimer_center_y", "split_top_speaker_y",
+                                   "split_bottom_speaker_y"}}],
+     "recommended": {"camera": {"focus_y"}, "hook": {"center_y"}, "captions": {"center_y"},
+                     "cta": {"center_y"}, "disclaimer": {"center_y"}},
+     "summary": "..."}
+
+The recommended centers use the default styles (manchete hook, impacto captions, CTA with a sub
+line, default disclaimer) and a zoom up to `assumed_zoom`. compose_final.py and style_samples.py
+recompute them with the real sizes whenever a center_y (or camera.focus_y) is omitted or "auto".
+The split speaker offsets are the source row (pixels of the camera frame) shown at the top of the
+speaker band for the default split 0.46, with the face slid away from the seam so a caption there
+misses the eyes and the mouth (compose_final.py does the same per segment with the real style).
+
+Usage:
+    uv run python helpers/face_layout.py --edit-dir DIR [--video cut.mp4] [--force] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import ASSETS_DIR, file_signature, load_json, now_iso, probe_video, require_binary, save_json  # noqa: E402
+
+LAYOUT_VERSION = 1
+RULES = 3                  # bump when the recommendations change, so cached files are redone
+MODEL_PATH = ASSETS_DIR / "models" / "face_detection_yunet_2023mar.onnx"
+SCORE_MIN = 0.7            # YuNet confidence for the speaker's face
+MIN_FACE_H = 0.06          # smaller boxes are background faces or false hits (fraction of the frame height)
+DETECT_SHORT_SIDE = 540    # frames are scaled to this short side before detection
+PAD_TOP = 0.08             # zone margin above the box (hair line), fraction of the box height
+PAD_BOTTOM = 0.07          # zone margin under the box (chin, beard)
+ASSUMED_ZOOM = 1.15        # recommendations stay valid with zoom_levels up to this
+MAX_SAMPLES = 40
+SAMPLE_EVERY = 0.25        # seconds between sampled frames inside a segment (heads move: sample often)
+DECODE_EVERY = 0.125       # seconds between decoded frames (the samples are picked from these)
+GAP_FRAC = 0.012           # breathing room between text and a face or another text (fraction of the height)
+DISCLAIMER_MIN_CENTER_FRAC = 300.0 / 1920.0
+DEFAULT_FOCUS_Y = 0.40
+FACE_MOVES = 0.15          # eye lines further apart than this (fraction of the height): one number does not fit every take
+
+
+class FaceLayoutError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------- detection
+
+_DETECTORS: dict[tuple[int, int], object] = {}
+
+
+def _cv2():
+    os.environ.setdefault("OPENCV_LOG_LEVEL", "ERROR")   # no engine notes on the user's terminal
+    try:
+        import cv2  # noqa: PLC0415
+    except ImportError as e:  # pragma: no cover - depends on the install
+        raise FaceLayoutError(f"OpenCV não está instalado ({e}). Rode 'uv sync' na pasta da skill.")
+    if not hasattr(cv2, "FaceDetectorYN"):
+        raise FaceLayoutError("esta versão do OpenCV não tem o detector de rosto YuNet. Rode 'uv sync' na pasta da skill.")
+    if not MODEL_PATH.exists():
+        raise FaceLayoutError(f"modelo de rosto não encontrado: {MODEL_PATH}")
+    return cv2
+
+
+def _detector(w: int, h: int):
+    cv2 = _cv2()
+    det = _DETECTORS.get((w, h))
+    if det is None:
+        det = cv2.FaceDetectorYN.create(str(MODEL_PATH), "", (w, h), SCORE_MIN, 0.3, 50)
+        _DETECTORS[(w, h)] = det
+    return det
+
+
+def detect_array(bgr) -> dict | None:
+    """The speaker's face in one BGR frame (numpy HxWx3): the largest confident box.
+
+    -> {"x0", "y0", "x1", "y1", "eyes_y", "mouth_y", "score"} as fractions of the frame, or None.
+    """
+    import numpy as np  # noqa: PLC0415
+
+    h, w = bgr.shape[:2]
+    scale = DETECT_SHORT_SIDE / min(w, h) if min(w, h) > DETECT_SHORT_SIDE else 1.0
+    if scale != 1.0:
+        cv2 = _cv2()
+        dw, dh = max(2, int(round(w * scale))), max(2, int(round(h * scale)))
+        img = cv2.resize(bgr, (dw, dh), interpolation=cv2.INTER_AREA)
+    else:
+        dw, dh, img = w, h, np.ascontiguousarray(bgr)
+    det = _detector(dw, dh)
+    _, faces = det.detect(img)
+    if faces is None:
+        return None
+    best = None
+    for f in faces:
+        x, y, fw, fh, score = float(f[0]), float(f[1]), float(f[2]), float(f[3]), float(f[14])
+        if score < SCORE_MIN or fh < MIN_FACE_H * dh:
+            continue
+        if best is None or fw * fh > best[2] * best[3]:
+            best = (x, y, fw, fh, score, (f[5] + f[7]) / 2.0, (f[11] + f[13]) / 2.0)
+    if best is None:
+        return None
+    x, y, fw, fh, score, eyes, mouth = best
+    return {"x0": max(0.0, x / dw), "y0": max(0.0, y / dh), "x1": min(1.0, (x + fw) / dw),
+            "y1": min(1.0, (y + fh) / dh), "eyes_y": float(eyes) / dh, "mouth_y": float(mouth) / dh, "score": score}
+
+
+def detect_image(img) -> dict | None:
+    """detect_array for a PIL image."""
+    import numpy as np  # noqa: PLC0415
+
+    rgb = np.asarray(img.convert("RGB"))
+    return detect_array(np.ascontiguousarray(rgb[:, :, ::-1]))
+
+
+def _read_frames(video: Path, frames: list[int], width: int, height: int, step: int) -> dict[int, object]:
+    """Decode every `step`-th frame in one streamed pass (scaled for detection) and keep the listed ones.
+
+    A short `not(mod(n,step))` select keeps the ffmpeg expression tiny (a long list of frame
+    numbers overflows its parser) and streaming keeps memory flat on long videos."""
+    import numpy as np  # noqa: PLC0415
+
+    wanted = set(f for f in frames if f >= 0)
+    if not wanted:
+        return {}
+    scale = min(1.0, DETECT_SHORT_SIDE / max(1, min(width, height)))
+    dw, dh = max(2, int(round(width * scale / 2)) * 2), max(2, int(round(height * scale / 2)) * 2)
+    cmd = ["ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-i", str(video),
+           "-vf", f"select='not(mod(n\\,{step}))',scale={dw}:{dh}:flags=area", "-fps_mode", "passthrough",
+           "-an", "-f", "rawvideo", "-pix_fmt", "bgr24", "-"]
+    size = dw * dh * 3
+    out = {}
+    last = max(wanted)
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    try:
+        k = 0
+        while True:
+            buf = proc.stdout.read(size) if proc.stdout else b""
+            if len(buf) < size:
+                break
+            n = k * step
+            if n in wanted:
+                out[n] = np.frombuffer(buf, np.uint8).reshape(dh, dw, 3)
+            k += 1
+            if n >= last:
+                break
+    finally:
+        if proc.poll() is None:
+            proc.kill()
+        err = proc.stderr.read().decode("utf-8", "replace") if proc.stderr else ""
+        proc.wait()
+    if not out and err.strip():
+        raise FaceLayoutError(f"não consegui ler os quadros de {video.name}: {' '.join(err.strip().splitlines()[-3:])}")
+    return out
+
+
+def _summarize(dets: list[dict]) -> tuple[dict | None, dict | None, dict | None]:
+    """-> (typical face, protected zone, core zone) for the faces found in one segment."""
+    if not dets:
+        return None, None, None
+    tallest = max(d["y1"] - d["y0"] for d in dets)
+    dets = [d for d in dets if d["y1"] - d["y0"] >= 0.4 * tallest]
+
+    def med(key):
+        vals = sorted(d[key] for d in dets)
+        n = len(vals)
+        return vals[n // 2] if n % 2 else (vals[n // 2 - 1] + vals[n // 2]) / 2.0
+
+    face = {k: round(med(k), 4) for k in ("x0", "y0", "x1", "y1", "eyes_y", "mouth_y", "score")}
+    zone = {"x0": round(min(d["x0"] for d in dets), 4),
+            "y0": round(max(0.0, min(d["y0"] - PAD_TOP * (d["y1"] - d["y0"]) for d in dets)), 4),
+            "x1": round(max(d["x1"] for d in dets), 4),
+            "y1": round(min(1.0, max(d["y1"] + PAD_BOTTOM * (d["y1"] - d["y0"]) for d in dets)), 4)}
+    core = {"x0": zone["x0"], "x1": zone["x1"],
+            "y0": round(max(0.0, min(d["eyes_y"] - 0.4 * max(0.02, d["mouth_y"] - d["eyes_y"]) for d in dets)), 4),
+            "y1": round(min(1.0, max(d["mouth_y"] + 0.3 * max(0.02, d["mouth_y"] - d["eyes_y"]) for d in dets)), 4)}
+    return face, zone, core
+
+
+def _segments_from_timeline(timeline: dict | None, duration: float, fps: float) -> list[dict]:
+    segs = []
+    for s in (timeline or {}).get("segments", []) or []:
+        try:
+            a, b = float(s["out_start"]), float(s["out_end"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        if b > a:
+            segs.append({"id": str(s.get("id") or f"t{len(segs) + 1}"), "start": a, "end": b})
+    segs.sort(key=lambda s: s["start"])
+    if not segs and duration > 0:
+        # no timeline: pieces of about 3 s, so a face that moves along the video is followed
+        n = max(1, int(round(duration / 3.0)))
+        segs = [{"id": f"p{i + 1}", "start": round(duration * i / n, 3), "end": round(duration * (i + 1) / n, 3)}
+                for i in range(n)]
+    return segs
+
+
+def _segments_key(segs: list[dict]) -> str:
+    """Changes with the segments and with the detection settings, so an old face_layout.json is redone."""
+    params = (SCORE_MIN, MIN_FACE_H, DETECT_SHORT_SIDE, PAD_TOP, PAD_BOTTOM, ASSUMED_ZOOM, MAX_SAMPLES, SAMPLE_EVERY,
+              DECODE_EVERY, GAP_FRAC, RULES)
+    rows = [(round(s["start"], 3), round(s["end"], 3)) for s in segs]
+    return hashlib.sha1(repr((params, rows)).encode()).hexdigest()[:16]
+
+
+def detect_segments(video: Path, segs: list[dict], fps: float, width: int, height: int) -> list[dict]:
+    step = max(1, int(round(fps * DECODE_EVERY)))
+    plan = []
+    for s in segs:
+        f0 = int(round(s["start"] * fps))
+        f1 = max(f0 + 1, int(round(s["end"] * fps)))
+        grid = [f for f in range(((f0 + step - 1) // step) * step, f1, step)]
+        if not grid:   # segment shorter than the decoding step: the nearest decoded frame
+            grid = [int(round((f0 + f1) / 2.0 / step)) * step]
+        n = max(3, min(MAX_SAMPLES, int(math.ceil((s["end"] - s["start"]) / SAMPLE_EVERY))))
+        if len(grid) > n:
+            grid = [grid[int(len(grid) * (k + 0.5) / n)] for k in range(n)]
+        plan.append(sorted(set(grid)))
+    decoded = _read_frames(video, [f for fr in plan for f in fr], width, height, step)
+    out = []
+    for s, frames in zip(segs, plan):
+        dets = [d for d in (detect_array(decoded[f]) for f in frames if f in decoded) if d]
+        face, zone, core = _summarize(dets)
+        out.append(dict(s, samples=len([f for f in frames if f in decoded]), detected=len(dets),
+                        face=face, zone=zone, core=core,
+                        focus_y=round(face["eyes_y"], 4) if face else None))
+    return out
+
+
+# ---------------------------------------------------------------- placement primitives
+
+def free_center(pref: float, above: float, below: float, blocked: list[tuple[float, float]],
+                lo: float, hi: float, gap: float = 0.0) -> float | None:
+    """Center closest to `pref` for a layer reaching `above` px up and `below` px down, with its
+    edges inside [lo, hi] and at least `gap` px away from every blocked (y0, y1) band. None when
+    nothing fits."""
+    cmin, cmax = lo + above, hi - below
+    if cmax < cmin:
+        return None
+    bad = sorted((y0 - below - gap, y1 + above + gap) for y0, y1 in blocked if y1 > y0)
+    merged: list[list[float]] = []
+    for a, b in bad:
+        if merged and a <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], b)
+        else:
+            merged.append([a, b])
+    free, cur = [], cmin
+    for a, b in merged:
+        if b <= cur:
+            continue
+        if a > cmax:
+            break
+        if a > cur:
+            free.append((cur, min(a, cmax)))
+        cur = max(cur, b)
+    if cur <= cmax:
+        free.append((cur, cmax))
+    if not free:
+        return None
+    best = min(free, key=lambda iv: 0.0 if iv[0] <= pref <= iv[1] else min(abs(pref - iv[0]), abs(pref - iv[1])))
+    return min(max(pref, best[0]), best[1])
+
+
+def place(prefs: list[float], above: float, below: float, blocked: list[tuple[float, float]],
+          lo: float, hi: float, gap: float) -> float | None:
+    """First preferred center that is free as is; otherwise the free center closest to prefs[0]."""
+    for p in prefs:
+        if free_center(p, above, below, blocked, lo, hi, gap) == p:
+            return p
+    return free_center(prefs[0], above, below, blocked, lo, hi, gap)
+
+
+def zoom_rect(rect: dict, zoom: float, anchor_y: float) -> dict:
+    """A normalized rect after the camera zoom (crop centered on x, anchored at anchor_y)."""
+    return {"x0": max(0.0, 0.5 + (rect["x0"] - 0.5) * zoom), "x1": min(1.0, 0.5 + (rect["x1"] - 0.5) * zoom),
+            "y0": max(0.0, anchor_y + (rect["y0"] - anchor_y) * zoom), "y1": min(1.0, anchor_y + (rect["y1"] - anchor_y) * zoom)}
+
+
+def speaker_src_y(typ: str, split: float, eyes_px: float, W: int, H: int, safe_top: float, safe_bottom: float,
+                  core: tuple[float, float] | None = None, clear: float = 0.0) -> int:
+    """Row of the (camera) frame shown at the top of the speaker band of a split, putting the eyes
+    at 45% of the visible band (split_top) or in its middle (split_bottom).
+
+    With `core` (top and bottom of eyes-to-mouth in px of the camera frame) and `clear` (how far the
+    caption on the seam reaches into the speaker band), the face slides away from the seam until
+    that caption misses it, as long as the eyes stay well inside the visible band."""
+    hb = max(2, int(round(split * H / 2.0)) * 2)
+    hs = H - hb
+    if typ == "split_top":
+        band_y, vis0, vis1 = hb, hb, min(H, safe_bottom)
+        target = vis0 + 0.45 * max(0.0, vis1 - vis0)
+    else:
+        band_y, vis0, vis1 = 0, safe_top, hs
+        target = vis0 + 0.5 * max(0.0, vis1 - vis0)
+    src = eyes_px - (target - band_y)
+    if core is not None and clear > 0:
+        span = max(0.0, vis1 - vis0)
+        if typ == "split_top":      # the core top must sit `clear` under the seam; eyes not in the last 15% of the band
+            eyes_limit = eyes_px + band_y - (vis1 - 0.15 * span)
+            src = max(eyes_limit, min(src, core[0] - clear))
+        else:                       # the core bottom must sit `clear` above the seam; eyes not in the first 15%
+            eyes_limit = eyes_px - band_y - (vis0 + 0.15 * span)
+            src = min(eyes_limit, max(src, core[1] - hs + clear))
+    return int(round(min(max(src, 0), H - hs)))
+
+
+# ---------------------------------------------------------------- recommendations
+
+def _extents(canvas: tuple[int, int]) -> dict[str, tuple[float, float]]:
+    """(above, below) px of the default text layers, measured on rendered art."""
+    import text_render as tr  # noqa: PLC0415
+
+    W, H = canvas
+    lay = tr.layout_defaults(canvas)
+
+    def ext(img, cy, grow=1.0):
+        bb = img.getchannel("A").getbbox()
+        if not bb:
+            return (0.0, 0.0)
+        return ((cy - bb[1]) * grow, (bb[3] - cy) * grow)
+
+    return {
+        "hook": ext(tr.render_hook("Você está perdendo venda assim", "manchete", tr.DEFAULT_ACCENT, canvas,
+                                   center_y=lay["hook"], max_width=int(900 * W / 1080)), lay["hook"], 1.05),
+        "captions": tr.caption_extent([], "impacto", canvas),
+        "cta": ext(tr.render_cta("Toque em Saiba Mais", "Acesso na hora", tr.DEFAULT_ACCENT, canvas,
+                                 center_y=lay["cta"]), lay["cta"], 1.03),
+        "disclaimer": ext(tr.render_disclaimer("Resultado individual. Depende de execução. Não é promessa de ganho.",
+                                               canvas, center_y=lay["disclaimer"]), lay["disclaimer"]),
+    }
+
+
+def _bands(segs: list[dict], t0: float, t1: float, H: int, zoom: float, core: bool = False) -> list[tuple[float, float]]:
+    out = []
+    for s in segs:
+        z = s.get("core" if core else "zone")
+        if not z or s["end"] <= t0 or s["start"] >= t1:
+            continue
+        r = zoom_rect(z, zoom, s["focus_y"] if s.get("focus_y") is not None else DEFAULT_FOCUS_Y)
+        out.append((r["y0"] * H, r["y1"] * H))
+    return out
+
+
+def recommend(segs: list[dict], canvas: tuple[int, int], duration: float, zoom: float = ASSUMED_ZOOM) -> dict:
+    import text_render as tr  # noqa: PLC0415
+
+    W, H = canvas
+    lay = tr.layout_defaults(canvas)
+    ext = _extents(canvas)
+    gap = GAP_FRAC * H
+    lo, hi = lay["top"], lay["bottom"]
+    disc_hi = min(H - 8.0 * H / 1920.0, lay["bottom"] + 0.035 * H)
+    # The disclaimer center never goes above 300 px on a 1920 canvas (Reels top bar), same rule as
+    # references/phase2.md gives for manual numbers.
+    disc_lo = max(lo, DISCLAIMER_MIN_CENTER_FRAC * H - ext["disclaimer"][0])
+
+    def centers(t0: float, t1: float, captions_band: tuple[float, float] | None = None) -> dict:
+        faces = _bands(segs, t0, t1, H, zoom)
+        cores = _bands(segs, t0, t1, H, zoom, core=True)
+        r = {}
+        c = place([lay["cta"]], *ext["cta"], faces, lo, hi, gap)
+        r["cta_center_y"] = c
+        r["hook_center_y"] = place([lay["hook"]], *ext["hook"], faces, lo, hi, gap)
+        cap = place([lay["caption"]], *ext["captions"], faces, lo, hi, gap)
+        r["captions_center_y"] = cap
+        cap_band = captions_band or ((cap - ext["captions"][0], cap + ext["captions"][1]) if cap is not None else None)
+        top_anchor = disc_lo + ext["disclaimer"][0] + gap
+        blocked = faces + ([cap_band] if cap_band else [])
+        d = place([lay["disclaimer"], top_anchor], *ext["disclaimer"], blocked, disc_lo, disc_hi, gap)
+        if d is None:   # small print may sit on the chin or the forehead, never on the eyes or the mouth
+            d = place([lay["disclaimer"], top_anchor], *ext["disclaimer"], cores + ([cap_band] if cap_band else []),
+                      disc_lo, disc_hi, 3 * gap)
+        r["disclaimer_center_y"] = d
+        return {k: (round(v) if v is not None else None) for k, v in r.items()}
+
+    safe_top, safe_bottom = lay["top"], lay["bottom"]
+    for s in segs:
+        rec = centers(s["start"], s["end"])
+        if s.get("face"):
+            eyes = s["face"]["eyes_y"] * H
+            core = (s["core"]["y0"] * H, s["core"]["y1"] * H) if s.get("core") else None
+            above, below = ext["captions"]
+            rec["split_top_speaker_y"] = speaker_src_y("split_top", 0.46, eyes, W, H, safe_top, safe_bottom,
+                                                       core=core, clear=below + gap)
+            rec["split_bottom_speaker_y"] = speaker_src_y("split_bottom", 0.46, eyes, W, H, safe_top, safe_bottom,
+                                                          core=core, clear=above + gap)
+        else:
+            rec["split_top_speaker_y"] = rec["split_bottom_speaker_y"] = None
+        s["recommended"] = rec
+
+    with_face = [s for s in segs if s.get("face")]
+    if with_face:
+        weights = sorted((s["face"]["eyes_y"], s["end"] - s["start"]) for s in with_face)
+        half, acc, focus = sum(w for _, w in weights) / 2.0, 0.0, weights[-1][0]
+        for v, w in weights:
+            acc += w
+            if acc >= half:
+                focus = v
+                break
+    else:
+        focus = DEFAULT_FOCUS_Y
+    hook_end = min(duration, 3.0)
+    cta_start = max(0.0, duration - 2.5)
+    faces_all = _bands(segs, 0.0, duration, H, zoom)
+    faces_after_hook = _bands(segs, hook_end, duration, H, zoom) or faces_all
+    cap = place([lay["caption"]], *ext["captions"], faces_after_hook, lo, hi, gap)
+    cap_band = (cap - ext["captions"][0], cap + ext["captions"][1]) if cap is not None else None
+    top_anchor = disc_lo + ext["disclaimer"][0] + gap
+    disc = place([lay["disclaimer"], top_anchor], *ext["disclaimer"], faces_all + ([cap_band] if cap_band else []),
+                 disc_lo, disc_hi, gap)
+    if disc is None:
+        disc = place([lay["disclaimer"], top_anchor], *ext["disclaimer"],
+                     _bands(segs, 0.0, duration, H, zoom, core=True) + ([cap_band] if cap_band else []), disc_lo, disc_hi, 3 * gap)
+    rec = {
+        "camera": {"focus_y": round(focus, 3)},
+        "hook": {"center_y": place([lay["hook"]], *ext["hook"], _bands(segs, 0.0, hook_end, H, zoom), lo, hi, gap)},
+        "captions": {"center_y": cap},
+        "cta": {"center_y": (place([lay["cta"]], *ext["cta"],
+                                   _bands(segs, cta_start, duration, H, zoom) + ([cap_band] if cap_band else []), lo, hi, gap)
+                             or place([lay["cta"]], *ext["cta"], _bands(segs, cta_start, duration, H, zoom), lo, hi, gap))},
+        "disclaimer": {"center_y": disc},
+    }
+    for sec in rec.values():
+        for k, v in list(sec.items()):
+            if k == "center_y" and v is not None:
+                sec[k] = int(round(v))
+    return rec
+
+
+def _summary(layout: dict) -> str:
+    segs = layout["segments"]
+    found = [s for s in segs if s.get("face")]
+    rec = layout["recommended"]
+    if not found:
+        return (f"nenhum rosto encontrado em {len(segs)} trechos: os textos ficam nas posições padrão")
+    eyes = [s["face"]["eyes_y"] for s in found]
+    moves = max(eyes) - min(eyes) > FACE_MOVES
+    if moves:
+        where = "o rosto muda de altura entre os trechos"
+    else:
+        where = "rosto baixo" if rec["camera"]["focus_y"] > 0.5 else "rosto alto" if rec["camera"]["focus_y"] < 0.3 else "rosto no meio"
+    key = {"hook": "hook_center_y", "captions": "captions_center_y", "cta": "cta_center_y", "disclaimer": "disclaimer_center_y"}
+
+    def v(sec):
+        c = rec[sec]["center_y"]
+        if c is not None:
+            return str(c)
+        per = sorted({s["recommended"][key[sec]] for s in segs if (s.get("recommended") or {}).get(key[sec]) is not None})
+        return f"muda por trecho ({per[0]} a {per[-1]})" if per else "sem lugar livre"
+
+    tip = (". Deixe camera.focus_y e os center_y em \"auto\": o compose ajusta trecho por trecho" if moves else "")
+    return (f"rosto em {len(found)} de {len(segs)} trechos, olhos entre {min(eyes):.2f} e {max(eyes):.2f} da altura "
+            f"({where}). Sugestão: camera.focus_y {'auto' if moves else rec['camera']['focus_y']}, gancho {v('hook')}, "
+            f"legenda {v('captions')}, chamada {v('cta')}, aviso {v('disclaimer')}{tip}")
+
+
+# ---------------------------------------------------------------- build / cache
+
+def build(edit_dir: Path, video: Path | None = None, force: bool = False, timeline: dict | None = None) -> dict:
+    """Load edit/face_layout.json when it matches the video and the timeline, else detect and write it."""
+    edit_dir = Path(edit_dir).resolve()
+    video = Path(video).resolve() if video else edit_dir / "cut.mp4"
+    if not video.exists():
+        raise FaceLayoutError(f"vídeo não encontrado: {video}")
+    if timeline is None and video == edit_dir / "cut.mp4":
+        timeline = load_json(edit_dir / "cut_timeline.json")   # its segments are positions in cut.mp4
+    info = probe_video(video)
+    width = int(info.get("display_width") or info.get("width") or 0)
+    height = int(info.get("display_height") or info.get("height") or 0)
+    fps = float(info.get("fps") or 30.0)
+    duration = float(info.get("duration") or 0.0)
+    if width <= 0 or height <= 0:
+        raise FaceLayoutError(f"não consegui ler o tamanho de {video.name}")
+    segs = _segments_from_timeline(timeline, duration, fps)
+    key = _segments_key(segs)
+    out_path = edit_dir / "face_layout.json"
+    sig = file_signature(video)
+    old = load_json(out_path) if out_path.exists() and not force else None
+    if (isinstance(old, dict) and old.get("version") == LAYOUT_VERSION and old.get("video_sig") == sig
+            and old.get("segments_key") == key and old.get("video") == _rel(video, edit_dir)):
+        try:
+            old["summary"] = _summary(old)   # the wording may be newer than the cached file
+        except (KeyError, TypeError, ValueError):
+            pass
+        return old
+    require_binary("ffmpeg")
+    started = time.time()
+    detected = detect_segments(video, segs, fps, width, height)
+    layout = {
+        "version": LAYOUT_VERSION,
+        "video": _rel(video, edit_dir),
+        "video_sig": sig,
+        "segments_key": key,
+        "width": width, "height": height, "fps": round(fps, 3), "duration": round(duration, 3),
+        "model": MODEL_PATH.name,
+        "assumed_zoom": ASSUMED_ZOOM,
+        "segments": detected,
+    }
+    layout["recommended"] = recommend(detected, (width, height), duration)
+    layout["summary"] = _summary(layout)
+    layout["seconds"] = round(time.time() - started, 2)
+    layout["created_at"] = now_iso()
+    save_json(out_path, layout)
+    return layout
+
+
+def _rel(p: Path, base: Path) -> str:
+    try:
+        return str(p.resolve().relative_to(base))
+    except ValueError:
+        return str(p.resolve())
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Acha o rosto em cada trecho do corte e sugere onde pôr gancho, legenda, chamada e aviso.")
+    ap.add_argument("--edit-dir", required=True, help="pasta edit da sessão")
+    ap.add_argument("--video", help="vídeo a analisar (padrão: edit/cut.mp4)")
+    ap.add_argument("--force", action="store_true", help="analisa de novo mesmo com o face_layout.json em dia")
+    ap.add_argument("--json", action="store_true", help="imprime o face_layout.json")
+    args = ap.parse_args(argv)
+    edit = Path(args.edit_dir).expanduser().resolve()
+    if not edit.is_dir():
+        print(f"erro: pasta de edição não encontrada: {edit}", file=sys.stderr)
+        return 2
+    try:
+        layout = build(edit, Path(args.video).expanduser() if args.video else None, force=args.force)
+    except FaceLayoutError as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(layout, ensure_ascii=False, indent=2))
+        return 0
+    for s in layout["segments"]:
+        if s.get("face"):
+            z = s["zone"]
+            print(f"  {s['id']:>5} {s['start']:6.2f}-{s['end']:6.2f}s  rosto {s['detected']}/{s['samples']}  "
+                  f"altura {z['y0']:.2f}-{z['y1']:.2f}  olhos {s['face']['eyes_y']:.2f}")
+        else:
+            print(f"  {s['id']:>5} {s['start']:6.2f}-{s['end']:6.2f}s  sem rosto (0/{s['samples']})")
+    print(f"ok: {layout['summary']} -> {edit / 'face_layout.json'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())