@arbidocs/blocks 0.4.106 → 0.4.108

package/record/render-take.py

@@ -0,0 +1,985 @@
+#!/usr/bin/env python3
+"""Render a recorded take into the demo video: cut the long waits, zoom and pan onto the action,
+picture-in-picture for long typing, and the brand overlays (title and chapter cards, lower-thirds,
+captions, callouts). Everything else stays at real speed.
+
+Usage:
+  python3 -I render-take.py <take.webm> <out.mp4> --waits <story>.waits.json [--focus <story>.focus.json]
+      [--story <story>.json] [--no-zoom] [--max-zoom 1.8] [--no-pip] [--head 3] [--tail 1.5] [--min 5]
+      [--stills <dir>] [--plan <plan.json>]
+
+Inputs are what a take writes (`@arbidocs/blocks/record`: `cine.take`), in seconds from the take's
+start: `waits.json` ({"waits": [{label, start, end}]}) and `focus.json` (the focus timeline: each
+click, type and read with its target's box, the key moments `take.focus()` marked, the cards,
+lower-thirds and captions, and the story's config).
+
+A take recorded before the focus timeline existed has none: the renderer then finds the action
+from the video itself (`track_cursor`: the kit's green cursor, its click ripples, typing beside a
+resting cursor, the page moving, the caption bar and the cards), and `--story` gives the text of its
+title, chapter and closing cards to lay over the dark card spans it finds. The guards are stricter
+there: a zoom needs a click or typing the video shows, never runs while the cursor is lost or across
+a scroll or reflow, and stays above a caption bar that is in the frames (which is pasted back).
+
+How it works:
+  1. Sync: the take paints a one-frame marker at a logged time; finding it in the video lines the
+     take's clock up with the video's.
+  2. Cuts: the middle of each wait longer than --min (keeping --head s of it and its last --tail s),
+     the frames before the title card, the overlong part of a card (the setup done behind it), and
+     everything after the closing card has held.
+  3. Camera: focus events are mapped through the cuts. Typing, key moments and dwells start a zoom
+     shot (eased in over ~0.45 s to at most --max-zoom around the target, clamped in the frame);
+     clicks and targets close behind join it as a pan, or widen it when both fit; it holds at least
+     1.6 s, then eases out. Long typing gets a picture-in-picture inset instead, the full frame kept.
+  4. Frames: ffmpeg decodes the cut take; numpy/OpenCV draw callouts (in page space, so they zoom
+     with the page), the camera and the inset; ffmpeg encodes H.264 1080p, overlaying the brand
+     PNGs (render-overlays.mjs, styled with the brand the take recorded) in their `enable` windows.
+"""
+import argparse
+import json
+import math
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+import cv2
+import numpy as np
+
+FPS = 25
+W, H = 1920, 1080
+INK_BGR = (26, 16, 8)  # brand ink #08101a, for letterboxing a take of another shape
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+# Camera
+EASE_IN, PAN, EASE_OUT = 0.45, 0.6, 0.55
+MIN_HOLD = 1.6        # a shot holds at least this long once in, so it never flickers
+JOIN_GAP = 1.6        # a target this soon after the shot's last one pans instead of out-and-in
+MIN_ZOOM = 1.25       # less than this is not worth moving the camera for
+DWELL_MIN = 1.5       # a glide-and-look (point/read) starts a shot only if it is held this long
+TYPE_MIN = 0.9        # typing shorter than this (a number, a short code) does not start a shot
+POINT_MAX = 5.0
+# Picture-in-picture
+PIP_MIN = 3.0         # typing at least this long gets an inset instead of a zoom
+PIP_W = 0.40 * W
+PIP_MARGIN, PIP_BOTTOM = 40, 150   # bottom corners sit above the caption band
+PIP_RADIUS, PIP_FADE = 20, 0.3
+# Overlays
+CARD_HOLD = {"title": 5.0, "chapter": 4.0, "end": 4.0}  # longer cards are cut to this
+CARD_FADE, CAPTION_FADE, LT_FADE, CALLOUT_FADE = 0.4, 0.22, 0.3, 0.25
+CAPTION_MIN = 1.0     # a caption shown for less than this after the cuts is dropped
+DEAD_AIR = 12.0       # this long with no gesture, caption or card is cut like a wait
+SHADOW_PAD = 64       # render-overlays.mjs: room for the shadow around a cropped overlay (its whole blur)
+CALLOUT_RING_PAD, CALLOUT_TAG = 10, 46  # the tag's height plus its gap (render-overlays.mjs)
+
+
+def probe(src):
+    out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                          "stream=width,height:format=duration", "-of", "json", src],
+                         capture_output=True, text=True, check=True).stdout
+    info = json.loads(out)
+    s = info["streams"][0]
+    return int(s["width"]), int(s["height"]), float(info["format"]["duration"])
+
+
+def find_sync(src, sync_t):
+    """The video time of the take's sync marker (a full magenta frame), or None."""
+    span = (sync_t or 0) + 30
+    raw = subprocess.run(["ffmpeg", "-v", "error", "-t", f"{span:.2f}", "-i", src, "-vf", f"fps={FPS},scale=32:18",
+                          "-pix_fmt", "rgb24", "-f", "rawvideo", "-"], capture_output=True, check=True).stdout
+    size = 32 * 18 * 3
+    for i in range(len(raw) // size):
+        f = np.frombuffer(raw[i * size:(i + 1) * size], np.uint8).reshape(-1, 3).astype(int)
+        r, g, b = f.mean(axis=0)
+        if r > 200 and g < 70 and b > 200:
+            return i / FPS
+    return None
+
+
+TIMECODE_CELL, TIMECODE_CELLS = 8, 18  # @arbidocs/blocks/record: two guards and 16 bits, in page px
+
+
+def timecode_rect(vw, vh, s):
+    """The timecode strip's rect in the take's frames (page px times the take's scale)."""
+    w, h = TIMECODE_CELL * TIMECODE_CELLS * s, TIMECODE_CELL * s
+    return vw * s - w, vh * s - h, w, h
+
+
+def read_timecode(src, vw, vh, sw, sh):
+    """The take's clock against the video's, from the timecode the kit draws in every frame:
+    (take seconds, video seconds) where each tenth of a second first shows, or None."""
+    s = sw / vw
+    x, y, w, h = (int(round(n)) for n in timecode_rect(vw, vh, s))
+    raw = subprocess.run(["ffmpeg", "-v", "error", "-i", src, "-vf", f"crop={w}:{h}:{x}:{y},format=gray",
+                          "-f", "rawvideo", "-"], capture_output=True, check=True).stdout
+    cell = w / TIMECODE_CELLS
+    first = {}
+    for i in range(len(raw) // (w * h)):
+        f = np.frombuffer(raw[i * w * h:(i + 1) * w * h], np.uint8).reshape(h, w).astype(np.float32)
+        lv = [f[int(h * 0.3):int(h * 0.7) + 1, int(cell * (c + 0.3)):int(cell * (c + 0.7)) + 1].mean() for c in range(TIMECODE_CELLS)]
+        if lv[0] < 170 or lv[1] > 80 or any(80 < x_ < 170 for x_ in lv[2:]):
+            continue  # covered (a card, the cursor) or mid-change
+        ds = int("".join("1" if x_ >= 170 else "0" for x_ in lv[2:]), 2)
+        first.setdefault(ds, i / FPS)
+    if len(first) < 20:
+        return None
+    pairs = sorted((ds / 10, t) for ds, t in first.items())
+    lag = np.median([t - ds for ds, t in pairs])
+    pairs = [(ds, t) for ds, t in pairs if abs(t - ds - lag) < 30]  # drop misreads far off the clock
+    tt = np.array([p[0] for p in pairs])
+    vt = np.maximum.accumulate(np.array([p[1] for p in pairs]))  # a misread never runs the clock back
+    return tt, vt
+
+
+def dark_spans(src, fps=10):
+    """Spans of the video where the frame is nearly all dark (a card is up), in seconds."""
+    raw = subprocess.run(["ffmpeg", "-v", "error", "-i", src, "-vf", f"fps={fps},scale=32:18,format=gray",
+                          "-f", "rawvideo", "-"], capture_output=True, check=True).stdout
+    n = len(raw) // 576
+    dark = [np.frombuffer(raw[i * 576:(i + 1) * 576], np.uint8).mean() < 70 for i in range(n)] + [False]
+    spans, start = [], None
+    for i, d in enumerate(dark):
+        if d and start is None:
+            start = i
+        elif not d and start is not None:
+            if i - start >= 3:
+                spans.append((start / fps, i / fps))
+            start = None
+    return spans
+
+
+def card_anchors(src, cards, offset):
+    """A take without the timecode: line its clock up with the video's at each card, which the
+    page shows and takes down at once at a logged time (a dark span starts and ends there)."""
+    spans = dark_spans(src)
+    pairs, lag = [(0.0, offset)], offset
+    for c in cards:
+        for key, edge in (("start", 0), ("end", 1)):
+            t = c.get(key)
+            if t is None:
+                continue
+            near = [s[edge] for s in spans if -3 <= s[edge] - (t + lag) <= 15]
+            if near:
+                at = min(near, key=lambda x: abs(x - (t + lag)))
+                lag = at - t
+                pairs.append((t, at - t))
+    if len(pairs) < 3:
+        return None
+    tt = np.array([p[0] for p in pairs])
+    vt = np.maximum.accumulate(np.array([p[0] + p[1] for p in pairs]))
+    return tt, vt
+
+
+# ---------------------------------------------------------------------------------------------
+# Fallback focus: the kit's cursor, tracked in the video
+# ---------------------------------------------------------------------------------------------
+
+MOVE_FRACTION = 0.025    # a frame where this much of the page changes at once is a scroll, reflow or navigation
+TRACK_WINDOW = (520, 90)   # the fixed window (page px) a tracked click or typing is framed by
+CURSOR_SIZE = (12, 22)     # the cursor disc after erosion, in page px (22 px drawn)
+
+
+def nearest_change(diff, cx, x0, y0):
+    """The box of the changed pixels nearest the cursor (columns split where 40 px stay unchanged):
+    the characters being typed, not a label elsewhere on the row updating with them."""
+    cols = np.flatnonzero(diff.any(axis=0))
+    groups, start = [], cols[0]
+    for a, b in zip(cols, np.append(cols[1:], 10 ** 6)):
+        if b - a > 40:
+            groups.append((start, a))
+            start = b
+    g0, g1 = min(groups, key=lambda g: 0 if g[0] <= cx <= g[1] else min(abs(g[0] - cx), abs(g[1] - cx)))
+    ys = np.flatnonzero(diff[:, g0:g1 + 1].any(axis=1))
+    return (x0 + g0, y0 + ys[0], x0 + g1, y0 + ys[-1])
+
+
+def track_cursor(src):
+    """A focus timeline from the video alone, for a take recorded without one.
+
+    The recording kit draws a green cursor disc (22 px, a white ring) and a ripple on every
+    mousedown. Per frame: the green pixels; eroded, the disc is the one round blob of the right
+    size; a ripple is a ring around the resting cursor that darkens as it grows (in a compressed
+    take it is grey, not green). Clicks are
+    ripples. Typing is a click, then the cursor resting while a small band of pixels beside it
+    keeps changing (characters arriving), not a scroll (most of the band changing). Frames that are
+    nearly all dark are cards: no zoom there. Times are the video's.
+    """
+    cap = cv2.VideoCapture(src)
+    fps = cap.get(cv2.CAP_PROP_FPS) or FPS
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+    yy, xx = np.mgrid[-30:31, -30:31]
+    rr = np.hypot(xx, yy)
+    bins = [(rr >= r) & (rr < r + 2) for r in range(14, 24, 2)]
+    track, ripples, activity, dark, profiles, captioned, changed, moved = [], [], [], [], [], [], [], []
+    prev_gray, prev_pos, prev_small = None, None, None
+    i = 0
+    while True:
+        ok, f = cap.read()
+        if not ok:
+            break
+        t = i / fps
+        i += 1
+        sh, sw = f.shape[:2]
+        b, g, r = (f[:, :, k].astype(np.int16) for k in range(3))
+        green = ((g > r + 45) & (g > b + 12) & (r < 100)).astype(np.uint8)
+        core = cv2.erode(green, kernel)
+        n, _, st, cen = cv2.connectedComponentsWithStats(core)
+        best = None
+        for j in range(1, n):
+            x, y, w, h, a = st[j]
+            if CURSOR_SIZE[0] <= w <= CURSOR_SIZE[1] and CURSOR_SIZE[0] <= h <= CURSOR_SIZE[1] and abs(w - h) <= 4 and a / (w * h) > 0.6:
+                c = (float(cen[j][0]), float(cen[j][1]))
+                d = 0 if prev_pos is None else math.hypot(c[0] - prev_pos[0], c[1] - prev_pos[1])
+                if best is None or d < best[1]:
+                    best = (c, d)
+        pos = best[0] if best else None
+        track.append(pos)
+        gray = cv2.cvtColor(f, cv2.COLOR_BGR2GRAY)
+        dark.append(float(gray.mean()) < 70)
+        small = cv2.resize(gray, (sw // 4, sh // 4), interpolation=cv2.INTER_AREA)
+        moved.append(prev_small is not None and float((cv2.absdiff(small, prev_small) > 30).mean()) > MOVE_FRACTION)
+        prev_small = small
+        mid = gray[sh - 75:sh - 45, int(0.45 * sw):int(0.55 * sw)]
+        captioned.append(float((mid < 90).mean()) > 0.5)
+        rip, act, prof, dbox = 0.0, 0, None, None
+        if pos:
+            cx, cy = int(round(pos[0])), int(round(pos[1]))
+            if 30 <= cx < sw - 30 and 30 <= cy < sh - 30:
+                crop = gray[cy - 30:cy + 31, cx - 30:cx + 31].astype(np.float32)
+                prof = (pos, np.array([crop[m].mean() for m in bins]))
+                back = profiles[-6] if len(profiles) >= 6 else None
+                if back and math.hypot(back[0][0] - pos[0], back[0][1] - pos[1]) < 3:
+                    rip = float(-(prof[1] - back[1]).min())  # the ripple's ring darkens a band as it grows
+            if prev_gray is not None:
+                y0, y1, x0, x1 = max(cy - 40, 0), min(cy + 40, sh), max(cx - 500, 0), min(cx + 500, sw)
+                diff = cv2.absdiff(gray[y0:y1, x0:x1], prev_gray[y0:y1, x0:x1]) > 30
+                diff[max(cy - 18 - y0, 0):cy + 18 - y0, max(cx - 18 - x0, 0):cx + 18 - x0] = False
+                act = int(diff.sum())
+                if act:
+                    dbox = nearest_change(diff, cx - x0, x0, y0)
+        ripples.append(rip)
+        activity.append(act)
+        changed.append(dbox)
+        profiles.append(prof)
+        prev_gray, prev_pos = gray, pos or prev_pos
+    cap.release()
+    nf = len(track)
+
+    def runs(flags, min_len=1, gap=0):
+        out, a, last = [], None, None
+        for k, on in enumerate(flags):
+            if on:
+                if a is None or (last is not None and k - last > gap + 1):
+                    if a is not None:
+                        out.append((a, last))
+                    a = k
+                last = k
+        if a is not None:
+            out.append((a, last))
+        return [(a, b) for a, b in out if b - a + 1 >= min_len]
+
+    def box(p):
+        w, h = TRACK_WINDOW
+        return {"x": p[0] - w / 2, "y": p[1] - h / 2, "width": w, "height": h}
+
+    def in_caption_band(p):
+        return p[1] > sh - 130 and abs(p[0] - sw / 2) < 0.36 * sw
+
+    clicks = []
+    for a, b in runs([rp > 15 for rp in ripples], min_len=2, gap=1):
+        p = track[a]
+        if p and not in_caption_band(p):
+            clicks.append((max(a - 3, 0) / fps, p))
+
+    def still(k, p):
+        q = track[k]
+        return q is not None and math.hypot(q[0] - p[0], q[1] - p[1]) < 4
+
+    focus, used = [], set()
+    for ci, (tc, p) in enumerate(clicks):
+        k0 = int(tc * fps) + 3
+        # Typing: within 1.5 s of the click, characters arriving beside the resting cursor.
+        k, last_hit, hits = k0, None, []
+        while k < nf and still(k, p) and (last_hit is None or k - last_hit <= int(0.6 * fps)):
+            if 12 <= activity[k] <= 2500:
+                last_hit = k
+                hits.append(changed[k])
+            elif last_hit is None and k - k0 > int(1.5 * fps):
+                break
+            k += 1
+        if last_hit is not None and (last_hit - k0) / fps >= 0.8:
+            # Where the characters arrived: the inset frames that, not the cursor's window.
+            x0_, y0_ = min(h[0] for h in hits), min(h[1] for h in hits)
+            x1_, y1_ = max(h[2] for h in hits), max(h[3] for h in hits)
+            text = {"x": float(x0_), "y": float(y0_), "width": float(x1_ - x0_ + 1), "height": float(y1_ - y0_ + 1)}
+            focus.append({"kind": "type", "label": "typing (tracked)", "start": tc, "end": last_hit / fps + 0.2, "box": box(p), "textBox": text})
+            used.add(ci)
+    for ci, (tc, p) in enumerate(clicks):
+        if ci in used:
+            continue
+        # A click the page answers beside the cursor (a tile picked, a popover opened) while the
+        # cursor rests on it is worth a look; any other click only joins a shot.
+        k0 = int(tc * fps) + 3
+        k = k0
+        while k < nf and still(k, p) and k - k0 < int(3 * fps):
+            k += 1
+        # Answered beside the cursor, and only there: a click that scrolls or reflows the page is a
+        # change of scene, not a thing to look at.
+        window = range(k0, min(k, k0 + int(fps)))
+        answered = any(12 <= activity[j] <= 2500 for j in window) and not any(moved[j] for j in range(k0, k))
+        if answered and (k - k0) / fps >= 1.2:
+            focus.append({"kind": "point", "label": "click, answered (tracked)", "start": tc, "end": k / fps, "box": box(p)})
+        else:
+            focus.append({"kind": "click", "label": "click (tracked)", "start": tc, "end": tc + 0.5, "box": box(p)})
+    # No zoom while the cursor is lost: a shot may not run over a stretch of a second without it.
+    lost = [(a / fps, (b + 1) / fps) for a, b in runs([p is None for p in track], min_len=int(fps))]
+    cards = [(a / fps, (b + 1) / fps) for a, b in runs(dark, min_len=int(fps / 2), gap=2)]
+    return {"viewport": {"width": sw, "height": sh}, "focus": sorted(focus, key=lambda e: e["start"]),
+            "blocked": cards + lost, "source": "cursor", "darkSpans": cards,
+            "moves": [a / fps for a, _ in runs(moved, gap=2)],
+            "captioned": [(a / fps, (b + 1) / fps) for a, b in runs(captioned, gap=3)]}
+
+
+# ---------------------------------------------------------------------------------------------
+# Cuts and the time map
+# ---------------------------------------------------------------------------------------------
+
+def cards_from_dark(spans, story, duration):
+    """The brand cards for a take whose cards are only in its frames: the story's title, chapters and
+    closing card, laid over the dark spans of the video in order (the first is the title; one that
+    runs to the end is the closing card). Spans with no card left keep what is in the frames."""
+    spans = [s for s in spans if s[1] - s[0] >= 2.0]  # a card holds 2.4 s or more; a dark dialog backdrop is briefer
+    cards = []
+    if spans and story.get("title"):
+        cards.append(dict(story["title"], start=spans[0][0], end=spans[0][1]))
+        spans = spans[1:]
+    closing = story.get("end")
+    if closing and spans and spans[-1][1] >= duration - 1.5:
+        last = spans.pop()
+    else:
+        last = None
+    for span, ch in zip(spans, story.get("chapters", [])):
+        cards.append(dict(ch, start=span[0], end=span[1]))
+    if last:
+        cards.append(dict(closing, start=last[0], end=None))
+    for c in cards:
+        print(f"card {c['start']:6.1f}-{c['end'] if c['end'] is not None else 'end'}  {c['title']}")
+    return cards
+
+
+def dead_air(tl, v, end_at, head, tail):
+    """Stretches of a take where nothing is done and nothing is said: no gesture, no caption, no
+    card for DEAD_AIR seconds (a step the server ran that the story did not log as a wait). Their
+    middle is cut like a wait's, keeping `head` s and the last `tail` s."""
+    marks = []
+    for e in tl.get("focus", []):
+        marks += [e["start"], e.get("end") or e["start"]]
+    for c in tl.get("captions", []) + tl.get("cards", []) + tl.get("lowerThirds", []):
+        marks += [c["start"]] + ([c["end"]] if c.get("end") is not None else [])
+    for w in tl.get("waits", []):
+        marks += [w["start"], w["end"]]
+    marks = sorted(v(t) for t in marks)
+    cuts = []
+    for a, b in zip(marks, marks[1:] + [end_at]):
+        if b - a >= DEAD_AIR and b - tail - (a + head) >= 1:
+            cuts.append((a + head, b - tail, "nothing on screen happens"))
+    return cuts
+
+
+def merge(ranges):
+    out = []
+    for a, b, why in sorted(ranges):
+        if b - a < 0.04:
+            continue
+        if out and a <= out[-1][1]:
+            out[-1] = (out[-1][0], max(b, out[-1][1]), out[-1][2] + " + " + why)
+        else:
+            out.append((a, b, why))
+    return out
+
+
+def make_map(cuts):
+    def m(t):
+        return t - sum(min(max(t - a, 0), b - a) for a, b, _ in cuts)
+    return m
+
+
+# ---------------------------------------------------------------------------------------------
+# The camera
+# ---------------------------------------------------------------------------------------------
+
+FULL = (0.0, 0.0, float(W))  # a camera is the source rect it shows: x, y, width (16:9)
+
+
+CAPTION_TOP = H - 190  # a burned-in caption bar sits below this on the output frame
+BOUNDS = [0.0, 0.0, float(W), float(H)]  # where the camera may look: the take's picture, above a burned-in caption bar
+
+
+def target_rect(box, max_zoom, safe=None):
+    """The camera rect framing `box`, or None. With `safe` (the top of a burned-in caption bar), the
+    rect stays above the bar and the box lands above where the bar sits on the zoomed frame."""
+    bx0, by0, bx1, by1 = BOUNDS
+    if safe:
+        by1 = min(by1, safe)
+    x0, y0 = max(box[0], bx0), max(box[1], by0)
+    x, y, w, h = x0, y0, min(box[0] + box[2], bx1) - x0, min(box[1] + box[3], by1) - y0
+    if w < 8 or h < 8:  # off the picture, or under the caption bar
+        return None
+    rw = max(w * 1.5 + 90, (h * 1.5 + 90) * W / H, W / max_zoom)
+    rh = rw * H / W
+    if rw > W / MIN_ZOOM or rw > bx1 - bx0 or rh > by1 - by0:
+        return None
+    cx, cy = x + w / 2, y + h / 2
+    f = safe / H if safe else 1.0
+    ry = min(max(cy - rh * f / 2, by0), by1 - rh)
+    if y + h > ry + rh * f:
+        return None
+    return (min(max(cx - rw / 2, bx0), bx1 - rw), ry, rw)
+
+
+def union(a, b):
+    x0, y0 = min(a[0], b[0]), min(a[1], b[1])
+    x1, y1 = max(a[0] + a[2], b[0] + b[2]), max(a[1] + a[3], b[1] + b[3])
+    return (x0, y0, x1 - x0, y1 - y0)
+
+
+def ease(u):
+    u = min(max(u, 0.0), 1.0)
+    return u * u * u * (u * (u * 6 - 15) + 10)  # smootherstep: no jolt at either end
+
+
+def lerp_rect(a, b, u):
+    """From rect a to b, zooming at a constant rate about their common fixed point."""
+    e = ease(u)
+    (ax, ay, aw), (bx, by, bw) = a, b
+    if abs(bw - aw) < 1:
+        return (ax + (bx - ax) * e, ay + (by - ay) * e, aw)
+    w = aw * (bw / aw) ** e
+    r = (w - aw) / (bw - aw)  # 0 -> 1, the same weight on both edges keeps the move straight
+    return (ax + (bx - ax) * r, ay + (by - ay) * r, w)
+
+
+def plan_camera(events, blocked, max_zoom, captioned=(), page_moves=()):
+    """`blocked`: windows with no zoom at all (cards, the cursor lost, insets). `page_moves`: moments the
+    page itself moves (scroll, reflow, navigation): a shot never runs over one, it is out before."""
+    """Zoom shots from the focus events: [(t0, t1, from, to)] moves of the camera."""
+    def clear(a, b):
+        return not any(a < bb and b > ba for ba, bb in blocked)
+
+    def still(a, b):
+        return not any(a < t < b for t in page_moves)
+
+    evs = []
+    for e in events:
+        if e.get("mode") in ("none", "pip") or not clear(e["start"] - EASE_IN, e["end"] + EASE_OUT) or not still(e["start"], e["end"]):
+            continue
+        e = dict(e, safe=CAPTION_TOP if any(e["start"] - 1.5 < b and e["end"] + 2.5 > a for a, b in captioned) else None)
+        rect = target_rect(e["box"], max_zoom, e["safe"])
+        if rect is None:
+            continue
+        dur = e["end"] - e["start"]
+        trigger = (e["kind"] == "focus" or e.get("mode") == "zoom"
+                   or (e["kind"] == "type" and dur >= TYPE_MIN)
+                   or (e["kind"] in ("point", "read") and dur >= DWELL_MIN))
+        evs.append(dict(e, rect=rect, trigger=trigger))
+
+    shots, cur = [], None
+    for e in sorted(evs, key=lambda e: e["start"]):
+        if cur and e["start"] <= cur["end"] + JOIN_GAP and clear(cur["end"], e["end"] + EASE_OUT) and still(cur["end"], e["start"]):
+            last = cur["keys"][-1]
+            both = union(last["box"], e["box"])
+            safe = last.get("safe") or e["safe"]
+            wide = target_rect(both, max_zoom, safe)
+            if wide and wide[2] <= 1.35 * max(last["rect"][2], e["rect"][2]):
+                last["box"], last["rect"], last["safe"] = both, wide, safe
+            else:
+                cur["keys"].append({"t": e["start"], "box": e["box"], "rect": e["rect"], "safe": e["safe"], "label": e.get("label", "")})
+            cur["end"] = max(cur["end"], e["end"])
+        elif e["trigger"]:
+            cur = {"start": e["start"], "end": e["end"], "keys": [{"t": e["start"], "box": e["box"], "rect": e["rect"], "safe": e["safe"], "label": e.get("label", "")}]}
+            shots.append(cur)
+
+    moves, free_at = [], 0.0
+    for s in shots:
+        t = max(s["start"] - 0.2, free_at)
+        moves.append((t, t + EASE_IN, FULL, s["keys"][0]["rect"]))
+        last_end = t + EASE_IN
+        for prev, k in zip(s["keys"], s["keys"][1:]):
+            ta = max(k["t"] - 0.25, last_end)
+            moves.append((ta, ta + PAN, prev["rect"], k["rect"]))
+            last_end = ta + PAN
+        out = max(s["end"] + 0.25, s["start"] + MIN_HOLD, last_end + 0.3)
+        nxt = min([ba for ba, _ in blocked if ba >= s["start"]] + [t for t in page_moves if t > s["end"]], default=None)
+        if nxt is not None and out + EASE_OUT > nxt:
+            out = max(nxt - EASE_OUT, last_end)
+        moves.append((out, out + EASE_OUT, s["keys"][-1]["rect"], FULL))
+        free_at = out + EASE_OUT
+        s["in"], s["out"] = t, out + EASE_OUT
+    return moves, shots
+
+
+def camera_at(moves, t):
+    cam = FULL
+    for a, b, frm, to in moves:
+        if t < a:
+            break
+        cam = lerp_rect(frm, to, (t - a) / (b - a)) if t < b else to
+    return cam
+
+
+# ---------------------------------------------------------------------------------------------
+# Picture-in-picture
+# ---------------------------------------------------------------------------------------------
+
+def plan_pip(e):
+    x, y, w, h = e.get("textBox") or e["box"]
+    aspect = min(max((w * 1.12 + 48) / (h * 1.12 + 32), 1.6), 3.0)
+    cw = max(w * 1.12 + 48, PIP_W / 2.2)
+    ch = cw / aspect
+    if ch < h * 1.12 + 32:
+        ch = h * 1.12 + 32
+        cw = ch * aspect
+    if PIP_W / cw < 1.3:
+        return None
+    cx, cy = x + w / 2, y + h / 2
+    crop = (min(max(cx - cw / 2, 0), W - cw), min(max(cy - ch / 2, 0), H - ch), cw, ch)
+    iw, ih = int(PIP_W), int(round(PIP_W / aspect))
+    corners = [(W - PIP_MARGIN - iw, PIP_MARGIN), (PIP_MARGIN, PIP_MARGIN),
+               (W - PIP_MARGIN - iw, H - PIP_BOTTOM - ih), (PIP_MARGIN, H - PIP_BOTTOM - ih)]
+
+    def overlap(c):
+        ox = max(0, min(c[0] + iw, x + w + 40) - max(c[0], x - 40))
+        oy = max(0, min(c[1] + ih, y + h + 40) - max(c[1], y - 40))
+        return ox * oy
+
+    pos = min(corners, key=overlap)
+    return {"crop": crop, "size": (iw, ih), "pos": pos}
+
+
+def rounded(w, h, r, inset=0, ss=4):
+    """A rounded-rect alpha mask (anti-aliased), `inset` px in from the edge."""
+    m = np.zeros((h * ss, w * ss), np.uint8)
+    x0, y0, x1, y1 = inset * ss, inset * ss, (w - inset) * ss - 1, (h - inset) * ss - 1
+    rr = max(r - inset, 1) * ss
+    cv2.rectangle(m, (x0 + rr, y0), (x1 - rr, y1), 255, -1)
+    cv2.rectangle(m, (x0, y0 + rr), (x1, y1 - rr), 255, -1)
+    for cx, cy in ((x0 + rr, y0 + rr), (x1 - rr, y0 + rr), (x0 + rr, y1 - rr), (x1 - rr, y1 - rr)):
+        cv2.circle(m, (cx, cy), rr, 255, -1)
+    return cv2.resize(m, (w, h), interpolation=cv2.INTER_AREA).astype(np.float32) / 255
+
+
+
+def pip_layers(iw, ih):
+    """The inset's mask, its border ring and its drop shadow (float alpha arrays)."""
+    outer = rounded(iw, ih, PIP_RADIUS)
+    inner = rounded(iw, ih, PIP_RADIUS, inset=3)
+    pad = 48
+    shadow = np.zeros((ih + 2 * pad, iw + 2 * pad), np.float32)
+    shadow[pad + 14:pad + 14 + ih, pad:pad + iw] = outer
+    shadow = cv2.GaussianBlur(shadow, (0, 0), 18) * 0.5
+    return outer, inner, shadow, pad
+
+
+def blend(frame, layer_bgr, alpha, x, y):
+    """Alpha-blend `layer_bgr` (h, w, 3) with alpha (h, w) onto frame at (x, y), clipped."""
+    h, w = alpha.shape
+    x0, y0, x1, y1 = max(x, 0), max(y, 0), min(x + w, W), min(y + h, H)
+    if x0 >= x1 or y0 >= y1:
+        return
+    a = alpha[y0 - y:y1 - y, x0 - x:x1 - x, None]
+    roi = frame[y0:y1, x0:x1].astype(np.float32)
+    src = layer_bgr if np.ndim(layer_bgr) == 1 else layer_bgr[y0 - y:y1 - y, x0 - x:x1 - x]
+    frame[y0:y1, x0:x1] = (roi * (1 - a) + np.asarray(src, np.float32) * a).astype(np.uint8)
+
+
+def keep_caption(src, dst):
+    """Copy the kit's caption bar (a dark rounded box at the bottom centre) from the unzoomed frame
+    onto the zoomed one, so a take with captions in its frames never loses its narration."""
+    y0, x0, x1 = H - 190, int(0.172 * W), int(0.83 * W)  # clear of the sidebar
+    dark = cv2.cvtColor(src[y0:H - 8, x0:x1], cv2.COLOR_BGR2GRAY) < 90
+    mid = (W // 2 - x0) - int(0.05 * W), (W // 2 - x0) + int(0.05 * W)
+    # The bar's rows: its fill is dark across the middle (its lines of text still leave a third of
+    # it dark); a line of the page's own text is not. The longest such run is the bar.
+    rows = np.flatnonzero(dark[:, mid[0]:mid[1]].mean(axis=1) > 0.32)
+    if len(rows) < 25:
+        return
+    runs_, start = [], rows[0]
+    for r0, r1 in zip(rows, np.append(rows[1:], 10 ** 6)):
+        if r1 - r0 > 3:
+            runs_.append((start, r0))
+            start = r1
+    a, b = max(runs_, key=lambda r: r[1] - r[0])
+    if b - a < 25:
+        return
+    on = dark[a:b + 1].mean(axis=0) > 0.35
+    best, run = (0, 0), None  # the widest run of dark columns is the box (not the sidebar's edge)
+    for i, c in enumerate(np.append(on, False)):
+        if c and run is None:
+            run = i
+        elif not c and run is not None:
+            if i - run > best[1] - best[0]:
+                best = (run, i)
+            run = None
+    if best[1] - best[0] < 200 or b - a > 170:
+        return
+    bx0, bx1, by0, by1 = x0 + best[0] - 3, x0 + best[1] + 3, y0 + a - 3, y0 + b + 4
+    mask = rounded(bx1 - bx0, by1 - by0, 18)
+    blend(dst, src[by0:by1, bx0:bx1], mask, bx0, by0)
+
+
+def window_alpha(t, a, b, fade):
+    if t < a or t > b:
+        return 0.0
+    return ease(min((t - a) / fade, (b - t) / fade, 1.0))
+
+
+# ---------------------------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("src")
+    ap.add_argument("out")
+    ap.add_argument("--waits")
+    ap.add_argument("--focus")
+    ap.add_argument("--no-zoom", action="store_true")
+    ap.add_argument("--no-pip", action="store_true")
+    ap.add_argument("--max-zoom", type=float)
+    ap.add_argument("--head", type=float, default=3)
+    ap.add_argument("--tail", type=float, default=1.5)
+    ap.add_argument("--min", type=float, default=5)
+    ap.add_argument("--stills")
+    ap.add_argument("--story", help="a take without a focus timeline: its cards and config, as JSON "
+                    '{"config": {...}, "title": {kicker, title, subtitle}, "chapters": [...], "end": {...}}')
+    ap.add_argument("--keep", action="store_true", help="keep the overlay PNGs and the filter graph")
+    ap.add_argument("--plan", help="where to write the edit's plan (default: beside the video)")
+    args = ap.parse_args()
+
+    sw, sh, duration = probe(args.src)
+    waits = []
+    if args.waits and os.path.exists(args.waits):
+        data = json.load(open(args.waits))
+        waits = data["waits"] if isinstance(data, dict) else [{"label": "", "start": a, "end": b} for a, b in data]
+    tl = json.load(open(args.focus)) if args.focus and os.path.exists(args.focus) else {}
+    if not tl and not args.no_zoom:
+        # A take recorded without a focus timeline: find the action from the kit's cursor.
+        tl = track_cursor(args.src)
+        print(f"no focus timeline: tracked the cursor ({len(tl['focus'])} clicks and typing)")
+    burned_captions = tl.get("source") == "cursor"  # the caption bar is in the frames: keep it unzoomed
+    cfg = tl.get("config", {})
+    zoom_on = cfg.get("zoom", True) and not args.no_zoom
+    pip_on = cfg.get("pip", True) and not args.no_pip
+    max_zoom = args.max_zoom or cfg.get("maxZoom", 1.8)
+
+    # 1. The take's clock on the video's: the timecode in every frame where the take drew one
+    #    (the video's clock drifts from the wall clock over a long take), else the sync marker.
+    offset = 0.0
+    vp = tl.get("viewport") or {}
+    clock = read_timecode(args.src, vp.get("width", sw), vp.get("height", sh), sw, sh) if tl.get("focus") is not None else None
+    if clock is None and tl.get("sync") is not None:
+        at = find_sync(args.src, tl["sync"])
+        if at is None:
+            print("warning: no timecode or sync marker found; the take's clock is used as is", file=sys.stderr)
+        else:
+            offset = at - tl["sync"]
+    if clock is None and tl.get("cards") and tl.get("focus") is not None:
+        clock = card_anchors(args.src, tl["cards"], offset)
+    if clock:
+        tt, vt = clock
+        print(f"take {duration:.1f} s, clock from {len(tt)} anchors, drift {vt[-1] - tt[-1] - (vt[0] - tt[0]):+.2f} s")
+    else:
+        print(f"take {duration:.1f} s, clock offset {offset:+.2f} s")
+
+    def v(t):
+        if t is None:
+            return None
+        if not clock:
+            return t + offset
+        if t <= tt[0]:
+            return vt[0] + (t - tt[0])
+        if t >= tt[-1]:
+            return vt[-1] + (t - tt[-1])
+        return float(np.interp(t, tt, vt))
+
+    # 2. Cuts, on the video's clock.
+    cuts = []
+    for w in waits:
+        a, b = v(w["start"]) + args.head, min(v(w["end"]), duration) - args.tail
+        if v(w["end"]) - v(w["start"]) >= args.min and b - a >= 1:
+            cuts.append((a, b, w["label"]))
+    story = json.load(open(args.story)) if args.story else {}
+    if tl.get("source") == "cursor" and story:
+        tl["cards"] = cards_from_dark(tl.get("darkSpans", []), story, duration)
+        cfg = {**cfg, **story.get("config", {})}
+        zoom_on = cfg.get("zoom", True) and not args.no_zoom
+        pip_on = cfg.get("pip", True) and not args.no_pip
+        max_zoom = args.max_zoom or cfg.get("maxZoom", 1.8)
+    cards = [dict(c, start=v(c["start"]), end=v(c.get("end"))) for c in tl.get("cards", [])]
+    end_at = duration
+    if cards:
+        cuts.append((0, cards[0]["start"], "before the title card"))
+        for i, c in enumerate(cards):
+            kind = "title" if i == 0 else ("end" if c["end"] is None else "chapter")
+            c["kind"] = kind
+            if c["end"] is None:
+                end_at = min(duration, c["start"] + CARD_HOLD["end"])
+                c["end"] = end_at
+            elif c["end"] - c["start"] > CARD_HOLD[kind]:
+                cuts.append((c["start"] + CARD_HOLD[kind] - CARD_FADE, c["end"] - CARD_FADE, f"behind the card '{c['title']}'"))
+        if end_at < duration:
+            cuts.append((end_at, duration + 1, "after the closing card"))
+    if tl.get("source") != "cursor" and tl.get("focus") is not None:
+        cuts += dead_air(dict(tl, waits=waits), v, end_at, args.head, args.tail)
+    cuts = merge(cuts)
+    m = make_map(cuts)
+    total = m(min(end_at, duration))
+    for a, b, why in cuts:
+        print(f"cut {a:7.1f} - {min(b, duration):7.1f}  ({min(b, duration) - a:5.1f} s)  {why}")
+    print(f"video {total:.1f} s")
+
+    # 3. The plan, on the cut video's clock, in output pixels.
+    vw, vh = (tl.get("viewport") or {}).get("width", sw), (tl.get("viewport") or {}).get("height", sh)
+    k = min(W / sw, H / sh)
+    ox, oy = (W - sw * k) / 2, (H - sh * k) / 2
+    s = (sw / vw) * k
+
+    BOUNDS[:] = [ox, oy, ox + sw * k, oy + sh * k]
+    timecode = None  # the strip's rows in the output frame, painted out with the rows above it
+    if clock:
+        tx, ty, tw, th = timecode_rect(vw, vh, sw / vw)
+        timecode = (int(ty * k + oy) - 1, min(int(np.ceil((ty + th) * k + oy)), H),
+                    int(tx * k + ox) - 1, min(int(np.ceil((tx + tw) * k + ox)), W))
+
+    def px(b):
+        return (b["x"] * s + ox, b["y"] * s + oy, b["width"] * s, b["height"] * s)
+
+    def mapped(a, b):
+        return m(a), m(b)
+
+    card_windows = []
+    for i, c in enumerate(cards):
+        c["start"], c["end"] = mapped(c["start"], c["end"])
+        # The brand card is opaque before the page's own card shows and fades out once it has gone,
+        # so the two never show at once (their type differs).
+        if i:
+            c["start"] = max(c["start"] - CARD_FADE, 0)
+        if c["kind"] != "end":
+            c["end"] = min(c["end"] + CARD_FADE, total)
+        card_windows.append((c["start"], c["end"]))
+
+    focus = sorted(tl.get("focus", []), key=lambda e: e["start"])
+    scene_moves = sorted(tl.get("moves", []))
+    events = []
+    for i, e in enumerate(focus):
+        end = e.get("end")
+        if end is None:  # a glide-and-look lasts until the next gesture
+            end = min(focus[i + 1]["start"] if i + 1 < len(focus) else e["start"] + 2, e["start"] + POINT_MAX)
+        b_raw = v(end)
+        nxt = next((t for t in scene_moves if v(e["start"]) + 0.3 < t < b_raw + 1.0), None)
+        if nxt is not None:  # the page moved under the target: what was framed is no longer there
+            b_raw = min(b_raw, nxt - 0.1)
+        a, b = mapped(v(e["start"]), b_raw)
+        if b - a < 0.15:
+            continue
+        events.append(dict(e, start=a, end=b, box=px(e["box"]), textBox=px(e["textBox"]) if e.get("textBox") else None))
+
+    pips = []
+    if pip_on:
+        for e in events:
+            long_type = e["kind"] == "type" and e["end"] - e["start"] >= PIP_MIN and e.get("mode") != "zoom"
+            if (e.get("mode") == "pip" or long_type) and not any(e["start"] < cb and e["end"] > ca for ca, cb in card_windows):
+                p = plan_pip(e)
+                if p:
+                    tail = min([0.8] + [m(t) - 0.05 - e["end"] for t in scene_moves if m(t) > e["end"]])
+                    p.update(start=e["start"] + 0.15, end=e["end"] + max(tail, 0.1), label=e.get("label", ""))
+                    pips.append(p)
+                    e["mode"] = "pip"
+    moves, shots = ([], [])
+    if zoom_on:
+        tracked_blocks = [mapped(v(a), v(b)) for a, b in tl.get("blocked", [])]
+        blocked = sorted(card_windows + tracked_blocks + [(p["start"], p["end"]) for p in pips])
+        captioned = [mapped(v(a), v(b)) for a, b in tl.get("captioned", [])]
+        moves, shots = plan_camera(events, blocked, max_zoom, captioned, [m(t) for t in scene_moves])
+
+    callouts = []
+    for e in events:
+        if e.get("callout"):
+            x, y, w, h = e["box"]
+            ring = (x - CALLOUT_RING_PAD, y - CALLOUT_RING_PAD, w + 2 * CALLOUT_RING_PAD, h + 2 * CALLOUT_RING_PAD)
+            label = e.get("label") or ""
+            below = bool(label) and ring[1] - CALLOUT_TAG < 12
+            callouts.append({"start": e["start"], "end": e["end"] + 0.5, "ring": ring, "label": label, "below": below})
+
+    captions, lts = [], []
+    raw_caps = sorted(tl.get("captions", []), key=lambda c: c["start"])
+    for i, c in enumerate(raw_caps):
+        end = c.get("end")
+        if end is None:
+            end = raw_caps[i + 1]["start"] if i + 1 < len(raw_caps) else c["start"] + 4
+        a, b = mapped(v(c["start"]), v(end))
+        if b - a >= CAPTION_MIN and c["text"].strip():
+            captions.append({"text": c["text"], "start": a, "end": b})
+    for c in tl.get("lowerThirds", []):
+        a, b = mapped(v(c["start"]), v(c["end"]))
+        if b - a >= 1:
+            lts.append({"kicker": c["kicker"], "title": c["title"], "start": a, "end": b})
+
+    print(f"plan: {len(shots)} zoom shots, {len(pips)} insets, {len(callouts)} callouts, "
+          f"{len(cards)} cards, {len(lts)} lower-thirds, {len(captions)} captions")
+
+    # 4. The overlays, as PNGs.
+    tmp = tempfile.mkdtemp(prefix="render-take-")
+    items = []
+    for i, c in enumerate(cards):
+        items.append({"id": f"card-{i}", "kind": c["kind"], "kicker": c.get("kicker", ""), "title": c["title"], "subtitle": c.get("subtitle") or ""})
+    for i, c in enumerate(lts):
+        items.append({"id": f"lt-{i}", "kind": "lower-third", "kicker": c["kicker"], "title": c["title"]})
+    texts = sorted({c["text"] for c in captions})
+    for i, t in enumerate(texts):
+        items.append({"id": f"cap-{i}", "kind": "caption", "text": t})
+    for i, c in enumerate(callouts):
+        items.append({"id": f"co-{i}", "kind": "callout", "w": round(c["ring"][2]), "h": round(c["ring"][3]), "label": c["label"], "tagBelow": c["below"]})
+    if items:
+        json.dump({"width": W, "height": H, "brand": tl.get("brand") or {}, "items": items},
+                  open(os.path.join(tmp, "overlays.json"), "w"))
+        subprocess.run(["node", os.path.join(HERE, "render-overlays.mjs"),
+                        os.path.join(tmp, "overlays.json"), tmp], check=True)
+
+    def png(i):
+        return os.path.join(tmp, f"{i}.png")
+
+    for i, c in enumerate(callouts):
+        img = cv2.imread(png(f"co-{i}"), cv2.IMREAD_UNCHANGED)
+        c["bgr"], c["alpha"] = img[:, :, :3].astype(np.float32), img[:, :, 3].astype(np.float32) / 255
+        c["x"] = int(round(c["ring"][0] - SHADOW_PAD))
+        c["y"] = int(round(c["ring"][1] - SHADOW_PAD - (CALLOUT_TAG if c["label"] and not c["below"] else 0)))
+    for p in pips:
+        p["layers"] = pip_layers(*p["size"])
+
+    # 5. The ffmpeg graph for the overlays drawn over the camera: captions, lower-thirds, cards.
+    inputs, graph, last = [], [], "0:v"
+    placed = []
+    for c in captions:
+        placed.append(("cap", f"cap-{texts.index(c['text'])}", c["start"], c["end"], CAPTION_FADE))
+    for i, c in enumerate(lts):
+        placed.append(("lt", f"lt-{i}", c["start"], c["end"], LT_FADE))
+    for i, c in enumerate(cards):
+        placed.append(("card", f"card-{i}", c["start"], c["end"], CARD_FADE))
+    for n, (kind, pid, a, b, fade) in enumerate(placed, start=1):
+        d = max(b - a, 2 * fade + 0.04)
+        img = cv2.imread(png(pid), cv2.IMREAD_UNCHANGED)
+        ih, iw = img.shape[:2]
+        if kind == "cap":
+            x, y = (W - iw) // 2, H - ih - 48 + SHADOW_PAD
+        elif kind == "lt":
+            x, y = 64 - SHADOW_PAD, H - ih - 190 + SHADOW_PAD
+        else:
+            x, y = 0, 0
+        fin = 0 if (kind == "card" and a < 0.05) else fade  # the video opens on the title card
+        inputs += ["-loop", "1", "-framerate", str(FPS), "-t", f"{d:.3f}", "-i", png(pid)]
+        chain = f"[{n}:v]format=rgba"
+        if fin:
+            chain += f",fade=t=in:st=0:d={fin}:alpha=1"
+        chain += f",fade=t=out:st={d - fade:.3f}:d={fade}:alpha=1,setpts=PTS-STARTPTS+{a:.3f}/TB[o{n}]"
+        graph.append(chain)
+        graph.append(f"[{last}][o{n}]overlay=x={x}:y={y}:eof_action=pass:enable='between(t,{a:.3f},{a + d:.3f})'[v{n}]")
+        last = f"v{n}"
+    graph.append(f"[{last}]format=yuv420p[vout]")
+    graph_file = os.path.join(tmp, "graph.txt")
+    open(graph_file, "w").write(";\n".join(graph))
+
+    # 6. Frames: decode the cut take, draw the camera, the inset and the callouts, encode.
+    select = "+".join(f"between(t,{a:.3f},{b:.3f})" for a, b, _ in cuts) or "0"
+    dec = subprocess.Popen(
+        ["ffmpeg", "-v", "error", "-i", args.src, "-an", "-vf",
+         f"select='not({select})',setpts=N/({FPS}*TB),"
+         f"scale={W}:{H}:force_original_aspect_ratio=decrease:flags=lanczos,pad={W}:{H}:(ow-iw)/2:(oh-ih)/2:color=0x08101a",
+         "-r", str(FPS), "-f", "rawvideo", "-pix_fmt", "bgr24", "-"], stdout=subprocess.PIPE)
+    enc = subprocess.Popen(
+        ["ffmpeg", "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "bgr24", "-s", f"{W}x{H}", "-r", str(FPS), "-i", "-",
+         *inputs, "-filter_complex_script", graph_file, "-map", "[vout]", "-t", f"{total:.3f}",
+         "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-threads", "8", "-movflags", "+faststart", args.out],
+        stdin=subprocess.PIPE)
+    parchment = np.array([230, 239, 243], np.float32)
+    frame_bytes = W * H * 3
+    n = 0
+    while True:
+        buf = dec.stdout.read(frame_bytes)
+        if len(buf) < frame_bytes:
+            break
+        t = n / FPS
+        n += 1
+        if t > total + 0.5:
+            continue
+        frame = np.frombuffer(buf, np.uint8).reshape(H, W, 3)
+        touched = False
+        if timecode:
+            y0_, y1_, x0_, x1_ = timecode
+            frame, touched = frame.copy(), True
+            frame[y0_:y1_, x0_:x1_] = frame[2 * y0_ - y1_:y0_, x0_:x1_]
+        for c in callouts:
+            a = window_alpha(t, c["start"], c["end"], CALLOUT_FADE)
+            if a > 0:
+                if not touched:
+                    frame, touched = frame.copy(), True
+                blend(frame, c["bgr"], c["alpha"] * a, c["x"], c["y"])
+        x, y, w = camera_at(moves, t)
+        if w < W - 0.5:
+            z = W / w
+            before = frame
+            frame = cv2.warpAffine(frame, np.float32([[z, 0, -x * z], [0, z, -y * z]]), (W, H), flags=cv2.INTER_CUBIC)
+            touched = True
+            if burned_captions:
+                keep_caption(before, frame)
+        for p in pips:
+            a = window_alpha(t, p["start"], p["end"], PIP_FADE)
+            if a <= 0:
+                continue
+            if not touched:
+                frame, touched = frame.copy(), True
+            (cx, cy, cw, ch), (iw, ih), (px_, py_) = p["crop"], p["size"], p["pos"]
+            zi = iw / cw
+            inset = cv2.warpAffine(frame, np.float32([[zi, 0, -cx * zi], [0, ih / ch, -cy * ih / ch]]), (iw, ih), flags=cv2.INTER_CUBIC)
+            outer, inner, shadow, pad = p["layers"]
+            dy = int(round((1 - a) * 18))
+            blend(frame, np.zeros(3, np.float32), shadow * a, px_ - pad, py_ - pad + dy)
+            blend(frame, parchment, outer * a, px_, py_ + dy)
+            blend(frame, inset, inner * a, px_, py_ + dy)
+        enc.stdin.write(frame.tobytes() if touched else buf)
+    enc.stdin.close()
+    dec.wait()
+    if enc.wait() != 0:
+        sys.exit("ffmpeg could not encode the video")
+
+    # 7. The plan beside the video, and stills of each effect for a check.
+    plan = {
+        "duration": total, "offset": offset, "cuts": [(a, b, w) for a, b, w in cuts],
+        "shots": [{"in": s_["in"], "out": s_["out"], "labels": [k_["label"] for k_ in s_["keys"]],
+                   "zoom": round(W / min(k_["rect"][2] for k_ in s_["keys"]), 2)} for s_ in shots],
+        "pips": [{"start": p["start"], "end": p["end"], "label": p["label"], "corner": p["pos"]} for p in pips],
+        "cards": [{"kind": c["kind"], "title": c["title"], "start": c["start"], "end": c["end"]} for c in cards],
+        "lowerThirds": [{"title": c["title"], "start": c["start"], "end": c["end"]} for c in lts],
+        "callouts": [{"label": c["label"], "start": c["start"], "end": c["end"]} for c in callouts],
+    }
+    json.dump(plan, open(args.plan or os.path.splitext(args.out)[0] + ".plan.json", "w"), indent=1)
+    if args.stills:
+        os.makedirs(args.stills, exist_ok=True)
+        stem = os.path.splitext(os.path.basename(args.out))[0]
+        shots_at = [("zoom", (s_["in"] + s_["out"]) / 2) for s_ in shots]
+        shots_at += [("pip", (p["start"] + p["end"]) / 2) for p in pips]
+        shots_at += [("callout", (c["start"] + c["end"]) / 2) for c in callouts]
+        shots_at += [("card", c["start"] + 1.5) for c in cards[:2]]
+        for i, (kind, t) in enumerate(shots_at):
+            subprocess.run(["ffmpeg", "-v", "error", "-y", "-ss", f"{t:.2f}", "-i", args.out, "-frames:v", "1",
+                            os.path.join(args.stills, f"{stem}-{kind}-{i:02d}-{t:05.1f}s.png")], check=True)
+    if args.keep:
+        print(f"overlays and graph kept in {tmp}")
+    else:
+        shutil.rmtree(tmp, ignore_errors=True)
+    print(f"wrote {args.out} ({total:.1f} s): {len(shots)} zooms, {len(pips)} insets, {len(cards)} cards, {len(captions)} captions")
+
+
+if __name__ == "__main__":
+    main()