primocode 10.16.0 → 10.17.1

package/editor/helpers/render_cut.py

@@ -0,0 +1,1256 @@
+# Adapted from browser-use/video-use (MIT, (c) 2026 Browser Use). See THIRD_PARTY_NOTICES.md.
+"""EDL -> cut.mp4 + cut_timeline.json (Contract 5 of SPEC.md).
+
+Usage:
+    uv run python helpers/render_cut.py <edit>/edl.json [-o cut.mp4] [--jobs N] [--no-jcut] [--preview]
+
+Pipeline
+  1. Plan: the audio of a range starts exactly at the EDL start. The picture starts on the
+     nearest source frame when one is within half an output frame, else at the exact time
+     (sparse VFR sources such as screen recordings: the frame on screen at that time is used).
+     Lengths are whole output frames. J-cut per junction: the incoming picture skips
+     `lead_frames` while its audio keeps them (so it starts earlier, over the outgoing
+     picture); the outgoing tail loses up to `tail_trim_frames` only where there is no
+     measured speech (edit/regions/<stem>.json, or an inline silencedetect when missing).
+     A range with "dry": false keeps its written edges: no lead and no tail trim on it (a video playing
+     on screen starts on its first frame).
+     A source whose shape differs from the output is cropped around `focus_x`/`focus_y` of
+     the range, or around the face found by YuNet when the crop is large.
+     "imagem_de": "CAM2" on a range: the audio still comes from the range's source and the picture
+     from CAM2 at the same instant, through sincronia.json (sincronizar_cameras.py; the EDL key
+     "sincronia" points to another file). A source used only as audio (a lapela .wav) needs no video.
+     Two ranges in a row from the same audio source that touch (start of the second within half a
+     frame of the end of the first) are one continuous voice: no J-cut and no 30 ms fades there, and
+     the second one's audio starts on the exact sample where the first one's ends (a camera switch in
+     the middle of a sentence does not dip or skip). Their gain_db must match, or the fades stay.
+  2. Extract, in parallel, one picture clip (H.264, final quality, upright, scaled+cropped,
+     fps, HDR->SDR, 8-bit guard, grade, bt709/tv tags) and one float WAV (48k stereo,
+     gain+limiter, 30 ms fades, sample-exact length) per range into edit/clips/ (cached).
+  3. Count the encoded frames of each clip -> out_start/out_end (frame-accurate).
+  4. Picture: concat demuxer, stream copy. Audio: adelay in samples + amix normalize=0,
+     loudnorm two-pass (I=-14, TP=-1, LRA=11), AAC 192k, length pinned with -t. The true peak
+     of the encoded file is measured; above -1.05 dBTP (a margin for verify_cut's ebur128 reading)
+     the audio is lowered and encoded again.
+  5. Write <output stem>_timeline.json (cut_timeline.json by default). A full render inside
+     the edit dir also merges state.json (awaiting stays null: verify_cut asks for approval).
+     `--preview` writes cut_preview.mp4 and leaves cut.mp4 and state.json alone.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import re
+import subprocess
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from fractions import Fraction
+from pathlib import Path
+
+from functools import lru_cache
+
+from common import (ASSETS_DIR, OUTPUT_FORMATS, file_signature, fmt_time, load_json, nominal_fps, now_iso,
+                    output_fps_for, probe_video, require_binary, save_json)
+from common import has_ffmpeg_filter as _has_ffmpeg_filter
+from grade import check_filter, graded_chain, hdr_to_sdr_chain, resolve_grade
+
+SR = 48000
+FADE_SAMPLES = 1440            # 30 ms
+SPEECH_GUARD_S = 0.10          # the tail trim never gets closer than this to measured speech (a weak
+                               # final consonant sits under the speech regions; 0.04 bit it)
+MIN_JOIN_GAP_S = 0.10          # silence kept between outgoing and incoming speech after a J-cut
+SILENCE_NOISE_DB = -35
+MIN_PIC_FRAMES = 6
+DEFAULT_JCUT = {"lead_frames": 4, "tail_trim_frames": 2}
+LOUDNORM = {"I": -14.0, "TP": -1.0, "LRA": 11.0}
+TRUE_PEAK_LIMIT = -1.0         # delivered cut.mp4 (after AAC) must not go above this
+TRUE_PEAK_MARGIN = 0.05        # loudnorm (here) and ebur128 (verify_cut) read the true peak a few hundredths apart
+CACHE_VERSION = "render_cut/2"
+SYNC_FILE = "sincronia.json"
+BT709_TAGS = "setparams=range=tv:color_primaries=bt709:color_trc=bt709:colorspace=bt709"
+ASPECT_WARN = 1.15             # source/output shape ratio beyond this: warn and frame on the face
+CROP_MIN = 0.02                # crops smaller than this are just "fill", not recorded
+REPEAT_TOL_S = 0.02
+FACE_MODEL = ASSETS_DIR / "models" / "face_detection_yunet_2023mar.onnx"
+FACE_SAMPLES = 5
+
+
+@lru_cache(maxsize=None)
+def has_ffmpeg_filter(name: str) -> bool:
+    return _has_ffmpeg_filter(name)
+
+
+class CutError(Exception):
+    def __init__(self, message: str, code: int = 1):
+        super().__init__(message)
+        self.code = code
+
+
+def log(msg: str = "") -> None:
+    print(msg, flush=True)
+
+
+def warn(msg: str) -> None:
+    print(f"aviso: {msg}", file=sys.stderr, flush=True)
+
+
+def ffmpeg(cmd: list[str], what: str) -> subprocess.CompletedProcess:
+    proc = subprocess.run([str(c) for c in cmd], capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise CutError(f"o ffmpeg falhou ao {what}:\n{(proc.stderr or '').strip()[-1500:]}")
+    return proc
+
+
+def edl_signature(edl: dict) -> str:
+    return hashlib.sha1(json.dumps(edl, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()[:16]
+
+
+# ------------------------------------------------------------------ EDL loading
+
+
+def resolve_source(value: str, edit_dir: Path) -> Path:
+    p = Path(value).expanduser()
+    if p.is_absolute():
+        return p
+    for base in (edit_dir, edit_dir.parent):
+        cand = Path(os.path.abspath(base / p))
+        if cand.exists():
+            return cand
+    return Path(os.path.abspath(edit_dir / p))
+
+
+def load_edl(path: Path) -> dict:
+    if not path.exists():
+        raise CutError(f"EDL não encontrado: {path}", 2)
+    try:
+        edl = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise CutError(f"o EDL não é um JSON válido ({path.name}, linha {exc.lineno}): {exc.msg}", 2)
+    if not isinstance(edl, dict):
+        raise CutError("o EDL precisa ser um objeto JSON", 2)
+    ranges = edl.get("ranges")
+    if not isinstance(ranges, list) or not ranges:
+        raise CutError("o EDL não tem trechos em \"ranges\"", 2)
+    sources = edl.get("sources") or {}
+    if not isinstance(sources, dict) or not sources:
+        raise CutError("o EDL não tem \"sources\" (mapa nome -> caminho do vídeo)", 2)
+    seen: set[str] = set()
+    for i, r in enumerate(ranges):
+        rid = str(r.get("id") or f"r{i + 1}")
+        r["id"] = rid
+        if rid in seen:
+            raise CutError(f"id repetido no EDL: {rid}", 2)
+        seen.add(rid)
+        if r.get("source") not in sources:
+            raise CutError(f"trecho {rid}: fonte {r.get('source')!r} não está em \"sources\"", 2)
+        try:
+            r["start"], r["end"] = float(r["start"]), float(r["end"])
+        except (KeyError, TypeError, ValueError):
+            raise CutError(f"trecho {rid}: start/end precisam ser números em segundos", 2)
+        if r["start"] < 0 or r["end"] <= r["start"]:
+            raise CutError(f"trecho {rid}: end ({r['end']}) precisa ser maior que start ({r['start']})", 2)
+        try:
+            r["gain_db"] = float(r.get("gain_db") or 0.0)
+        except (TypeError, ValueError):
+            raise CutError(f"trecho {rid}: gain_db inválido", 2)
+        for k in ("focus_x", "focus_y"):
+            if r.get(k) is None:
+                continue
+            try:
+                r[k] = float(r[k])
+            except (TypeError, ValueError):
+                raise CutError(f"trecho {rid}: {k} precisa ser um número de 0 a 1", 2)
+            if not 0.0 <= r[k] <= 1.0:
+                raise CutError(f"trecho {rid}: {k} precisa ficar entre 0 e 1 (0 = esquerda/topo, 1 = direita/base)", 2)
+        pic = r.get("imagem_de")
+        if pic in (None, "", False) or pic == r["source"]:
+            r["imagem_de"] = None
+        elif not isinstance(pic, str) or pic not in sources:
+            raise CutError(f"trecho {rid}: imagem_de {pic!r} não está em \"sources\" (ponha a câmera lá, com o caminho)", 2)
+    return edl
+
+
+def picture_key(r: dict) -> str:
+    """The source the picture of a range comes from."""
+    return r.get("imagem_de") or r["source"]
+
+
+def load_sync(edl: dict, edit_dir: Path, probes: dict) -> tuple[dict[str, tuple[float, float]], Path | None]:
+    """{source: (offset, scale)} from sincronia.json for every source a range with imagem_de touches.
+
+    Rule of the file: time in the source = deslocamento + ajuste_s + escala x time in the main one."""
+    needed = sorted({k for r in edl["ranges"] if r.get("imagem_de") for k in (r["source"], r["imagem_de"])})
+    if not needed:
+        return {}, None
+    raw = edl.get("sincronia") or SYNC_FILE
+    path = resolve_source(str(raw), edit_dir)
+    if not path.exists():
+        raise CutError(f"trechos com imagem_de precisam da sincronia das câmeras e {path} não existe. Rode "
+                       f"helpers/sincronizar_cameras.py --edl <EDIT>/edl_manual.json (ou ponha \"sincronia\" no EDL)", 2)
+    doc = load_json(path)
+    fontes = doc.get("fontes") if isinstance(doc, dict) else None
+    if not isinstance(fontes, dict):
+        raise CutError(f"{path.name} não é um arquivo de sincronia (falta \"fontes\")", 2)
+    out: dict[str, tuple[float, float]] = {}
+    for key in needed:
+        f = fontes.get(key)
+        if not isinstance(f, dict):
+            raise CutError(f"a fonte {key} não está em {path.name}: rode sincronizar_cameras.py com ela junto", 2)
+        try:
+            off = float(f.get("deslocamento") or 0.0) + float(f.get("ajuste_s") or 0.0)
+            scale = float(f.get("escala") or 1.0)
+        except (TypeError, ValueError):
+            raise CutError(f"{path.name}: deslocamento, ajuste_s ou escala de {key} não é número", 2)
+        if not 0.9 < scale < 1.1:
+            raise CutError(f"{path.name}: escala {scale} de {key} fora do razoável", 2)
+        src = probes[key]["path"]
+        measured = Path(str(f.get("arquivo") or ""))
+        same_path = measured.exists() and os.path.samefile(measured, src)
+        same_sig = f.get("assinatura") == file_signature(src)
+        if not same_path and not same_sig:
+            raise CutError(f"{path.name} mediu {key} em outro arquivo ({measured}), não em {src}: rode "
+                           "sincronizar_cameras.py de novo", 2)
+        if same_path and not same_sig and f.get("assinatura"):
+            warn(f"{src.name} mudou depois da sincronia ({path.name}): se foi reexportado, rode sincronizar_cameras.py de novo")
+        if f.get("confianca") == "fraca":
+            warn(f"a sincronia de {key} saiu fraca em {path.name}: confira no olho (sincronizar_cameras.py --prova)")
+        out[key] = (off, scale)
+    return out, path
+
+
+def jcut_settings(edl: dict, no_jcut: bool) -> dict:
+    raw = edl.get("jcut", None)
+    if no_jcut or raw is False:
+        return {"enabled": False, "lead_frames": 0, "tail_trim_frames": 0}
+    cfg = dict(DEFAULT_JCUT)
+    if isinstance(raw, dict):
+        for k in cfg:
+            if raw.get(k) is not None:
+                cfg[k] = max(0, int(raw[k]))
+    return {"enabled": cfg["lead_frames"] > 0 or cfg["tail_trim_frames"] > 0, **cfg}
+
+
+# ------------------------------------------------------------------ source analysis
+
+
+def source_frame_times(src: Path, t: float, before: float = 3.0, after: float = 3.0) -> list[float]:
+    """Presentation times of the source frames around t (packets, no decoding).
+
+    The window is wide and the list is sorted: with B-frames the packets come in decode order,
+    and ffprobe stops reading at the first packet past the window end, so a narrow window
+    loses frames that sit just before t.
+    """
+    proc = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "v:0", "-read_intervals",
+         f"{max(0.0, t - before):.3f}%{t + after:.3f}", "-show_entries", "packet=pts_time",
+         "-of", "csv=p=0", str(src)], capture_output=True, text=True)
+    out = set()
+    for line in proc.stdout.splitlines():
+        try:
+            out.add(float(line.strip().strip(",")))
+        except ValueError:
+            continue
+    return sorted(out)
+
+
+def picture_start(src: Path, t: float, fps: int) -> tuple[float, bool]:
+    """(source time of the first picture frame, snapped?).
+
+    Snaps to the nearest real frame only when it is within half an output frame. A sparse VFR
+    source (static screen recording) has no frame near t: the exact time is kept and the
+    extraction shows the frame that is on screen at t.
+    """
+    times = source_frame_times(src, t)
+    if times:
+        near = min(times, key=lambda x: abs(x - t))
+        if abs(near - t) <= 0.5 / fps + 1e-6:
+            return near, True
+    return t, False
+
+
+def nominal_rate(src: Path, info: dict) -> float | None:
+    """Nominal fps of a source for choosing the output fps; None for sparse or variable sources
+    (screen recordings write frames only when the screen changes) that must not drag it down."""
+    avg = float(info.get("fps") or 0.0)
+    proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                           "stream=r_frame_rate", "-of", "csv=p=0", str(src)], capture_output=True, text=True)
+    try:
+        r = float(Fraction(proc.stdout.strip().split(",")[0]))
+    except (ValueError, ZeroDivisionError):
+        r = 0.0
+    if avg <= 0 or (r > 0 and avg < 0.8 * r):
+        return None
+    n = nominal_fps(avg)
+    return n if n >= 23.0 else None
+
+
+def choose_output_fps(probes: dict) -> int:
+    rates = [nominal_rate(pr["path"], pr["info"]) for pr in probes.values()]
+    rates = [r for r in rates if r]
+    return output_fps_for(max(rates)) if rates else 30
+
+
+def crop_geometry(info: dict, W: int, H: int) -> tuple[str | None, float, float]:
+    """(axis cropped "x"/"y" or None, kept fraction of that axis, source/output shape ratio)."""
+    dw, dh = info.get("display_width") or W, info.get("display_height") or H
+    ratio = (dw / dh) / (W / H)
+    if ratio > 1.0 + CROP_MIN:
+        return "x", 1.0 / ratio, ratio
+    if ratio < 1.0 - CROP_MIN:
+        return "y", ratio, ratio
+    return None, 1.0, ratio
+
+
+def face_focus(src: Path, t0: float, t1: float) -> tuple[float, float, int] | None:
+    """Median center (0..1, upright frame) of the biggest face on FACE_SAMPLES frames of [t0, t1].
+
+    Returns (x, y, frames with a face), or None when OpenCV or the model is missing."""
+    if not FACE_MODEL.exists():
+        return None
+    os.environ.setdefault("OPENCV_LOG_LEVEL", "ERROR")
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        return None
+    xs, ys = [], []
+    for i in range(FACE_SAMPLES):
+        t = t0 + (i + 0.5) * (t1 - t0) / FACE_SAMPLES
+        proc = subprocess.run(["ffmpeg", "-v", "error", "-nostdin", "-ss", f"{t:.3f}", "-i", str(src), "-frames:v", "1",
+                               "-an", "-vf", "scale=640:-2", "-f", "image2pipe", "-c:v", "png", "-"], capture_output=True)
+        if proc.returncode != 0 or not proc.stdout:
+            continue
+        img = cv2.imdecode(np.frombuffer(proc.stdout, np.uint8), cv2.IMREAD_COLOR)
+        if img is None:
+            continue
+        h, w = img.shape[:2]
+        try:
+            det = cv2.FaceDetectorYN.create(str(FACE_MODEL), "", (w, h), 0.6, 0.3, 50)
+            _, faces = det.detect(img)
+        except cv2.error:
+            return None
+        if faces is None or not len(faces):
+            continue
+        x, y, fw, fh = max(faces, key=lambda f: f[2] * f[3])[:4]
+        xs.append(min(1.0, max(0.0, (x + fw / 2) / w)))
+        ys.append(min(1.0, max(0.0, (y + fh / 2) / h)))
+    if not xs:
+        return 0.5, 0.5, 0
+    return float(np.median(xs)), float(np.median(ys)), len(xs)
+
+
+def parse_silences(stderr: str, t0: float, t1: float) -> list[list[float]]:
+    sil: list[list[float]] = []
+    cur = None
+    for line in stderr.splitlines():
+        m = re.search(r"silence_start: (-?[\d.]+)", line)
+        if m:
+            cur = max(0.0, float(m.group(1)))
+            continue
+        m = re.search(r"silence_end: (-?[\d.]+)", line)
+        if m and cur is not None:
+            sil.append([t0 + cur, t0 + float(m.group(1))])
+            cur = None
+    if cur is not None:
+        sil.append([t0 + cur, t1])
+    return sil
+
+
+def _intersect(a: list, b: list) -> list:
+    out, i, j = [], 0, 0
+    while i < len(a) and j < len(b):
+        lo, hi = max(a[i][0], b[j][0]), min(a[i][1], b[j][1])
+        if hi > lo:
+            out.append([lo, hi])
+        if a[i][1] < b[j][1]:
+            i += 1
+        else:
+            j += 1
+    return out
+
+
+def speech_in_window(edit_dir: Path, stem: str, src: Path, info: dict, t0: float, t1: float) -> tuple[list, str]:
+    """Measured speech intervals inside [t0, t1] of a source.
+
+    edit/regions/<stem>.json is the authority when present and made from this very file (same
+    source_sig); its coarse min_silence (0.25 s)
+    hides the short pauses editors cut at, so the edge window is refined with a fine
+    silencedetect (same noise floor, 0.08 s) and the two are intersected. Without a regions
+    file only the fine pass is used (noise -35 dB).
+    """
+    t0 = max(0.0, t0)
+    if not info.get("has_audio") or t1 - t0 <= 0.01:
+        return [], "sem áudio"
+    reg = load_json(edit_dir / "regions" / f"{stem}.json")
+    reg_spans = None
+    noise = SILENCE_NOISE_DB
+    if isinstance(reg, dict) and isinstance(reg.get("speech"), list) and "start" not in reg:
+        # regions of another file with the same name (video.mov + video.mp4) or of an older copy do not count
+        same_file = reg.get("source_sig") in (None, file_signature(src))
+        if same_file and abs(float(reg.get("duration") or info["duration"]) - info["duration"]) < 0.2:
+            reg_spans = [[max(t0, float(a)), min(t1, float(b))] for a, b in reg["speech"]
+                         if float(b) > t0 and float(a) < t1]
+            try:
+                noise = float(reg.get("noise_db", noise))
+            except (TypeError, ValueError):
+                pass
+    proc = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-nostats", "-nostdin", "-ss", f"{t0:.3f}", "-t", f"{t1 - t0:.3f}",
+         "-i", str(src), "-vn", "-af", f"silencedetect=n={noise:g}dB:d=0.08", "-f", "null", "-"],
+        capture_output=True, text=True)
+    sil = parse_silences(proc.stderr, t0, t1)
+    fine, cur = [], t0
+    for a, b in sil:
+        if a > cur + 1e-3:
+            fine.append([cur, a])
+        cur = max(cur, b)
+    if cur < t1 - 1e-3:
+        fine.append([cur, t1])
+    if reg_spans is None:
+        return fine, "silencedetect"
+    return _intersect(sorted(reg_spans), fine), "regions+silencedetect"
+
+
+def channel_mode(src: Path, info: dict) -> str:
+    """stereo | mono | left | right | multi. Phase-cancelled stereo -> use the stronger channel."""
+    ch = info.get("audio_channels") or 0
+    if ch == 1:
+        return "mono"
+    if ch != 2:
+        return "multi"
+    proc = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-nostats", "-nostdin", "-t", "120", "-i", str(src), "-vn", "-af",
+         "pan=3c|c0=c0|c1=c1|c2=0.5*c0+0.5*c1,astats=metadata=0:measure_perchannel=RMS_level:measure_overall=none",
+         "-f", "null", "-"], capture_output=True, text=True)
+    levels = [float(x) if x not in ("-inf", "inf", "nan") else -120.0
+              for x in re.findall(r"RMS level dB: (-?[\w.]+)", proc.stderr)]
+    if len(levels) < 3:
+        return "stereo"
+    left, right, both = levels[:3]
+    best = max(left, right)
+    if best > -90 and both < best - 6:
+        warn(f"{src.name}: estéreo com fase invertida (L+R {both:.1f} dB contra {best:.1f} dB). Usando um canal só.")
+        return "left" if left >= right else "right"
+    return "stereo"
+
+
+_HWACCEL_CACHE: dict[str, bool] = {}
+
+
+def hwaccel_for(src: Path, info: dict) -> bool:
+    if os.environ.get("EDITOR_VIDEO_HWACCEL", "1") == "0" or sys.platform != "darwin":
+        return False
+    codec = info.get("codec", "")
+    if codec not in ("hevc", "h264", "prores"):
+        return False
+    if codec not in _HWACCEL_CACHE:
+        hw = subprocess.run(["ffmpeg", "-hide_banner", "-hwaccels"], capture_output=True, text=True).stdout
+        ok = "videotoolbox" in hw
+        if ok:
+            ok = subprocess.run(["ffmpeg", "-v", "error", "-nostdin", "-hwaccel", "videotoolbox", "-i", str(src),
+                                 "-frames:v", "2", "-an", "-f", "null", "-"], capture_output=True).returncode == 0
+        _HWACCEL_CACHE[codec] = ok
+    return _HWACCEL_CACHE[codec]
+
+
+# ------------------------------------------------------------------ planning
+
+
+@dataclass
+class Plan:
+    idx: int
+    rid: str
+    source: str
+    src: Path
+    info: dict
+    edl_start: float
+    edl_end: float
+    gain_db: float
+    beat: str = ""
+    quote: str = ""
+    pic_source: str = ""       # source key of the picture ("imagem_de", else the audio source)
+    pic_src: Path = field(default_factory=Path)
+    pic_info: dict = field(default_factory=dict)
+    pic_a: float = 0.0         # picture time = pic_a + pic_b x audio time (identity without imagem_de)
+    pic_b: float = 1.0
+    audio_start_s: float | None = None   # set when the audio continues the previous range sample for sample
+    joined: bool = False       # the audio continues from the previous range (no J-cut, no fades between them)
+    fade_in: bool = True
+    fade_out: bool = True
+    lead: int = 0
+    tail: int = 0
+    pic_start: float = 0.0     # source time of the first picture frame
+    pic_snapped: bool = True   # pic_start is a real source frame (False: sparse VFR, exact time)
+    frames: int = 0            # picture frames
+    crop: dict | None = None   # {"axis", "kept", "focus_x", "focus_y", "focus_from"} when the shape differs
+    speech_src: str = ""
+    gap_in: float = 0.0
+    gap_out: float = 0.0
+    lead_note: str = ""
+    key: str = ""
+    video_path: Path = field(default_factory=Path)
+    audio_path: Path = field(default_factory=Path)
+    meta_path: Path = field(default_factory=Path)
+    cached: bool = False
+    seconds: float = 0.0
+
+    @property
+    def audio_frames(self) -> int:
+        return self.lead + self.frames
+
+    @property
+    def audio_start(self) -> float:
+        """The audio of a range starts where the EDL says (lead frames included), or where the previous
+        range's audio ends when the two are one continuous voice."""
+        return self.edl_start if self.audio_start_s is None else self.audio_start_s
+
+    @property
+    def other_picture(self) -> bool:
+        return self.pic_source != self.source
+
+    def to_pic(self, t: float) -> float:
+        """Audio-source time -> picture-source time."""
+        return self.pic_a + self.pic_b * t
+
+
+def plan_crops(plans: list[Plan], ranges: list[dict], W: int, H: int, edit_dir: Path, jobs: int) -> None:
+    """Crop position of every range whose source shape differs from the output.
+
+    focus_x/focus_y from the EDL win; a large crop (shape ratio beyond ASPECT_WARN) is framed on
+    the median face center of the range; otherwise the crop stays centered.
+    """
+    cache_path = edit_dir / "clips" / "focus_cache.json"
+    cache = load_json(cache_path, default={}) or {}
+    warned: set[str] = set()
+    todo = []
+    for p, r in zip(plans, ranges):
+        axis, kept, ratio = crop_geometry(p.pic_info, W, H)
+        if axis is None:
+            continue
+        fx, fy = r.get("focus_x"), r.get("focus_y")
+        big = ratio > ASPECT_WARN or ratio < 1.0 / ASPECT_WARN
+        if big and p.pic_source not in warned:
+            warned.add(p.pic_source)
+            dw, dh = p.pic_info.get("display_width"), p.pic_info.get("display_height")
+            part = "largura" if axis == "x" else "altura"
+            warn(f"{p.pic_src.name} é {dw}x{dh} e a saída é {W}x{H}: o corte guarda só {kept:.0%} da {part}. "
+                 "Enquadro pelo rosto (ou pelo focus_x/focus_y do trecho); confira na folha de quadros.")
+        given = fx if axis == "x" else fy
+        p.crop = {"axis": axis, "kept": round(kept, 3), "focus_x": 0.5 if fx is None else fx,
+                  "focus_y": 0.5 if fy is None else fy, "focus_from": "edl" if given is not None else "centro"}
+        if given is None and big:
+            key = f"{file_signature(p.pic_src)}|{p.to_pic(p.edl_start):.3f}|{p.to_pic(p.edl_end):.3f}"
+            todo.append((p, key, fx, fy))
+
+    def detect(job):
+        p, key, fx, fy = job
+        hit = cache.get(key)
+        if not (isinstance(hit, list) and len(hit) == 3):
+            found = face_focus(p.pic_src, p.to_pic(p.edl_start), p.to_pic(p.edl_end))
+            hit = list(found) if found else None
+        return job, hit
+
+    with ThreadPoolExecutor(max_workers=max(1, jobs)) as pool:
+        results = list(pool.map(detect, todo))
+    for (p, key, fx, fy), hit in results:
+        if hit is None:
+            warn(f"trecho {p.rid}: não deu para procurar rosto (OpenCV indisponível); corte no centro")
+            continue
+        cache[key] = hit
+        if hit[2] == 0:
+            warn(f"trecho {p.rid}: não achei rosto em {p.pic_src.name}; corte no centro. "
+                 "Ajuste focus_x/focus_y no trecho se precisar.")
+            continue
+        if p.crop["axis"] == "x":
+            p.crop["focus_x"] = round(hit[0], 3)
+        else:
+            p.crop["focus_y"] = round(hit[1], 3)
+        p.crop["focus_from"] = "rosto"
+    if results:
+        save_json(cache_path, cache)
+
+
+def plan_cut(edl: dict, edit_dir: Path, fps: int, jcut: dict, probes: dict, jobs: int,
+             W: int = 1080, H: int = 1920, sync: dict | None = None) -> list[Plan]:
+    ranges = edl["ranges"]
+    n = len(ranges)
+    sync = sync or {}
+    plans: list[Plan] = []
+    for i, r in enumerate(ranges):
+        src = probes[r["source"]]["path"]
+        info = probes[r["source"]]["info"]
+        dur = info["duration"]
+        if r["start"] >= dur - 1.0 / fps:
+            raise CutError(f"trecho {r['id']}: start {r['start']:.2f}s passa do fim de {src.name} ({dur:.2f}s)", 2)
+        end = r["end"]
+        if end > dur:
+            warn(f"trecho {r['id']}: end {end:.2f}s passa do fim de {src.name}; usando {dur:.2f}s")
+            end = dur
+        p = Plan(i, r["id"], r["source"], src, info, r["start"], end, r["gain_db"],
+                 str(r.get("beat") or ""), str(r.get("quote") or ""))
+        p.pic_source = picture_key(r)
+        p.pic_src, p.pic_info = probes[p.pic_source]["path"], probes[p.pic_source]["info"]
+        if p.other_picture:
+            (oa, sa), (ob, sb) = sync[p.source], sync[p.pic_source]
+            p.pic_b = sb / sa
+            p.pic_a = ob - p.pic_b * oa
+            t0, t1 = p.to_pic(p.edl_start), p.to_pic(end)
+            pdur = p.pic_info["duration"]
+            if t0 < -0.5 / fps or t1 > pdur + 0.5 / fps:
+                raise CutError(f"trecho {p.rid}: a {p.pic_source} não tem imagem de {p.edl_start:.2f} a {end:.2f}s da "
+                               f"{p.source} (pela sincronia isso é {t0:.2f} a {t1:.2f}s dela, que tem {pdur:.2f}s). "
+                               "Use outra câmera nesse trecho ou encurte", 2)
+        plans.append(p)
+    for a, b in zip(plans, plans[1:]):
+        if a.source == b.source and b.edl_start < a.edl_end - REPEAT_TOL_S and b.edl_end > a.edl_start:
+            warn(f"trecho {b.rid} repete {a.edl_end - b.edl_start:.2f}s do trecho {a.rid} (mesma fonte): "
+                 f"o start {b.edl_start:.2f}s fica antes do end {a.edl_end:.2f}s do anterior")
+    # One continuous voice: the next range picks up the same audio source where this one stops.
+    for a, b in zip(plans, plans[1:]):
+        if a.source != b.source or abs(b.edl_start - a.edl_end) > 0.5 / fps:
+            continue
+        if abs(a.gain_db - b.gain_db) > 0.05:
+            warn(f"trechos {a.rid} e {b.rid} continuam a mesma fala mas têm gain_db diferente "
+                 f"({a.gain_db:+.1f} e {b.gain_db:+.1f}): a voz leva um corte de 30 ms ali. Use o mesmo gain_db "
+                 "nos dois para ela seguir inteira")
+            continue
+        b.joined = True
+        a.fade_out = b.fade_in = False
+    plan_crops(plans, ranges, W, H, edit_dir, jobs)
+
+    lead_req = jcut["lead_frames"] if jcut["enabled"] else 0
+    tail_req = jcut["tail_trim_frames"] if jcut["enabled"] else 0
+
+    # Measured silence at both edges of every range (only needed around junctions).
+    def edge_gaps(p: Plan) -> tuple[float, float, str]:
+        if not jcut["enabled"] or n == 1:
+            return 0.0, 0.0, ""
+        stem = Path(p.src).stem
+        gap_in = gap_out = 0.0
+        how = ""
+        if p.idx > 0:
+            w1 = min(p.edl_end, p.edl_start + 1.0)
+            spans, how = speech_in_window(edit_dir, stem, p.src, p.info, p.edl_start, w1)
+            first = min((max(a, p.edl_start) for a, b in spans if b > p.edl_start), default=None)
+            gap_in = (w1 - p.edl_start) if first is None else max(0.0, first - p.edl_start)
+        if p.idx < n - 1:
+            w0 = max(p.edl_start, p.edl_end - 1.0)
+            spans, how = speech_in_window(edit_dir, stem, p.src, p.info, w0, p.edl_end)
+            last = max((min(b, p.edl_end) for a, b in spans if a < p.edl_end), default=None)
+            gap_out = (p.edl_end - w0) if last is None else max(0.0, p.edl_end - last)
+        return gap_in, gap_out, how
+
+    with ThreadPoolExecutor(max_workers=max(2, jobs * 2)) as pool:
+        gaps = list(pool.map(edge_gaps, plans))
+
+    prev: Plan | None = None
+    for p, (gap_in, gap_out, how) in zip(plans, gaps):
+        p.gap_in, p.gap_out, p.speech_src = gap_in, gap_out, how
+        dur = p.pic_info["duration"]
+        # "dry": false (a video on screen, a held ending): the edges are the ones written, no J-cut on it.
+        whole = not ranges[p.idx].get("dry", True)
+        nxt_joined = p.idx < n - 1 and plans[p.idx + 1].joined
+        # Outgoing tail: trim only silence, keeping SPEECH_GUARD_S after the last word.
+        p.tail = 0
+        if tail_req and p.idx < n - 1 and not whole and not nxt_joined:
+            p.tail = max(0, min(tail_req, math.floor((gap_out - SPEECH_GUARD_S) * fps + 1e-6)))
+        # Incoming lead: the early audio overlaps the outgoing tail, but the two voices must not
+        # meet: keep MIN_JOIN_GAP_S of measured silence between them. It also may not reach back
+        # before the outgoing picture starts, nor before the source start.
+        p.lead = 0
+        if lead_req and prev is not None and not whole and not p.joined:
+            room = prev.gap_out - prev.tail / fps + gap_in - MIN_JOIN_GAP_S
+            p.lead = max(0, min(lead_req, math.floor(room * fps + 1e-6), prev.frames))
+            if p.lead < lead_req:
+                p.lead_note = "pouco silêncio na junção" if room * fps < lead_req else "trecho anterior curto"
+        if p.joined and prev is not None:
+            # the audio goes on from the exact sample where the previous range's audio stops
+            p.audio_start_s = prev.audio_start + (prev.lead + prev.frames) / fps
+        p.pic_start, p.pic_snapped = picture_start(p.pic_src, p.to_pic(p.audio_start + p.lead / fps), fps)
+        frames = 0
+        for _ in range(4):
+            total = min(round((p.to_pic(p.edl_end) - p.pic_start) * fps),
+                        math.floor((dur - p.pic_start) * fps + 1e-6))
+            frames = total - p.tail
+            if frames >= MIN_PIC_FRAMES or (p.tail == 0 and p.lead == 0):
+                break
+            if p.tail:
+                p.tail = max(0, p.tail - (MIN_PIC_FRAMES - frames))
+            elif p.lead:
+                p.lead = 0
+                p.pic_start, p.pic_snapped = picture_start(p.pic_src, p.to_pic(p.audio_start), fps)
+        if frames < 1:
+            raise CutError(f"trecho {p.rid} é curto demais ({p.edl_end - p.edl_start:.3f}s)", 2)
+        p.frames = frames
+        prev = p
+    return plans
+
+
+# ------------------------------------------------------------------ extraction
+
+
+def crop_filter(W: int, H: int, crop: dict | None) -> str:
+    """crop to WxH, centered, or around the focus point (0..1 of the scaled frame), clamped inside."""
+    if not crop or (abs(crop["focus_x"] - 0.5) < 1e-6 and abs(crop["focus_y"] - 0.5) < 1e-6):
+        return f"crop={W}:{H}"
+    fx, fy = crop["focus_x"], crop["focus_y"]
+    return (f"crop={W}:{H}:x=max(0\\,min(iw-ow\\,iw*{fx:.4f}-ow/2))"
+            f":y=max(0\\,min(ih-oh\\,ih*{fy:.4f}-oh/2))")
+
+
+def build_vf(info: dict, W: int, H: int, fps: int, grade_filter: str, crop: dict | None = None) -> str:
+    # SDR: convert any matrix (e.g. BT.601 phones) and full range to BT.709 tv while scaling.
+    # HDR keeps its matrix here; the shared HDR->SDR chain (grade.hdr_to_sdr_chain) converts it.
+    # start_time=0: with -noaccurate_seek the frames before the seek point fill the first slot,
+    # so a sparse VFR source shows the frame that is on screen at the start time.
+    matrix = "" if info.get("is_hdr") else ":out_color_matrix=bt709"
+    parts = [f"fps={fps}:start_time=0",
+             f"scale={W}:{H}:force_original_aspect_ratio=increase:flags=lanczos:out_range=tv{matrix}",
+             crop_filter(W, H, crop), "setsar=1"]
+    hdr = hdr_to_sdr_chain(info)
+    if hdr:
+        parts.append(hdr)
+    parts.append(graded_chain(grade_filter))
+    # ffmpeg takes the stream color tags from the frames: stamp them so untagged sources are tagged too.
+    parts.append(BT709_TAGS)
+    return ",".join(parts)
+
+
+AUDIO_RESAMPLE = f"aresample={SR}:async=1:first_pts=0"
+
+
+def channel_filter(mode: str) -> str:
+    """How a source's channels become stereo (mode from channel_mode)."""
+    return {"mono": "pan=stereo|c0=c0|c1=c0", "left": "pan=stereo|c0=c0|c1=c0",
+            "right": "pan=stereo|c0=c1|c1=c1"}.get(mode, "aformat=channel_layouts=stereo")
+
+
+def af_tail(gain_db: float, samples: int, fade_in: bool = True, fade_out: bool = True) -> list[str]:
+    """Gain + limiter, exact length and 30 ms fades of a range (after resampling and channel choice).
+    No fade on a side where the voice goes on into the next range (or comes from the previous one).
+    compose_final's background-noise removal runs its denoiser before this same tail."""
+    parts = []
+    if gain_db:
+        parts.append(f"volume={gain_db:.2f}dB")
+        if gain_db > 0:
+            parts.append("alimiter=limit=0.891:attack=5:release=60:level=false:latency=true")
+    fade = max(1, min(FADE_SAMPLES, samples // 4))
+    parts += [f"apad=whole_len={samples}", f"atrim=end_sample={samples}"]
+    if fade_in:
+        parts.append(f"afade=t=in:start_sample=0:nb_samples={fade}")
+    if fade_out:
+        parts.append(f"afade=t=out:start_sample={samples - fade}:nb_samples={fade}")
+    parts.append("aformat=sample_fmts=flt:channel_layouts=stereo")
+    return parts
+
+
+def build_af(p: Plan, mode: str, samples: int) -> str:
+    return ",".join([AUDIO_RESAMPLE, channel_filter(mode), *af_tail(p.gain_db, samples, p.fade_in, p.fade_out)])
+
+
+def count_frames(path: Path) -> int:
+    proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=nb_frames",
+                           "-of", "csv=p=0", str(path)], capture_output=True, text=True)
+    try:
+        return int(proc.stdout.strip().split(",")[0])
+    except ValueError:
+        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)
+        return int(proc.stdout.strip().split(",")[0] or 0)
+
+
+def wav_samples(path: Path) -> int:
+    """Sample frames in a WAV by walking its chunks (the stdlib `wave` rejects float WAVs)."""
+    try:
+        with open(path, "rb") as fh:
+            if fh.read(4) != b"RIFF":
+                return -1
+            fh.read(4)
+            if fh.read(4) != b"WAVE":
+                return -1
+            block_align = 0
+            while True:
+                head = fh.read(8)
+                if len(head) < 8:
+                    return -1
+                cid, size = head[:4], int.from_bytes(head[4:], "little")
+                if cid == b"fmt ":
+                    fmt = fh.read(size)
+                    block_align = int.from_bytes(fmt[12:14], "little")
+                    continue
+                if cid == b"data":
+                    if size in (0, 0xFFFFFFFF):   # streamed header: use the file size
+                        size = os.path.getsize(path) - fh.tell()
+                    return size // block_align if block_align else -1
+                fh.seek(size + (size & 1), 1)
+    except OSError:
+        return -1
+
+
+def extract(p: Plan, cfg: dict) -> Plan:
+    t0 = time.time()
+    fps, W, H = cfg["fps"], cfg["width"], cfg["height"]
+    spf = SR / fps
+    src_fps = p.pic_info.get("fps") or fps
+    vf = build_vf(p.pic_info, W, H, fps, cfg["grade_filter"], p.crop)
+    samples = int(round(p.audio_frames * spf))
+    audio_start = p.audio_start
+    mode = cfg["channel_modes"].get(p.source, "stereo") if p.info.get("has_audio") else "silent"
+    af = build_af(p, mode, samples)
+    enc = ["-c:v", "libx264", "-profile:v", "high", "-preset", cfg["x264_preset"], "-crf", str(cfg["crf"]),
+           "-pix_fmt", "yuv420p", "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709",
+           "-color_range", "tv", "-video_track_timescale", str(fps * 1000), "-movflags", "+faststart"]
+    key_src = {"v": CACHE_VERSION, "src": str(p.src), "sig": file_signature(p.src), "pic": round(p.pic_start, 6),
+               "snap": p.pic_snapped, "frames": p.frames, "astart": round(audio_start, 6), "samples": samples, "vf": vf, "af": af,
+               "enc": enc, "mode": mode}
+    if p.other_picture:
+        key_src.update(pic_src=str(p.pic_src), pic_sig=file_signature(p.pic_src))
+    p.key = hashlib.sha1(json.dumps(key_src, sort_keys=True).encode()).hexdigest()[:12]
+    stem = f"{cfg['mode']}_{p.idx:03d}_{re.sub(r'[^A-Za-z0-9_-]', '_', p.rid)}_{p.key}"
+    clips = cfg["clips_dir"]
+    p.video_path, p.audio_path, p.meta_path = clips / f"{stem}.mp4", clips / f"{stem}.wav", clips / f"{stem}.json"
+    meta = load_json(p.meta_path)
+    if (isinstance(meta, dict) and meta.get("key") == p.key and p.video_path.exists() and p.audio_path.exists()):
+        p.frames = int(meta["frames"])
+        p.cached = True
+        return p
+
+    # A snapped start seeks a quarter frame early so that frame lands on the first output slot.
+    pic_seek = max(0.0, p.pic_start - (0.25 / max(src_fps, fps) if p.pic_snapped else 0.0))
+    tmp_v, tmp_a = p.video_path.with_suffix(".part.mp4"), p.audio_path.with_suffix(".part.wav")
+
+    def run_extract(hw: bool) -> subprocess.CompletedProcess:
+        cmd = ["ffmpeg", "-y", "-v", "error", "-nostdin"]
+        if hw:
+            cmd += ["-hwaccel", "videotoolbox"]
+        cmd += ["-noaccurate_seek", "-ss", f"{pic_seek:.6f}", "-i", str(p.pic_src)]
+        if p.info.get("has_audio"):
+            cmd += ["-ss", f"{max(0.0, audio_start):.6f}", "-i", str(p.src)]
+            amap = "1:a:0"
+        else:
+            cmd += ["-f", "lavfi", "-i", f"anullsrc=r={SR}:cl=stereo"]
+            amap = "1:a:0"
+        cmd += ["-map", "0:v:0", "-vf", vf, "-frames:v", str(p.frames), "-an", *enc, "-f", "mp4", str(tmp_v)]
+        cmd += ["-map", amap, "-af", af, "-vn", "-c:a", "pcm_f32le", "-ar", str(SR), "-ac", "2",
+                "-f", "wav", str(tmp_a)]
+        return subprocess.run(cmd, capture_output=True, text=True)
+
+    use_hw = hwaccel_for(p.pic_src, p.pic_info)
+    proc = run_extract(use_hw)
+    if proc.returncode != 0 and use_hw:
+        warn(f"trecho {p.rid}: decodificação por hardware falhou, tentando por software")
+        proc = run_extract(False)
+    if proc.returncode != 0:
+        tmp_v.unlink(missing_ok=True)
+        tmp_a.unlink(missing_ok=True)
+        raise CutError(f"o ffmpeg falhou ao extrair o trecho {p.rid}:\n{proc.stderr.strip()[-1500:]}")
+
+    got = count_frames(tmp_v)
+    if got <= 0:
+        raise CutError(f"trecho {p.rid}: nenhum quadro extraído de {p.pic_src.name}")
+    if got != p.frames:
+        warn(f"trecho {p.rid}: esperava {p.frames} quadros e saíram {got}; ajustando o áudio")
+        p.frames = got
+        samples = int(round(p.audio_frames * spf))
+        af = build_af(p, mode, samples)
+        cmd = ["ffmpeg", "-y", "-v", "error", "-nostdin"]
+        if p.info.get("has_audio"):
+            cmd += ["-ss", f"{max(0.0, audio_start):.6f}", "-i", str(p.src), "-map", "0:a:0"]
+        else:
+            cmd += ["-f", "lavfi", "-i", f"anullsrc=r={SR}:cl=stereo", "-map", "0:a:0"]
+        cmd += ["-af", af, "-vn", "-c:a", "pcm_f32le", "-ar", str(SR), "-ac", "2", "-f", "wav", str(tmp_a)]
+        ffmpeg(cmd, f"refazer o áudio do trecho {p.rid}")
+    got_samples = wav_samples(tmp_a)
+    if got_samples >= 0 and got_samples != samples:
+        raise CutError(f"trecho {p.rid}: o áudio saiu com {got_samples} amostras, esperava {samples}")
+    os.replace(tmp_v, p.video_path)
+    os.replace(tmp_a, p.audio_path)
+    save_json(p.meta_path, {"key": p.key, "frames": p.frames, "samples": samples, "id": p.rid,
+                            "source": str(p.src), "picture": str(p.pic_src), "pic_start": p.pic_start,
+                            "pic_snapped": p.pic_snapped, "audio_start": audio_start})
+    p.seconds = time.time() - t0
+    return p
+
+
+# ------------------------------------------------------------------ assembly
+
+
+def concat_escape(path: Path) -> str:
+    return str(path).replace("'", "'\\''")
+
+
+def mix_audio(plans: list[Plan], fps: int, total_samples: int, out_wav: Path) -> None:
+    spf = SR / fps
+    cmd = ["ffmpeg", "-y", "-v", "error", "-nostdin"]
+    for p in plans:
+        cmd += ["-i", str(p.audio_path)]
+    chains, labels = [], []
+    pos = 0
+    for i, p in enumerate(plans):
+        delay = int(round((pos - p.lead) * spf))
+        if delay < 0:
+            raise CutError(f"trecho {p.rid}: atraso de áudio negativo ({delay}); J-cut inconsistente")
+        chains.append(f"[{i}:a]adelay=delays={delay}S:all=1[a{i}]")
+        labels.append(f"[a{i}]")
+        pos += p.frames
+    if len(plans) == 1:
+        graph = f"{chains[0]};[a0]apad=whole_len={total_samples},atrim=end_sample={total_samples}[out]"
+    else:
+        graph = (";".join(chains) + ";" + "".join(labels)
+                 + f"amix=inputs={len(plans)}:normalize=0:duration=longest:dropout_transition=0,"
+                 + f"apad=whole_len={total_samples},atrim=end_sample={total_samples}[out]")
+    cmd += ["-filter_complex", graph, "-map", "[out]", "-c:a", "pcm_f32le", "-ar", str(SR), "-f", "wav", str(out_wav)]
+    ffmpeg(cmd, "mixar o áudio")
+
+
+def loudnorm_measure(wav_path: Path) -> dict | None:
+    proc = subprocess.run(
+        ["ffmpeg", "-hide_banner", "-nostats", "-nostdin", "-i", str(wav_path), "-af",
+         f"loudnorm=I={LOUDNORM['I']}:TP={LOUDNORM['TP']}:LRA={LOUDNORM['LRA']}:print_format=json",
+         "-f", "null", "-"], capture_output=True, text=True)
+    text = proc.stderr
+    start, end = text.rfind("{"), text.rfind("}")
+    if start < 0 or end <= start:
+        return None
+    try:
+        data = json.loads(text[start:end + 1])
+    except json.JSONDecodeError:
+        return None
+    try:
+        if not math.isfinite(float(data["input_i"])) or float(data["input_i"]) < -70:
+            return None
+    except (KeyError, ValueError):
+        return None
+    return data
+
+
+def loudnorm_modo(measured: dict | None) -> str | None:
+    """O modo que o loudnorm de 2 passadas vai usar com estas medidas (a regra do ffmpeg, af_loudnorm.c): linear só
+    quando o pico real medido mais o ganho que falta até o alvo não passa do TP. Senão ele cai calado no dinâmico,
+    que comprime a voz. (PrimoCode: o portão reprova o dinâmico; ver helpers/ganho_por_trecho.py.)"""
+    if not measured:
+        return None
+    try:
+        offset_tp = float(measured["input_tp"]) + (LOUDNORM["I"] - float(measured["input_i"]))
+    except (KeyError, ValueError):
+        return None
+    return "linear" if offset_tp <= LOUDNORM["TP"] else "dinamico"
+
+
+def true_peak_db(path: Path) -> float | None:
+    """True peak (dBTP) of the first audio track with 2 decimals (loudnorm's measurement; ebur128,
+    used by verify_cut, prints 1 decimal and hides a -0.96 as -1.0). -120 for silence."""
+    proc = subprocess.run(["ffmpeg", "-hide_banner", "-nostats", "-nostdin", "-i", str(path), "-vn", "-af",
+                           f"loudnorm=I={LOUDNORM['I']}:TP={LOUDNORM['TP']}:LRA={LOUDNORM['LRA']}:print_format=json",
+                           "-f", "null", "-"], capture_output=True, text=True)
+    m = re.search(r'"input_tp"\s*:\s*"(-?inf|-?[\d.]+)"', proc.stderr or "")
+    if not m:
+        return None
+    return -120.0 if "inf" in m.group(1) else float(m.group(1))
+
+
+# ------------------------------------------------------------------ main
+
+
+def acquire_lock(clips_dir: Path):
+    """One render per edit dir at a time (clips cache and pruning are shared)."""
+    fh = open(clips_dir / ".render.lock", "a+")
+    try:
+        import fcntl
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except ImportError:          # Windows: no advisory lock, run anyway
+        pass
+    except OSError:
+        fh.close()
+        raise CutError("já tem um render_cut rodando nesta pasta edit. Espere ele terminar.", 2)
+    return fh
+
+
+def render(args: argparse.Namespace) -> int:
+    t_all = time.time()
+    require_binary("ffmpeg")
+    require_binary("ffprobe")
+    edl_path = Path(os.path.abspath(args.edl.expanduser()))
+    edl = load_edl(edl_path)
+    edl_sig = edl_signature(json.loads(edl_path.read_text(encoding="utf-8")))  # raw file, before normalizing
+    edit_dir = edl_path.parent
+    jcut = jcut_settings(edl, args.no_jcut)
+
+    probes: dict[str, dict] = {}
+    audio_keys = {r["source"] for r in edl["ranges"]}
+    picture_keys = {picture_key(r) for r in edl["ranges"]}
+    for key, value in edl["sources"].items():
+        if key not in audio_keys and key not in picture_keys:
+            continue
+        src = resolve_source(str(value), edit_dir)
+        if not src.exists():
+            raise CutError(f"vídeo da fonte {key!r} não encontrado: {src}", 2)
+        try:
+            info = probe_video(src)
+        except Exception as exc:  # noqa: BLE001
+            raise CutError(f"não consegui ler {src.name}: {exc}", 2)
+        if key in picture_keys and not info.get("has_video"):
+            if key in audio_keys:
+                raise CutError(f"{src.name} não tem trilha de vídeo: nos trechos dela, ponha \"imagem_de\" com a "
+                               "câmera de onde vem a imagem", 2)
+            raise CutError(f"{src.name} não tem trilha de vídeo", 2)
+        probes[key] = {"path": src, "info": info}
+    sync, sync_path = load_sync(edl, edit_dir, probes)
+
+    out_cfg = edl.get("output") or {}
+    fmt = out_cfg.get("format") or "vertical"
+    if fmt not in OUTPUT_FORMATS and not (out_cfg.get("width") and out_cfg.get("height")):
+        raise CutError(f"output.format {fmt!r} desconhecido (use {', '.join(OUTPUT_FORMATS)})", 2)
+    W = int(out_cfg.get("width") or OUTPUT_FORMATS[fmt][0])
+    H = int(out_cfg.get("height") or OUTPUT_FORMATS[fmt][1])
+    fps = int(round(float(out_cfg.get("fps") or choose_output_fps({k: v for k, v in probes.items()
+                                                                      if k in picture_keys}))))
+    if fps <= 0 or SR % fps:
+        raise CutError(f"output.fps {fps} não suportado (use 24, 25, 30, 48, 50 ou 60)", 2)
+    if args.preview:
+        W, H = (W // 2) - (W // 2) % 2, (H // 2) - (H // 2) % 2
+    W, H = W - W % 2, H - H % 2
+
+    try:
+        grade_filter = resolve_grade(edl.get("grade"))
+    except ValueError as exc:
+        raise CutError(str(exc), 2)
+    err = check_filter(grade_filter)
+    if err:
+        raise CutError(f"o grade do EDL não funciona no ffmpeg: {err}", 2)
+
+    jobs = args.jobs if args.jobs and args.jobs > 0 else min(4, max(1, (os.cpu_count() or 4) // 3))
+    out_path = (Path(os.path.abspath(args.output.expanduser())) if args.output
+                else edit_dir / ("cut_preview.mp4" if args.preview else "cut.mp4"))
+    timeline_path = out_path.with_name(f"{out_path.stem}_timeline.json")
+    clips_dir = edit_dir / "clips"
+    clips_dir.mkdir(parents=True, exist_ok=True)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    lock = acquire_lock(clips_dir)
+
+    mode = "prev" if args.preview else "full"
+    log(f"Corte: {len(edl['ranges'])} trechos de {len(probes)} fonte(s) -> {W}x{H} {fps} fps"
+        f"{' (prévia)' if args.preview else ''}")
+    if jcut["enabled"]:
+        log(f"J-cut: áudio entra {jcut['lead_frames']} quadros antes, cauda aparada até "
+            f"{jcut['tail_trim_frames']} quadros fora da fala")
+    else:
+        log("Junções secas (sem J-cut)")
+    if sync:
+        log(f"Imagem de outra câmera em {sum(1 for r in edl['ranges'] if r.get('imagem_de'))} trecho(s), "
+            f"sincronia de {sync_path.name}")
+    if any(pr["info"].get("is_hdr") for pr in probes.values()) and not has_ffmpeg_filter("zscale"):
+        warn("fonte HDR e o ffmpeg não tem zscale: conversão para SDR aproximada, confira as cores")
+
+    t_plan = time.time()
+    plans = plan_cut(edl, edit_dir, fps, jcut, probes, jobs, W, H, sync)
+    channel_modes = {}
+    for key, pr in probes.items():
+        if key in audio_keys:
+            channel_modes[key] = channel_mode(pr["path"], pr["info"]) if pr["info"].get("has_audio") else "silent"
+    t_plan = time.time() - t_plan
+
+    cfg = {"fps": fps, "width": W, "height": H, "grade_filter": grade_filter, "channel_modes": channel_modes,
+           "x264_preset": "veryfast" if args.preview else "medium", "crf": 26 if args.preview else 18,
+           "clips_dir": clips_dir, "mode": mode}
+    t_ext = time.time()
+    log(f"Extraindo {len(plans)} trechos ({jobs} em paralelo)...")
+    with ThreadPoolExecutor(max_workers=jobs) as pool:
+        futures = [pool.submit(extract, p, cfg) for p in plans]
+        plans = [f.result() for f in futures]
+    t_ext = time.time() - t_ext
+    for a, b in zip(plans, plans[1:]):
+        if b.joined and abs(a.audio_start + (a.lead + a.frames) / fps - b.audio_start) > 0.5 / SR:
+            warn(f"a fala que continua de {a.rid} para {b.rid} saiu fora do lugar (o trecho {a.rid} mudou de "
+                 "quadros na extração): a voz pode pular ali. Rode de novo")
+
+    # Frame-accurate positions from the encoded clips.
+    pos = 0
+    total_frames = sum(p.frames for p in plans)
+    total_samples = int(round(total_frames * SR / fps))
+    duration = total_frames / fps
+
+    t_mix = time.time()
+    mix_wav = clips_dir / f"{mode}_mix.wav"
+    mix_audio(plans, fps, total_samples, mix_wav)
+    measured = loudnorm_measure(mix_wav)
+    t_mix = time.time() - t_mix
+
+    concat_list = clips_dir / f"{mode}_concat.txt"
+    lines = ["ffconcat version 1.0"]
+    for p in plans:
+        lines.append(f"file '{concat_escape(p.video_path)}'")
+        lines.append(f"duration {p.frames / fps:.6f}")
+    concat_list.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    norm_wav = clips_dir / f"{mode}_norm.wav"
+    if measured:
+        af = (f"loudnorm=I={LOUDNORM['I']}:TP={LOUDNORM['TP']}:LRA={LOUDNORM['LRA']}"
+              f":measured_I={measured['input_i']}:measured_TP={measured['input_tp']}"
+              f":measured_LRA={measured['input_lra']}:measured_thresh={measured['input_thresh']}"
+              f":offset={measured['target_offset']}:linear=true,aresample={SR}")
+        ffmpeg(["ffmpeg", "-y", "-v", "error", "-nostdin", "-i", str(mix_wav), "-af", af, "-c:a", "pcm_f32le",
+                "-ar", str(SR), "-ac", "2", "-f", "wav", str(norm_wav)], "normalizar o volume")
+        audio_in = norm_wav
+    else:
+        warn("não deu para medir a loudness (áudio mudo?); o áudio sai sem normalizar")
+        audio_in = mix_wav
+
+    t_mux = time.time()
+    tmp_out = out_path.with_name(f".{out_path.stem}.part.mp4")
+
+    def mux(gain_db: float) -> None:
+        af_mux = ["-af", f"volume={gain_db:.2f}dB"] if abs(gain_db) > 0.001 else []
+        ffmpeg(["ffmpeg", "-y", "-v", "error", "-nostdin", "-f", "concat", "-safe", "0", "-i", str(concat_list),
+                "-i", str(audio_in), "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy", *af_mux,
+                "-c:a", "aac", "-b:a", "192k", "-ar", str(SR), "-ac", "2", "-t", f"{duration:.6f}",
+                "-movflags", "+faststart", "-f", "mp4", str(tmp_out)], f"montar o {out_path.name}")
+
+    peak_gain = 0.0
+    try:
+        mux(peak_gain)
+        out_tp = true_peak_db(tmp_out)
+        # The AAC encoder adds inter-sample peaks over the loudnorm target: lower just enough and encode again.
+        peak_goal = TRUE_PEAK_LIMIT - TRUE_PEAK_MARGIN
+        for _ in range(3):
+            if out_tp is None or out_tp <= peak_goal:
+                break
+            peak_gain += peak_goal - out_tp - 0.15
+            mux(peak_gain)
+            out_tp = true_peak_db(tmp_out)
+        if out_tp is not None and out_tp > TRUE_PEAK_LIMIT:
+            warn(f"o pico real ficou em {out_tp:.2f} dBTP, acima de {TRUE_PEAK_LIMIT:.0f}, mesmo baixando "
+                 f"{peak_gain:.1f} dB: diminua o gain_db do trecho mais alto")
+        os.replace(tmp_out, out_path)
+    finally:
+        tmp_out.unlink(missing_ok=True)
+        norm_wav.unlink(missing_ok=True)
+    t_mux = time.time() - t_mux
+
+    got_frames = count_frames(out_path)
+    if got_frames != total_frames:
+        warn(f"o arquivo final tem {got_frames} quadros, o timeline espera {total_frames}")
+
+    segments = []
+    for p in plans:
+        out_start_f, out_end_f = pos, pos + p.frames
+        src_start = p.pic_start
+        src_end = p.pic_start + p.frames / fps
+        imagem = {"imagem_de": None}
+        if p.other_picture:
+            # src_start/src_end stay on the audio source's clock (the voice tools read them); the picture has its own
+            imagem = {"imagem_de": p.pic_source, "imagem_path": str(p.pic_src),
+                      "imagem_src_start": round(src_start, 6), "imagem_src_end": round(src_end, 6)}
+            src_start = p.audio_start + p.lead / fps
+            src_end = p.audio_start + (p.lead + p.frames) / fps
+        segments.append({
+            "id": p.rid, "source": p.source, "source_path": str(p.src),
+            "audio_mode": channel_modes.get(p.source, "stereo"),
+            "src_start": round(src_start, 6), "src_end": round(src_end, 6), **imagem,
+            "audio_continua": p.joined, "audio_fade_in": p.fade_in, "audio_fade_out": p.fade_out,
+            "out_start": round(out_start_f / fps, 6), "out_end": round(out_end_f / fps, 6),
+            "audio_out_start": round((out_start_f - p.lead) / fps, 6), "audio_out_end": round(out_end_f / fps, 6),
+            "beat": p.beat, "quote": p.quote,
+            "out_start_frame": out_start_f, "out_end_frame": out_end_f, "frames": p.frames,
+            "lead_frames": p.lead, "tail_trim_frames": p.tail,
+            "audio_src_start": round(p.audio_start, 6), "pic_snapped": p.pic_snapped,
+            "edl_start": p.edl_start, "edl_end": p.edl_end, "gain_db": p.gain_db,
+            "crop": p.crop,
+        })
+        pos = out_end_f
+
+    timeline = {
+        "edl_sig": edl_sig, "fps": fps, "width": W, "height": H,
+        "duration": round(duration, 6), "frames": total_frames,
+        "video": out_path.name, "preview": bool(args.preview),
+        "jcut": jcut, "grade": edl.get("grade") or "",
+        "loudnorm_input": ({k: float(measured[k]) for k in ("input_i", "input_tp", "input_lra")} if measured else None),
+        "loudnorm_modo": loudnorm_modo(measured),
+        "true_peak_db": out_tp, "peak_guard_db": round(peak_gain, 2),
+        "hdr_sources": sorted(k for k, pr in probes.items() if pr["info"].get("is_hdr")),
+        "sincronia": ({"arquivo": str(sync_path), "fontes": {k: {"deslocamento": v[0], "escala": v[1]}
+                                                              for k, v in sync.items()}} if sync else None),
+        "rendered_at": now_iso(),
+        "segments": segments,
+    }
+    save_json(timeline_path, timeline)
+
+    # Only a full render inside the edit dir drives the preview. It does not ask for approval yet:
+    # verify_cut.py does that after checking the file.
+    state_note = ""
+    if out_path.parent == edit_dir and not args.preview:
+        state_path = edit_dir / "state.json"
+        state = load_json(state_path, default={}) or {}
+        state.update({
+            "phase": "cut", "awaiting": None,
+            "message": "Corte renderizado. Conferindo antes de mostrar...",
+            "cut_video": out_path.name, "cut_timeline": timeline_path.name, "updated_at": now_iso(),
+        })
+        save_json(state_path, state)
+        state_note = " · state.json atualizado (aprovação só depois do verify_cut)"
+
+    # Drop stale cached clips of this quality mode and the temp mix.
+    keep = {q.video_path.name for q in plans} | {q.audio_path.name for q in plans} | {q.meta_path.name for q in plans}
+    for f in clips_dir.glob(f"{mode}_*"):
+        if f.name not in keep:
+            f.unlink(missing_ok=True)
+
+    log("")
+    log(f"{'id':6s} {'fonte':10s} {'origem':>15s}  {'no corte':>17s}  {'quadros':>7s}  lead tail")
+    for s, p in zip(segments, plans):
+        pic = f"  imagem da {p.pic_source} em {p.pic_start:.2f}s" if p.other_picture else ""
+        log(f"{s['id']:6s} {s['source'][:10]:10s} {s['src_start']:6.2f}-{s['src_end']:6.2f}s  "
+            f"{fmt_time(s['out_start'])}-{fmt_time(s['out_end'])}  {s['frames']:7d}  {p.lead:4d} {p.tail:4d}"
+            f"{'  (cache)' if p.cached else ''}{'  lead reduzido: ' + p.lead_note if p.lead_note else ''}"
+            f"{'  voz continua do anterior' if p.joined else ''}{pic}")
+    for s in segments:
+        if s["crop"] and s["crop"]["focus_from"] != "centro":
+            c = s["crop"]
+            log(f"Enquadramento {s['id']}: focus_x {c['focus_x']:.2f} focus_y {c['focus_y']:.2f} ({c['focus_from']})")
+    if measured:
+        log(f"Loudness antes: {float(measured['input_i']):.1f} LUFS, pico {float(measured['input_tp']):.1f} dBTP"
+            f" -> alvo {LOUDNORM['I']:.0f} LUFS (ajuste {loudnorm_modo(measured)})")
+        if loudnorm_modo(measured) == "dinamico":
+            warn("o loudnorm vai cair no modo DINÂMICO (comprime a voz): rode helpers/ganho_por_trecho.py no EDL antes")
+    if out_tp is not None and out_tp <= -100:
+        log("Pico real no arquivo: sem som")
+    elif out_tp is not None:
+        guard =f" (volume {peak_gain:+.1f} dB para não passar de {TRUE_PEAK_LIMIT:.0f})" if peak_gain else ""
+        log(f"Pico real no arquivo: {out_tp:.2f} dBTP{guard}")
+    log(f"Pronto: {out_path} · {fmt_time(duration)} ({total_frames} quadros){state_note}")
+    log(f"Timeline: {timeline_path}")
+    log(f"Tempo: total {time.time() - t_all:.1f}s (plano {t_plan:.1f}s, extração {t_ext:.1f}s, "
+        f"áudio {t_mix:.1f}s, montagem {t_mux:.1f}s)")
+    mix_wav.unlink(missing_ok=True)
+    concat_list.unlink(missing_ok=True)
+    lock.close()
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Renderiza o corte (cut.mp4 + cut_timeline.json) a partir do edl.json.")
+    ap.add_argument("edl", type=Path, help="caminho do edl.json (a pasta dele é a pasta edit/)")
+    ap.add_argument("-o", "--output", type=Path, help="vídeo de saída (padrão: cut.mp4 ao lado do EDL)")
+    ap.add_argument("--jobs", type=int, default=0, help="trechos extraídos em paralelo (padrão automático)")
+    ap.add_argument("--no-jcut", action="store_true", help="junções secas, sem J-cut")
+    ap.add_argument("--preview", action="store_true",
+                    help="prévia rápida: metade da resolução, CRF 26, grava cut_preview.mp4 (não mexe no cut.mp4 nem no state.json)")
+    args = ap.parse_args()
+    try:
+        return render(args)
+    except CutError as exc:
+        print(f"erro: {exc}", file=sys.stderr)
+        return exc.code
+    except KeyboardInterrupt:
+        print("interrompido", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())