primocode 10.16.0 → 10.17.1

package/editor/helpers/tela_verde.py

@@ -0,0 +1,2113 @@
+"""Tela verde (green screen without a green screen): the speaker cut out of the cut and placed over a
+background, as the base layer of compose_final.py (SPEC Contract 13).
+
+edit_data.json:
+    "edit_type": "tela_verde",
+    "tela_verde": {"posicao": "direita" | "esquerda" | "centro", "altura": 0.55,
+                   "contorno": {"cor": "#FFFFFF", "largura": 8} | null, "sombra": true,
+                   "fundo": [{"src": "assets/x.mp4" | "assets/y.png" | "#101010", "start": 0, "end": 12.3,
+                              "ken_burns": true, "escurecer": 0.15, "desfocar": 0,
+                              "encaixe": "auto" | "cobrir" | "inteiro"}],
+                   "fundo_original_desfocado": false, "sem_rosto": "original" | "recorte", "espelhar": false}
+    "inserts": [{"type": "split_top" | "split_bottom", ...}]   -> backgrounds too (add_insert_backgrounds)
+
+How a frame is made (numpy + OpenCV, several frames at once in threads):
+  - background track: the items of "fundo" are the base; the split_top / split_bottom inserts of the edit become
+    background items that win during their own [start, end) (no split panel). A later item wins where two of
+    the same kind overlap; a gap keeps the item before it; before the first item, the blurred original with
+    fundo_original_desfocado, else a dark color.
+  - encaixe: "cobrir" fills the screen (cropping; a page taller than the screen keeps its top), "inteiro" shows
+    the whole picture or video, sharp, scaled to the width and placed in the stage above the person (the part of
+    the screen the person does not cover, minus a band for auto captions when there is room) over a blurred and
+    darkened cover copy of itself; "auto" is cobrir when the shape is close to the screen's (or taller), else
+    inteiro. Ken Burns is an eased 6% zoom over the item's time (at most twice that time when a gap holds it,
+    then it holds). Videos start at their own frame 0 and play untouched, except empty frames at the start or
+    end of the clip (scan_video): the background right before it dissolves into an empty start while the clip
+    builds up (with nothing before it, the first full frame is held there) and an empty end holds the last full
+    frame; only a video held past its end loops, dissolving from its last frame
+    into the new pass (no jump, no freeze). A video shown whole with a plain border (a studio, a flat color)
+    stays wide (down to QUIET_MIN of the width, to leave the captions a band above the head), its main area
+    (the rows that hold most of its detail over the whole clip) placed in the stage, and its border is carried
+    out to the screen edges, so it has no box around it; the part that does not fit above the head goes behind
+    the captions and the person.
+  - person (cut ranges where face_layout found a face, or every range with "sem_rosto": "recorte"): the frame
+    of cut.mp4 times the cached matte (helpers/matte.py; on a tripod take, without the room its RoomPlate
+    recognizes where the matte is unsure, and with that room's color out of its soft edge), scaled so the
+    person, from the top of the head to
+    the bottom of the screen, is `altura` of the screen height (never wider than 72% of the screen in a
+    corner, or than the screen in the center, before the zoom; a centered tight shot cut on both sides grows up to
+    CENTER_FILL to fill the width), flush with the bottom. In a corner the side the camera cut sits on the screen
+    edge; in the center a cut side never lands inside the screen when the frame is wide enough; in a corner, a
+    segment cut on both sides fills the screen width (up to CORNER_FILL times its corner size), a little lower
+    (up to FILL_DROP of the camera frame goes below the screen), so no cut lands inside the screen. A segment whose
+    face is cut by a side of the camera goes to that side (a face is never sliced in the middle of the screen). A
+    cut edge that still falls inside the screen gets a fade only on the rows the body really touches (SIDE_FADE
+    on a side, so an arm or shoulder dissolves instead of ending in a straight line; a short one on the top; the
+    person, its outline and its shadow fade together, so the other rows stay solid and the outline never shows
+    through).
+    The outline follows the outer body only: a gap it encloses (between an arm and the body, counting the
+    bottom and the cut sides as closed) shows the background with no outline around it.
+    zoom_cuts and push_in scale the person (anchored on that edge, or on the head for centro). "espelhar" flips
+    the person segments (not the ones shown as recorded). Outline and shadow are drawn at half size and blended
+    with cv2.blendLinear.
+  - ranges without a face ("sem_rosto": "original", the default) show the cut frame itself, full screen,
+    with the zoom of the camera section (screen recordings, product close-ups).
+The result is one H.264 clip (renders/<full|preview>/telaverde/tv_<key>.mp4, cached by everything that goes
+into it) that compose_final.py uses in place of cut.mp4.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import subprocess
+import time
+from collections import deque
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+import matte as M
+
+TV_VERSION = "tv5"                  # bump to redo cached composites
+POSITIONS = ("direita", "esquerda", "centro")
+POSITION_ALIASES = {"direita": "direita", "right": "direita", "canto direito": "direita", "canto_direito": "direita",
+                    "esquerda": "esquerda", "left": "esquerda", "canto esquerdo": "esquerda",
+                    "canto_esquerdo": "esquerda", "centro": "centro", "center": "centro", "meio": "centro"}
+DEFAULT_HEIGHT = {"direita": 0.55, "esquerda": 0.55, "centro": 0.75}
+HEIGHT_RANGE = (0.3, 1.0)
+CORNER_MAX_WIDTH = 0.72             # a corner person is never wider than this share of the screen (before the zoom)
+CENTER_MAX_WIDTH = 1.0              # a centered person is never wider than the screen (a tight shot is not enlarged)
+CENTER_FILL = 1.15                  # ...except a shot cut on both sides, grown up to this much to fill the width
+CORNER_FILL = 1.6                   # a corner person cut on both sides grows up to this much to fill the width
+FILL_DROP = 0.2                     # ...and loses up to this share of the bottom of the camera frame, so the head
+                                    # stays where the corner size puts it (the images above keep their room)
+FACE_EDGE = 0.015                   # a face box this close to a side of the camera frame is cut by it
+INNER_CUT_WARN = 0.4                # share of the person time with a body cut inside the screen that gets advice
+MAX_SCALE = 2.0                     # never enlarge the camera frame more than this
+SIDE_MARGIN = 40                    # px (1080 wide) between a person that is not cut by the camera and the edge
+EDGE_FADE = 28                      # px (1080 wide) of fade where the top of the camera frame cuts the body
+SIDE_FADE = 90                      # px (1080 wide) of fade where a side of the camera frame cuts the body inside
+                                    # the screen (the arm or shoulder dissolves instead of ending in a straight line)
+TOUCH_FLUSH = 0.2                   # share of frames touching a side for that side to sit on the screen edge
+OUTLINE_DEFAULT = {"cor": "#FFFFFF", "largura": 8}
+OUTLINE_MAX = 40
+SHADOW = {"alpha": 0.5, "blur": 10.0, "dx": 6.0, "dy": 12.0}     # px on 1080 wide
+DARK_DEFAULT = "#101010"
+DARKEN_DEFAULT = 0.15
+DARKEN_MAX = 0.9
+BLUR_MAX = 80.0
+ORIGINAL_BLUR = {"sigma": 40.0, "darken": 0.35}
+BACKDROP = {"sigma": 70.0, "darken": 0.55, "saturation": 0.55, "feather": 36.0}   # behind a picture shown whole
+KB_DRIFT = 0.06
+KB_HOLD_AFTER = 2.0                 # a held gap stretches the Ken Burns to at most this many times the item's time
+FIT_RATIO = 1.25                    # auto: a shape this close to the screen's (or taller) fills it, else it is whole
+FITS = ("auto", "cobrir", "inteiro")
+FIT_ALIASES = {"auto": "auto", "automatico": "auto", "automático": "auto", "cobrir": "cobrir", "cobre": "cobrir",
+               "cover": "cobrir", "preencher": "cobrir", "encher": "cobrir", "fill": "cobrir", "inteiro": "inteiro",
+               "inteira": "inteiro", "contain": "inteiro", "whole": "inteiro", "fit": "inteiro"}
+STAGE_TOP = 120 / 1920              # the stage for a whole picture starts this far down (the app bar sits above it)
+STAGE_GAP = 0.012                   # share of the height between a whole picture and the head (and the captions)
+WHOLE_MIN = 0.5                     # a whole picture shrinks to fit the stage down to this share of the width
+RESERVE_KEEP = 0.75                 # the stage leaves room for captions when the picture keeps this share of its size
+LOOP_FADE = 0.4                     # s of crossfade where a background video loops
+SCAN_VERSION = "scan3"              # bump when scan_video changes (its cache is redone)
+SCAN_SIDE = 160                     # px of the long side the videos are scanned at
+SCAN_DETAIL = 24                    # 0-255: a pixel this far from its blurred surroundings is detail
+SCAN_EMPTY = (0.003, 0.15, 0.5)     # a frame with less detail than max(abs, share of the clip's median) is empty;
+                                    # next to an empty first or last frame, the ones under the last share still
+                                    # build up or fade out (they count as empty too)
+SCAN_FADE = (0.02, 0.65)            # a clip that ends empty after a steady fall (noise allowed: this share of the
+                                    # median) holds the last frame that still has this share of the fall's peak
+SCAN_ROW = 0.01                     # share of detail (over the clip, and 10% of the busiest) a row or column
+                                    # needs to be main area
+SCAN_MASS = 0.85                    # ...and the main rows are the band that holds this share of the detail (a thin
+                                    # cable or a glow at the edge of the clip is not its main area)
+QUIET_MIN = 0.75                    # a plain-border video shrinks down to this share of the width (its border is
+                                    # carried out, so it has no box) to leave the captions a band above the head
+QUIET_RING = (0.06, 0.04)           # top and bottom bands (share of the height) with less detail: a plain border
+EXTEND = {"blur": 48.0, "fall": 320.0, "darken": 0.3}   # px on 1080 wide: the plain border carried to the screen
+PLATE_VERSION = "placa1"            # bump when the room plate changes (its cache is redone)
+PLATE_ENV = "EDITOR_VIDEO_TELA_VERDE_PLACA"   # =0 turns the room plate off (to compare)
+PLATE = {
+    "step": 2,                      # every other frame of a take feeds its plate
+    "bg": 8,                        # matte (0-255) under this, `fringe` px away from the body, is the room
+    "fringe": 4,
+    "n": [2.0, 8.0],                # frames that saw the room there: none trusted .. fully trusted
+    "std": [6.0, 12.0],             # spread of the room color (noise, a 1 px drift, a screen): trusted .. not
+    "static": 6.0,                  # median spread above this: the camera moved, no plate
+    "known": 0.08,                  # share of the frame the plate must know
+    "blur": 0.7, "win": 5,          # px (plate size): blur of the frame and the plate, window of the comparison
+    "tol": 4.0, "width": 8.0,       # color distance (0-255) that still is the room (plus the spread there)
+    "unsure": [0.8, 0.98],          # matte values the model was not sure of: only there the room goes
+    "near": 8.0, "unlike": [18.0, 32.0],   # the body color nearby (px), how far a dark room color must be from it
+    "bright": [45.0, 70.0],         # a room brighter than this needs no such distance
+    "halo": [30.0, 50.0],           # a room this much brighter than the body next to it is a halo (per pixel)
+    "on": 0.5,                      # evidence that counts
+    "unsure_px": 7, "round_px": 5, "soft": 1.5,   # narrowest piece (px), rounding of the pieces, blur of their
+                                                  # edge
+    "edge": [8, 247], "edge_floor": 0.35,         # soft edge pixels (0-255) whose color is cleaned of the room
+}
+FIELDS = ("posicao", "altura", "contorno", "sombra", "fundo", "fundo_original_desfocado", "sem_rosto", "espelhar")
+BG_FIELDS = ("src", "start", "end", "ken_burns", "escurecer", "desfocar", "encaixe")
+IMAGE_EXT = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".tif", ".tiff"}
+VIDEO_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".gif", ".mts"}
+EXAMPLE = '"tela_verde": {"posicao": "direita", "fundo": [{"src": "assets/pagina.png"}]}'
+ALIASES = {"position": "posicao", "posição": "posicao", "height": "altura", "outline": "contorno", "shadow": "sombra",
+           "background": "fundo", "backgrounds": "fundo", "fundos": "fundo", "blur": "desfocar", "desfoque": "desfocar",
+           "darken": "escurecer", "dim": "escurecer", "inicio": "start", "início": "start", "fim": "end",
+           "kenburns": "ken_burns", "arquivo": "src", "file": "src", "cor": "src", "color": "src",
+           "fit": "encaixe", "encaixar": "encaixe", "ajuste": "encaixe", "modo": "encaixe",
+           "mirror": "espelhar", "flip": "espelhar", "espelho": "espelhar", "espelhado": "espelhar",
+           "inverter": "espelhar"}
+SPLIT_LABEL = {"split_top": "imagem em cima", "split_bottom": "imagem embaixo"}
+
+
+def _hint(name: str, fields) -> str:
+    near = ALIASES.get(str(name).strip().lower())
+    if near not in fields:
+        import difflib  # noqa: PLC0415
+        close = difflib.get_close_matches(str(name), list(fields), n=1, cutoff=0.6)
+        near = close[0] if close else None
+    return f" Você quis dizer \"{near}\"?" if near else ""
+
+
+class TelaVerdeError(Exception):
+    def __init__(self, message: str, code: int = 2):
+        super().__init__(message)
+        self.code = code
+
+
+def _cv2():
+    return M._cv2()
+
+
+def hex_rgb(value) -> tuple[int, int, int] | None:
+    if not isinstance(value, str):
+        return None
+    h = value.strip().lstrip("#")
+    if len(h) == 3:
+        h = "".join(c * 2 for c in h)
+    if len(h) != 6 or not value.strip().startswith("#"):
+        return None
+    try:
+        return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    except ValueError:
+        return None
+
+
+def _num(value) -> float | None:
+    if isinstance(value, bool):
+        return None
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return None
+    return v if math.isfinite(v) else None
+
+
+def _json(value) -> str:
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+def ease(p: float) -> float:
+    p = min(1.0, max(0.0, p))
+    return 0.5 - 0.5 * math.cos(math.pi * p)
+
+
+# ================================================================== config
+
+@dataclass
+class Background:
+    idx: int                      # 1-based position in "fundo" (or in "inserts" when insert is set)
+    kind: str                     # color | image | video
+    src: Path | None
+    color: tuple[int, int, int] | None
+    f0: int
+    f1: int                       # as asked (a gap after it is still this item, see runs)
+    ken_burns: bool
+    darken: float
+    blur: float
+    asked: str = ""
+    fit_asked: str = "auto"
+    fit: str = "cobrir"           # cobrir | inteiro (resolved)
+    size: tuple[int, int] | None = None                    # the source's width and height (upright)
+    insert: int | None = None     # 1-based insert number: a split_top / split_bottom insert shown as background
+    insert_type: str | None = None
+    content: tuple[float, float, float, float] = (0.0, 0.0, 1.0, 1.0)   # main area of the picture (fractions)
+    place: tuple[int, int, int, int] | None = None         # inteiro: x, y, w, h of the sharp copy (render px)
+    stage: tuple[float, float] | None = None               # inteiro: the band it was fitted into (render px)
+    quiet: bool = False           # video with a plain border (a studio, a flat color): it melts into the screen
+    lead: int = 0                 # video: empty frames at the start of a pass (the first full one shows instead)
+    tail: int = 0                 # video: empty frames at the end of a pass (the last full one shows instead)
+    pass_frames: int = 0          # video: frames of one pass at the edit fps (0 = not scanned)
+
+    @property
+    def name(self) -> str:
+        return f"insert {self.insert}" if self.insert else f"fundo {self.idx}"
+
+    @property
+    def where(self) -> str:
+        return f"inserts[{self.idx - 1}]" if self.insert else f"tela_verde.fundo[{self.idx - 1}]"
+
+    def content_rect(self, W: int, H: int) -> tuple[float, float, float, float] | None:
+        """Where the main area of a whole picture lands (render px), grown by the Ken Burns zoom."""
+        if self.fit != "inteiro" or self.place is None:
+            return None
+        x, y, w, h = self.place
+        c = self.content
+        x0, y0, x1, y1 = x + c[0] * w, y + c[1] * h, x + c[2] * w, y + c[3] * h
+        if self.ken_burns:
+            g = KB_DRIFT / 2.0
+            dx, dy = (x1 - x0) * g, (y1 - y0) * g
+            x0, y0, x1, y1 = x0 - dx, y0 - dy, x1 + dx, y1 + dy
+        return (max(0.0, x0), max(0.0, y0), min(float(W), x1), min(float(H), y1))
+
+    def signature(self) -> list:
+        sig = None
+        if self.src is not None:
+            st = self.src.stat()
+            sig = [str(self.src), st.st_size, st.st_mtime_ns]
+        return [self.idx, self.insert, self.kind, sig, self.color, self.f0, self.f1, self.ken_burns,
+                round(self.darken, 4), round(self.blur, 3), self.fit, self.size,
+                [round(v, 4) for v in self.content], self.place, self.quiet, self.lead, self.tail,
+                self.pass_frames]
+
+
+def media_size(path: Path | None, kind: str) -> tuple[int, int] | None:
+    """Upright width and height of an image or video (None when it cannot be read)."""
+    if path is None or kind == "color":
+        return None
+    try:
+        if kind == "image":
+            from PIL import Image  # noqa: PLC0415
+            with Image.open(path) as im:
+                w, h = im.size
+                try:
+                    orient = im.getexif().get(274, 1)
+                except Exception:  # noqa: BLE001
+                    orient = 1
+            return (h, w) if orient in (5, 6, 7, 8) else (w, h)
+        proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                               "stream=width,height:stream_side_data=rotation", "-of", "json", str(path)],
+                              capture_output=True, text=True)
+        st = (json.loads(proc.stdout or "{}").get("streams") or [{}])[0]
+        w, h = int(st.get("width") or 0), int(st.get("height") or 0)
+        rot = 0
+        for sd in st.get("side_data_list") or []:
+            if "rotation" in sd:
+                rot = abs(int(round(float(sd["rotation"])))) % 180
+        if w <= 0 or h <= 0:
+            return None
+        return (h, w) if rot == 90 else (w, h)
+    except (OSError, ValueError, TypeError, IndexError):
+        return None
+
+
+def choose_fit(asked: str, kind: str, size: tuple[int, int] | None, screen: tuple[int, int]) -> str:
+    """encaixe "auto": cobrir when the shape is close to the screen's (a page taller than a vertical screen too),
+    inteiro otherwise (a wide print, a square clip)."""
+    if kind == "color":
+        return "cobrir"
+    if asked in ("cobrir", "inteiro"):
+        return asked
+    if not size:
+        return "cobrir"
+    ar, car = size[0] / max(1, size[1]), screen[0] / max(1, screen[1])
+    if car / FIT_RATIO <= ar <= car * FIT_RATIO:
+        return "cobrir"
+    if ar < car / FIT_RATIO and car < 1.0:
+        return "cobrir"                      # a long page on a vertical screen: fill it and keep the top
+    return "inteiro"
+
+
+def _fit_value(value, where: str) -> str:
+    if value is None:
+        return "auto"
+    fit = FIT_ALIASES.get(value.strip().lower()) if isinstance(value, str) else None
+    if fit is None:
+        raise TelaVerdeError(f"{where}.encaixe precisa ser \"auto\", \"cobrir\" (enche a tela, cortando) ou \"inteiro\" "
+                             f"(aparece inteiro, acima de você) (veio {_json(value)})")
+    return fit
+
+
+def _look_values(item: dict, where: str, kind: str, fit: str, warnings: list[str]) -> tuple[float, float]:
+    """escurecer and desfocar of a background item (the default darkening is 0 for a whole picture and a color)."""
+    default = 0.0 if (kind == "color" or fit == "inteiro") else DARKEN_DEFAULT
+    darken = item.get("escurecer", default)
+    dk = _num(darken)
+    if dk is None or dk < 0 or dk > 1:
+        raise TelaVerdeError(f"{where}.escurecer precisa ser um número de 0 a {DARKEN_MAX} (0 = como está; veio "
+                             f"{_json(darken)})")
+    if dk > DARKEN_MAX:
+        warnings.append(f"{where}.escurecer {dk:g} ficou em {DARKEN_MAX}")
+        dk = DARKEN_MAX
+    blur = _num(item.get("desfocar", 0))
+    if blur is None or blur < 0:
+        raise TelaVerdeError(f"{where}.desfocar precisa ser um número de 0 a {BLUR_MAX:g} (pixels de desfoque; veio "
+                             f"{_json(item.get('desfocar'))})")
+    return dk, min(BLUR_MAX, blur)
+
+
+@dataclass
+class Config:
+    position: str
+    height: float
+    height_asked: bool
+    outline: tuple[tuple[int, int, int], float] | None     # (rgb, width px on 1080 wide)
+    shadow: bool
+    backgrounds: list[Background]
+    blurred_original: bool
+    no_face: str                                            # original | recorte
+    mirror: bool = False                                    # espelhar: the person segments flipped left-right
+    runs: list[tuple[int, int, int | None]] = field(default_factory=list)   # (f0, f1, background index or None)
+    warnings: list[str] = field(default_factory=list)
+    run_notes: list[str] = field(default_factory=list)      # the warnings about the runs (also in warnings)
+    screen: tuple[int, int] = (1080, 1920)
+
+    @property
+    def from_inserts(self) -> list[Background]:
+        return [b for b in self.backgrounds if b.insert]
+
+
+def parse_config(section, fps: int, nf: int, resolve: Callable[[str, str], tuple[Path, str]],
+                 fr: Callable[[float], int], screen: tuple[int, int] = (1080, 1920),
+                 probe: Callable[[Path | None, str], tuple[int, int] | None] = media_size) -> Config:
+    """Check "tela_verde" (exit 2 on a mistake, before anything renders)."""
+    if section is None:
+        section = {}
+    if not isinstance(section, dict):
+        raise TelaVerdeError(f"tela_verde precisa ser um objeto (ex: {EXAMPLE})")
+    unknown = [k for k in section if k not in FIELDS]
+    if unknown:
+        raise TelaVerdeError(f"tela_verde.{unknown[0]} não existe.{_hint(unknown[0], FIELDS)} Campos: {', '.join(FIELDS)}")
+    warnings: list[str] = []
+    raw_pos = section.get("posicao", "direita")
+    key = raw_pos.strip().lower() if isinstance(raw_pos, str) else None
+    position = POSITION_ALIASES.get(key or "")
+    if position is None:
+        raise TelaVerdeError(f"tela_verde.posicao precisa ser \"direita\", \"esquerda\" ou \"centro\" (veio {_json(raw_pos)})")
+    height_asked = section.get("altura") is not None
+    height = DEFAULT_HEIGHT[position]
+    if height_asked:
+        h = _num(section.get("altura"))
+        if h is None or h <= 0:
+            raise TelaVerdeError(f"tela_verde.altura precisa ser a fração da altura da tela que a pessoa ocupa, de "
+                                 f"{HEIGHT_RANGE[0]} a {HEIGHT_RANGE[1]} (ex: 0.55; veio {_json(section.get('altura'))})")
+        if h > 1.0 and h <= 100:
+            h = h / 100.0 if h > 1.5 else 1.0                 # "55" read as percent
+        if not HEIGHT_RANGE[0] <= h <= HEIGHT_RANGE[1]:
+            clipped = min(HEIGHT_RANGE[1], max(HEIGHT_RANGE[0], h))
+            warnings.append(f"tela_verde.altura {h:g} ficou em {clipped:g} (use de {HEIGHT_RANGE[0]} a {HEIGHT_RANGE[1]})")
+            h = clipped
+        height = h
+    outline_raw = section.get("contorno", OUTLINE_DEFAULT)
+    outline = None
+    if outline_raw is True:
+        outline_raw = OUTLINE_DEFAULT
+    if outline_raw not in (None, False):
+        if not isinstance(outline_raw, dict) or set(outline_raw) - {"cor", "largura"}:
+            raise TelaVerdeError(f"tela_verde.contorno precisa ser {{\"cor\": \"#FFFFFF\", \"largura\": 8}} ou null "
+                                 f"(veio {_json(outline_raw)})")
+        color = hex_rgb(outline_raw.get("cor", OUTLINE_DEFAULT["cor"]))
+        if color is None:
+            raise TelaVerdeError(f"tela_verde.contorno.cor precisa ser uma cor #RRGGBB (veio {_json(outline_raw.get('cor'))})")
+        width = _num(outline_raw.get("largura", OUTLINE_DEFAULT["largura"]))
+        if width is None or width < 0:
+            raise TelaVerdeError(f"tela_verde.contorno.largura precisa ser um número de pixels, de 0 a {OUTLINE_MAX} "
+                                 f"(veio {_json(outline_raw.get('largura'))})")
+        if width > OUTLINE_MAX:
+            warnings.append(f"tela_verde.contorno.largura {width:g} ficou em {OUTLINE_MAX}")
+            width = float(OUTLINE_MAX)
+        outline = (color, float(width)) if width > 0 else None
+    shadow = section.get("sombra", True)
+    if not isinstance(shadow, bool):
+        raise TelaVerdeError(f"tela_verde.sombra precisa ser true ou false (veio {_json(shadow)})")
+    blurred = section.get("fundo_original_desfocado", False)
+    if not isinstance(blurred, bool):
+        raise TelaVerdeError(f"tela_verde.fundo_original_desfocado precisa ser true ou false (veio {_json(blurred)})")
+    no_face = section.get("sem_rosto", "original")
+    if no_face not in ("original", "recorte"):
+        raise TelaVerdeError(f"tela_verde.sem_rosto precisa ser \"original\" (o trecho sem rosto aparece como foi "
+                             f"gravado) ou \"recorte\" (veio {_json(no_face)})")
+    mirror = section.get("espelhar", False)
+    if not isinstance(mirror, bool):
+        raise TelaVerdeError(f"tela_verde.espelhar precisa ser true ou false (true vira você de lado, como num "
+                             f"espelho; veio {_json(mirror)})")
+    fundo = section.get("fundo")
+    if fundo is None:
+        fundo = []
+    if isinstance(fundo, (str, dict)):
+        fundo = [fundo]
+    if not isinstance(fundo, list):
+        raise TelaVerdeError("tela_verde.fundo precisa ser uma lista (ex: [{\"src\": \"assets/pagina.png\", \"start\": 0, "
+                             "\"end\": 8}])")
+    items: list[Background] = []
+    prev_end = 0.0
+    for i, item in enumerate(fundo):
+        where = f"tela_verde.fundo[{i}]"
+        if isinstance(item, str):
+            item = {"src": item}
+        if not isinstance(item, dict):
+            raise TelaVerdeError(f"{where} precisa ser um objeto (ex: {{\"src\": \"assets/pagina.png\", \"start\": 0}})")
+        bad = [k for k in item if k not in BG_FIELDS]
+        if bad:
+            raise TelaVerdeError(f"{where}.{bad[0]} não existe.{_hint(bad[0], BG_FIELDS)} Campos: {', '.join(BG_FIELDS)}")
+        src = item.get("src")
+        if not isinstance(src, str) or not src.strip():
+            raise TelaVerdeError(f"{where} precisa de \"src\": um arquivo (\"assets/foto.png\", \"assets/clipe.mp4\") "
+                                 f"ou uma cor (\"#101010\")")
+        color = hex_rgb(src) if src.strip().startswith("#") else None
+        if src.strip().startswith("#") and color is None:
+            raise TelaVerdeError(f"{where}.src: cor inválida {_json(src)} (use #RRGGBB)")
+        path, kind = (None, "color") if color else resolve(src, f"{where}.src")
+        start = item.get("start")
+        if start is None:
+            t0 = prev_end
+        else:
+            t0 = _num(start)
+            if t0 is None or t0 < 0:
+                raise TelaVerdeError(f"{where}.start precisa ser um número de segundos, 0 ou mais (veio {_json(start)})")
+        end = item.get("end")
+        t1 = None
+        if end is not None:
+            t1 = _num(end)
+            if t1 is None or t1 <= t0:
+                raise TelaVerdeError(f"{where}.end precisa ser um número de segundos maior que o start ({t0:g}) "
+                                     f"(veio {_json(end)})")
+        kb = item.get("ken_burns", kind == "image")
+        if not isinstance(kb, bool):
+            raise TelaVerdeError(f"{where}.ken_burns precisa ser true ou false (veio {_json(kb)})")
+        fit_asked = _fit_value(item.get("encaixe"), where)
+        size = probe(path, kind) if kind != "color" else None
+        fit = choose_fit(fit_asked, kind, size, screen)
+        dk, blur = _look_values(item, where, kind, fit, warnings)
+        f0 = fr(t0)
+        f1 = fr(t1) if t1 is not None else None
+        if f0 >= nf:
+            warnings.append(f"{where} começa depois do fim do vídeo e foi ignorado")
+            prev_end = t1 if t1 is not None else t0
+            continue
+        items.append(Background(idx=i + 1, kind=kind, src=path, color=color, f0=f0, f1=f1 if f1 is not None else -1,
+                                ken_burns=kb and kind != "color", darken=dk, blur=blur, asked=src.strip(),
+                                fit_asked=fit_asked, fit=fit, size=size))
+        prev_end = t1 if t1 is not None else t0
+    # an item without "end" lasts until the next item starts (or the end of the video)
+    for k, b in enumerate(items):
+        if b.f1 < 0:
+            later = [o.f0 for o in items[k + 1:] if o.f0 > b.f0]
+            b.f1 = min(later) if later else nf
+        b.f1 = min(nf, b.f1)
+        if b.f1 - b.f0 < 1:
+            warnings.append(f"tela_verde.fundo[{b.idx - 1}] dura menos de 1 quadro e foi ignorado")
+    items = [b for b in items if b.f1 > b.f0]
+    for k, a in enumerate(items):
+        for b in items[k + 1:]:
+            if b.f0 < a.f1 and a.f0 < b.f1:
+                warnings.append(f"os fundos {a.idx} e {b.idx} se sobrepõem: o {b.idx}, que vem depois na lista, fica por cima")
+    cfg = Config(position=position, height=height, height_asked=height_asked, outline=outline, shadow=shadow,
+                 backgrounds=items, blurred_original=blurred, no_face=no_face, mirror=mirror, warnings=warnings,
+                 screen=screen)
+    set_runs(cfg, nf, fps)
+    return cfg
+
+
+def set_runs(cfg: Config, nf: int, fps: int) -> None:
+    """(Re)compute the runs and their warnings (after the split inserts joined the track)."""
+    for note in cfg.run_notes:
+        if note in cfg.warnings:
+            cfg.warnings.remove(note)
+    notes: list[str] = []
+    items = cfg.backgrounds
+    cfg.runs = background_runs(items, nf)
+    if not items and not cfg.blurred_original:
+        notes.append("tela_verde sem fundo: usei um fundo escuro. Planeje as imagens e vídeos como inserts "
+                     "(split_top), que eles vão para o fundo, ou use tela_verde.fundo (ou "
+                     "\"fundo_original_desfocado\": true)")
+    elif items and cfg.runs and cfg.runs[0][2] is None:
+        what = "o vídeo original desfocado" if cfg.blurred_original else "um fundo escuro"
+        notes.append(f"o primeiro fundo começa em {cfg.runs[0][1] / fps:.2f}s: antes dele entra {what}")
+    cfg.run_notes = notes
+    cfg.warnings.extend(notes)
+
+
+def add_insert_backgrounds(cfg: Config, inserts: list[dict], nf: int, fps: int,
+                           probe: Callable[[Path | None, str], tuple[int, int] | None] = media_size) -> list[Background]:
+    """split_top / split_bottom inserts -> background items that win over tela_verde.fundo during their own frames.
+
+    inserts: [{"insert": 1-based number, "type", "src" (Path), "kind", "f0", "f1", "ken_burns", "item" (the raw
+    dict, for escurecer / desfocar / encaixe)}]."""
+    added = []
+    for it in inserts:
+        where = f"inserts[{it['insert'] - 1}]"
+        raw = it.get("item") or {}
+        fit_asked = _fit_value(raw.get("encaixe"), where)
+        size = probe(it["src"], it["kind"])
+        fit = choose_fit(fit_asked, it["kind"], size, cfg.screen)
+        dk, blur = _look_values(raw, where, it["kind"], fit, cfg.warnings)
+        f0, f1 = int(it["f0"]), min(nf, int(it["f1"]))
+        if f1 <= f0:
+            continue
+        b = Background(idx=it["insert"], kind=it["kind"], src=it["src"], color=None, f0=f0, f1=f1,
+                       ken_burns=bool(it["ken_burns"]), darken=dk, blur=blur, asked=str(raw.get("src") or it["src"]),
+                       fit_asked=fit_asked, fit=fit, size=size, insert=it["insert"], insert_type=it["type"])
+        added.append(b)
+    # the fundo items first: an insert (drawn later in the list) wins during its own frames
+    cfg.backgrounds = [b for b in cfg.backgrounds if not b.insert] + added
+    set_runs(cfg, nf, fps)
+    return added
+
+
+def background_runs(items: list[Background], nf: int) -> list[tuple[int, int, int | None]]:
+    """(f0, f1, index in items or None): a later item wins; a gap keeps the item before it."""
+    owner = np.full(nf, -1, np.int32)
+    for k, b in enumerate(items):
+        owner[b.f0:b.f1] = k
+    last = -1
+    for f in range(nf):          # gaps: hold the previous background
+        if owner[f] < 0:
+            owner[f] = last
+        else:
+            last = owner[f]
+    runs: list[tuple[int, int, int | None]] = []
+    start = 0
+    for f in range(1, nf + 1):
+        if f == nf or owner[f] != owner[start]:
+            runs.append((start, f, int(owner[start]) if owner[start] >= 0 else None))
+            start = f
+    return runs
+
+
+# ================================================================== placement
+
+@dataclass
+class Segment:
+    f0: int
+    f1: int
+    mode: str                        # pessoa | original
+    zoom: float = 1.0
+    zoom_max: float = 1.0
+    push: float = 0.0                # push_in amount (0 = none)
+    focus_y: float = 0.4             # eye line of the cut frame (zoom anchor of an original segment)
+    stats: dict | None = None
+    scale: float = 1.0               # camera frame -> screen, before the zoom
+    flush_left: bool = False
+    flush_right: bool = False
+    face: dict | None = None         # face_layout face / zone / core (fractions of the cut frame)
+    side: str | None = None          # esquerda | direita: this segment sits on that side (its face is cut there)
+    fill: bool = False               # corner, cut on both sides: the camera frame fills the screen width
+    drop: float = 0.0                # fill: share of the camera frame below the bottom of the screen
+    note: str = ""
+
+    @property
+    def frames(self) -> int:
+        return self.f1 - self.f0
+
+    def zoom_at(self, f: int) -> float:
+        if self.push <= 0 or self.frames <= 1:
+            return self.zoom
+        return self.zoom * (1.0 + self.push * ease((f - self.f0) / (self.frames - 1)))
+
+
+def base_scale(cfg: Config, st: dict) -> float:
+    top = float(st.get("top", 0.0))
+    s = cfg.height / max(0.05, 1.0 - top)
+    width = max(0.05, float(st.get("right", 1.0)) - float(st.get("left", 0.0)))
+    s = min(s, (CENTER_MAX_WIDTH if cfg.position == "centro" else CORNER_MAX_WIDTH) / width)
+    if (cfg.position == "centro" and float(st.get("touch_left", 0)) >= TOUCH_FLUSH
+            and float(st.get("touch_right", 0)) >= TOUCH_FLUSH and s < 1.0 and s * CENTER_FILL >= 1.0):
+        s = 1.0                  # cut on both sides: fill the width instead of showing two cut edges
+    return min(MAX_SCALE, max(0.05, s))
+
+
+def mirror_stats(st: dict | None) -> dict | None:
+    """Placement numbers of a flipped camera frame."""
+    if not st or not st.get("person_frames"):
+        return st
+    out = dict(st)
+    out["left"] = round(1.0 - float(st.get("right", 1.0)), 5)
+    out["right"] = round(1.0 - float(st.get("left", 0.0)), 5)
+    out["head_cx"] = round(1.0 - float(st.get("head_cx", 0.5)), 5)
+    out["touch_left"], out["touch_right"] = st.get("touch_right", 0), st.get("touch_left", 0)
+    return out
+
+
+def mirror_face(face: dict | None) -> dict | None:
+    """face_layout segment (face / zone / core boxes) of a flipped camera frame."""
+    if not isinstance(face, dict):
+        return face
+    out = dict(face)
+    for key in ("face", "zone", "core"):
+        r = face.get(key)
+        if isinstance(r, dict) and "x0" in r and "x1" in r:
+            out[key] = {**r, "x0": round(1.0 - float(r["x1"]), 5), "x1": round(1.0 - float(r["x0"]), 5)}
+    return out
+
+
+def face_cut_sides(seg: "Segment") -> tuple[bool, bool]:
+    """(left, right): the detected face touches that side of the camera frame."""
+    f = seg.face.get("face") if isinstance(seg.face, dict) else None
+    if not isinstance(f, dict):
+        return False, False
+    try:
+        return float(f.get("x0", 0.5)) <= FACE_EDGE, float(f.get("x1", 0.5)) >= 1.0 - FACE_EDGE
+    except (TypeError, ValueError):
+        return False, False
+
+
+def plan_segments(cfg: Config, segs: list[Segment]) -> None:
+    """Scale and flush sides per person segment; segments close to the typical size share it (no jump at a cut
+    of the same take)."""
+    people = [s for s in segs if s.mode == "pessoa" and s.stats and s.stats.get("person_frames")]
+    for s in people:
+        st = s.stats
+        s.scale = base_scale(cfg, st)
+        cut_l, cut_r = face_cut_sides(s)
+        s.flush_left = float(st.get("touch_left", 0)) >= TOUCH_FLUSH or cut_l
+        s.flush_right = float(st.get("touch_right", 0)) >= TOUCH_FLUSH or cut_r
+        s.side = None
+        if cut_l != cut_r:
+            side = "esquerda" if cut_l else "direita"
+            if side != cfg.position:
+                s.side = side
+                s.note = (f"o rosto sai da câmera pela {side}: aqui você fica encostado na {side} "
+                          f"da tela, para o rosto não aparecer cortado no meio")
+    if people:
+        weights = sorted((s.scale, s.frames) for s in people)
+        half, acc, med = sum(w for _, w in weights) / 2.0, 0.0, weights[-1][0]
+        for v, w in weights:
+            acc += w
+            if acc >= half:
+                med = v
+                break
+        for s in people:
+            if abs(s.scale - med) <= 0.08 * med:
+                s.scale = med
+    if cfg.position != "centro":
+        # cut on both sides: in a corner one of the cuts would land in the middle of the screen (an arm or a
+        # shoulder ending on a vertical line), so the person fills the width instead, a little lower
+        for s in people:
+            st = s.stats
+            if min(float(st.get("touch_left", 0)), float(st.get("touch_right", 0))) < TOUCH_FLUSH:
+                continue
+            corner = s.scale
+            if corner >= 1.0 or 1.0 / corner > CORNER_FILL:
+                continue
+            top = float(st.get("top", 0.0))
+            s.fill, s.scale = True, 1.0
+            s.flush_left = s.flush_right = True
+            s.drop = round(min(FILL_DROP, max(0.0, (1.0 - top) * (1.0 - corner))), 5)
+    fallback = people[0] if people else None
+    for s in segs:
+        if s.mode == "pessoa" and s not in people:
+            s.note = "não achei a pessoa neste trecho: só o fundo aparece"
+            if fallback is not None:
+                s.scale = fallback.scale
+
+
+def layer_rect(cfg: Config, seg: Segment, z: float, W: int, H: int) -> tuple[float, float, float]:
+    """(scale, x0, y0) of the camera frame on the screen for zoom z (float px)."""
+    st = seg.stats or {}
+    s = seg.scale * z
+    lw, lh = W * s, H * s
+    y0 = H - lh
+    margin = SIDE_MARGIN * W / 1080.0
+    pos = seg.side or cfg.position
+    if seg.fill:
+        # both cut edges on or past the screen edges; the extra width goes to the side away from the corner
+        return s, (0.0 if pos == "direita" else W - lw), H - lh + seg.drop * lh
+    if pos == "direita":
+        x0 = W - lw if seg.flush_right else W - margin - float(st.get("right", 1.0)) * lw
+    elif pos == "esquerda":
+        x0 = 0.0 if seg.flush_left else margin - float(st.get("left", 0.0)) * lw
+    else:
+        x0 = W / 2.0 - float(st.get("head_cx", 0.5)) * lw
+        # a side the camera cut stays on (or past) the screen edge when the frame allows it
+        if seg.flush_left and seg.flush_right:
+            if lw >= W:
+                x0 = min(0.0, max(W - lw, x0))
+        elif seg.flush_left:
+            x0 = min(x0, 0.0)
+        elif seg.flush_right:
+            x0 = max(x0, W - lw)
+    return s, x0, y0
+
+
+def inner_cut(cfg: Config, segs: list[Segment], W: int, H: int) -> dict | None:
+    """Corner positions: how much of the person time shows the body cut by the camera inside the screen, and
+    what would look more natural. None when it is little (or centro)."""
+    if cfg.position == "centro":
+        return None
+    total = inner = both = 0.0
+    for s in segs:
+        if s.mode != "pessoa" or not s.stats or not s.stats.get("person_frames"):
+            continue
+        st = s.stats
+        sc, x0, _ = layer_rect(cfg, s, s.zoom, W, H)
+        lw = W * sc
+        pos = s.side or cfg.position
+        if pos == "direita":
+            t_in = float(st.get("touch_left", 0)) if x0 > 0.5 else 0.0
+            t_out = float(st.get("touch_right", 0))
+        else:
+            t_in = float(st.get("touch_right", 0)) if x0 + lw < W - 0.5 else 0.0
+            t_out = float(st.get("touch_left", 0))
+        total += s.frames
+        inner += s.frames * t_in
+        both += s.frames * min(t_in, t_out)
+    if total <= 0 or inner / total < INNER_CUT_WARN:
+        return None
+    other = "esquerda" if cfg.position == "direita" else "direita"
+    corner = "canto direito" if cfg.position == "direita" else "canto esquerdo"
+    if both / total >= INNER_CUT_WARN:
+        tip = "\"posicao\": \"centro\" (a câmera corta os dois lados do corpo)"
+        better = "centro"
+    else:
+        tip = (f"\"posicao\": \"{other}\" ou com \"espelhar\": true (se não tiver texto na roupa ou nos objetos "
+               f"que aparecem)")
+        better = other
+    return {"lado": other, "parte": round(inner / total, 3), "melhor": better, "espelhar": better == other,
+            "aviso": (f"a câmera corta seu corpo pela {other} em {inner / total * 100:.0f}% do tempo: no {corner} esse "
+                      f"corte aparece no meio da tela (braço ou ombro somem num degradê). Fica mais natural com {tip}")}
+
+
+def _map_rect(rect: dict, s: float, x0: float, y0: float, W: int, H: int) -> tuple[float, float, float, float]:
+    return (x0 + rect["x0"] * W * s, y0 + rect["y0"] * H * s, x0 + rect["x1"] * W * s, y0 + rect["y1"] * H * s)
+
+
+def _union(rects: list[tuple]) -> tuple:
+    return (min(r[0] for r in rects), min(r[1] for r in rects), max(r[2] for r in rects), max(r[3] for r in rects))
+
+
+def _frac(rect: tuple, W: int, H: int) -> dict:
+    return {"x0": round(max(0.0, rect[0] / W), 5), "y0": round(max(0.0, rect[1] / H), 5),
+            "x1": round(min(1.0, rect[2] / W), 5), "y1": round(min(1.0, rect[3] / H), 5)}
+
+
+def screen_zones(cfg: Config, seg: Segment, W: int, H: int) -> dict:
+    """Where the face and the body end up on the screen (fractions), over the zoom range of the segment.
+
+    -> {"face": {zone, core, eyes_y} | None, "person": rect | None}"""
+    if seg.mode != "pessoa" or not seg.stats or not seg.stats.get("person_frames"):
+        return {"face": None, "person": None}
+    st = seg.stats
+    zooms = {seg.zoom, seg.zoom * (1 + seg.push)}
+    places = [layer_rect(cfg, seg, z, W, H) for z in zooms]
+    body = {"x0": float(st.get("left", 0.0)), "y0": float(st.get("top", 0.0)),
+            "x1": float(st.get("right", 1.0)), "y1": 1.0}
+    person = _union([_map_rect(body, s, x, y, W, H) for s, x, y in places])
+    face = None
+    src = seg.face
+    if src and src.get("zone"):
+        zone = _union([_map_rect(src["zone"], s, x, y, W, H) for s, x, y in places])
+        core = _union([_map_rect(src.get("core") or src["zone"], s, x, y, W, H) for s, x, y in places])
+        eyes = src.get("face", {}).get("eyes_y") if isinstance(src.get("face"), dict) else None
+        eyes = eyes if eyes is not None else (src["zone"]["y0"] + src["zone"]["y1"]) / 2.0
+        s, _, y = places[0]
+        face = {"zone": _frac(zone, W, H), "core": _frac(core, W, H), "eyes_y": round((y + eyes * H * s) / H, 5)}
+    else:
+        # no face found by the detector: protect the top of the body (head) anyway
+        head_h = 0.28 * (1.0 - float(st.get("top", 0.0)))
+        cx = float(st.get("head_cx", 0.5))
+        head = {"x0": max(0.0, cx - 0.16), "y0": float(st.get("top", 0.0)), "x1": min(1.0, cx + 0.16),
+                "y1": float(st.get("top", 0.0)) + head_h}
+        zone = _union([_map_rect(head, s, x, y, W, H) for s, x, y in places])
+        s, _, y = places[0]
+        face = {"zone": _frac(zone, W, H), "core": _frac(zone, W, H),
+                "eyes_y": round((y + (head["y0"] + head_h * 0.45) * H * s) / H, 5)}
+    return {"face": face, "person": _frac(person, W, H)}
+
+
+# ================================================================== backgrounds
+
+def _darken(img: np.ndarray, amount: float) -> np.ndarray:
+    if amount <= 0:
+        return img
+    cv2 = _cv2()
+    return cv2.convertScaleAbs(img, alpha=1.0 - amount, beta=0)
+
+
+def _blur(img: np.ndarray, sigma: float, W: int) -> np.ndarray:
+    """Gaussian blur of `sigma` px (1080 wide), done at a smaller size (fast and the same look)."""
+    if sigma <= 0.3:
+        return img
+    cv2 = _cv2()
+    s = sigma * W / 1080.0
+    h, w = img.shape[:2]
+    k = max(1, min(8, int(s // 3)))
+    small = cv2.resize(img, (max(2, w // k), max(2, h // k)), interpolation=cv2.INTER_AREA)
+    small = cv2.GaussianBlur(small, (0, 0), s / k)
+    return cv2.resize(small, (w, h), interpolation=cv2.INTER_LINEAR)
+
+
+def _cover(img: np.ndarray, W: int, H: int, top: bool = False) -> np.ndarray:
+    cv2 = _cv2()
+    ih, iw = img.shape[:2]
+    sc = max(W / iw, H / ih)
+    nw, nh = max(W, int(math.ceil(iw * sc))), max(H, int(math.ceil(ih * sc)))
+    big = cv2.resize(img, (nw, nh), interpolation=cv2.INTER_AREA if sc < 1 else cv2.INTER_CUBIC)
+    x0 = (nw - W) // 2
+    y0 = 0 if top else (nh - H) // 2
+    return np.ascontiguousarray(big[y0:y0 + H, x0:x0 + W])
+
+
+def content_box(img: np.ndarray) -> tuple[float, float, float, float]:
+    """The main area of a picture (fractions): where it differs from its border color, so the empty margin of a
+    print may go behind the captions or the person. A busy border (a photo) means the whole picture matters."""
+    cv2 = _cv2()
+    ih, iw = img.shape[:2]
+    k = max(1, int(round(max(iw, ih) / 320)))
+    small = cv2.resize(img, (max(8, iw // k), max(8, ih // k)), interpolation=cv2.INTER_AREA).astype(np.int16)
+    sh, sw = small.shape[:2]
+    ring = max(1, int(round(min(sw, sh) * 0.03)))
+    border = np.concatenate([small[:ring].reshape(-1, 3), small[-ring:].reshape(-1, 3),
+                             small[:, :ring].reshape(-1, 3), small[:, -ring:].reshape(-1, 3)])
+    ref = np.median(border, axis=0)
+    spread = float(np.percentile(np.abs(border - ref).max(axis=1), 90))
+    whole = (0.0, 0.0, 1.0, 1.0)
+    if spread > 24:
+        return whole
+    diff = np.abs(small - ref).max(axis=2) > max(28.0, spread + 16.0)
+    rows = np.flatnonzero(diff.mean(axis=1) > 0.015)
+    cols = np.flatnonzero(diff.mean(axis=0) > 0.015)
+    if rows.size == 0 or cols.size == 0:
+        return whole
+    pad = 0.02
+    box = (max(0.0, cols[0] / sw - pad), max(0.0, rows[0] / sh - pad),
+           min(1.0, (cols[-1] + 1) / sw + pad), min(1.0, (rows[-1] + 1) / sh + pad))
+    if box[2] - box[0] > 0.9 and box[3] - box[1] > 0.9:
+        return whole
+    return tuple(round(v, 4) for v in box)
+
+
+def whole_place(size: tuple[int, int], content: tuple[float, float, float, float], stage: tuple[float, float],
+                W: int, H: int, min_share: float = WHOLE_MIN) -> tuple[int, int, int, int]:
+    """x, y, w, h of a picture shown whole: as wide as the screen, smaller (down to min_share of the width) only
+    when its main area does not fit the stage, main area centered in the stage (or on its top when it still does
+    not fit)."""
+    iw, ih = size
+    top, bottom = stage
+    room = max(1.0, bottom - top)
+    s = W / iw
+    main = max(1e-6, (content[3] - content[1]) * ih)
+    if main * s > room:
+        s = max(room / main, min_share * W / iw)
+    w = min(W, max(2, int(round(iw * s))))
+    h = max(2, int(round(ih * s)))
+    x = (W - w) // 2
+    c0, c1 = content[1] * h, content[3] * h
+    y = (top + bottom) / 2.0 - (c0 + c1) / 2.0 if c1 - c0 <= room + 0.5 else top - c0
+    return (x, int(round(y)), w, h)
+
+
+def backdrop(img: np.ndarray, W: int, H: int) -> np.ndarray:
+    """A blurred, desaturated and darkened cover copy of img, made at 1/8 size (behind a picture shown whole)."""
+    cv2 = _cv2()
+    sw, sh = max(2, int(round(W / 8))), max(2, int(round(H / 8)))
+    ih, iw = img.shape[:2]
+    sc = max(sw / iw, sh / ih)
+    nw, nh = max(sw, int(math.ceil(iw * sc))), max(sh, int(math.ceil(ih * sc)))
+    small = cv2.resize(img, (nw, nh), interpolation=cv2.INTER_AREA)
+    x0, y0 = (nw - sw) // 2, (nh - sh) // 2
+    small = cv2.GaussianBlur(np.ascontiguousarray(small[y0:y0 + sh, x0:x0 + sw]), (0, 0), BACKDROP["sigma"] * sw / 1080.0)
+    gray = cv2.cvtColor(cv2.cvtColor(small, cv2.COLOR_RGB2GRAY), cv2.COLOR_GRAY2RGB)
+    small = cv2.addWeighted(small, BACKDROP["saturation"], gray, 1.0 - BACKDROP["saturation"], 0)
+    small = cv2.convertScaleAbs(small, alpha=1.0 - BACKDROP["darken"], beta=0)
+    return cv2.resize(small, (W, H), interpolation=cv2.INTER_LINEAR)
+
+
+def detail_map(img: np.ndarray) -> np.ndarray:
+    """0/1 per pixel of a small frame: detail (an edge, an object) against its blurred surroundings."""
+    cv2 = _cv2()
+    f = img.astype(np.float32)
+    sigma = 6.0 * max(img.shape[:2]) / SCAN_SIDE
+    return (np.abs(f - cv2.GaussianBlur(f, (0, 0), sigma)).max(axis=2) > SCAN_DETAIL).astype(np.float32)
+
+
+def quiet_border(acc: np.ndarray) -> bool:
+    """acc: share of detail per pixel. A plain top and bottom border (a studio wall and floor, a flat color) has
+    almost none; those are the borders carried out to the screen (the sides of a full-width video are the
+    screen's)."""
+    h, w = acc.shape
+    r = max(1, int(round(min(h, w) * QUIET_RING[0])))
+    return max(float(acc[:r].mean()), float(acc[-r:].mean())) < QUIET_RING[1]
+
+
+def scan_video(path: Path, fps: int, cache_dir: Path | None = None) -> dict:
+    """What a background video has where: {frames (one pass at fps), lead and tail (empty frames at its start and
+    end, at most a third of it each; a tail also covers a clip shrinking away after its last full frame),
+    content (main area, fractions, over the whole clip), quiet (plain border)}. Cached by the file signature."""
+    cv2 = _cv2()
+    st = path.stat()
+    key = hashlib.sha1(json.dumps([SCAN_VERSION, str(path), st.st_size, st.st_mtime_ns, fps, SCAN_SIDE, SCAN_DETAIL,
+                                   SCAN_EMPTY, SCAN_FADE, SCAN_ROW, SCAN_MASS,
+                                   QUIET_RING]).encode("utf-8")).hexdigest()[:16]
+    cached = cache_dir / f"scan_{key}.json" if cache_dir else None
+    if cached and cached.exists():
+        data = M.load_json(cached) or {}
+        if data.get("key") == key:
+            return data
+    size = media_size(path, "video") or (SCAN_SIDE, SCAN_SIDE)
+    k = SCAN_SIDE / max(size)
+    sw, sh = max(8, int(round(size[0] * k / 2)) * 2), max(8, int(round(size[1] * k / 2)) * 2)
+    cmd = M._ff() + ["-i", str(path), "-map", "0:v:0", "-an", "-vf",
+                     f"fps={fps},scale={sw}:{sh}:flags=area,setsar=1,format=rgb24", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
+    reader = M.FrameReader(cmd, (sw, sh), 3, "ler o vídeo do fundo", queue_len=8)
+    energy: list[float] = []
+    acc = np.zeros((sh, sw), np.float32)
+    try:
+        while True:
+            fr = reader.read()
+            if fr is None:
+                break
+            d = detail_map(fr)
+            energy.append(float(d.mean()))
+            acc += d
+    finally:
+        reader.close()
+    n = len(energy)
+    out = {"key": key, "frames": n, "lead": 0, "tail": 0, "content": [0.0, 0.0, 1.0, 1.0], "quiet": False}
+    if n:
+        acc /= n
+        e = np.array(energy)
+        med = float(np.median(e))
+        empty = max(SCAN_EMPTY[0], SCAN_EMPTY[1] * med)
+        thin = e < max(empty, SCAN_EMPTY[2] * med)
+
+        def run(flags: np.ndarray, edge: float) -> int:
+            """Frames from that end that are empty or still building up (0 unless the end frame is empty; 0 in a
+            clip with no detail at all, a flat color)."""
+            if edge >= empty or med < SCAN_EMPTY[0]:
+                return 0
+            full = np.flatnonzero(~flags)
+            return int(full[0]) if full.size else n
+        def fade_out() -> int:
+            """Frames after the last full one of a clip that shrinks away to nothing (an X that shrinks after it
+            landed): the fall from its last peak, past the frames with SCAN_FADE[1] of that peak."""
+            if float(e[-1]) >= empty or med < SCAN_EMPTY[0]:
+                return 0
+            i = n - 1
+            while i > 0 and e[i - 1] >= e[i] - SCAN_FADE[0] * med:
+                i -= 1
+            fall = e[i:]
+            kept = np.flatnonzero(fall >= SCAN_FADE[1] * float(fall.max()))
+            return n - 1 - (i + int(kept[-1]))
+        out["lead"] = int(min(run(thin, float(e[0])), n // 3))
+        out["tail"] = int(min(max(run(thin[::-1], float(e[-1])), fade_out()), n // 3))
+        rm, cm = acc.mean(axis=1), acc.mean(axis=0)
+        rows = np.flatnonzero(rm > max(SCAN_ROW, 0.1 * float(rm.max())))
+        cols = np.flatnonzero(cm > max(SCAN_ROW, 0.1 * float(cm.max())))
+        if rows.size and cols.size:
+            pad = 0.02
+            box = [max(0.0, cols[0] / sw - pad), max(0.0, rows[0] / sh - pad),
+                   min(1.0, (cols[-1] + 1) / sw + pad), min(1.0, (rows[-1] + 1) / sh + pad)]
+            if not (box[2] - box[0] > 0.9 and box[3] - box[1] > 0.9):      # a busy clip is all main area
+                cum = np.cumsum(rm) / max(1e-9, float(rm.sum()))
+                cut = (1.0 - SCAN_MASS) / 2.0
+                r0 = max(int(rows[0]), int(np.searchsorted(cum, cut)))
+                r1 = min(int(rows[-1]) + 1, int(np.searchsorted(cum, 1.0 - cut)) + 1)
+                box[1], box[3] = max(0.0, r0 / sh - pad), min(1.0, r1 / sh + pad)
+                out["content"] = [round(float(v), 4) for v in box]
+        out["quiet"] = quiet_border(acc)
+    if cached:
+        cached.parent.mkdir(parents=True, exist_ok=True)
+        M.save_json(cached, out)
+    return out
+
+
+def extend_weights(place: tuple[int, int, int, int], W: int, H: int) -> np.ndarray:
+    """0 on a plain-border copy and 1 far from it (EXTEND fall), at 1/8 size: how far the border color has
+    faded into its darker average."""
+    sw, sh = max(2, int(round(W / 8))), max(2, int(round(H / 8)))
+    x, y, w, h = (v / 8.0 for v in place)
+    xs = np.arange(sw, dtype=np.float32) + 0.5
+    ys = np.arange(sh, dtype=np.float32) + 0.5
+    dx = np.maximum(0.0, np.maximum(x - xs, xs - (x + w)))
+    dy = np.maximum(0.0, np.maximum(y - ys, ys - (y + h)))
+    d = np.sqrt(dx[None, :] ** 2 + dy[:, None] ** 2) / max(1.0, EXTEND["fall"] * W / 1080.0 / 8.0)
+    t = np.clip(d, 0, 1)
+    return (t * t * (3 - 2 * t)).astype(np.float32)
+
+
+def extend_backdrop(sharp: np.ndarray, place: tuple[int, int, int, int], W: int, H: int,
+                    weights: np.ndarray) -> np.ndarray:
+    """The screen around a plain-border copy: its own border carried outwards (blurred) and fading into its
+    average color, a little darker, so the copy has no visible box."""
+    cv2 = _cv2()
+    sw, sh = weights.shape[1], weights.shape[0]
+    x, y, w, h = place
+    cw, ch = max(1, int(round(w / 8))), max(1, int(round(h / 8)))
+    small = cv2.resize(sharp, (cw, ch), interpolation=cv2.INTER_AREA)
+    x8, y8 = int(round(x / 8)), int(round(y / 8))
+    # the part of the small copy on the screen, then its border carried to the screen edges
+    cx0, cy0 = max(0, -x8), max(0, -y8)
+    cx1, cy1 = min(cw, sw - x8), min(ch, sh - y8)
+    if cx1 <= cx0 or cy1 <= cy0:
+        part = small
+        top = bottom = left = right = 0
+        canvas = cv2.resize(small, (sw, sh), interpolation=cv2.INTER_AREA)
+    else:
+        part = np.ascontiguousarray(small[cy0:cy1, cx0:cx1])
+        top, left = max(0, y8), max(0, x8)
+        bottom, right = max(0, sh - top - part.shape[0]), max(0, sw - left - part.shape[1])
+        canvas = cv2.copyMakeBorder(part, top, bottom, left, right, cv2.BORDER_REPLICATE)[:sh, :sw]
+    sigma = EXTEND["blur"] * W / 1080.0 / 8.0
+    canvas = cv2.GaussianBlur(canvas, (0, 0), sigma).astype(np.float32)
+    ring = np.concatenate([part[:1].reshape(-1, 3), part[-1:].reshape(-1, 3), part[:, :1].reshape(-1, 3),
+                           part[:, -1:].reshape(-1, 3)]).astype(np.float32)
+    flat = np.median(ring, axis=0) * (1.0 - EXTEND["darken"])
+    t = weights[..., None]
+    out = canvas * (1.0 - t) + flat[None, None, :] * t
+    return cv2.resize(np.clip(out, 0, 255).astype(np.uint8), (W, H), interpolation=cv2.INTER_LINEAR)
+
+
+def feather_mask(w: int, h: int, x: int, y: int, W: int, H: int) -> np.ndarray:
+    """Blend weights of a sharp copy at (x, y): smooth ramps on the sides that fall inside the screen."""
+    f = max(2, int(round(BACKDROP["feather"] * W / 1080.0)))
+
+    def ramp(n: int, lead: bool, trail: bool) -> np.ndarray:
+        r = np.ones(n, np.float32)
+        m = min(f, n // 4)
+        if m > 1:
+            e = np.linspace(0.0, 1.0, m, dtype=np.float32)
+            e = e * e * (3 - 2 * e)
+            if lead:
+                r[:m] = np.minimum(r[:m], e)
+            if trail:
+                r[n - m:] = np.minimum(r[n - m:], e[::-1])
+        return r
+
+    return np.ascontiguousarray(ramp(h, y > 0, y + h < H)[:, None] * ramp(w, x > 0, x + w < W)[None, :])
+
+
+def whole_frame(sharp: np.ndarray, place: tuple[int, int, int, int], W: int, H: int, mask: np.ndarray,
+                extend: np.ndarray | None = None) -> np.ndarray:
+    """The sharp copy (already w x h) at its place over the backdrop made from it (its own border carried
+    outwards when extend, the weights of extend_weights, is given)."""
+    cv2 = _cv2()
+    base = backdrop(sharp, W, H) if extend is None else extend_backdrop(sharp, place, W, H, extend)
+    x, y, w, h = place
+    if sharp.shape[1] != w or sharp.shape[0] != h:
+        sharp = cv2.resize(sharp, (w, h), interpolation=cv2.INTER_AREA if w < sharp.shape[1] else cv2.INTER_CUBIC)
+    X0, Y0, X1, Y1 = max(0, x), max(0, y), min(W, x + w), min(H, y + h)
+    if X1 <= X0 or Y1 <= Y0:
+        return base
+    part = np.ascontiguousarray(sharp[Y0 - y:Y1 - y, X0 - x:X1 - x])
+    m = np.ascontiguousarray(mask[Y0 - y:Y1 - y, X0 - x:X1 - x])
+    base[Y0:Y1, X0:X1] = cv2.blendLinear(np.ascontiguousarray(base[Y0:Y1, X0:X1]), part, 1.0 - m, m)
+    return base
+
+
+def picture_frame(img: np.ndarray, b: Background, W: int, H: int) -> tuple[np.ndarray, tuple[float, float]]:
+    """A still picture on the screen -> (frame, Ken Burns center)."""
+    cv2 = _cv2()
+    ih, iw = img.shape[:2]
+    if b.fit == "inteiro" and b.place:
+        x, y, w, h = b.place
+        sharp = cv2.resize(img, (w, h), interpolation=cv2.INTER_AREA if w < iw else cv2.INTER_CUBIC)
+        frame = whole_frame(sharp, b.place, W, H, feather_mask(w, h, x, y, W, H))
+        c = b.content
+        return frame, (x + (c[0] + c[2]) / 2.0 * w, y + (c[1] + c[3]) / 2.0 * h)
+    tall = iw / ih < (W / H) / FIT_RATIO and W < H
+    return _cover(img, W, H, top=tall), (W / 2.0, H * 0.3 if tall else H / 2.0)
+
+
+def _kb_frame(base: np.ndarray, center: tuple[float, float], p: float, W: int, H: int) -> np.ndarray:
+    cv2 = _cv2()
+    z = 1.0 + KB_DRIFT * ease(p)
+    cx, cy = center
+    m = np.array([[z, 0.0, cx - z * cx], [0.0, z, cy - z * cy]], np.float32)
+    return cv2.warpAffine(base, m, (W, H), flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_REFLECT)
+
+
+def read_image(path: Path) -> np.ndarray:
+    from PIL import Image, ImageOps  # noqa: PLC0415
+    with Image.open(path) 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"))
+            im = bg
+        return np.ascontiguousarray(np.asarray(im.convert("RGB")))
+
+
+class LoopReader:
+    """Frames of a background video in order. Every pass plays untouched (an insert shows its clip frame by frame,
+    as in the split screen), except its empty frames: the `lead` empty frames at the start show the first frame
+    with something in it and the `tail` ones at the end the last (a pass never flashes an empty scene;
+    first_lead replaces lead on the first pass, 0 when a dissolve covers the start). Only
+    when the clip has to go on past its end does it start again (a new ffmpeg reader), and the first `fade`
+    frames of the new pass dissolve from the last frame shown, so the loop neither jumps nor freezes."""
+
+    def __init__(self, cmd: list[str], size: tuple[int, int], what: str, fade: int, lead: int = 0, tail: int = 0,
+                 frames: int = 0, first_lead: int | None = None):
+        self.cmd, self.size, self.what = cmd, size, what
+        self.fade = max(0, int(fade))
+        self.lead, self.tail, self.frames = max(0, int(lead)), max(0, int(tail)), max(0, int(frames))
+        self.first_lead = self.lead if first_lead is None else max(0, int(first_lead))   # the first pass
+        self.cur: M.FrameReader | None = self._open()
+        self.cycle = 0                              # frames given from the current pass
+        self.length = 0                             # frames of one pass (known when the first one ends)
+        self.shown: np.ndarray | None = None        # the last frame given (before a dissolve)
+        self.ahead = 0                              # frames of this pass already read (the empty start)
+        self.hold: np.ndarray | None = None         # the frame shown over the empty start or end
+        self.blend_from: np.ndarray | None = None   # the last frame of the pass before, while the new one dissolves in
+        self.blend_n = 0
+        self.loops = 0
+
+    def _open(self) -> "M.FrameReader":
+        return M.FrameReader(self.cmd, self.size, 3, self.what, queue_len=4)
+
+    def read(self) -> np.ndarray | None:
+        if self.cur is None:
+            return None
+        if self.ahead > 0:
+            self.ahead -= 1
+            return self._give(self.hold)
+        fr = self.cur.read()
+        if fr is None:
+            if self.cycle == 0 or self.shown is None:
+                self.close()
+                return None
+            self.length = self.length or self.cycle
+            self.cur.close()
+            self.cur = self._open()
+            self.loops += 1
+            self.cycle = 0
+            self.blend_from, self.blend_n = self.shown, min(self.fade, self.length // 3)
+            fr = self.cur.read()
+            if fr is None:
+                self.close()
+                return None
+        i = self.cycle
+        lead = self.first_lead if self.loops == 0 else self.lead
+        if i == 0 and lead > 0:
+            for _ in range(lead):
+                nxt = self.cur.read()
+                if nxt is None:
+                    break
+                fr = nxt
+                self.ahead += 1
+            self.hold = fr
+        elif self.frames and self.tail > 0 and i >= self.frames - self.tail and self.hold is not None:
+            fr = self.hold
+        if self.frames and self.tail > 0 and i == self.frames - self.tail - 1:
+            self.hold = fr
+        return self._give(fr)
+
+    def _give(self, fr: np.ndarray) -> np.ndarray:
+        self.cycle += 1
+        self.shown = fr
+        if self.blend_from is not None and self.cycle <= self.blend_n:
+            w = self.cycle / (self.blend_n + 1)
+            return _cv2().addWeighted(self.blend_from, 1.0 - w, fr, w, 0)
+        self.blend_from = None
+        return fr
+
+    def close(self) -> None:
+        if self.cur is not None:
+            self.cur.close()
+            self.cur = None
+
+
+class BackgroundTrack:
+    """Background frames in order: fetch(f) reads what has to be read in order (video frames) and returns a
+    function that makes the frame (run in the worker threads)."""
+
+    def __init__(self, cfg: Config, W: int, H: int, fps: int):
+        self.cfg, self.W, self.H, self.fps = cfg, W, H, fps
+        self.runs = cfg.runs
+        self.run_i = 0
+        self.stills: dict[int, tuple[np.ndarray, tuple[float, float]]] = {}
+        self.videos: dict[int, dict] = {}
+        self.masks: dict[int, np.ndarray] = {}
+        self.dark = np.empty((H, W, 3), np.uint8)
+        self.dark[:] = np.array(hex_rgb(DARK_DEFAULT), np.uint8)
+        self.ends: dict[int, int] = {}
+        for f0, f1, k in cfg.runs:       # a background lasts until the last run it owns (gaps included)
+            if k is not None:
+                self.ends[k] = max(self.ends.get(k, 0), f1)
+        self.extends: dict[int, np.ndarray] = {}
+        self.last: tuple[int, int | None, Callable[[], np.ndarray]] | None = None   # (frame, owner, make)
+        self.dissolve: tuple[int, np.ndarray | None] | None = None                 # (owner, frame it comes from)
+        self.no_hold: set[int] = set()   # videos whose empty start plays under a dissolve (first pass)
+
+    def kb_span(self, k: int) -> int:
+        """Frames of the Ken Burns: the item's own time, stretched over a held gap up to KB_HOLD_AFTER times it."""
+        b = self.cfg.backgrounds[k]
+        own = max(1, b.f1 - b.f0)
+        total = max(own, self.ends.get(k, b.f1) - b.f0)
+        return max(1, min(total, int(round(own * KB_HOLD_AFTER))) - 1)
+
+    def _still(self, k: int) -> tuple[np.ndarray, tuple[float, float]]:
+        if k not in self.stills:
+            b = self.cfg.backgrounds[k]
+            if b.kind == "color":
+                frame = np.empty((self.H, self.W, 3), np.uint8)
+                frame[:] = np.array(b.color, np.uint8)
+                self.stills[k] = (_darken(frame, b.darken), (self.W / 2.0, self.H / 2.0))
+            else:
+                frame, center = picture_frame(read_image(b.src), b, self.W, self.H)
+                frame = _darken(_blur(frame, b.blur, self.W), b.darken)
+                self.stills[k] = (frame, center)
+        return self.stills[k]
+
+    def _mask(self, k: int) -> np.ndarray:
+        if k not in self.masks:
+            b = self.cfg.backgrounds[k]
+            x, y, w, h = b.place
+            self.masks[k] = feather_mask(w, h, x, y, self.W, self.H)
+            if b.quiet:
+                self.extends[k] = extend_weights(b.place, self.W, self.H)
+        return self.masks[k]
+
+    def _video_raw(self, k: int, local: int) -> np.ndarray:
+        b = self.cfg.backgrounds[k]
+        v = self.videos.get(k)
+        if v is None:
+            if b.fit == "inteiro" and b.place:
+                size = (b.place[2], b.place[3])
+                vf = f"fps={self.fps},scale={size[0]}:{size[1]}:flags=bicubic,setsar=1,format=rgb24"
+            else:
+                size = (self.W, self.H)
+                vf = (f"fps={self.fps},scale={self.W}:{self.H}:force_original_aspect_ratio=increase:flags=bicubic,"
+                      f"crop={self.W}:{self.H},setsar=1,format=rgb24")
+            cmd = M._ff() + ["-i", str(b.src), "-map", "0:v:0", "-an", "-vf", vf, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
+            v = {"reader": LoopReader(cmd, size, "ler o vídeo do fundo", int(round(LOOP_FADE * self.fps)),
+                                      lead=b.lead, tail=b.tail, frames=b.pass_frames,
+                                      first_lead=0 if k in self.no_hold else None),
+                 "pos": 0, "last": None}
+            self.videos[k] = v
+        while v["pos"] <= local:
+            fr = v["reader"].read()
+            if fr is None:
+                break
+            v["last"] = fr
+            v["pos"] += 1
+        if v["last"] is None:
+            raise TelaVerdeError(f"não consegui ler o vídeo do fundo ({b.name}): {b.src}", 1)
+        return v["last"]
+
+    def _video_frame(self, k: int, raw: np.ndarray, local: int) -> np.ndarray:
+        b = self.cfg.backgrounds[k]
+        frame, center = raw, (self.W / 2.0, self.H / 2.0)
+        if b.fit == "inteiro" and b.place:
+            frame = whole_frame(raw, b.place, self.W, self.H, self._mask(k), self.extends.get(k))
+            x, y, w, h = b.place
+            center = (x + w / 2.0, y + h / 2.0)
+        if b.ken_burns:
+            frame = _kb_frame(frame, center, min(1.0, local / self.kb_span(k)), self.W, self.H)
+        frame = _darken(_blur(frame, b.blur, self.W), b.darken)
+        return frame if frame is not raw else frame.copy()
+
+    def owner(self, f: int) -> int | None:
+        while self.run_i < len(self.runs) - 1 and f >= self.runs[self.run_i][1]:
+            self.run_i += 1
+        return self.runs[self.run_i][2]
+
+    def fetch(self, f: int, original: np.ndarray | None) -> Callable[[], np.ndarray]:
+        k = self.owner(f)
+        src, w = None, 1.0
+        if k is not None:
+            b = self.cfg.backgrounds[k]
+            local = f - b.f0
+            if b.kind == "video" and b.lead > 0 and local < b.lead:
+                # the clip starts empty: the background right before it dissolves into it while it builds up
+                # (its own frames play under the dissolve); with nothing before it, its first full frame is held
+                if self.dissolve is None or self.dissolve[0] != k:
+                    prev = self.last
+                    first = local == 0 and prev and prev[0] == f - 1 and prev[1] is not None and prev[1] != k
+                    self.dissolve = (k, prev[2]() if first else None)
+                    if first and k not in self.videos:
+                        self.no_hold.add(k)
+                src = self.dissolve[1]
+                w = (local + 1) / (b.lead + 1)
+        make = self._make(f, k, original)
+        if src is not None:
+            inner = make
+            make = lambda: _cv2().addWeighted(src, 1.0 - w, inner(), w, 0)  # noqa: E731
+        self.last = (f, k, make)
+        return make
+
+    def _make(self, f: int, k: int | None, original: np.ndarray | None) -> Callable[[], np.ndarray]:
+        W, H = self.W, self.H
+        if k is None:
+            if self.cfg.blurred_original and original is not None:
+                return lambda: _darken(_blur(original, ORIGINAL_BLUR["sigma"], W), ORIGINAL_BLUR["darken"])
+            return self.dark.copy
+        b = self.cfg.backgrounds[k]
+        local = f - b.f0
+        if b.kind == "video":
+            raw = self._video_raw(k, local)
+            if k not in self.masks and b.fit == "inteiro" and b.place:
+                self._mask(k)            # made once, here, before the workers share it
+            return lambda: self._video_frame(k, raw, local)
+        base, center = self._still(k)
+        if b.ken_burns:
+            p = min(1.0, local / self.kb_span(k))
+            return lambda: _kb_frame(base, center, p, W, H)
+        return base.copy
+
+    def frame(self, f: int, original: np.ndarray | None) -> np.ndarray:
+        return self.fetch(f, original)()
+
+    def close(self) -> None:
+        for v in self.videos.values():
+            v["reader"].close()
+        self.videos.clear()
+
+
+# ================================================================== room plate (the room of a tripod shot)
+
+def _ss(x: np.ndarray, a: float, b: float) -> np.ndarray:
+    t = np.clip((x - a) / (b - a), 0.0, 1.0)
+    return t * t * (3.0 - 2.0 * t)
+
+
+def plate_size(full: tuple[int, int]) -> tuple[int, int]:
+    """The plate works at the matte work size (half the output)."""
+    return max(2, (full[0] // 2) // 2 * 2), max(2, (full[1] // 2) // 2 * 2)
+
+
+@dataclass
+class RoomPlate:
+    """What the room behind a take looks like, learned from every other frame of its ranges where the matte says
+    room (the camera on a tripod). evidence() finds where a frame's matte is unsure (a haze, a patch the model
+    flickers on) and the picture there is exactly that room: those pieces go (a dark room only when it is unlike
+    the body next to it), and so does each pixel of a light halo of the room around a darker body. A matte that
+    is sure is never touched (a kept object), nor is the rest of the soft edge of the body or a dark shirt
+    blurred over a dark desk; clean_edge() takes the room's color out of that soft edge."""
+    key: str
+    size: tuple[int, int]
+    P: np.ndarray                 # blurred room color (float32 h x w x 3)
+    rel: np.ndarray               # 0..1 how much the plate is trusted there
+    tol: np.ndarray               # color distance that still is the room there
+    known: float = 0.0            # share of the frame the plate knows
+    spread: float = 0.0           # median spread of the room color (0-255)
+    mask: np.ndarray | None = None
+
+    def __post_init__(self):
+        self.mask = self.rel > 0.02
+
+    def evidence(self, frame: np.ndarray, alpha: np.ndarray) -> np.ndarray | None:
+        """frame: RGB uint8 at the plate size; alpha: 0..1. -> 0..1 map of room to take out of the matte (None
+        when there is none)."""
+        cv2 = _cv2()
+        lo, hi = PLATE["unsure"]
+        cand = self.mask & (alpha > 0.02) & (alpha < hi)
+        rows = np.flatnonzero(cand.any(axis=1))
+        if rows.size == 0:
+            return None
+        cols = np.flatnonzero(cand.any(axis=0))
+        w, h = self.size
+        pad = PLATE["unsure_px"] + 8
+        y0, y1 = max(0, int(rows[0]) - pad), min(h, int(rows[-1]) + pad + 1)
+        x0, x1 = max(0, int(cols[0]) - pad), min(w, int(cols[-1]) + pad + 1)
+        sl = (slice(y0, y1), slice(x0, x1))
+        img = cv2.GaussianBlur(np.ascontiguousarray(frame[sl]).astype(np.float32), (0, 0), PLATE["blur"])
+        a = alpha[sl]
+        room_P = self.P[sl]
+        tol = self.tol[sl]
+        win = PLATE["win"]
+        d1 = cv2.absdiff(img, room_P).max(axis=2)
+        d = cv2.blur(d1, (win, win))
+        # a dark room must look unlike the body next to it (a dark shirt blurred over a dark desk is left alone)
+        core = (a >= hi).astype(np.float32)
+        sig = PLATE["near"]
+        body = cv2.GaussianBlur(img * core[..., None], (0, 0), sig) / np.maximum(
+            cv2.GaussianBlur(core, (0, 0), sig), 1e-3)[..., None]
+        unlike = np.maximum(_ss(cv2.absdiff(body, room_P).max(axis=2), *PLATE["unlike"]),
+                            _ss(room_P.mean(axis=2), *PLATE["bright"]))
+        base = self.rel[sl] * (1.0 - _ss(a, lo, hi)) * cand[sl]
+        # a light halo of the room around a darker body goes pixel by pixel (only the pixels that are that room)
+        halo = (base * _ss(room_P.mean(axis=2) - body.mean(axis=2), *PLATE["halo"])
+                * (1.0 - _ss(d1, tol, tol + PLATE["width"])))
+        halo = np.where(halo > 0.05, halo, 0.0).astype(np.float32)
+        e = base * unlike * (1.0 - _ss(d, tol, tol + PLATE["width"]))
+        m = (e > PLATE["on"]).astype(np.uint8)
+        # only pieces wider than the soft edge of a body, rounded, and only when they reach the room around the
+        # person or the frame edge (a piece inside the body would leave a hole)
+        ker = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (PLATE["unsure_px"], PLATE["unsure_px"]))
+        m = cv2.morphologyEx(m, cv2.MORPH_OPEN, ker)
+        out_sl = halo
+        if m.any():
+            round_ = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (PLATE["round_px"], PLATE["round_px"]))
+            m = cv2.morphologyEx(cv2.morphologyEx(m, cv2.MORPH_CLOSE, round_), cv2.MORPH_OPEN, round_)
+            n, lab, st, _ = cv2.connectedComponentsWithStats(m, connectivity=8)
+            room = cv2.dilate((a < 0.5).astype(np.uint8), np.ones((5, 5), np.uint8)) > 0
+            keep = np.zeros(n, bool)
+            keep[np.unique(lab[room & (m > 0)])] = True
+            bx, by, bw, bh = st.T[:4]
+            keep |= (bx + x0 == 0) | (by + y0 == 0) | (bx + bw + x0 == w) | (by + bh + y0 == h)
+            keep[0] = False
+            k = keep[lab]
+            if k.any():
+                whole = cv2.GaussianBlur(cv2.dilate(k.astype(np.uint8), np.ones((3, 3), np.uint8)).astype(np.float32),
+                                         (0, 0), PLATE["soft"])
+                out_sl = np.maximum(out_sl, whole)
+        if not out_sl.any():
+            return None
+        out = np.zeros((h, w), np.float32)
+        out[sl] = out_sl
+        return out
+
+    def clean_edge(self, frame: np.ndarray, alpha: np.ndarray) -> np.ndarray:
+        """The colors of the soft edge of the matte without the known room mixed into them (a light or blue
+        fringe from the room behind): each partly transparent pixel is solved for the body color, where the plate
+        knows the room. frame: RGB uint8, alpha: uint8, both at the layer size. -> a new frame (or frame)."""
+        lo, hi = PLATE["edge"]
+        h, w = alpha.shape
+        pw, ph = self.size
+        ys, xs = np.nonzero((alpha > lo) & (alpha < hi))
+        if ys.size == 0:
+            return frame
+        py = np.minimum(ph - 1, (ys * ph) // h)
+        px = np.minimum(pw - 1, (xs * pw) // w)
+        rel = self.rel[py, px]
+        use = rel > 0.3
+        if not use.any():
+            return frame
+        ys, xs, py, px, rel = ys[use], xs[use], py[use], px[use], rel[use]
+        a = (alpha[ys, xs].astype(np.float32) / 255.0)[:, None]
+        img = frame[ys, xs].astype(np.float32)
+        B = self.P[py, px]
+        solved = (img - (1.0 - a) * B) / np.maximum(a, PLATE["edge_floor"])
+        out = frame.copy()
+        out[ys, xs] = np.clip(img + rel[:, None] * (solved - img), 0, 255).astype(np.uint8)
+        return out
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(".tmp-" + path.name)
+        with open(tmp, "wb") as fh:
+            np.savez_compressed(fh, P=self.P, rel=self.rel, tol=self.tol,
+                                meta=np.array(json.dumps({"key": self.key, "size": list(self.size),
+                                                          "known": self.known, "spread": self.spread})))
+        os.replace(tmp, path)
+
+    @staticmethod
+    def load(path: Path, key: str) -> RoomPlate | None:
+        try:
+            with np.load(path) as z:
+                meta = json.loads(str(z["meta"]))
+                if meta.get("key") != key:
+                    return None
+                return RoomPlate(key=key, size=tuple(meta["size"]), P=z["P"], rel=z["rel"], tol=z["tol"],
+                                 known=float(meta.get("known", 0.0)), spread=float(meta.get("spread", 0.0)))
+        except (OSError, ValueError, KeyError):
+            return None
+
+
+class _PlateAcc:
+    def __init__(self, size: tuple[int, int]):
+        w, h = size
+        self.size = size
+        self.sum = np.zeros((h, w, 3), np.float32)
+        self.sq = np.zeros((h, w, 3), np.float32)
+        self.n = np.zeros((h, w), np.float32)
+        cv2 = _cv2()
+        r = PLATE["fringe"]
+        self.ker = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * r + 1, 2 * r + 1))
+
+    def add(self, frame: np.ndarray, alpha: np.ndarray) -> None:
+        cv2 = _cv2()
+        room = (cv2.dilate((alpha >= PLATE["bg"]).astype(np.uint8), self.ker) == 0).astype(np.uint8)
+        x = frame.astype(np.float32)
+        cv2.accumulate(x, self.sum, room)
+        cv2.accumulateSquare(x, self.sq, room)
+        cv2.accumulate(room.astype(np.float32), self.n)
+
+    def finish(self, key: str) -> tuple[RoomPlate | None, str]:
+        cv2 = _cv2()
+        n = self.n
+        nn = np.maximum(n, 1.0)[..., None]
+        mean = self.sum / nn
+        std = np.sqrt(np.maximum(self.sq / nn - mean * mean, 0.0)).max(axis=2)
+        well = n >= PLATE["n"][1]
+        known = float(well.mean())
+        if known < PLATE["known"]:
+            return None, "o fundo quase não aparece nesses trechos"
+        spread = float(np.median(std[well]))
+        if spread > PLATE["static"]:
+            return None, "a câmera se mexe nesses trechos"
+        P = cv2.GaussianBlur(mean, (0, 0), PLATE["blur"]).astype(np.float32)
+        rel = (_ss(n, *PLATE["n"]) * (1.0 - _ss(std, *PLATE["std"]))).astype(np.float32)
+        tol = (PLATE["tol"] + np.minimum(std, PLATE["std"][0] + 2.0)).astype(np.float32)
+        return RoomPlate(key=key, size=self.size, P=P, rel=rel, tol=tol, known=round(known, 3),
+                         spread=round(spread, 2)), ""
+
+
+def room_plates(base: Path, base_pre: list[str], base_fps: float, fps: int, full_size: tuple[int, int],
+                groups: dict[str, list[tuple[int, int, M.RangeJob]]], cache_dir: Path,
+                progress: Callable[[str], None] | None = None) -> tuple[dict[str, RoomPlate], dict[str, str]]:
+    """One plate per take (groups: take -> [(f0, f1, matte job)]), read from the cut at the plate size in one
+    pass (only when a plate is not cached). -> ({take: plate}, {take: why there is none})."""
+    size = plate_size(full_size)
+    sig = M.file_signature(base)
+    keys, plates, notes = {}, {}, {}
+    for g, parts in groups.items():
+        keys[g] = hashlib.sha1(json.dumps([PLATE_VERSION, PLATE, str(base), sig, base_pre, fps, list(full_size),
+                                           sorted([a, b, j.key] for a, b, j in parts)],
+                                          sort_keys=True).encode("utf-8")).hexdigest()[:16]
+    todo = {}
+    for g, key in keys.items():
+        path = cache_dir / f"plate_{key}.npz"
+        note_path = cache_dir / f"plate_{key}.json"
+        if path.exists():
+            plate = RoomPlate.load(path, key)
+            if plate is not None:
+                plates[g] = plate
+                continue
+        if note_path.exists():
+            data = M.load_json(note_path) or {}
+            if data.get("key") == key:
+                notes[g] = str(data.get("note") or "")
+                continue
+        todo[g] = key
+    if not todo:
+        return plates, notes
+    started = time.time()
+    spans = sorted((a, b, g, j) for g in todo for a, b, j in groups[g])
+    last = max(b for a, b, _, _ in spans)
+    accs = {g: _PlateAcc(size) for g in todo}
+    reader = M.FrameReader(M.base_cmd(base, base_pre, base_fps, fps, 0, last, size=size, full_size=full_size),
+                           size, 3, "ler o corte", queue_len=8)
+    try:
+        f = 0
+        for a, b, g, job in spans:
+            while f < a:
+                if reader.read() is None:
+                    break
+                f += 1
+            mreader = M.FrameReader(M.matte_cmd(job.path, size, full_size), size, 1, "ler o recorte", queue_len=8)
+            try:
+                for k in range(b - a):
+                    frame = reader.read()
+                    alpha = mreader.read()
+                    f += 1
+                    if frame is None or alpha is None:
+                        break
+                    if k % PLATE["step"] == 0:
+                        accs[g].add(frame, alpha)
+            finally:
+                mreader.close()
+    finally:
+        reader.close()
+    for g, key in todo.items():
+        plate, note = accs[g].finish(key)
+        if plate is not None:
+            plate.save(cache_dir / f"plate_{key}.npz")
+            plates[g] = plate
+        else:
+            notes[g] = note
+            M.save_json(cache_dir / f"plate_{key}.json", {"key": key, "note": note})
+    if progress:
+        progress(f"tela verde: fundo do cenário aprendido em {time.time() - started:.1f}s")
+    return plates, notes
+
+
+# ================================================================== the person layer
+
+@dataclass
+class Look:
+    W: int
+    H: int
+    outline: tuple[np.ndarray, float] | None      # (rgb float, width px at this size)
+    shadow: bool
+    fade: float                                   # px at this size (the top cut)
+    side_fade: float | None = None                # px at this size (a side cut; None = fade)
+
+
+def _edge_profile(edge: np.ndarray) -> np.ndarray:
+    """0..1 along one edge of the camera frame: where the body touches it (widened and softened, so the fade
+    has no steps and covers the whole cut)."""
+    cv2 = _cv2()
+    n = edge.size
+    t = (edge > 127).astype(np.float32).reshape(-1, 1)
+    if not t.any():
+        return np.zeros(n, np.float32)
+    k = max(3, n // 40) | 1
+    t = cv2.dilate(t, np.ones((k, 1), np.uint8))
+    if n > 4:
+        t = cv2.GaussianBlur(t, (1, 0), sigmaX=0.1, sigmaY=k / 6.0)
+    return np.clip(t[:, 0], 0, 1)
+
+
+def enclosed_gaps(inside: np.ndarray, wall: np.ndarray) -> np.ndarray | None:
+    """0/1 map of the background pockets of `inside` (0/1) that do not reach the open border, or None. wall marks
+    the edges where the body goes on past the camera frame (the bottom, a cut side): a pocket that only reaches
+    the border through them is closed (the gap between an arm and the body, a hole in a hand)."""
+    cv2 = _cv2()
+    free = ((inside == 0) & (wall == 0)).astype(np.uint8)
+    if not free.any():
+        return None
+    n, lab = cv2.connectedComponents(free, connectivity=4)
+    border = np.concatenate([lab[0], lab[-1], lab[:, 0], lab[:, -1]])
+    outside = np.zeros(n, bool)
+    outside[np.unique(border)] = True
+    outside[0] = False
+    if not outside.any():
+        return None                   # nothing is open (a body filling the frame): leave it as it is
+    holes = (~outside[lab]) & (free > 0)
+    if not holes.any():
+        return None
+    holes = holes.astype(np.uint8)
+    return holes | (wall & (inside == 0) & cv2.dilate(holes, np.ones((3, 3), np.uint8)))
+
+
+def compose_person(bg: np.ndarray, person: np.ndarray, alpha: np.ndarray, s: float, x0: float, y0: float,
+                   look: Look) -> np.ndarray:
+    """Draw the cut-out person (scaled by s, camera frame corner at x0, y0) with outline and shadow onto bg."""
+    cv2 = _cv2()
+    W, H = look.W, look.H
+    ow = look.outline[1] if look.outline else 0.0
+    sh = SHADOW
+    k = W / 1080.0
+    pad = int(math.ceil(ow + (3 * sh["blur"] + max(sh["dx"], sh["dy"])) * k if look.shadow else ow)) + 2
+    lw, lh = int(round(W * s)), int(round(H * s))
+    lx, ly = int(round(x0)), int(round(y0))
+    if lw < 4 or lh < 4:
+        return bg
+    X0, Y0 = max(0, lx - pad), max(0, ly - pad)
+    X1, Y1 = min(W, lx + lw + pad), min(H, ly + lh + pad)
+    if X1 - X0 < 2 or Y1 - Y0 < 2:
+        return bg
+    interp = cv2.INTER_AREA if s < 1 else cv2.INTER_LINEAR
+    # only the part of the camera frame that lands on the screen
+    sx0, sx1 = max(0, X0 - lx), min(lw, X1 - lx)
+    sy0, sy1 = max(0, Y0 - ly), min(lh, Y1 - ly)
+    P = cv2.resize(person, (lw, lh), interpolation=interp)[sy0:sy1, sx0:sx1]
+    A = cv2.resize(alpha, (lw, lh), interpolation=interp)[sy0:sy1, sx0:sx1]
+    rw, rh = X1 - X0, Y1 - Y0
+    ox, oy = lx + sx0 - X0, ly + sy0 - Y0            # where P starts inside the region
+    A_reg = np.zeros((rh, rw), np.uint8)
+    A_reg[oy:oy + A.shape[0], ox:ox + A.shape[1]] = A
+    P_reg = np.zeros((rh, rw, 3), np.uint8)
+    P_reg[oy:oy + P.shape[0], ox:ox + P.shape[1]] = P
+
+    # edges where the camera frame cuts the body inside the screen: left, right, top
+    cuts = {}
+    e = max(2, alpha.shape[1] // 270)             # a body within this many px of the edge counts as cut by it
+    if lx > 0 and sx0 == 0:
+        cuts["left"] = _edge_profile(alpha[:, :e].max(axis=1))
+    if lx + lw < W and sx1 == lw:
+        cuts["right"] = _edge_profile(alpha[:, -e:].max(axis=1))
+    if ly > 0 and sy0 == 0:
+        cuts["top"] = _edge_profile(alpha[:e, :].max(axis=0))
+    cuts = {name: prof for name, prof in cuts.items() if prof.any()}
+    for name in list(cuts):     # the rows/columns of the edge profile map to the layer, then to the region
+        prof = cuts[name]
+        if name in ("left", "right"):
+            full = np.zeros(rh, np.float32)
+            rows = cv2.resize(prof.reshape(-1, 1), (1, lh), interpolation=cv2.INTER_LINEAR)[:, 0][sy0:sy1]
+            full[oy:oy + rows.size] = rows
+        else:
+            full = np.zeros(rw, np.float32)
+            cols = cv2.resize(prof.reshape(1, -1), (lw, 1), interpolation=cv2.INTER_LINEAR)[0][sx0:sx1]
+            full[ox:ox + cols.size] = cols
+        cuts[name] = full
+
+    # outline and shadow at half size; the matte is carried past the bottom edge, so neither draws a line along it
+    # (past a side or top cut the keep mask below removes them)
+    hw, hh = max(2, rw // 2), max(2, rh // 2)
+    Ah = cv2.resize(A_reg, (hw, hh), interpolation=cv2.INTER_AREA).astype(np.float32) / 255.0
+    hox = int(ox // 2)
+    hx1, hy1 = min(hw, int(math.ceil((ox + A.shape[1]) / 2))), min(hh, int(math.ceil((oy + A.shape[0]) / 2)))
+    if hy1 < hh and ly + lh >= H - 1:
+        Ah[hy1:, hox:hx1] = Ah[hy1 - 1:hy1, hox:hx1]
+    D = None
+    gaps = None
+    if look.outline:
+        oh = ow / 2.0
+        sm = cv2.GaussianBlur(Ah, (0, 0), max(0.6, oh / 2.5))
+        inside = ((sm > 0.5) | (Ah > 0.5)).astype(np.uint8)
+        # the outline goes around the body only: a gap it encloses (with the edges the body goes on past) stays
+        # see-through but gets no outline
+        wall = np.zeros((hh, hw), np.uint8)
+        hoy = int(oy // 2)
+        if hy1 > hoy and hx1 > hox:
+            if ly + lh >= H - 1:
+                wall[hy1 - 1, hox:hx1] = 1
+            if "top" in cuts:
+                wall[hoy, hox:hx1] = 1
+            if "left" in cuts:
+                wall[hoy:hy1, hox] = 1
+            elif lx <= 0:
+                wall[hoy:hy1, 0] = 1
+            if "right" in cuts:
+                wall[hoy:hy1, hx1 - 1] = 1
+            elif lx + lw >= W:
+                wall[hoy:hy1, hw - 1] = 1
+        gaps = enclosed_gaps(inside, wall)
+        if gaps is not None:
+            inside = inside | gaps
+        dist = cv2.distanceTransform(1 - inside, cv2.DIST_L2, cv2.DIST_MASK_PRECISE)
+        Dh = np.clip(oh + 0.5 - dist, 0, 1).astype(np.float32)
+        Dh = cv2.GaussianBlur(Dh, (0, 0), 0.6)
+        D = cv2.resize(Dh, (rw, rh), interpolation=cv2.INTER_LINEAR)
+    S = None
+    if look.shadow:
+        src = Dh if D is not None else Ah
+        q = cv2.resize(src, (max(2, hw // 2), max(2, hh // 2)), interpolation=cv2.INTER_AREA)
+        q = cv2.GaussianBlur(q, (0, 0), max(0.5, sh["blur"] * k / 4.0))
+        S = cv2.resize(q, (rw, rh), interpolation=cv2.INTER_LINEAR)
+        mshift = np.float32([[1, 0, sh["dx"] * k], [0, 1, sh["dy"] * k]])
+        S = cv2.warpAffine(S, mshift, (rw, rh), flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
+        S *= sh["alpha"]
+    if gaps is not None:
+        # an enclosed gap shows the background as it is: no outline color, no shadow in it (2 px wider, so the
+        # soft edge of the body around it blends with the background, not with the outline)
+        g = cv2.resize(cv2.dilate(gaps, np.ones((5, 5), np.uint8)).astype(np.float32), (rw, rh),
+                       interpolation=cv2.INTER_LINEAR)
+        gap_keep = 1.0 - g
+        if S is not None:
+            S = S * gap_keep
+
+    # keep mask: short fade on the cut rows near a cut edge, nothing past it
+    K = None
+    if cuts:
+        top_fade = max(2.0, look.fade)
+        side_fade = max(2.0, look.side_fade if look.side_fade is not None else look.fade)
+        K = np.ones((rh, rw), np.float32)
+        xs = np.arange(rw, dtype=np.float32)
+        ys = np.arange(rh, dtype=np.float32)
+
+        def ramp(d: np.ndarray, fade: float) -> np.ndarray:
+            r = np.clip(d / fade, 0, 1)
+            return r * r * (3 - 2 * r)
+        if "left" in cuts:
+            K *= 1.0 - cuts["left"][:, None] * (1.0 - ramp(xs - float(ox), side_fade)[None, :])
+        if "right" in cuts:
+            K *= 1.0 - cuts["right"][:, None] * (1.0 - ramp(float(ox + A.shape[1]) - xs, side_fade)[None, :])
+        if "top" in cuts:
+            K *= 1.0 - cuts["top"][None, :] * (1.0 - ramp(ys - float(oy), top_fade)[:, None])
+
+    region0 = bg[Y0:Y1, X0:X1]
+    region = region0
+    Af = A_reg.astype(np.float32) / 255.0
+    if D is not None:
+        D = np.maximum(D, Af)
+        if gaps is not None:
+            D *= gap_keep
+    if S is not None:
+        region = cv2.blendLinear(region, np.zeros_like(region), 1.0 - S, S)
+    if D is not None:
+        color = np.empty_like(region)
+        color[:] = look.outline[0].astype(np.uint8)
+        region = cv2.blendLinear(region, color, 1.0 - D, D)
+    region = cv2.blendLinear(region, P_reg, 1.0 - Af, Af)
+    if K is not None:
+        # shadow, outline and person fade together (the outline never shows through a fading arm)
+        region = cv2.blendLinear(region0, region, 1.0 - K, K)
+    bg[Y0:Y1, X0:X1] = region
+    return bg
+
+
+def without_room(plate: RoomPlate, frame: np.ndarray, alpha: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """(frame, matte) of a camera frame with the room its take's plate recognizes taken out of the matte and out
+    of the colors of its soft edge (uint8, camera frame size)."""
+    cv2 = _cv2()
+    h, w = alpha.shape
+    pw, ph = plate.size
+    if (w, h) != (pw, ph):
+        small = cv2.resize(frame, (pw, ph), interpolation=cv2.INTER_AREA)
+        a = cv2.resize(alpha, (pw, ph), interpolation=cv2.INTER_AREA)
+    else:
+        small, a = frame, alpha
+    e = plate.evidence(small, a.astype(np.float32) / 255.0)
+    if e is not None:
+        if (w, h) != (pw, ph):
+            e = cv2.resize(e, (w, h), interpolation=cv2.INTER_LINEAR)
+        alpha = (alpha.astype(np.float32) * (1.0 - e) + 0.5).astype(np.uint8)
+    return plate.clean_edge(frame, alpha), alpha
+
+
+def zoom_original(frame: np.ndarray, z: float, focus_y: float) -> np.ndarray:
+    """The camera zoom of compose_final (crop centered on x, eye line kept) on a full frame."""
+    if abs(z - 1.0) < 1e-4:
+        return frame
+    cv2 = _cv2()
+    H, W = frame.shape[:2]
+    top = H * focus_y * (1 - 1 / z)
+    left = W * 0.5 * (1 - 1 / z)
+    m = np.array([[z, 0.0, -left * z], [0.0, z, -top * z]], np.float32)
+    return cv2.warpAffine(frame, m, (W, H), flags=cv2.INTER_CUBIC, borderMode=cv2.BORDER_REPLICATE)
+
+
+# ================================================================== the clip
+
+@dataclass
+class Job:
+    cfg: Config
+    segments: list[Segment]
+    mattes: dict[int, "M.RangeJob"]              # segment index -> matte job
+    base: Path
+    base_pre: list[str]
+    base_fps: float
+    fps: int
+    size: tuple[int, int]                          # render size
+    full_size: tuple[int, int]                     # output size (the mattes are stored at it)
+    nf: int
+    out_dir: Path
+    extra_key: list = field(default_factory=list)
+    plates: dict[int, RoomPlate] = field(default_factory=dict)     # segment index -> the room plate of its take
+
+    def key(self) -> str:
+        blob = [TV_VERSION, M.engine_version(), str(self.base), M.file_signature(self.base), self.base_pre,
+                self.fps, self.size, self.full_size, self.nf, self.cfg.position, round(self.cfg.height, 5),
+                self.cfg.outline and [list(self.cfg.outline[0]), self.cfg.outline[1]], self.cfg.shadow,
+                self.cfg.blurred_original, self.cfg.no_face, self.cfg.mirror, self.cfg.runs, EDGE_FADE, SIDE_FADE,
+                [b.signature() for b in self.cfg.backgrounds], LOOP_FADE, KB_HOLD_AFTER, EXTEND, BACKDROP,
+                [[s.f0, s.f1, s.mode, round(s.zoom, 5), round(s.push, 5), round(s.scale, 6), s.flush_left,
+                  s.flush_right, round(s.focus_y, 5), s.stats, s.side, s.fill, s.drop] for s in self.segments],
+                {k: j.key for k, j in self.mattes.items()}, {k: p.key for k, p in self.plates.items()},
+                self.extra_key]
+        return hashlib.sha1(json.dumps(blob, sort_keys=True, default=str).encode("utf-8")).hexdigest()[:16]
+
+
+def _encoder(tmp: Path, W: int, H: int, fps: int, n: int) -> subprocess.Popen:
+    return subprocess.Popen(
+        M._ff() + ["-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(tmp)],
+        stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+
+
+def render(job: Job, progress: Callable[[str], None] | None = None, workers: int | None = None) -> dict:
+    """Write the tela verde clip (cached). -> {file, cached, seconds, frames, key}."""
+    started = time.time()
+    W, H = job.size
+    key = job.key()
+    job.out_dir.mkdir(parents=True, exist_ok=True)
+    out = job.out_dir / f"tv_{key}.mp4"
+    meta_path = out.with_suffix(".json")
+    if out.exists() and meta_path.exists():
+        meta = M.load_json(meta_path) or {}
+        if meta.get("key") == key and out.stat().st_size > 0:
+            return {**meta, "file": str(out), "cached": True, "render_seconds": round(time.time() - started, 2)}
+    cfg = job.cfg
+    k = W / 1080.0
+    look = Look(W=W, H=H, shadow=cfg.shadow, fade=EDGE_FADE * k, side_fade=SIDE_FADE * k,
+                outline=(np.array(cfg.outline[0], np.float32), cfg.outline[1] * k) if cfg.outline else None)
+    base_reader = M.FrameReader(M.base_cmd(job.base, job.base_pre, job.base_fps, job.fps, 0, job.nf, size=(W, H),
+                                           full_size=job.full_size), (W, H), 3, "ler o corte", queue_len=8)
+    bgs = BackgroundTrack(cfg, W, H, job.fps)
+    tmp = out.with_name(".tmp-" + out.name)
+    enc = _encoder(tmp, W, H, job.fps, job.nf)
+    workers = workers or max(2, min(6, (os.cpu_count() or 4) // 2))
+    pool = ThreadPoolExecutor(max_workers=workers)
+    pending: deque = deque()
+    written = 0
+    last_frame = None
+    last_print = time.time()
+
+    def flush(block: bool) -> None:
+        nonlocal written
+        while pending and (block or pending[0].done()):
+            fr = pending.popleft().result()
+            enc.stdin.write(fr.tobytes())
+            written += 1
+
+    def person_frame(make_bg, person, alpha, seg, f, plate):
+        s, x0, y0 = layer_rect(cfg, seg, seg.zoom_at(f), W, H)
+        if plate is not None:
+            person, alpha = without_room(plate, person, alpha)
+        if cfg.mirror:
+            cv2 = _cv2()
+            person, alpha = cv2.flip(person, 1), cv2.flip(alpha, 1)
+        return compose_person(make_bg(), person, alpha, s, x0, y0, look)
+
+    try:
+        f = 0
+        for si, seg in enumerate(job.segments):
+            mreader = None
+            mjob = job.mattes.get(si)
+            plate = job.plates.get(si)
+            if seg.mode == "pessoa" and mjob is not None:
+                mreader = M.FrameReader(M.matte_cmd(mjob.path, (W, H), job.full_size), (W, H), 1, "ler o recorte",
+                                        queue_len=8)
+            last_alpha = None
+            try:
+                for f in range(seg.f0, seg.f1):
+                    frame = base_reader.read()
+                    if frame is None:
+                        frame = last_frame
+                    if frame is None:
+                        raise TelaVerdeError("não consegui ler o corte para montar a tela verde", 1)
+                    last_frame = frame
+                    if seg.mode == "original":
+                        z, fy = seg.zoom_at(f), seg.focus_y
+                        pending.append(pool.submit(zoom_original, frame, z, fy))
+                    else:
+                        make_bg = bgs.fetch(f, frame)
+                        alpha = mreader.read() if mreader is not None else None
+                        if alpha is None:
+                            alpha = last_alpha
+                        if alpha is None:
+                            pending.append(pool.submit(make_bg))
+                        else:
+                            last_alpha = alpha
+                            pending.append(pool.submit(person_frame, make_bg, frame, alpha, seg, f, plate))
+                    flush(len(pending) >= 2 * workers)
+                    now = time.time()
+                    if progress and now - last_print >= M.PROGRESS_EVERY:
+                        last_print = now
+                        progress(f"tela verde: montando {100.0 * (f + 1) / job.nf:.0f}%")
+            finally:
+                if mreader is not None:
+                    mreader.close()
+        flush(True)
+    except BrokenPipeError:
+        pass
+    finally:
+        pool.shutdown(wait=True)
+        base_reader.close()
+        bgs.close()
+        try:
+            enc.stdin.close()
+        except OSError:
+            pass
+        err = enc.stderr.read().decode("utf-8", "replace") if enc.stderr else ""
+        code = enc.wait()
+    if code != 0 or written != job.nf:
+        tmp.unlink(missing_ok=True)
+        raise TelaVerdeError(f"falha ao gravar a tela verde ({written} de {job.nf} quadros): {err.strip()[-300:]}", 1)
+    os.replace(tmp, out)
+    seconds = time.time() - started
+    meta = {"key": key, "frames": job.nf, "size": [W, H], "fps": job.fps, "seconds": round(seconds, 2),
+            "created_at": M.now_iso()}
+    M.save_json(meta_path, meta)
+    return {**meta, "file": str(out), "cached": False, "render_seconds": round(seconds, 2)}
+
+
+def plan_stages(cfg: Config, segs: list[Segment], W: int, H: int,
+                reserve: Callable[[list[tuple[int, int]]], float] | None = None) -> None:
+    """Place every background shown whole (encaixe inteiro). Its stage is the band from STAGE_TOP to a little
+    above the highest head top of the person segments it is shown with; when auto captions play over it and
+    the picture keeps at least RESERVE_KEEP of the size it would have without them, the stage leaves room for
+    them right above the head. Needs cfg.runs; sets b.place and b.stage (render px)."""
+    gap = STAGE_GAP * H
+    top = STAGE_TOP * H
+    for k, b in enumerate(cfg.backgrounds):
+        b.place, b.stage = None, None
+        if b.fit != "inteiro" or not b.size:
+            continue
+        spans = [(f0, f1) for f0, f1, kk in cfg.runs if kk == k]
+        if not spans:
+            continue
+        heads = []
+        for s in segs:
+            if s.mode != "pessoa" or not s.stats or not s.stats.get("person_frames"):
+                continue
+            if not any(s.f0 < b1 and a0 < s.f1 for a0, b1 in spans):
+                continue
+            z = screen_zones(cfg, s, W, H)
+            if z["person"]:
+                heads.append(z["person"]["y0"] * H)
+        head = min(heads) if heads else H * (1.0 - cfg.height)
+        bottom = max(top + 0.1 * H, head - gap)
+        iw, ih = b.size
+        need = (b.content[3] - b.content[1]) * ih * W / iw          # main area height at the full width
+        room = reserve(spans) if reserve else 0.0
+        # a video with a plain border melts into the screen: it stays wide (down to QUIET_MIN, to leave the
+        # captions their band; what still does not fit above the head goes behind the captions and the person)
+        # instead of becoming a small box
+        least = QUIET_MIN if (b.kind == "video" and b.quiet) else WHOLE_MIN
+
+        def size(h: float) -> float:
+            return min(need, max(h, least * need))
+        if room > 0 and size(bottom - room - top) >= RESERVE_KEEP * size(bottom - top):
+            bottom -= room
+        b.stage = (round(top, 1), round(bottom, 1))
+        b.place = whole_place(b.size, b.content, b.stage, W, H, least)
+
+
+def image_zones(cfg: Config, segs: list[Segment], W: int, H: int) -> list[tuple[int, int, tuple]]:
+    """(f0, f1, rect) where the main area of a whole picture is on the screen (render px), outside the segments
+    shown as recorded (the background is not seen there)."""
+    out = []
+    shown_as_recorded = [(s.f0, s.f1) for s in segs if s.mode == "original"]
+    for f0, f1, k in cfg.runs:
+        if k is None:
+            continue
+        rect = cfg.backgrounds[k].content_rect(W, H)
+        if rect is None:
+            continue
+        pieces = [(f0, f1)]
+        for a, b in shown_as_recorded:
+            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, rect) for p0, p1 in pieces if p1 > p0]
+    return out
+
+
+def report_backgrounds(cfg: Config, fps: int, W: int, H: int, scale_to_out: float,
+                       rel: Callable[[Path], str]) -> list[dict]:
+    """The background runs for the report (what shows when, from fundo or from an insert, and where)."""
+    out = []
+    for f0, f1, k in cfg.runs:
+        b = cfg.backgrounds[k] if k is not None else None
+        row = {"start": round(f0 / fps, 3), "end": round(f1 / fps, 3),
+               "src": (rel(b.src) if b and b.src else (b.asked if b else
+                       ("original desfocado" if cfg.blurred_original else DARK_DEFAULT))),
+               "item": (b.idx if b and not b.insert else None), "insert": (b.insert if b else None),
+               "kind": b.kind if b else ("original" if cfg.blurred_original else "color"),
+               "encaixe": b.fit if b else None,
+               "ken_burns": b.ken_burns if b else False, "escurecer": b.darken if b else None,
+               "desfocar": b.blur if b else None}
+        if b and b.place:
+            row["rect"] = [int(round(v * scale_to_out)) for v in b.place]
+            row["content"] = [int(round(v * scale_to_out)) for v in b.content_rect(W, H)]
+        if b and b.kind == "video":
+            row["borda_lisa"] = b.quiet
+            row["quadros_vazios"] = {"inicio": b.lead, "fim": b.tail}
+        out.append(row)
+    return out
+
+
+def report_segments(cfg: Config, segs: list[Segment], fps: int, W: int, H: int, scale_to_out: float) -> list[dict]:
+    out = []
+    for s in segs:
+        row = {"start": round(s.f0 / fps, 3), "end": round(s.f1 / fps, 3), "mode": s.mode}
+        if s.mode == "pessoa" and cfg.mirror:
+            row["espelhado"] = True
+        if s.side:
+            row["posicao"] = s.side
+        if s.fill:
+            row["largura_toda"] = True
+            row["corte_embaixo"] = s.drop
+        if s.mode == "pessoa" and s.stats and s.stats.get("person_frames"):
+            sc, x0, y0 = layer_rect(cfg, s, s.zoom, W, H)
+            lw = W * sc
+            row.update({"scale": round(sc, 4), "x": int(round(x0 * scale_to_out)), "y": int(round(y0 * scale_to_out)),
+                        "zoom": s.zoom, "push_in": s.push,
+                        "on_screen_edge": [n for n, on in (("esquerda", s.flush_left), ("direita", s.flush_right)) if on],
+                        "height_share": round((H - (y0 + float(s.stats.get("top", 0)) * H * sc)) / H, 3),
+                        "width_share": round((float(s.stats.get("right", 1)) - float(s.stats.get("left", 0))) * lw / W, 3),
+                        "cut_edge_inside": [side for side, cond in (("esquerda", s.stats.get("touch_left", 0) > 0.05 and x0 > 0.5),
+                                                                    ("direita", s.stats.get("touch_right", 0) > 0.05 and x0 + lw < W - 0.5))
+                                            if cond]})
+        if s.note:
+            row["note"] = s.note
+        out.append(row)
+    return out
+