"""Person matte for the "tela verde" edit: the speaker cut out of every frame, cached per cut range.

Engine (chosen by measurement on 16/09/2026 against MODNet and Apple Vision, SPEC Contract 13): Google's
selfie_multiclass_256x256 (Apache-2.0, model card: https://storage.googleapis.com/mediapipe-assets/Model%20Card%20Multiclass%20Segmentation.pdf)
converted from TFLite to ONNX (assets/models/selfie_multiclass_256x256.onnx, weights unchanged), run by
onnxruntime on every system: CPU, or CoreML on a Mac with an Apple chip (25% faster, same matte). person =
1 - background class (softmax of the 6 logits).

Per frame, on the output canvas (1080x1920 for a vertical cut):
  1. inference on square tiles along the long side (2 overlapping 1080x1080 tiles on 9:16), each on its own
     session in parallel, blended in the overlap; levels 0.18..0.75 remove the background haze
  2. half size ("work"): DIS optical-flow guided EMA against the previous matte, trusted by the photometric
     warp error (a fast hand follows the current frame; where the picture did not change at all, a jump of the
     model is flicker and the matte only eases toward it); it starts again at every cut. The first frames of a
     range have no past to lean on, so once frame 12 (SETTINGS["start"]) is done, its matte is carried back
     through them (same flow): where the picture barely changed and that later matte clearly says background,
     a patch of the old room the model still took for the person is taken out (only patches that touch the
     background, never a hole inside the body)
  3. cleanup: the largest body plus the pieces near it (hand, microphone), small holes filled, far blobs out
  4. full size: fast colour guided filter only inside an edge band, then a soft contrast curve
Cache: <edit>/renders/matte/m_<key>.mkv (FFV1 gray, lossless, full output size) + m_<key>.json per cut range.
The key has the source signature, the picture range, the decode chain, ENGINE_VERSION and SETTINGS, so a new
cut reuses every range it kept, and the preview and the final share the files.
Decode: a range is read from its source video with render_cut's own chain (the frames of cut.mp4 before they
were encoded). The first and last frames are compared with cut.mp4; when they do not line up (a cut made by an
older version, a source that changed) or the source is gone, the range is read from cut.mp4 itself.

Usage:
    uv run python helpers/matte.py --edit-dir DIR [--video cut.mp4] [--force] [--json]
    uv run python helpers/matte.py --check
    uv run python helpers/matte.py --image FOTO.jpg -o recorte.png
"""

from __future__ import annotations

import argparse
import hashlib
import json
import math
import os
import subprocess
import sys
import threading
import time
from collections import deque
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from pathlib import Path
from typing import Callable, Iterator

import numpy as np

sys.path.insert(0, str(Path(__file__).resolve().parent))
from common import ASSETS_DIR, file_signature, fmt_time, load_json, now_iso, probe_video, require_binary, save_json  # noqa: E402

ENGINE_VERSION = "mc256-3"          # bump when the model or the post-processing changes (every cached matte is redone)
MODEL_NAME = "selfie_multiclass_256x256.onnx"
MODEL_PATH = ASSETS_DIR / "models" / MODEL_NAME
MODEL_SHA256 = "35549e14dc62c73b34f0fd04ec1765d9f1577230a2d068cb25c39f600350f477"
MODEL_SIDE = 256
SECONDS_PER_SECOND = 3.0            # what to tell the person: about 3 minutes of work per minute of video
SETTINGS = {
    "tiles": "long_side",
    "levels": [0.18, 0.75],
    "temporal": {"strength": 0.85, "flow_scale": 0.5, "err_sigma": 0.06, "dual": True, "still": [0.012, 0.03]},
    "cleanup": {"near_px": 28, "min_piece": 0.0006, "hole_small": 0.0005, "hole_max": 0.012, "hole_prob": 0.25},
    "refine": {"r": 3, "eps": 0.002, "band_px": 10, "curve": [0.12, 0.88], "erode": 0.6, "gf_div": 3},
    "start": {"frames": 12, "min_range": 8, "err_floor": 0.01, "err_sigma": 0.02, "bg": [0.1, 0.3], "open_px": 6,
              "min_drop": 0.2},
}
REF_WORK_SHORT = 540                # the settings above are in px of a 540 wide work frame
SYNC_FRAMES = 10                    # frames compared with cut.mp4 at each end of a range read from the source
SYNC_SIZE = 96                      # short side of the frames compared
SYNC_MAX_MAD = 2.0                  # mean gray difference (0-255) above which the frames are not the same picture
                                    # (same frame measured at 0.24-0.28 on a real cut; x264 noise is averaged away)
PROGRESS_EVERY = 5.0                # seconds between progress lines
CACHE_DIR = Path("renders") / "matte"
COREML_ENV = "EDITOR_VIDEO_MATTE_COREML"
THREADS_ENV = "EDITOR_VIDEO_MATTE_THREADS"


class MatteError(Exception):
    def __init__(self, message: str, code: int = 1):
        super().__init__(message)
        self.code = code


def _cv2():
    os.environ.setdefault("OPENCV_LOG_LEVEL", "ERROR")
    try:
        import cv2  # noqa: PLC0415
    except ImportError as e:  # pragma: no cover - depends on the install
        raise MatteError(f"o OpenCV não está instalado ({e}). Rode o instalador de novo (ou 'uv sync' na pasta da skill)", 2)
    return cv2


def _short(obj) -> str:
    return hashlib.sha1(json.dumps(obj, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()[:16]


# ================================================================== engine check

_MODEL_OK: dict[str, str] = {}


def import_ort():
    try:
        import onnxruntime as ort  # noqa: PLC0415
    except ImportError:
        raise MatteError("a tela verde precisa da biblioteca onnxruntime, que não está instalada. Rode o instalador "
                         "de novo (ou 'uv sync' na pasta da skill)", 2) from None
    try:
        ort.set_default_logger_severity(3)      # no engine notes on the person's terminal
    except Exception:  # noqa: BLE001
        pass
    return ort


def check_model(path: Path = MODEL_PATH) -> None:
    """The model file is there and is the one this version was measured with."""
    if not path.is_file():
        raise MatteError(f"o modelo do recorte da pessoa não foi encontrado ({path}). Instale a skill de novo", 2)
    sig = file_signature(path)
    if _MODEL_OK.get(str(path)) == sig:
        return
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1 << 20), b""):
            h.update(chunk)
    if h.hexdigest() != MODEL_SHA256:
        raise MatteError(f"o arquivo do modelo do recorte ({path.name}) está diferente do original (pode ter "
                         f"corrompido na cópia). Instale a skill de novo", 2)
    _MODEL_OK[str(path)] = sig


def check_engine() -> dict:
    """PT-BR errors when the default engine cannot run here. -> {"onnxruntime": version, "model": name}."""
    ort = import_ort()
    check_model()
    _cv2()
    return {"onnxruntime": getattr(ort, "__version__", "?"), "model": MODEL_NAME}


def use_coreml() -> bool:
    """CoreML on Macs with an Apple chip (measured 16/09/2026: 25% faster, same matte, IoU 0.9997 against the CPU);
    EDITOR_VIDEO_MATTE_COREML=0 keeps the CPU, =1 also tries it on an Intel Mac."""
    raw = (os.environ.get(COREML_ENV) or "").strip()
    if raw in ("0", "1"):
        return raw == "1" and sys.platform == "darwin"
    import platform  # noqa: PLC0415
    return sys.platform == "darwin" and platform.machine().lower() in ("arm64", "aarch64")


def _threads_per_session() -> int:
    raw = (os.environ.get(THREADS_ENV) or "").strip()
    if raw.isdigit() and int(raw) > 0:
        return int(raw)
    return max(1, min(4, (os.cpu_count() or 4) // 3))


# ================================================================== model + post-processing

def _levels(p: np.ndarray, lo: float, hi: float) -> np.ndarray:
    return np.clip((p - lo) / (hi - lo), 0.0, 1.0)


def smoothstep(x: np.ndarray, e0: float, e1: float) -> np.ndarray:
    t = np.clip((x - e0) / (e1 - e0), 0.0, 1.0)
    return t * t * (3 - 2 * t)


def tile_origins(length: int, side: int) -> list[int]:
    """Start of each square tile along one axis: as few as cover it, evenly spread."""
    if length <= side:
        return [0]
    n = int(math.ceil(length / side))
    n = max(2, n)
    return [int(round((length - side) * k / (n - 1))) for k in range(n)]


class OnnxSegmenter:
    """selfie_multiclass_256x256 on onnxruntime: person probability of a frame, tile by tile."""

    name = "onnx"

    def __init__(self, sessions: int = 2, threads: int | None = None, coreml: bool | None = None):
        ort = import_ort()
        check_model()
        threads = threads or _threads_per_session()
        if coreml is None:
            coreml = use_coreml()
        cpu: list = ["CPUExecutionProvider"]
        provs = cpu
        if coreml and sys.platform == "darwin" and "CoreMLExecutionProvider" in ort.get_available_providers():
            provs = [("CoreMLExecutionProvider", {"ModelFormat": "NeuralNetwork", "MLComputeUnits": "ALL"})] + cpu
        self.sessions = self._open(ort, sessions, threads, provs)
        if provs is not cpu:
            try:   # CoreML compiles on the first run: a failure there falls back to the CPU
                for s in self.sessions:
                    s.run(None, {s.get_inputs()[0].name: np.zeros((1, MODEL_SIDE, MODEL_SIDE, 3), np.float32)})
            except Exception:  # noqa: BLE001
                self.sessions = self._open(ort, sessions, threads, cpu)
        self.provider = self.sessions[0].get_providers()[0]
        self.input_name = self.sessions[0].get_inputs()[0].name
        self.pool = ThreadPoolExecutor(max_workers=len(self.sessions))
        self.infer_time = 0.0
        self.threads = threads

    @staticmethod
    def _open(ort, sessions: int, threads: int, provs: list) -> list:
        out = []
        for _ in range(max(1, sessions)):
            so = ort.SessionOptions()
            so.log_severity_level = 3
            so.intra_op_num_threads = threads
            so.inter_op_num_threads = 1
            try:
                out.append(ort.InferenceSession(str(MODEL_PATH), so, providers=provs))
            except Exception as e:  # noqa: BLE001
                if provs[0] != "CPUExecutionProvider":
                    return OnnxSegmenter._open(ort, sessions, threads, ["CPUExecutionProvider"])
                raise MatteError(f"o onnxruntime não conseguiu abrir o modelo do recorte ({e.__class__.__name__}). "
                                 f"Instale a skill de novo", 2) from None
        return out

    def raw(self, tile_rgb: np.ndarray, k: int = 0) -> np.ndarray:
        """(256, 256, 6) logits of one square RGB tile (any size, resized here)."""
        cv2 = _cv2()
        x = cv2.resize(tile_rgb, (MODEL_SIDE, MODEL_SIDE), interpolation=cv2.INTER_AREA).astype(np.float32)
        x = x / 127.5 - 1.0
        return self.sessions[k % len(self.sessions)].run(None, {self.input_name: x[None]})[0][0]

    def _person(self, tile_rgb: np.ndarray, k: int, out_size: tuple[int, int]) -> np.ndarray:
        cv2 = _cv2()
        y = self.raw(tile_rgb, k)
        e = np.exp(y - y.max(axis=-1, keepdims=True))
        bg = e[..., 0] / e.sum(axis=-1)
        return cv2.resize((1.0 - bg).astype(np.float32), out_size, interpolation=cv2.INTER_LINEAR)

    def person_prob(self, rgb: np.ndarray, work: tuple[int, int]) -> np.ndarray:
        """rgb: HxWx3 uint8 -> float32 person probability at work (w, h)."""
        t0 = time.perf_counter()
        h, w = rgb.shape[:2]
        ww, wh = work
        vertical = h >= w
        side = w if vertical else h
        length, total = (h, wh) if vertical else (w, ww)
        sc = total / length                                    # work px per frame px along the long side
        origins = tile_origins(length, side)
        span = min(total, max(1, int(round(side * sc))))       # tile length at work res
        starts = [min(total - span, int(round(o * sc))) for o in origins]
        jobs = []
        for k, o in enumerate(origins):
            tile = rgb[o:o + side] if vertical else rgb[:, o:o + side]
            size = (ww, span) if vertical else (span, wh)
            jobs.append(self.pool.submit(self._person, tile, k, size))
        acc = np.zeros(total, np.float32)
        out = np.zeros((wh, ww), np.float32)
        for k, (start, job) in enumerate(zip(starts, jobs)):
            p = job.result()
            ramp = np.ones(span, np.float32)
            if k > 0:                                          # overlap with the previous tile: fade in
                ov = max(0, starts[k - 1] + span - start)
                if ov:
                    ramp[:ov] = np.linspace(0, 1, ov, dtype=np.float32)
            if k < len(starts) - 1:                            # overlap with the next tile: fade out
                ov = max(0, start + span - starts[k + 1])
                if ov:
                    ramp[span - ov:] = np.minimum(ramp[span - ov:], np.linspace(1, 0, ov, dtype=np.float32))
            acc[start:start + span] += ramp
            if vertical:
                out[start:start + span] += p * ramp[:, None]
            else:
                out[:, start:start + span] += p * ramp[None, :]
        weight = np.maximum(acc, 1e-6)
        out /= weight[:, None] if vertical else weight[None, :]
        self.infer_time += time.perf_counter() - t0
        return out

    def close(self) -> None:
        self.pool.shutdown(wait=False)


class Temporal:
    """Optical-flow guided EMA at work resolution."""

    def __init__(self, strength: float, flow_scale: float, err_sigma: float, dual: bool = True,
                 still: tuple[float, float] | None = None):
        cv2 = _cv2()
        self.strength, self.flow_scale, self.err_sigma, self.dual = strength, flow_scale, err_sigma, dual
        self.still = tuple(still) if still else None
        self.dis = cv2.DISOpticalFlow_create(cv2.DISOPTICAL_FLOW_PRESET_FAST)
        self.prev_gray = None
        self.prev_alpha = None
        self._grid = None

    def reset(self) -> None:
        self.prev_gray = self.prev_alpha = None

    def carry(self, gray: np.ndarray, prev_gray: np.ndarray, prev_alpha: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
        """prev_alpha moved onto the frame `gray` (optical flow from prev_gray) -> (alpha, photometric error 0..1)."""
        cv2 = _cv2()
        h, w = gray.shape
        fw, fh = max(8, int(w * self.flow_scale)), max(8, int(h * self.flow_scale))
        g1 = cv2.resize(gray, (fw, fh), interpolation=cv2.INTER_AREA)
        g0 = cv2.resize(prev_gray, (fw, fh), interpolation=cv2.INTER_AREA)
        flow = self.dis.calc(g1, g0, None)                 # cur(x) ~ prev(x + flow)
        flow = cv2.resize(flow, (w, h), interpolation=cv2.INTER_LINEAR) * (w / fw)
        if self._grid is None or self._grid[0].shape != (h, w):
            self._grid = np.meshgrid(np.arange(w, dtype=np.float32), np.arange(h, dtype=np.float32))
        gx, gy = self._grid
        mx, my = gx + flow[..., 0], gy + flow[..., 1]
        warped_a = cv2.remap(prev_alpha, mx, my, cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
        warped_g = cv2.remap(prev_gray, mx, my, cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
        g = gray.astype(np.float32)
        err_w = cv2.GaussianBlur(np.abs(g - warped_g.astype(np.float32)) / 255.0, (0, 0), 2)
        if not self.dual:
            return warped_a, err_w
        # where the picture did not move, the previous matte as it was is the better guess
        err_0 = cv2.GaussianBlur(np.abs(g - prev_gray.astype(np.float32)) / 255.0, (0, 0), 2)
        use0 = err_0 <= err_w
        return np.where(use0, prev_alpha, warped_a).astype(np.float32), np.minimum(err_0, err_w)

    def __call__(self, gray: np.ndarray, p: np.ndarray) -> np.ndarray:
        if self.prev_gray is None or self.strength <= 0:
            self.prev_gray, self.prev_alpha = gray, p
            return p
        prev_a, err = self.carry(gray, self.prev_gray, self.prev_alpha)
        conf = np.exp(-err / self.err_sigma)
        # a big disagreement the flow cannot explain is a real change: follow the model. Where the picture did
        # not change at all, nothing came in or went out: a jump of the model there is its own flicker (a patch
        # of room it takes for the body for a few frames), so the matte keeps easing instead of jumping
        dis = np.abs(p - prev_a)
        jump = smoothstep(dis, 0.35, 0.8)
        if self.still:
            jump = jump * smoothstep(err, self.still[0], self.still[1])
        wprev = self.strength * conf * (1.0 - jump)
        out = ((1 - wprev) * p + wprev * prev_a).astype(np.float32)
        self.prev_gray, self.prev_alpha = gray, out
        return out


def cleanup(a: np.ndarray, prob: np.ndarray | None, near_px: float, min_piece: float, hole_small: float,
            hole_max: float, hole_prob: float) -> np.ndarray:
    """Keep the body and the pieces close to it; fill the holes the model was unsure about.

    A background gap the model saw clearly (between an arm and the body, behind glasses) stays open: only
    tiny holes, or holes whose mean model probability is at least hole_prob, are filled."""
    cv2 = _cv2()
    h, w = a.shape
    b = (a > 0.5).astype(np.uint8)
    n, lab, stats, _ = cv2.connectedComponentsWithStats(b, connectivity=8)
    if n <= 1:
        return a
    areas = stats[1:, cv2.CC_STAT_AREA]
    main = 1 + int(np.argmax(areas))
    keep = (lab == main).astype(np.uint8)
    if n > 2:
        dist = cv2.distanceTransform(1 - keep, cv2.DIST_L2, 3)
        for i in range(1, n):
            if i == main or stats[i, cv2.CC_STAT_AREA] < min_piece * h * w:
                continue
            comp = lab == i
            if dist[comp].min() <= near_px:
                keep[comp] = 1
    inv = (1 - keep).astype(np.uint8)
    n2, lab2, st2, _ = cv2.connectedComponentsWithStats(inv, connectivity=4)
    holes = np.zeros_like(keep)
    src = a if prob is None else prob
    for i in range(1, n2):
        x, y, ww, hh, ar = st2[i]
        touches = x == 0 or y == 0 or x + ww == w or y + hh == h
        if touches or ar >= hole_max * h * w:
            continue
        comp = lab2 == i
        if ar < hole_small * h * w or float(src[comp].mean()) >= hole_prob:
            holes[comp] = 1
    solid = keep | holes
    # soft keep mask: 1 on the kept pieces and 4 px around them, fading to 0 by 8 px
    dout = cv2.distanceTransform(1 - solid, cv2.DIST_L2, 3)
    keep_soft = np.clip((8.0 - dout) / 4.0, 0, 1)
    out = a * keep_soft
    if holes.any():
        out = np.maximum(out, cv2.GaussianBlur(holes.astype(np.float32), (0, 0), 1.0) * holes)
    return out.astype(np.float32)


def _box(x, r):
    cv2 = _cv2()
    return cv2.boxFilter(x, -1, (2 * r + 1, 2 * r + 1), borderType=cv2.BORDER_REFLECT)


def fast_guided_filter(guide_full: np.ndarray, p_low: np.ndarray, r: int, eps: float) -> np.ndarray:
    """Colour guided filter (He et al.): coefficients at the size of p_low, applied with the full size guide."""
    cv2 = _cv2()
    H, W = guide_full.shape[:2]
    h, w = p_low.shape
    I = cv2.resize(guide_full, (w, h), interpolation=cv2.INTER_AREA)  # noqa: E741
    p = p_low
    mI = _box(I, r)
    mp_ = _box(p, r)
    mIp = _box(I * p[..., None], r)
    cov = mIp - mI * mp_[..., None]
    rr = _box(I[..., 0] * I[..., 0], r) - mI[..., 0] * mI[..., 0] + eps
    rg = _box(I[..., 0] * I[..., 1], r) - mI[..., 0] * mI[..., 1]
    rb = _box(I[..., 0] * I[..., 2], r) - mI[..., 0] * mI[..., 2]
    gg = _box(I[..., 1] * I[..., 1], r) - mI[..., 1] * mI[..., 1] + eps
    gb = _box(I[..., 1] * I[..., 2], r) - mI[..., 1] * mI[..., 2]
    bb = _box(I[..., 2] * I[..., 2], r) - mI[..., 2] * mI[..., 2] + eps
    inv_rr = gg * bb - gb * gb
    inv_rg = gb * rb - rg * bb
    inv_rb = rg * gb - gg * rb
    inv_gg = rr * bb - rb * rb
    inv_gb = rb * rg - rr * gb
    inv_bb = rr * gg - rg * rg
    det = rr * inv_rr + rg * inv_rg + rb * inv_rb
    c0, c1, c2 = cov[..., 0], cov[..., 1], cov[..., 2]
    a0 = (inv_rr * c0 + inv_rg * c1 + inv_rb * c2) / det
    a1 = (inv_rg * c0 + inv_gg * c1 + inv_gb * c2) / det
    a2 = (inv_rb * c0 + inv_gb * c1 + inv_bb * c2) / det
    A = np.dstack([a0, a1, a2]).astype(np.float32)
    b = (mp_ - (A * mI).sum(axis=2)).astype(np.float32)
    A = _box(A, r)
    b = _box(b, r)
    A_full = cv2.resize(A, (W, H), interpolation=cv2.INTER_LINEAR)
    q = cv2.resize(b, (W, H), interpolation=cv2.INTER_LINEAR)
    for c in range(3):
        q += cv2.multiply(A_full[..., c], guide_full[..., c])
    return q


class Refiner:
    def __init__(self, r: int, eps: float, band_px: float, curve, erode: float, gf_div: int):
        self.r, self.eps, self.band_px, self.curve, self.erode, self.gf_div = r, eps, band_px, tuple(curve), erode, gf_div

    def __call__(self, rgb_full: np.ndarray, a_low: np.ndarray) -> np.ndarray:
        cv2 = _cv2()
        H, W = rgb_full.shape[:2]
        guide = rgb_full.astype(np.float32) / 255.0
        gf_size = (max(8, W // self.gf_div), max(8, H // self.gf_div))
        p_gf = cv2.resize(a_low, gf_size, interpolation=cv2.INTER_AREA)
        q = fast_guided_filter(guide, p_gf, self.r, self.eps)
        coarse = cv2.resize(a_low, (W, H), interpolation=cv2.INTER_LINEAR)
        b = (a_low > 0.5).astype(np.uint8)
        d_in = cv2.distanceTransform(b, cv2.DIST_L2, 3)
        d_out = cv2.distanceTransform(1 - b, cv2.DIST_L2, 3)
        d = np.maximum(d_in, d_out)                          # distance to the contour (work px)
        band = np.clip((self.band_px + 2 - d) / 4.0, 0, 1).astype(np.float32)
        band = cv2.resize(band, (W, H), interpolation=cv2.INTER_LINEAR)
        a = band * np.clip(q, 0, 1) + (1 - band) * coarse
        a = smoothstep(a, *self.curve)
        if self.erode > 0:   # pull the edge in a little so the old background does not fringe
            a = cv2.erode(a, np.ones((3, 3), np.uint8)) * self.erode + a * (1 - self.erode)
        return a.astype(np.float32)


class MatteEngine:
    """Frame by frame person matte. process() must see the frames of one range in order; reset() between ranges."""

    version = ENGINE_VERSION

    def __init__(self, size: tuple[int, int], segmenter: OnnxSegmenter | None = None):
        W, H = size
        self.size = (W, H)
        self.work = (max(2, (W // 2) // 2 * 2), max(2, (H // 2) // 2 * 2))
        k = min(self.work) / REF_WORK_SHORT
        t, c, r = SETTINGS["temporal"], SETTINGS["cleanup"], SETTINGS["refine"]
        self.seg = segmenter or OnnxSegmenter()
        self.provider = self.seg.provider
        self.temporal = Temporal(t["strength"], t["flow_scale"], t["err_sigma"], t["dual"], t.get("still"))
        self.clean = dict(c, near_px=c["near_px"] * k)
        self.refiner = Refiner(r["r"], r["eps"], r["band_px"] * k, r["curve"], r["erode"], r["gf_div"])

    def reset(self) -> None:
        self.temporal.reset()

    def coarse_parts(self, rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
        """(temporal matte, model probability, gray) of the next frame at work size (sequential)."""
        cv2 = _cv2()
        p = self.seg.person_prob(rgb, self.work)
        lo, hi = SETTINGS["levels"]
        p = _levels(p, lo, hi)
        gray = cv2.cvtColor(cv2.resize(rgb, self.work, interpolation=cv2.INTER_AREA), cv2.COLOR_RGB2GRAY)
        return self.temporal(gray, p), p, gray

    def finish(self, a: np.ndarray, p: np.ndarray) -> np.ndarray:
        return cleanup(a, p, **self.clean)

    def coarse(self, rgb: np.ndarray) -> np.ndarray:
        """Work-size matte of the next frame (sequential: it feeds the temporal filter)."""
        a, p, _ = self.coarse_parts(rgb)
        return self.finish(a, p)

    def settle_start(self, first: list[tuple[np.ndarray, np.ndarray, np.ndarray]],
                     anchor: tuple[np.ndarray, np.ndarray]) -> list[np.ndarray]:
        """The first frames of a range, (temporal matte, probability, gray) each, with the matte and gray of the
        frame right after them (anchor): the anchor matte is carried back frame by frame; where the picture
        barely changed along the way and it clearly says background, the start matte drops to it. Only
        patches of START open_px or more that touch the background change (a thin moving hand, a hole inside
        the body never do), fading in over the last half before the anchor. -> corrected temporal mattes."""
        cv2 = _cv2()
        st = SETTINGS["start"]
        n = len(first)
        if n == 0:
            return []
        b, gprev = anchor
        k = min(self.work) / REF_WORK_SHORT
        r = max(1, int(round(st["open_px"] * k)))
        ker = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (2 * r + 1, 2 * r + 1))
        near = np.ones((5, 5), np.uint8)
        cerr = None
        out: list[np.ndarray] = [None] * n  # type: ignore[list-item]
        for i in range(n - 1, -1, -1):
            a, _, gray = first[i]
            b, err = self.temporal.carry(gray, gprev, b)
            gprev = gray
            cerr = err if cerr is None else np.maximum(cerr, err)
            w = np.exp(-np.maximum(0.0, cerr - st["err_floor"]) / st["err_sigma"])
            w *= 1.0 - smoothstep(b, *st["bg"])
            w *= min(1.0, (n - i) / (n / 2.0))
            drop = (w * np.maximum(0.0, a - b)).astype(np.float32)
            m = cv2.morphologyEx((drop > st["min_drop"]).astype(np.uint8), cv2.MORPH_OPEN, ker)
            if m.any():
                cnt, lab = cv2.connectedComponents(m, connectivity=8)
                touch = cv2.dilate((a < 0.5).astype(np.uint8), near) > 0
                keep = np.zeros(cnt, bool)
                keep[np.unique(lab[touch & (m > 0)])] = True
                keep[0] = False
                m = keep[lab].astype(np.uint8)
            if not m.any():
                out[i] = a
                continue
            soft = cv2.GaussianBlur(cv2.dilate(m, ker).astype(np.float32), (0, 0), r / 2.0)
            out[i] = (a - drop * soft).astype(np.float32)
        return out

    def refine(self, rgb: np.ndarray, coarse: np.ndarray) -> np.ndarray:
        return self.refiner(rgb, coarse)

    def process(self, rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
        a = self.coarse(rgb)
        return a, self.refine(rgb, a)

    def close(self) -> None:
        self.seg.close()


# Engines can be swapped (tests use a fake one so they do not depend on the model).
EngineFactory = Callable[[tuple[int, int]], object]
_ENGINE_FACTORY: EngineFactory | None = None
_ENGINE_VERSION_OVERRIDE: str | None = None


def set_engine(factory: EngineFactory | None, version: str | None = None) -> None:
    """Use another engine (an object with version, provider, reset(), coarse(rgb), refine(rgb, coarse), close()).
    None goes back to the ONNX engine."""
    global _ENGINE_FACTORY, _ENGINE_VERSION_OVERRIDE
    _ENGINE_FACTORY = factory
    _ENGINE_VERSION_OVERRIDE = version if factory is not None else None


def engine_version() -> str:
    return _ENGINE_VERSION_OVERRIDE or ENGINE_VERSION


def make_engine(size: tuple[int, int]):
    if _ENGINE_FACTORY is not None:
        return _ENGINE_FACTORY(size)
    return MatteEngine(size)


def default_engine_ready() -> None:
    """Raise MatteError when the engine that would run cannot (a fake engine is always ready)."""
    if _ENGINE_FACTORY is None:
        check_engine()


# ================================================================== stats

def frame_stats(a: np.ndarray) -> tuple | None:
    """Per frame numbers used to place the person (work-size matte): None when nobody is there.

    -> (top, left, right, head_cx, touch_left, touch_right, touch_bottom) as fractions of the frame / bools."""
    m = a > 0.5
    rows = np.flatnonzero(m.any(axis=1))
    if rows.size == 0:
        return None
    h, w = a.shape
    cols = np.flatnonzero(m.any(axis=0))
    r0 = int(rows[0])
    r1 = r0 + max(1, int((h - r0) * 0.35))
    band = a[r0:r1]
    mass = band.sum(axis=0)
    cx = float((mass * np.arange(w)).sum() / max(1e-6, mass.sum()))
    edge = max(1, w // 270)
    return (r0 / h, int(cols[0]) / w, (int(cols[-1]) + 1) / w, cx / w,
            bool(m[:, :edge].any()), bool(m[:, w - edge:].any()), bool(m[h - max(1, h // 480):].any()))


def summarize_stats(rows: list[tuple | None]) -> dict:
    found = [r for r in rows if r is not None]
    n = len(rows)
    if not found:
        return {"frames": n, "person_frames": 0}
    arr = np.array([r[:4] for r in found], np.float64)
    touch = np.array([r[4:] for r in found], np.float64)
    return {
        "frames": n,
        "person_frames": len(found),
        "top": round(float(np.percentile(arr[:, 0], 5)), 5),
        "top_median": round(float(np.median(arr[:, 0])), 5),
        "left": round(float(np.percentile(arr[:, 1], 5)), 5),
        "right": round(float(np.percentile(arr[:, 2], 95)), 5),
        "head_cx": round(float(np.median(arr[:, 3])), 5),
        "touch_left": round(float(touch[:, 0].mean()), 4),
        "touch_right": round(float(touch[:, 1].mean()), 4),
        "touch_bottom": round(float(touch[:, 2].mean()), 4),
    }


# ================================================================== ranges

@dataclass
class RangeJob:
    index: int
    rid: str
    f0: int                     # first frame on the base video (output frame grid)
    f1: int
    size: tuple[int, int]       # full output size (the matte is stored at this size)
    fps: int
    key: str = ""
    method: str = "corte"       # "fonte" (source video) | "corte" (cut.mp4)
    source: Path | None = None
    source_args: list[str] = field(default_factory=list)   # ffmpeg input + filter args (method fonte)
    source_hw: bool = False
    base: Path | None = None
    base_pre: list[str] = field(default_factory=list)      # filters that put the base on the output grid
    base_fps: float = 0.0
    note: str = ""              # why the range is read from cut.mp4
    path: Path = field(default_factory=Path)
    meta_path: Path = field(default_factory=Path)
    meta: dict = field(default_factory=dict)
    cached: bool = False
    seconds: float = 0.0

    @property
    def frames(self) -> int:
        return self.f1 - self.f0


def base_pre_filters(base_fps: float, base_size: tuple[int, int], fps: int, size: tuple[int, int]) -> list[str]:
    """The same frame-grid filters compose_final.run_video puts on the base."""
    pre = []
    if abs(base_fps - fps) > 0.01:
        pre.append(f"fps={fps}")
    if tuple(base_size) != tuple(size):
        W, H = size
        pre.append(f"scale={W}:{H}:force_original_aspect_ratio=increase:flags=bicubic,crop={W}:{H},setsar=1")
    return pre


def _timeline_segment(timeline: dict | None, f0: int, f1: int, fps: int) -> dict | None:
    for s in (timeline or {}).get("segments") or []:
        try:
            a = int(s["out_start_frame"]) if "out_start_frame" in s else int(round(float(s["out_start"]) * fps))
            b = int(s["out_end_frame"]) if "out_end_frame" in s else int(round(float(s["out_end"]) * fps))
        except (KeyError, TypeError, ValueError):
            continue
        if a == f0 and b == f1:
            return s
    return None


def _source_plan(job: RangeJob, edit_dir: Path, timeline: dict, seg: dict, sources: dict | None,
                 base_info: dict) -> str:
    """Fill the source decode of a job. Returns "" or why the source cannot be used."""
    import render_cut as rc  # noqa: PLC0415
    from grade import resolve_grade  # noqa: PLC0415

    W, H = job.size
    try:
        tl_fps = int(round(float(timeline.get("fps"))))
        tl_size = (int(timeline.get("width")), int(timeline.get("height")))
    except (TypeError, ValueError):
        return "o cut_timeline.json não tem fps ou tamanho"
    if timeline.get("preview"):
        return "o corte é uma prévia"
    if tl_fps != job.fps or tl_size != (W, H):
        return "o corte tem outro tamanho ou outra taxa de quadros"
    if abs(float(base_info.get("fps") or 0) - job.fps) > 0.01 or tuple(base_info.get("size") or ()) != (W, H):
        return "o vídeo base não está no tamanho do corte"
    other = bool(seg.get("imagem_de"))   # the picture came from another camera (render_cut "imagem_de")
    try:
        src_start = float(seg["imagem_src_start"] if other else seg["src_start"])
        frames = int(seg.get("frames") or job.frames)
    except (KeyError, TypeError, ValueError):
        return "o cut_timeline.json é de uma versão antiga"
    if frames != job.frames:
        return "o trecho do timeline não bate com o vídeo"
    if other:
        src = Path(str(seg.get("imagem_path") or ""))
        if not src.is_file():
            return "o vídeo bruto da outra câmera não foi encontrado"
    elif not sources or str(seg.get("source")) not in sources:
        return "o vídeo bruto não foi encontrado"
    else:
        src = sources[str(seg.get("source"))]
    try:
        info = probe_video(src)
    except Exception:  # noqa: BLE001
        return f"não consegui ler {src.name}"
    if not info.get("has_video"):
        return f"{src.name} não tem imagem"
    try:
        grade_filter = resolve_grade(timeline.get("grade"))
    except ValueError:
        return "o grade do corte não existe mais"
    try:
        vf = rc.build_vf(info, W, H, job.fps, grade_filter, seg.get("crop"))
    except Exception:  # noqa: BLE001
        return "não consegui montar a leitura do vídeo bruto"
    snapped = bool(seg.get("pic_snapped", True))
    src_fps = float(info.get("fps") or job.fps)
    seek = max(0.0, src_start - (0.25 / max(src_fps, job.fps) if snapped else 0.0))
    job.method = "fonte"
    job.source = src
    job.source_args = ["-noaccurate_seek", "-ss", f"{seek:.6f}", "-i", str(src), "-map", "0:v:0", "-vf", vf]
    try:
        job.source_hw = bool(rc.hwaccel_for(src, info))
    except Exception:  # noqa: BLE001
        job.source_hw = False
    job.key = _short({"v": engine_version(), "s": SETTINGS, "how": "fonte", "src": str(src.resolve()),
                      "sig": file_signature(src), "pic": round(src_start, 6), "snap": snapped, "frames": job.frames,
                      "vf": vf, "size": [W, H], "fps": job.fps})
    return ""


def plan_jobs(edit_dir: Path, base: Path, bounds: list[tuple[int, int]], fps: int, size: tuple[int, int],
              timeline: dict | None, base_fps: float | None = None, base_size: tuple[int, int] | None = None) -> list[RangeJob]:
    """One job per cut range (bounds on the output frame grid)."""
    edit_dir = Path(edit_dir).resolve()
    base = Path(base).resolve()
    if base_fps is None or base_size is None:
        info = probe_video(base)
        base_fps = float(info.get("fps") or fps)
        base_size = (int(info.get("display_width") or info.get("width") or 0),
                     int(info.get("display_height") or info.get("height") or 0))
    base_info = {"fps": base_fps, "size": tuple(base_size)}
    pre = base_pre_filters(base_fps, base_size, fps, size)
    sources = None
    sources_note = ""
    if timeline and timeline.get("segments"):
        try:
            import denoise  # noqa: PLC0415
            sources, sources_note = denoise.resolve_segment_sources(edit_dir, timeline)
        except Exception as e:  # noqa: BLE001
            sources, sources_note = None, f"não consegui achar os vídeos brutos ({e.__class__.__name__})"
    base_sig = file_signature(base)
    out_dir = edit_dir / CACHE_DIR
    jobs = []
    for i, (a, b) in enumerate(bounds):
        seg = _timeline_segment(timeline, a, b, fps)
        rid = str(seg.get("id")) if seg and seg.get("id") else f"t{i + 1}"
        job = RangeJob(index=i, rid=rid, f0=a, f1=b, size=tuple(size), fps=fps, base=base, base_pre=pre,
                       base_fps=float(base_fps))
        why = "sem cut_timeline.json" if not timeline else ("o trecho não está no cut_timeline.json" if seg is None else "")
        if seg is not None:
            why = sources_note if sources is None and sources_note else ""
            if not why:
                why = _source_plan(job, edit_dir, timeline, seg, sources, base_info)
        if job.method != "fonte":
            job.note = why
            job.key = _short({"v": engine_version(), "s": SETTINGS, "how": "corte", "base": base.name,
                              "sig": base_sig, "f0": a, "f1": b, "size": list(size), "fps": fps, "pre": pre})
        job.path = out_dir / f"m_{job.key}.mkv"
        job.meta_path = out_dir / f"m_{job.key}.json"
        jobs.append(job)
    return jobs


# ================================================================== decode / encode

class FrameReader:
    """Raw frames from an ffmpeg command, read in a thread (the decode runs while the engine works)."""

    def __init__(self, cmd: list[str], size: tuple[int, int], channels: int, what: str, queue_len: int = 6):
        self.size, self.channels, self.what = size, channels, what
        self.proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.DEVNULL)
        self.frame_bytes = size[0] * size[1] * channels
        self.buf: deque = deque()
        self.cond = threading.Condition()
        self.done = False
        self.max = queue_len
        self.err = b""
        self.thread = threading.Thread(target=self._run, daemon=True)
        self.thread.start()
        self.err_thread = threading.Thread(target=self._drain_err, daemon=True)
        self.err_thread.start()

    def _drain_err(self) -> None:
        try:
            self.err = self.proc.stderr.read() if self.proc.stderr else b""
        except (OSError, ValueError):
            pass

    def _run(self) -> None:
        W, H = self.size
        shape = (H, W, self.channels) if self.channels > 1 else (H, W)
        try:
            while True:
                data = self.proc.stdout.read(self.frame_bytes) if self.proc.stdout else b""
                if len(data) < self.frame_bytes:
                    break
                frame = np.frombuffer(data, np.uint8).reshape(shape)
                with self.cond:
                    while len(self.buf) >= self.max and not self.done:
                        self.cond.wait()
                    if self.done:
                        break
                    self.buf.append(frame)
                    self.cond.notify_all()
        finally:
            with self.cond:
                self.done = True
                self.cond.notify_all()

    def read(self) -> np.ndarray | None:
        with self.cond:
            while not self.buf and not self.done:
                self.cond.wait()
            if self.buf:
                frame = self.buf.popleft()
                self.cond.notify_all()
                return frame
            return None

    def close(self) -> str:
        with self.cond:
            self.done = True
            self.buf.clear()
            self.cond.notify_all()
        if self.proc.poll() is None:
            self.proc.kill()
        self.proc.wait()
        self.err_thread.join(timeout=2)
        return self.err.decode("utf-8", "replace").strip()


def _ff() -> list[str]:
    return ["ffmpeg", "-hide_banner", "-nostdin", "-v", "error"]


def source_cmd(job: RangeJob, hw: bool, size: tuple[int, int] | None = None, frames: int | None = None) -> list[str]:
    args = list(job.source_args)
    vf_i = args.index("-vf") + 1
    W, H = size or job.size
    extra = "" if (W, H) == tuple(job.size) else f",scale={W}:{H}:flags=area"
    args[vf_i] = args[vf_i] + extra + ",format=rgb24"
    cmd = _ff() + (["-hwaccel", "videotoolbox"] if hw else []) + args
    return cmd + ["-frames:v", str(frames or job.frames), "-an", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]


def base_cmd(base: Path, pre: list[str], base_fps: float, fps: int, f0: int, n: int,
             size: tuple[int, int] | None = None, full_size: tuple[int, int] | None = None, pix_fmt: str = "rgb24") -> list[str]:
    """Frames f0..f0+n of the base on the output grid (exact: accurate seek without an fps change, else from 0)."""
    filters = list(pre)
    if size is not None and full_size is not None and tuple(size) != tuple(full_size):
        filters.append(f"scale={size[0]}:{size[1]}:flags=area")
    seek: list[str] = []
    if f0 > 0 and abs(base_fps - fps) <= 0.01:
        seek = ["-ss", f"{max(0.0, (f0 - 0.25) / fps):.6f}"]
    elif f0 > 0:
        filters.append(f"select='gte(n\\,{f0})'")
    filters.append(f"format={pix_fmt}")
    return _ff() + seek + ["-i", str(base), "-map", "0:v:0", "-vf", ",".join(filters), "-fps_mode", "passthrough",
                           "-frames:v", str(n), "-an", "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]


def matte_cmd(path: Path, size: tuple[int, int] | None = None, full_size: tuple[int, int] | None = None) -> list[str]:
    vf = ["format=gray"]
    if size is not None and full_size is not None and tuple(size) != tuple(full_size):
        vf.insert(0, f"scale={size[0]}:{size[1]}:flags=area")
    return _ff() + ["-i", str(path), "-map", "0:v:0", "-vf", ",".join(vf), "-fps_mode", "passthrough",
                    "-an", "-f", "rawvideo", "-pix_fmt", "gray", "-"]


def _encoder(tmp: Path, size: tuple[int, int], fps: int) -> subprocess.Popen:
    W, H = size
    return subprocess.Popen(_ff() + ["-y", "-f", "rawvideo", "-pix_fmt", "gray", "-s", f"{W}x{H}", "-framerate", str(fps),
                                     "-i", "-", "-c:v", "ffv1", "-level", "3", "-slices", "4", "-g", "1",
                                     "-pix_fmt", "gray", "-f", "matroska", str(tmp)],
                            stdin=subprocess.PIPE, stderr=subprocess.PIPE)


def count_frames(path: Path) -> int:
    proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries",
                           "stream=nb_read_packets", "-of", "csv=p=0", str(path)], capture_output=True, text=True)
    try:
        return int(proc.stdout.strip().split(",")[0])
    except ValueError:
        return -1


def _small(frame: np.ndarray) -> np.ndarray:
    cv2 = _cv2()
    h, w = frame.shape[:2]
    k = SYNC_SIZE / min(h, w)
    size = (max(8, int(round(w * k))), max(8, int(round(h * k))))
    g = cv2.cvtColor(frame, cv2.COLOR_RGB2GRAY) if frame.ndim == 3 else frame
    return cv2.resize(g, size, interpolation=cv2.INTER_AREA).astype(np.float32)


def _read_all(cmd: list[str], size: tuple[int, int], what: str) -> list[np.ndarray]:
    W, H = size
    proc = subprocess.run(cmd, capture_output=True)
    n = W * H * 3
    data = proc.stdout
    if proc.returncode != 0 and not data:
        raise MatteError(f"o ffmpeg falhou ao {what}: {proc.stderr.decode('utf-8', 'replace').strip()[-300:]}")
    return [np.frombuffer(data[i:i + n], np.uint8).reshape(H, W, 3) for i in range(0, len(data) - n + 1, n)]


def sync_check(job: RangeJob, got_head: list[np.ndarray], got_tail: list[np.ndarray]) -> tuple[bool, dict]:
    """Do the first and last frames read from the source match cut.mp4 at the same positions?"""
    out = {}
    ok = True
    for name, frames, start in (("inicio", got_head, job.f0), ("fim", got_tail, job.f1 - len(got_tail))):
        if not frames:
            continue
        lo = max(0, start - 2)
        n = len(frames) + 4 + (start - 2 - lo)
        ref = _read_all(base_cmd(job.base, job.base_pre, job.base_fps, job.fps, lo, n), job.size,
                        "ler o corte para conferir o recorte")
        ref_s = [_small(f) for f in ref]
        got_s = [_small(f) for f in frames]
        mads = {}
        for off in (-2, -1, 0, 1, 2):
            diffs = []
            for i, g in enumerate(got_s):
                j = start + off + i - lo
                if 0 <= j < len(ref_s) and ref_s[j].shape == g.shape:
                    diffs.append(float(np.abs(ref_s[j] - g).mean()))
            if diffs:
                mads[off] = sum(diffs) / len(diffs)
        if 0 not in mads:
            ok = False
            out[name] = {"mad": None}
            continue
        best = min(mads.values())
        good = mads[0] <= SYNC_MAX_MAD and mads[0] <= best * 1.3 + 0.1
        out[name] = {"mad": round(mads[0], 3), "best_offset": min(mads, key=mads.get), "ok": good}
        ok = ok and good
    return ok, out


# ================================================================== computing one range

def _progress_line(msg: str, progress: Callable[[str], None] | None) -> None:
    if progress:
        progress(msg)


def compute_job(job: RangeJob, engine, progress: Callable[[str], None] | None = None,
                on_frames: Callable[[int], None] | None = None) -> dict:
    """Run the engine over one range and write its matte file. Returns the meta."""
    W, H = job.size
    job.path.parent.mkdir(parents=True, exist_ok=True)
    tmp = job.path.with_name(".tmp-" + job.path.name)
    started = time.time()
    method = job.method
    if method == "fonte":
        cmd = source_cmd(job, job.source_hw)
    else:
        cmd = base_cmd(job.base, job.base_pre, job.base_fps, job.fps, job.f0, job.frames)
    reader = FrameReader(cmd, (W, H), 3, "ler o vídeo")
    enc = _encoder(tmp, (W, H), job.fps)
    rows: list = []
    head: list[np.ndarray] = []
    tail: deque = deque(maxlen=SYNC_FRAMES)
    pending: deque = deque()
    written = 0
    engine.reset()
    pool = ThreadPoolExecutor(max_workers=2)
    err = ""

    def write_ready(block: bool) -> None:
        nonlocal written
        while pending and (block or pending[0].done()):
            alpha = pending.popleft().result()
            enc.stdin.write((np.clip(alpha, 0.0, 1.0) * 255.0 + 0.5).astype(np.uint8).tobytes())
            written += 1
            if on_frames:
                on_frames(1)

    st = SETTINGS["start"]
    settle = getattr(engine, "settle_start", None)
    n_start = min(st["frames"], job.frames // 3) if settle is not None and job.frames >= st["min_range"] else 0
    first: list[tuple] = []           # (frame, temporal matte, probability, gray) of the first n_start frames

    def emit(frame: np.ndarray, coarse: np.ndarray) -> None:
        rows.append(frame_stats(coarse))
        pending.append(pool.submit(engine.refine, frame, coarse))
        write_ready(len(pending) >= 3)

    try:
        for i in range(job.frames):
            frame = reader.read()
            if frame is None:
                break
            if method == "fonte":
                if len(head) < SYNC_FRAMES:
                    head.append(frame)
                tail.append(frame)
            if not n_start:
                emit(frame, engine.coarse(frame))
                continue
            a, p, gray = engine.coarse_parts(frame)
            if i < n_start:
                first.append((frame, a, p, gray))
                continue
            if i == n_start:
                fixed = settle([(fa, fp, fg) for _, fa, fp, fg in first], (a, gray))
                for (f_rgb, _, fp, _), fa in zip(first, fixed):
                    emit(f_rgb, engine.finish(fa, fp))
                first = []
            emit(frame, engine.finish(a, p))
        for f_rgb, fa, fp, _ in first:             # a range that ended before the anchor frame
            emit(f_rgb, engine.finish(fa, fp))
        write_ready(True)
    except BrokenPipeError:
        pass
    finally:
        pool.shutdown(wait=True)
        err = reader.close()
        try:
            enc.stdin.close()
        except OSError:
            pass
        enc_err = enc.stderr.read().decode("utf-8", "replace") if enc.stderr else ""
        code = enc.wait()
    if code != 0:
        tmp.unlink(missing_ok=True)
        raise MatteError(f"o ffmpeg falhou ao gravar o recorte do trecho {job.rid}: {enc_err.strip()[-300:]}")
    if written == 0:
        tmp.unlink(missing_ok=True)
        if method == "fonte":
            return {"retry": "nenhum quadro lido do vídeo bruto", "written": 0}
        raise MatteError(f"não consegui ler os quadros do trecho {job.rid} ({err[-300:] or 'vídeo vazio'})")
    sync = None
    if method == "fonte":
        ok, sync = sync_check(job, head, list(tail))
        if not ok or written != job.frames:
            tmp.unlink(missing_ok=True)
            why = "os quadros do vídeo bruto não batem com o corte" if not ok else "o vídeo bruto terminou antes"
            return {"retry": why, "sync": sync, "written": written}
    if written < job.frames:
        # the base ended early: hold the last matte so the frame count stays exact
        tmp.unlink(missing_ok=True)
        raise MatteError(f"o trecho {job.rid} tem {written} quadros e o corte espera {job.frames}. Renderize o corte de novo")
    got = count_frames(tmp)
    if got != job.frames:
        tmp.unlink(missing_ok=True)
        raise MatteError(f"o recorte do trecho {job.rid} saiu com {got} quadros, esperava {job.frames}")
    os.replace(tmp, job.path)
    seconds = time.time() - started
    meta = {"key": job.key, "engine": engine_version(), "provider": getattr(engine, "provider", "?"),
            "id": job.rid, "method": method, "source": str(job.source) if job.source else None,
            "base": job.base.name if job.base else None, "note": job.note, "frames": job.frames,
            "size": list(job.size), "fps": job.fps, "stats": summarize_stats(rows), "sync": sync,
            "seconds": round(seconds, 2), "created_at": now_iso()}
    save_json(job.meta_path, meta)
    job.seconds = seconds
    return meta


def _load_cached(job: RangeJob) -> dict | None:
    meta = load_json(job.meta_path) if job.meta_path.exists() else None
    if (isinstance(meta, dict) and meta.get("key") == job.key and job.path.exists()
            and job.path.stat().st_size > 0 and int(meta.get("frames") or -1) == job.frames):
        return meta
    return None


@dataclass
class MatteSet:
    jobs: list[RangeJob]
    size: tuple[int, int]
    fps: int
    seconds: float = 0.0
    computed: int = 0
    warnings: list[str] = field(default_factory=list)
    provider: str = ""

    @property
    def cached(self) -> int:
        return sum(1 for j in self.jobs if j.cached)

    def report(self, rel: Callable[[Path], str] = str) -> dict:
        return {"engine": engine_version(), "model": MODEL_NAME, "provider": self.provider or None,
                "seconds": round(self.seconds, 2), "cached": self.cached, "computed": self.computed,
                "ranges": [{"id": j.rid, "start_frame": j.f0, "end_frame": j.f1, "method": j.method,
                            "note": j.note or None, "file": rel(j.path), "cached": j.cached,
                            "seconds": j.meta.get("seconds"), "stats": j.meta.get("stats")} for j in self.jobs]}

    def frames(self, size: tuple[int, int] | None = None) -> Iterator[np.ndarray]:
        """Every matte frame in order (uint8 HxW), optionally scaled to `size`."""
        W, H = size or self.size
        for job in self.jobs:
            reader = FrameReader(matte_cmd(job.path, (W, H), self.size), (W, H), 1, "ler o recorte")
            got = 0
            last = None
            try:
                for _ in range(job.frames):
                    fr = reader.read()
                    if fr is None:
                        break
                    last = fr
                    got += 1
                    yield fr
            finally:
                err = reader.close()
            if got < job.frames:
                if last is None:
                    raise MatteError(f"não consegui ler o recorte do trecho {job.rid} ({err[-200:]})")
                for _ in range(job.frames - got):
                    yield last


def ensure(edit_dir: Path, base: Path, bounds: list[tuple[int, int]], fps: int, size: tuple[int, int],
           timeline: dict | None, progress: Callable[[str], None] | None = print, force: bool = False,
           base_fps: float | None = None, base_size: tuple[int, int] | None = None) -> MatteSet:
    """The matte of every range, computed now when it is not in the cache."""
    require_binary("ffmpeg")
    jobs = plan_jobs(edit_dir, base, bounds, fps, size, timeline, base_fps, base_size)
    mset = MatteSet(jobs=jobs, size=tuple(size), fps=fps)
    todo = []
    for job in jobs:
        meta = None if force else _load_cached(job)
        if meta is not None:
            job.cached, job.meta = True, meta
            mset.provider = mset.provider or str(meta.get("provider") or "")
        else:
            todo.append(job)
    if not todo:
        return mset
    default_engine_ready()
    total_frames = sum(j.frames for j in todo)
    video_s = total_frames / fps
    est = video_s * SECONDS_PER_SECOND
    cached_note = f", {len(jobs) - len(todo)} já prontos" if len(todo) < len(jobs) else ""
    _progress_line(f"recorte da pessoa: {len(todo)} trecho(s), {video_s:.1f}s de vídeo (leva uns "
                   f"{_duration_words(est)}{cached_note})", progress)
    started = time.time()
    done_frames = [0]
    last_print = [started]

    def tick(n: int) -> None:
        done_frames[0] += n
        now = time.time()
        if now - last_print[0] >= PROGRESS_EVERY and done_frames[0] < total_frames:
            last_print[0] = now
            pct = 100.0 * done_frames[0] / max(1, total_frames)
            rate = done_frames[0] / max(1e-6, now - started)
            left = (total_frames - done_frames[0]) / max(1e-6, rate)
            _progress_line(f"recorte da pessoa: {pct:.0f}% (falta uns {_duration_words(left)})", progress)

    engine = make_engine(tuple(size))
    mset.provider = str(getattr(engine, "provider", "") or "")
    try:
        for job in todo:
            meta = compute_job(job, engine, progress, tick)
            if "retry" in meta:
                why = meta["retry"]
                # back to cut.mp4 for this range: frames already counted are counted again
                done_frames[0] -= min(done_frames[0], int(meta.get("written") or 0))
                job.method, job.note, job.source = "corte", why, None
                job.key = _short({"v": engine_version(), "s": SETTINGS, "how": "corte", "base": job.base.name,
                                  "sig": file_signature(job.base), "f0": job.f0, "f1": job.f1, "size": list(size),
                                  "fps": fps, "pre": job.base_pre})
                job.path = job.path.with_name(f"m_{job.key}.mkv")
                job.meta_path = job.path.with_suffix(".json")
                cached = None if force else _load_cached(job)
                if cached is not None:
                    job.cached, job.meta = True, cached
                    continue
                meta = compute_job(job, engine, progress, tick)
            job.meta = meta
            mset.computed += 1
    finally:
        try:
            engine.close()
        except Exception:  # noqa: BLE001
            pass
    mset.seconds = time.time() - started
    notes = sorted({j.note for j in jobs if j.method == "corte" and j.note and not j.cached})
    if notes and timeline:
        mset.warnings.append("recorte feito a partir do cut.mp4 em vez do vídeo bruto (" + "; ".join(notes) + ")")
    _progress_line(f"recorte da pessoa pronto: {len(jobs)} trecho(s) ({mset.cached} do cache) em {mset.seconds:.1f}s "
                   f"({mset.seconds / max(video_s, 1e-6):.1f}x a duração)", progress)
    return mset


def _duration_words(seconds: float) -> str:
    if seconds < 90:
        return f"{max(1, int(round(seconds)))} s"
    return f"{int(round(seconds / 60.0))} min"


def estimate_seconds(duration: float) -> float:
    return duration * SECONDS_PER_SECOND


# ================================================================== CLI

def _segments_bounds(timeline: dict | None, nf: int, fps: int) -> list[tuple[int, int]]:
    starts = []
    for s in (timeline or {}).get("segments") or []:
        try:
            starts.append(int(round(float(s["out_start"]) * fps + 1e-6)))
        except (KeyError, TypeError, ValueError):
            continue
    cuts = sorted({f for f in starts if 0 < f < nf})
    b = [0] + cuts + [nf]
    return [(x, y) for x, y in zip(b, b[1:]) if y > x]


def _base_facts(base: Path) -> tuple[float, tuple[int, int], int]:
    info = probe_video(base)
    fps = float(info.get("fps") or 30.0)
    size = (int(info.get("display_width") or info.get("width") or 0), int(info.get("display_height") or info.get("height") or 0))
    frames = count_frames(base)
    if frames <= 0:
        frames = int(round(float(info.get("duration") or 0) * fps))
    return fps, size, frames


def run_edit(edit_dir: Path, video: Path | None, force: bool) -> tuple[MatteSet, dict]:
    edit_dir = edit_dir.resolve()
    base = (video or edit_dir / "cut.mp4").resolve()
    if not base.exists():
        raise MatteError(f"vídeo não encontrado: {base}", 2)
    timeline = load_json(edit_dir / "cut_timeline.json") if base == edit_dir / "cut.mp4" else None
    base_fps, base_size, nf = _base_facts(base)
    from common import output_fps_for  # noqa: PLC0415
    fps = int(round(float((timeline or {}).get("fps") or output_fps_for(base_fps))))
    size = (int((timeline or {}).get("width") or base_size[0]), int((timeline or {}).get("height") or base_size[1]))
    size = (size[0] - size[0] % 2, size[1] - size[1] % 2)
    if abs(base_fps - fps) > 0.01:
        nf = int(round(nf / base_fps * fps))
    bounds = _segments_bounds(timeline, nf, fps)
    mset = ensure(edit_dir, base, bounds, fps, size, timeline, progress=lambda m: print(m, flush=True), force=force,
                  base_fps=base_fps, base_size=base_size)
    return mset, {"base": base, "frames": nf, "fps": fps}


def image_matte(src: Path, out: Path) -> dict:
    """One photo: the cut-out as a PNG with transparency (no temporal filter)."""
    cv2 = _cv2()
    bgr = cv2.imread(str(src), cv2.IMREAD_COLOR)
    if bgr is None:
        raise MatteError(f"não consegui abrir a imagem {src}", 2)
    h, w = bgr.shape[:2]
    rgb = np.ascontiguousarray(bgr[..., ::-1])
    rgb = np.ascontiguousarray(rgb[:h - h % 2, :w - w % 2])
    engine = make_engine((rgb.shape[1], rgb.shape[0]))
    try:
        alpha = engine.refine(rgb, engine.coarse(rgb))
    finally:
        engine.close()
    a8 = (np.clip(alpha, 0, 1) * 255 + 0.5).astype(np.uint8)
    rgba = np.dstack([rgb[..., ::-1], a8])
    out.parent.mkdir(parents=True, exist_ok=True)
    cv2.imwrite(str(out), rgba)
    return {"file": str(out), "width": rgb.shape[1], "height": rgb.shape[0],
            "person_share": round(float((alpha > 0.5).mean()), 4)}


def main(argv: list[str] | None = None) -> int:
    for stream in (sys.stdout, sys.stderr):
        try:
            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
        except (AttributeError, ValueError, OSError):
            pass
    ap = argparse.ArgumentParser(description="Recorta a pessoa de cada trecho do corte (tela verde) e guarda o "
                                             "recorte para o compose_final.py. Leva uns 3 minutos por minuto de vídeo.")
    ap.add_argument("--edit-dir", help="pasta edit da sessão")
    ap.add_argument("--video", help="vídeo a recortar (padrão: edit/cut.mp4)")
    ap.add_argument("--force", action="store_true", help="recorta de novo mesmo com o recorte guardado")
    ap.add_argument("--json", action="store_true", help="imprime o resumo em JSON")
    ap.add_argument("--check", action="store_true", help="só confere se o recorte funciona neste computador")
    ap.add_argument("--image", help="recorta uma foto (teste rápido)")
    ap.add_argument("-o", "--output", help="com --image: PNG de saída")
    args = ap.parse_args(argv)
    try:
        if args.check:
            info = check_engine()
            seg = OnnxSegmenter(sessions=1)
            t0 = time.perf_counter()
            y = seg.raw(np.zeros((64, 64, 3), np.uint8))
            ms = (time.perf_counter() - t0) * 1000
            seg.close()
            print(f"ok: recorte da pessoa pronto (onnxruntime {info['onnxruntime']}, {seg.provider}, saída "
                  f"{tuple(y.shape)}, {ms:.0f} ms no primeiro quadro)")
            return 0
        if args.image:
            if not args.output:
                print("erro: use -o arquivo.png junto com --image", file=sys.stderr)
                return 2
            res = image_matte(Path(args.image).expanduser(), Path(args.output).expanduser())
            print(f"ok: {res['file']} ({res['width']}x{res['height']}, pessoa em {res['person_share'] * 100:.0f}% da imagem)")
            return 0
        if not args.edit_dir:
            print("erro: diga a pasta com --edit-dir (ou use --check)", file=sys.stderr)
            return 2
        edit = Path(args.edit_dir).expanduser()
        if not edit.is_dir():
            print(f"erro: pasta de edição não encontrada: {edit}", file=sys.stderr)
            return 2
        mset, facts = run_edit(edit, Path(args.video).expanduser() if args.video else None, args.force)
        rep = mset.report(lambda p: str(p.relative_to(edit.resolve())) if p.is_relative_to(edit.resolve()) else str(p))
        for w in mset.warnings:
            print(f"aviso: {w}")
        if args.json:
            print(json.dumps(rep, ensure_ascii=False, indent=2))
            return 0
        for j in mset.jobs:
            st = j.meta.get("stats") or {}
            who = "sem pessoa" if not st.get("person_frames") else f"cabeça em {st.get('top', 0):.2f} da altura"
            print(f"  {j.rid:>5} {fmt_time(j.f0 / facts['fps'])}-{fmt_time(j.f1 / facts['fps'])}  "
                  f"{'cache' if j.cached else j.method:>6}  {who}")
        print(f"ok: {len(mset.jobs)} trecho(s) recortados em {edit.resolve() / CACHE_DIR}")
        return 0
    except MatteError as e:
        print(f"erro: {e}", file=sys.stderr)
        return e.code
    except KeyboardInterrupt:
        print("interrompido", file=sys.stderr)
        return 130


if __name__ == "__main__":
    sys.exit(main())