primocode 10.16.0 → 10.17.0

package/editor/helpers/motion/render.py

@@ -0,0 +1,665 @@
+"""Renderer: one motion item (template + params + place + length) -> frames, an alpha clip for the
+compose, previews and a contact sheet (SPEC Contract 12).
+
+Transport into compose_final (chosen by measurement, see SPEC): one QuickTime Animation (qtrle, ARGB,
+lossless) .mov per item, sized to the item's rectangle, placed with overlay at even x/y and started
+with `setpts=N+<start frame>` like the insert clips. Frame-exact, cacheable by content, tiny for held
+frames (qtrle only stores the lines that changed).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Sequence
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter, ImageOps
+
+from . import engine as E
+from . import registry as Rg
+from .engine import MotionError
+
+RENDER_VERSION = 2
+EXIT_FRAMES = 6                 # generic exit (fade + 3% shrink) of templates with exit "fade"
+EXIT_SHRINK = 0.03
+INK_ALPHA = 24                  # a pixel counts as drawn ("ink") above this alpha: faint glows and shadows do not
+_INK_LUT = [0] * (INK_ALPHA + 1) + [255] * (255 - INK_ALPHA)
+_OWN_HASH = hashlib.sha1(b"".join(p.read_bytes() for p in (Path(E.__file__), Path(__file__)))).hexdigest()[:12]
+
+
+@dataclass
+class MotionItem:
+    template: Rg.Template
+    params: dict                 # resolved (defaults filled)
+    box: E.Box
+    frames: int
+    region: list[float]          # [x, y, w, h] design px actually used
+    region_spec: Any
+    moved_by: float = 0.0        # design px the region moved to clear a face / text
+    warnings: list[str] = field(default_factory=list)
+    ink: tuple[float, float, float, float] | None = None   # box-local design px (measured when placing)
+
+    @property
+    def fps(self) -> int:
+        return self.box.fps
+
+    @property
+    def canvas(self) -> tuple[int, int]:
+        return self.box.canvas
+
+    @property
+    def key(self) -> str:
+        b = self.box
+        blob = json.dumps({
+            "engine": [E.ENGINE_VERSION, RENDER_VERSION, _OWN_HASH],
+            "template": [self.template.id, self.template.version, self.template.source_hash],
+            "params": self.params, "box": [round(b.x, 4), round(b.y, 4), round(b.w, 4), round(b.h, 4), b.bleed],
+            "canvas": list(b.canvas), "fps": b.fps, "frames": self.frames,
+            "theme": [b.theme.name, list(b.theme.accent)], "exit": self.template.exit,
+        }, sort_keys=True, ensure_ascii=False)
+        return hashlib.sha1(blob.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass
+class Frame:
+    image: Image.Image           # RGBA
+    x: int                       # render px of the image's top-left on the output canvas
+    y: int
+
+
+# ------------------------------------------------------------------ planning
+
+def _accent_for(params: dict, accent: str) -> str:
+    cor = params.get("cor")
+    if cor in (None, ""):
+        return accent
+    if isinstance(cor, str) and not cor.startswith("#"):
+        c = E.make_theme(accent).get(E.COLOR_NAMES[cor])
+        return "#%02X%02X%02X" % c[:3]
+    return str(cor)[:7]
+
+
+def plan_item(template_id: str, params: dict | None = None, *, fps: int = 30,
+              canvas: Sequence[int] = (1080, 1920), region=None, duration: float | None = None,
+              frames: int | None = None, accent: str = E.DEFAULT_ACCENT,
+              blocked: Sequence[tuple[float, float]] | None = None,
+              dirs: list[Path] | None = None) -> MotionItem:
+    """Check everything and decide where and how long the item is. `blocked` = vertical bands (y0, y1) in
+    design px of the canvas that the content must not touch (faces, other texts); the region slides
+    vertically inside the safe area to the free place closest to where it was."""
+    tpl = Rg.get(template_id, dirs)
+    resolved = Rg.resolve_params(tpl, params)
+    fps = int(fps)
+    if fps <= 0:
+        raise MotionError("fps precisa ser maior que 0")
+    canvas = (int(canvas[0]), int(canvas[1]))
+    if canvas[0] < 16 or canvas[1] < 16:
+        raise MotionError(f"tamanho de tela inválido: {canvas}")
+    if frames is None:
+        secs = tpl.suggested_duration(resolved) if duration is None else float(duration)
+        if not math.isfinite(secs) or secs <= 0:
+            raise MotionError(f"duração inválida: {duration!r}")
+        frames = E.frame_of(secs, fps)
+    frames = int(frames)
+    if frames < 2:
+        raise MotionError(f"'{tpl.id}' precisa durar pelo menos 2 quadros")
+    if frames > Rg.MAX_DURATION * fps:
+        raise MotionError(f"'{tpl.id}' pode durar no máximo {Rg.MAX_DURATION:g} s")
+    spec = tpl.default_region if region in (None, "", "auto") else region
+    x, y, w, h = E.region_box(spec, canvas)
+    warnings: list[str] = []
+    sx0, sy0, sx1, sy1 = E.safe_area(canvas)
+    if not isinstance(spec, str) and (y < sy0 - 0.5 or y + h > sy1 + 0.5):
+        warnings.append(f"'{tpl.id}': a região [{x:g}, {y:g}, {w:g}, {h:g}] passa da área segura "
+                        f"(de {sy0:.0f} a {sy1:.0f} na altura): a interface do Reels pode cobrir parte dela")
+    # without a card the text sits on the video: white letters with a dark outline read there, the dark letters
+    # of the light card do not, so "tema" only matters when there is a card
+    tema = resolved.get("tema", "escuro") if resolved.get("card", True) is not False else "escuro"
+    # a look with its own palette (papel, pop, neon) keeps its colors even when the video has another accent;
+    # only an item's own "cor" changes them
+    own_palette = tema in E.PAPEL or tema in ("pop", "neon")
+    base_accent = E.DEFAULT_ACCENT if own_palette and resolved.get("cor") in (None, "") else accent
+    theme = E.make_theme(_accent_for(resolved, base_accent), tema)
+    box = E.Box(x=x, y=y, w=w, h=h, scale=min(canvas) / E.REF, canvas=canvas, fps=fps, frames=frames,
+                theme=theme, bleed=tpl.bleed)
+    item = MotionItem(template=tpl, params=resolved, box=box, frames=frames, region=[x, y, w, h],
+                      region_spec=spec, warnings=warnings)
+    hook = getattr(tpl.module, "warnings", None)
+    if callable(hook):
+        with E.theme_fonts(theme):
+            texts = hook(resolved, box) or []
+        for text in texts:
+            item.warnings.append(f"'{tpl.id}': {text}")
+    if blocked:
+        place(item, blocked)
+    return item
+
+
+def _ink_hook(item: MotionItem) -> tuple[float, float, float, float] | None | bool:
+    """The template's own `ink(params, box)` (box-local design px), or False when it has none."""
+    fn = getattr(item.template.module, "ink", None)
+    if not callable(fn):
+        return False
+    with E.theme_fonts(item.box.theme):
+        box = fn(item.params, item.box)
+    if box is None:
+        return None
+    x0, y0, x1, y1 = (float(v) for v in box)
+    return (min(x0, x1), min(y0, y1), max(x0, x1), max(y0, y1))
+
+
+def measure_ink(item: MotionItem, samples: int = 6) -> tuple[float, float, float, float] | None:
+    """Union of the drawn pixels (alpha above INK_ALPHA) over a few frames (without the exit), in box-local
+    design px. A template with `ink(params, box)` gives it directly (a full-screen flash is not "ink")."""
+    hooked = _ink_hook(item)
+    if hooked is not False:
+        item.ink = hooked  # type: ignore[assignment]
+        return item.ink
+    n = item.frames
+    last = max(0, n - 1 - (EXIT_FRAMES if item.template.exit == "fade" else 0))
+    picks = sorted({int(round(last * k / max(1, samples - 1))) for k in range(samples)})
+    s = item.box.scale
+    union = None
+    for i in picks:
+        fr = render_frame(item, i, with_exit=False)
+        bb = fr.image.getchannel("A").point(_INK_LUT).getbbox()
+        if not bb:
+            continue
+        x0, y0 = (fr.x + bb[0]) / s - item.box.x, (fr.y + bb[1]) / s - item.box.y
+        x1, y1 = (fr.x + bb[2]) / s - item.box.x, (fr.y + bb[3]) / s - item.box.y
+        union = (x0, y0, x1, y1) if union is None else (min(union[0], x0), min(union[1], y0),
+                                                        max(union[2], x1), max(union[3], y1))
+    item.ink = union
+    return union
+
+
+def free_offset(item: MotionItem, blocked: Sequence[tuple[float, float]], gap: float = 23.0) -> float | None:
+    """Vertical move (design px, from where the item is now) that puts its drawn part at the free place
+    closest to where it is, inside the safe band and `gap` away from every blocked (y0, y1) band. 0 when it
+    draws nothing, None when there is no free place. The item is not changed."""
+    import face_layout  # noqa: PLC0415  (helpers/ is on sys.path through engine)
+
+    ink = item.ink if item.ink is not None else measure_ink(item)
+    if ink is None:
+        return 0.0
+    b = item.box
+    sx0, sy0, sx1, sy1 = E.safe_area(b.canvas)
+    top, bottom = b.y + ink[1], b.y + ink[3]
+    ref = (top + bottom) / 2.0
+    above, below = ref - top, bottom - ref
+    bands = [(float(a), float(c)) for a, c in blocked if c > a]
+    center = face_layout.free_center(ref, above, below, bands, sy0, sy1, gap)
+    return None if center is None else center - ref
+
+
+def move_item(item: MotionItem, dy: float) -> MotionItem:
+    """Slide the item `dy` design px down (negative: up)."""
+    if abs(dy) >= 0.5:
+        b = item.box
+        item.box = E.with_box(b, y=b.y + dy)
+        item.region = [b.x, b.y + dy, b.w, b.h]
+        item.moved_by += dy
+    return item
+
+
+def place(item: MotionItem, blocked: Sequence[tuple[float, float]], gap: float = 23.0) -> MotionItem:
+    """Slide the item vertically so its drawn part clears every blocked band (face_layout.free_center)."""
+    if not item.template.movable:
+        return item
+    dy = free_offset(item, blocked, gap)
+    if dy is None:
+        item.warnings.append(f"'{item.template.id}' não achou lugar livre do rosto e dos textos: ficou na região pedida")
+        return item
+    return move_item(item, dy)
+
+
+# ------------------------------------------------------------------ frames
+
+def _normalize(item: MotionItem, out: Any, i: int) -> Frame:
+    b = item.box
+    if isinstance(out, E.Canvas):
+        return Frame(out.image, out.origin_x, out.origin_y)
+    if isinstance(out, Image.Image):
+        img = out if out.mode == "RGBA" else out.convert("RGBA")
+        if img.size == tuple(b.canvas):
+            return Frame(img, 0, 0)
+        bw, bh = int(round(b.w * b.scale)), int(round(b.h * b.scale))
+        if abs(img.width - bw) <= 1 and abs(img.height - bh) <= 1:
+            return Frame(img, int(round(b.x * b.scale)), int(round(b.y * b.scale)))
+        raise MotionError(f"'{item.template.id}': render do quadro {i} devolveu {img.size}; o esperado é a tela "
+                          f"{tuple(b.canvas)}, a caixa ({bw}, {bh}) ou um Canvas")
+    raise MotionError(f"'{item.template.id}': render precisa devolver um Canvas ou uma imagem RGBA (veio {type(out).__name__})")
+
+
+def _exit(item: MotionItem, fr: Frame, i: int) -> Frame:
+    """Generic exit: the last frames fade out and shrink 3% around the box center. Only the drawn part is
+    resampled (premultiplied, so transparent pixels never darken the edges)."""
+    n = item.frames
+    k = min(EXIT_FRAMES, n // 3)
+    j = i - (n - k)
+    if item.template.exit != "fade" or k <= 0 or j < 0:
+        return fr
+    p = E.in_quad((j + 1) / (k + 1))
+    img = fr.image
+    bb = img.getchannel("A").getbbox()
+    if bb is None:
+        return fr
+    b = item.box
+    cx = (b.x + b.w / 2.0) * b.scale - fr.x
+    cy = (b.y + b.h / 2.0) * b.scale - fr.y
+    sc = 1.0 - EXIT_SHRINK * p
+    # the shrunk drawing stays between the drawn area and the center: resample only that rectangle
+    x0 = int(math.floor(min(bb[0], cx + (bb[0] - cx) * sc))) - 2
+    y0 = int(math.floor(min(bb[1], cy + (bb[1] - cy) * sc))) - 2
+    x1 = int(math.ceil(max(bb[2], cx + (bb[2] - cx) * sc))) + 2
+    y1 = int(math.ceil(max(bb[3], cy + (bb[3] - cy) * sc))) + 2
+    x0, y0, x1, y1 = max(0, x0), max(0, y0), min(img.width, x1), min(img.height, y1)
+    part = img.crop((x0, y0, x1, y1)).convert("RGBa")
+    inv = 1.0 / sc
+    lx, ly = cx - x0, cy - y0
+    part = part.transform(part.size, Image.AFFINE, (inv, 0.0, lx - lx * inv, 0.0, inv, ly - ly * inv),
+                          resample=Image.BICUBIC).convert("RGBA")
+    a = np.asarray(part.getchannel("A"), np.float32) * (1.0 - p)
+    part.putalpha(Image.fromarray(np.clip(a + 0.5, 0, 255).astype(np.uint8), "L"))
+    out = Image.new("RGBA", img.size, (0, 0, 0, 0))
+    out.paste(part, (x0, y0))
+    return Frame(out, fr.x, fr.y)
+
+
+def render_frame(item: MotionItem, i: int, with_exit: bool = True) -> Frame:
+    if not 0 <= i < item.frames:
+        raise MotionError(f"quadro {i} fora do item (0 a {item.frames - 1})")
+    with E.theme_fonts(item.box.theme):
+        out = item.template.render(int(i), int(item.fps), item.params, item.box)
+    fr = _normalize(item, out, i)
+    return _exit(item, fr, i) if with_exit else fr
+
+
+def iter_frames(item: MotionItem) -> Iterator[tuple[int, Frame, bool]]:
+    """(index, frame, repeated) for every frame; frames after the template's settle time reuse the last one."""
+    settle = item.template.settle(item.params, item.fps)
+    n = item.frames
+    exit_from = n - min(EXIT_FRAMES, n // 3) if item.template.exit == "fade" else n
+    still_from = E.frame_of(settle, item.fps) if settle is not None else None
+    held: Frame | None = None
+    for i in range(n):
+        if still_from is not None and still_from <= i < exit_from and held is not None:
+            yield i, held, True
+            continue
+        fr = render_frame(item, i)
+        if still_from is not None and i >= still_from and i < exit_from:
+            held = fr
+        yield i, fr, False
+
+
+def clip_rect(item: MotionItem, first: Frame) -> tuple[int, int, int, int]:
+    """(x, y, w, h) render px on the canvas that holds every frame: even origin and even size."""
+    W, H = item.canvas
+    x0, y0 = max(0, first.x), max(0, first.y)
+    x1, y1 = min(W, first.x + first.image.width), min(H, first.y + first.image.height)
+    x0, y0 = x0 // 2 * 2, y0 // 2 * 2
+    x1, y1 = min(W, (x1 + 1) // 2 * 2), min(H, (y1 + 1) // 2 * 2)
+    if x1 - x0 < 2 or y1 - y0 < 2:
+        raise MotionError(f"'{item.template.id}' desenha fora da tela")
+    return x0, y0, x1 - x0, y1 - y0
+
+
+def _place_on(fr: Frame, rect: tuple[int, int, int, int]) -> Image.Image:
+    x, y, w, h = rect
+    if (fr.x, fr.y, fr.image.width, fr.image.height) == rect:
+        return fr.image
+    out = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+    out.paste(fr.image, (fr.x - x, fr.y - y))
+    return out
+
+
+def _check_inside(item: MotionItem, fr: Frame, rect: tuple[int, int, int, int], i: int) -> None:
+    """Every frame must fit the rectangle of the first one (same kind of Canvas on every frame)."""
+    W, H = item.canvas
+    x0, y0 = max(0, fr.x), max(0, fr.y)
+    x1, y1 = min(W, fr.x + fr.image.width), min(H, fr.y + fr.image.height)
+    if x0 < rect[0] or y0 < rect[1] or x1 > rect[0] + rect[2] or y1 > rect[1] + rect[3]:
+        raise MotionError(f"'{item.template.id}': o quadro {i} desenha fora da área do quadro 0. Use sempre o mesmo "
+                          f"tipo de Canvas em todos os quadros (Canvas(box, full=True) se algum precisar da tela toda)")
+
+
+def full_frame(item: MotionItem, fr: Frame) -> Image.Image:
+    W, H = item.canvas
+    return _place_on(fr, (0, 0, W, H))
+
+
+# ------------------------------------------------------------------ sounds
+
+def sfx_cues(item: MotionItem, check_names: bool = False) -> list[dict]:
+    """[{frame (from the item start), name, volume, why?}] inside the item, sorted by frame."""
+    tpl = item.template
+    fn = getattr(tpl.module, "sfx", None)
+    raw = fn(item.params, item.fps, item.frames) if callable(fn) else tpl.sfx
+    if not isinstance(raw, list):
+        raise MotionError(f"'{tpl.id}': sfx() precisa devolver uma lista")
+    out = []
+    for k, cue in enumerate(raw):
+        if not isinstance(cue, dict) or not isinstance(cue.get("name"), str):
+            raise MotionError(f"'{tpl.id}': som {k} sem 'name'")
+        if "frame" in cue:
+            frame = int(cue["frame"])
+        else:
+            frame = E.frame_of(float(cue.get("at", 0.0)), item.fps)
+        if not 0 <= frame < item.frames:
+            continue
+        vol = float(cue.get("volume", 1.0))
+        entry = {"frame": frame, "name": cue["name"], "volume": round(min(2.0, max(0.0, vol)), 3)}
+        if cue.get("length") is not None and float(cue["length"]) > 0:
+            entry["length"] = round(float(cue["length"]), 4)       # seconds the sound plays after its strong point
+        if cue.get("why"):
+            entry["why"] = str(cue["why"])
+        out.append(entry)
+    if check_names:
+        import make_sfx  # noqa: PLC0415
+        manifest = make_sfx.load_manifest()
+        for cue in out:
+            if make_sfx.resolve_name(cue["name"], manifest) is None:
+                raise MotionError(f"'{tpl.id}': efeito sonoro '{cue['name']}' não existe (use um de {', '.join(make_sfx.NAMES)})")
+    return sorted(out, key=lambda c: (c["frame"], c["name"]))
+
+
+# ------------------------------------------------------------------ outputs
+
+def _ffmpeg() -> str:
+    from shutil import which
+    exe = which("ffmpeg")
+    if not exe:
+        raise MotionError("'ffmpeg' não encontrado no PATH. macOS: brew install ffmpeg · Windows: winget install Gyan.FFmpeg")
+    return exe
+
+
+class _Pipe:
+    def __init__(self, args: list[str], what: str):
+        self.what = what
+        self.proc = subprocess.Popen([_ffmpeg(), "-hide_banner", "-nostdin", "-v", "error", "-y", *args],
+                                     stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+
+    def write(self, data: bytes) -> None:
+        try:
+            self.proc.stdin.write(data)  # type: ignore[union-attr]
+        except BrokenPipeError:
+            self.close()
+
+    def close(self) -> None:
+        try:
+            self.proc.stdin.close()  # type: ignore[union-attr]
+        except OSError:
+            pass
+        err = self.proc.stderr.read().decode("utf-8", "replace") if self.proc.stderr else ""
+        if self.proc.wait() != 0:
+            raise MotionError(f"o ffmpeg falhou ao {self.what}: {err.strip()[-400:]}", code=1)
+
+    def kill(self) -> None:
+        try:
+            self.proc.kill()
+            self.proc.wait()
+        except OSError:
+            pass
+
+
+def _qtrle_args(w: int, h: int, fps: int, n: int, out: Path) -> list[str]:
+    return ["-f", "rawvideo", "-pix_fmt", "rgba", "-s", f"{w}x{h}", "-framerate", str(fps), "-i", "-",
+            "-c:v", "qtrle", "-pix_fmt", "argb", "-g", str(max(1, n)), "-frames:v", str(n),
+            "-f", "mov", str(out)]
+
+
+def _atomic_json(path: Path, obj: dict) -> None:
+    tmp = path.with_name(".tmp-" + path.name)
+    tmp.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def render_clip(item: MotionItem, out_dir: Path | str, cache: bool = True) -> dict:
+    """The alpha clip compose_final overlays: renders/motion/<id>_<key>.mov + .json (cached by content).
+
+    Returns {file, json, template, x, y, w, h (render px on the canvas), frames, fps, canvas, region
+    (design px), moved_by, ink (render px on the canvas or null), sfx (cues from the item start), params,
+    key, cached, warnings}."""
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    key = item.key
+    clip = out_dir / f"{item.template.id}_{key}.mov"
+    meta_path = clip.with_suffix(".json")
+    if cache and clip.exists() and meta_path.exists():
+        try:
+            meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            if meta.get("key") == key and clip.stat().st_size > 0:
+                meta.update({"file": str(clip), "json": str(meta_path), "cached": True,
+                             "warnings": list(item.warnings), "region": [round(v, 2) for v in item.region],
+                             "moved_by": round(item.moved_by, 2)})
+                return meta
+        except (OSError, ValueError):
+            pass
+    tmp = clip.with_name(".tmp-" + clip.name)
+    pipe = None
+    rect = None
+    ink = None
+    last_bytes = None
+    hooked = _ink_hook(item)
+    try:
+        for i, fr, repeated in iter_frames(item):
+            if rect is None:
+                rect = clip_rect(item, fr)
+                pipe = _Pipe(_qtrle_args(rect[2], rect[3], item.fps, item.frames, tmp), "gravar a animação")
+            if not repeated or last_bytes is None:
+                _check_inside(item, fr, rect, i)
+                img = _place_on(fr, rect)
+                if hooked is False:
+                    bb = img.getchannel("A").point(_INK_LUT).getbbox()
+                    if bb:
+                        ink = bb if ink is None else (min(ink[0], bb[0]), min(ink[1], bb[1]),
+                                                      max(ink[2], bb[2]), max(ink[3], bb[3]))
+                last_bytes = img.tobytes()
+            pipe.write(last_bytes)  # type: ignore[union-attr]
+        pipe.close()  # type: ignore[union-attr]
+    except BaseException:
+        if pipe is not None:
+            pipe.kill()
+        if tmp.exists():
+            tmp.unlink()
+        raise
+    os.replace(tmp, clip)
+    x, y, w, h = rect  # type: ignore[misc]
+    if hooked is False:
+        ink_px = [x + ink[0], y + ink[1], x + ink[2], y + ink[3]] if ink else None
+    elif hooked is None:
+        ink_px = None
+    else:
+        s, b = item.box.scale, item.box
+        ink_px = [int(math.floor((b.x + hooked[0]) * s)), int(math.floor((b.y + hooked[1]) * s)),
+                  int(math.ceil((b.x + hooked[2]) * s)), int(math.ceil((b.y + hooked[3]) * s))]
+    meta = {
+        "file": str(clip), "json": str(meta_path), "template": item.template.id, "x": x, "y": y, "w": w, "h": h,
+        "frames": item.frames, "fps": item.fps, "canvas": list(item.canvas),
+        "region": [round(v, 2) for v in item.region], "moved_by": round(item.moved_by, 2),
+        "ink": ink_px,
+        "sfx": sfx_cues(item), "params": item.params, "key": key, "cached": False, "warnings": list(item.warnings),
+    }
+    _atomic_json(meta_path, meta)
+    return meta
+
+
+def overlay_filters(clip: dict, input_index: int, base_label: str, out_label: str, start_frame: int,
+                    windows: Sequence[tuple[int, int]] | None = None) -> list[str]:
+    """Filter-graph lines that put a render_clip() result on the video from `start_frame` on (frame-exact).
+    `windows` = [(first, end)] output frames where it shows (default: the whole item); the clip keeps its own
+    timing, so a hidden stretch just skips those frames."""
+    fps, n = clip["fps"], clip["frames"]
+    lab = f"mo{input_index}"
+    spans = [(start_frame, start_frame + n)] if windows is None else list(windows)
+    enable = "+".join(f"between(n,{a},{b - 1})" for a, b in spans if b > a) or "0"
+    return [
+        f"[{input_index}:v]settb=1/{fps},setpts=N+{start_frame},format=rgba,"
+        f"scale=out_color_matrix=bt709:out_range=tv,format=yuva420p[{lab}]",
+        f"[{base_label}][{lab}]overlay=x={clip['x']}:y={clip['y']}:eof_action=pass:format=auto:"
+        f"enable='{enable}'[{out_label}]",
+    ]
+
+
+def write_mov(item: MotionItem, path: Path) -> Path:
+    """Transparent full-canvas QuickTime Animation .mov (for a video editor)."""
+    W, H = item.canvas
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(".tmp-" + path.name)
+    pipe = _Pipe(_qtrle_args(W, H, item.fps, item.frames, tmp), "gravar o .mov")
+    try:
+        last = None
+        for _, fr, repeated in iter_frames(item):
+            if not repeated or last is None:
+                last = full_frame(item, fr).tobytes()
+            pipe.write(last)
+        pipe.close()
+    except BaseException:
+        pipe.kill()
+        if tmp.exists():
+            tmp.unlink()
+        raise
+    os.replace(tmp, path)
+    return path
+
+
+def write_pngs(item: MotionItem, folder: Path) -> list[Path]:
+    folder.mkdir(parents=True, exist_ok=True)
+    out = []
+    for i, fr, _ in iter_frames(item):
+        p = folder / f"{item.template.id}_{i:04d}.png"
+        full_frame(item, fr).save(p, "PNG", compress_level=3)
+        out.append(p)
+    return out
+
+
+def background(canvas: Sequence[int], image: str | Path | None = None) -> Image.Image:
+    """A frame to judge the animation on: the given picture (cover) or a neutral talking-head mock."""
+    W, H = int(canvas[0]), int(canvas[1])
+    if image:
+        p = Path(image)
+        if not p.exists():
+            raise MotionError(f"fundo não encontrado: {p}")
+        with Image.open(p) as im:
+            im = ImageOps.exif_transpose(im).convert("RGB")
+            return ImageOps.fit(im, (W, H), Image.LANCZOS).convert("RGBA")
+    y = np.linspace(0.0, 1.0, H, dtype=np.float32)[:, None]
+    x = np.linspace(0.0, 1.0, W, dtype=np.float32)[None, :]
+    top, bot = np.array([62, 70, 84], np.float32), np.array([142, 128, 114], np.float32)
+    rgb = top[None, None, :] * (1 - y[..., None]) + bot[None, None, :] * y[..., None]
+    rgb = rgb + 14 * np.sin(x * 3.1)[..., None]
+    img = Image.fromarray(np.clip(rgb, 0, 255).astype(np.uint8), "RGB").convert("RGBA")
+    person = Image.new("L", (W, H), 0)
+    d = ImageDraw.Draw(person)
+    k = min(W, H) / 1080.0
+    cx = W / 2
+    head_cy = H * 0.36
+    d.ellipse((cx - 175 * k, head_cy - 230 * k, cx + 175 * k, head_cy + 230 * k), fill=255)
+    d.ellipse((cx - 470 * k, head_cy + 300 * k, cx + 470 * k, head_cy + 1300 * k), fill=255)
+    person = person.filter(ImageFilter.GaussianBlur(10 * k))
+    shade = Image.new("RGBA", (W, H), (40, 34, 32, 255))
+    shade.putalpha(person.point(lambda v: v * 150 // 255))
+    img.alpha_composite(shade)
+    return img
+
+
+def _dashed(d: ImageDraw.ImageDraw, x0, y0, x1, y1, fill, width=1, dash=10):
+    length = math.hypot(x1 - x0, y1 - y0)
+    if length <= 0:
+        return
+    n = max(1, int(length // (2 * dash)))
+    for k in range(n + 1):
+        a = min(1.0, k * 2 * dash / length)
+        b = min(1.0, (k * 2 * dash + dash) / length)
+        d.line((x0 + (x1 - x0) * a, y0 + (y1 - y0) * a, x0 + (x1 - x0) * b, y0 + (y1 - y0) * b), fill=fill, width=width)
+
+
+def contact_sheet(item: MotionItem, path: Path, count: int = 8, bg: str | Path | None = None,
+                  guides: bool = True, tile_width: int | None = None, cols: int = 4) -> Path:
+    """`count` frames spread over the item on one PNG, with the safe area and the region drawn."""
+    n = item.frames
+    picks = sorted({int(round(v)) for v in np.linspace(0, n - 1, max(2, min(count, n)))})
+    W, H = item.canvas
+    base = background(item.canvas, bg)
+    tw = tile_width or (270 if H >= W else 480)
+    th = int(round(tw * H / W))
+    rows = (len(picks) + cols - 1) // cols
+    label_h = 26
+    sheet = Image.new("RGB", (cols * tw + (cols + 1) * 8, rows * (th + label_h) + (rows + 1) * 8), (24, 24, 26))
+    d_sheet = ImageDraw.Draw(sheet)
+    lab_font = E.font("text_bold", 17)
+    s = item.box.scale
+    sx0, sy0, sx1, sy1 = (v * s for v in E.safe_area(item.canvas))
+    rx, ry, rw, rh = (v * s for v in item.region)
+    for k, i in enumerate(picks):
+        frame = base.copy()
+        frame.alpha_composite(full_frame(item, render_frame(item, i)))
+        if guides:
+            d = ImageDraw.Draw(frame)
+            lw = max(1, int(round(2 * s)))
+            for yy in (sy0, sy1):
+                _dashed(d, 0, yy, W, yy, (255, 80, 80, 255), lw, int(14 * s) + 2)
+            if H > W:
+                rail = W - E.SAFE_ZONE_VERTICAL["right_rail"] * s
+                _dashed(d, rail, H * 0.5, rail, sy1, (255, 80, 80, 255), lw, int(14 * s) + 2)
+            for (a, b_), (c, e) in (((rx, ry), (rx + rw, ry)), ((rx + rw, ry), (rx + rw, ry + rh)),
+                                    ((rx + rw, ry + rh), (rx, ry + rh)), ((rx, ry + rh), (rx, ry))):
+                _dashed(d, a, b_, c, e, (120, 220, 255, 255), lw, int(10 * s) + 2)
+        tile = frame.convert("RGB").resize((tw, th), Image.LANCZOS)
+        col, row = k % cols, k // cols
+        ox, oy = 8 + col * (tw + 8), 8 + row * (th + label_h + 8)
+        sheet.paste(tile, (ox, oy + label_h))
+        d_sheet.text((ox + 2, oy + 3), f"quadro {i} · {E.format_number(i / item.fps, 2)} s", font=lab_font,
+                     fill=(235, 235, 235))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(path, "PNG")
+    return path
+
+
+def write_mp4(item: MotionItem, path: Path, bg: str | Path | None = None) -> Path:
+    """H.264 preview of the animation over a background (to watch it, not to compose)."""
+    W, H = item.canvas
+    base = background(item.canvas, bg)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(".tmp-" + path.name)
+    pipe = _Pipe(["-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{W}x{H}", "-framerate", str(item.fps), "-i", "-",
+                  "-vf", "scale=out_color_matrix=bt709:out_range=tv,format=yuv420p", "-c:v", "libx264",
+                  "-preset", "veryfast", "-crf", "18", "-colorspace", "bt709", "-color_primaries", "bt709",
+                  "-color_trc", "bt709", "-color_range", "tv", "-frames:v", str(item.frames),
+                  "-movflags", "+faststart", "-f", "mp4", str(tmp)], "gravar a prévia .mp4")
+    try:
+        last = None
+        for _, fr, repeated in iter_frames(item):
+            if not repeated or last is None:
+                img = base.copy()
+                img.alpha_composite(full_frame(item, fr))
+                last = img.convert("RGB").tobytes()
+            pipe.write(last)
+        pipe.close()
+    except BaseException:
+        pipe.kill()
+        if tmp.exists():
+            tmp.unlink()
+        raise
+    os.replace(tmp, path)
+    return path
+
+
+def decode_clip(path: Path | str, w: int, h: int) -> np.ndarray:
+    """Frames of a clip as (n, h, w, 4) RGBA uint8 (tests and checks)."""
+    proc = subprocess.run([_ffmpeg(), "-v", "error", "-i", str(path), "-f", "rawvideo", "-pix_fmt", "rgba", "-"],
+                          capture_output=True)
+    if proc.returncode != 0:
+        raise MotionError(f"não consegui ler {path}: {proc.stderr.decode('utf-8', 'replace')[-300:]}", code=1)
+    return np.frombuffer(proc.stdout, np.uint8).reshape(-1, h, w, 4)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit("use helpers/motion_render.py")