Skip to content

Motion films that never cut to the next slide: every beat grows out of the one before, one continuous camera, continuity measured by an oracle. Product launch films and feature demos, made with a coding agent.

9.4 KB
Raw Blame
#!/usr/bin/env python3
# onetake · © 2026 Patrick (github.com/feitangyuan) · PolyForm Noncommercial 1.0.0 · lineage otk-7f3e1c
"""analyze_ref.py — read a reference clip in numbers before composing anything.

  python3 scripts/analyze_ref.py ref.mp4 --out ana/
  python3 scripts/analyze_ref.py ref.mp4 --out ana/ --no-flow      # rhythm only

Writes into --out:
  energy.txt      one char per 1/12 s (' .:-=+*#%@'), rows of 4 s — where the film rests and where it hits
  summary.json    duration, stillness ratios, cut times, burst windows, longest quiet stretch, and "flow"
  sheet_NN.png    contact sheets at 4 fps, 24 frames each (6×4)
  frame_NN.png    9 full frames spread across the clip

The energy map says WHEN things move. "flow" (optical flow at 30 fps — or the source's own rate if slower, so a
24 fps clip is not padded with repeated frames — 320 px wide) says HOW: the dominant speed per frame (median flow
over moving edges, px per 1/30 s normalised to 1920 wide), the moves cut from it with their t80
(share of the move's duration before 80 % of its travel is done — .23 is an expo snap, .67 a symmetric S-curve),
and whether fast frames are smeared along their motion. Smear = gradient energy along the motion / across it, on
the pixels that changed: < .78 is shutter blur (render.py's 180° shutter: a linear test move .64, Pocket Weather v3
.69); sharp renders read ~.9 or more (the test move unblurred .99, v3 as drafted 1.07, motion-web .88 — its CSS
blur() on fly-throughs is not motion blur). It is a fingerprint of the dominant motion, not a per-element track:
speed reads up to ~30 % low on fast small objects (a 100 px box at 167 px/frame reads 121–155). probe.py measures
a composition exactly.

Then write the beat sheet (references/reference-deconstruction.md). Also works on your own render:
`verify_promo.py` prints the same map next to the reference's.
"""
import argparse, glob, json, math, os, shutil, subprocess
import numpy as np
from PIL import Image

CHARS = " .:-=+*#%@"
SMEAR_BLUR = 0.78   # fast frames smeared below this were rendered with motion blur

def energy(video, workdir, fps=12, width=320):
    d = os.path.join(workdir, "_e"); shutil.rmtree(d, ignore_errors=True); os.makedirs(d)
    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", video, "-vf", f"fps={fps},scale={width}:-1", f"{d}/f_%05d.png"], check=True)
    prev = None; diffs = []
    for f in sorted(glob.glob(f"{d}/f_*.png")):
        a = np.asarray(Image.open(f).convert("L"), dtype=np.float32)
        diffs.append(0.0 if prev is None else float(np.abs(a - prev).mean())); prev = a
    shutil.rmtree(d, ignore_errors=True)
    return np.array(diffs), fps

def energy_map(d, fps, row_s=4):
    per = fps * row_s; lines = []
    for r in range(0, len(d), per):
        lines.append(f"{r/fps:5.1f}s |" + "".join(CHARS[min(9, int(v / 3))] for v in d[r:r + per]) + "|")
    return "\n".join(lines)

def stats(d, fps, cut_thr=18.0, still_thr=0.5, low_thr=2.0):
    cuts = [round(i / fps, 2) for i in range(1, len(d)) if d[i] > cut_thr]
    # bursts: windows of 1.5 s holding >= 3 big changes (> 8)
    big = [i for i in range(len(d)) if d[i] > 8]; bursts = []
    for i in big:
        win = [j for j in big if i <= j < i + int(1.5 * fps)]
        if len(win) >= 3 and (not bursts or i / fps > bursts[-1][1]): bursts.append((round(i / fps, 2), round(win[-1] / fps, 2)))
    # longest quiet stretch (below low_thr)
    best = cur = 0
    for v in d:
        cur = cur + 1 if v < low_thr else 0; best = max(best, cur)
    return {"duration_s": round(len(d) / fps, 2), "still_ratio": round(float((d < still_thr).mean()), 3),
            "low_ratio": round(float((d < low_thr).mean()), 3), "cuts": cuts, "bursts": bursts,
            "longest_quiet_s": round(best / fps, 2), "mean_energy": round(float(d.mean()), 3)}

def flow(video, fps=30, width=320, fast=24.0, vmin=2.0):
    try:
        import cv2
    except ImportError:
        return None
    wh = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,avg_frame_rate", "-of", "csv=p=0", video], capture_output=True, text=True).stdout.strip().split(",")
    h = int(round(int(wh[1]) * width / int(wh[0]) / 2) * 2)
    num, _, den = wh[2].partition("/")
    src = float(num) / float(den or 1) if float(den or 1) else 0.0
    # Resampling a slower source up to `fps` repeats frames (24 → 30 repeats every 4th): each repeat reads as a
    # zero-flow frame and splits every move in pieces. Sample slower sources at their own rate and rescale speeds
    # to px per 1/fps s, so peak, thresholds and the comparison with a render stay in one unit.
    sfps = src if 0 < src < fps else fps
    raw = subprocess.run(["ffmpeg", "-v", "error", "-i", video, "-vf", f"fps={sfps},scale={width}:{h}", "-f", "rawvideo", "-pix_fmt", "gray", "-"], capture_output=True, check=True).stdout
    frames = np.frombuffer(raw, np.uint8).reshape(-1, h, width)
    dis = cv2.DISOpticalFlow_create(cv2.DISOPTICAL_FLOW_PRESET_MEDIUM)
    norm = 1920.0 / width * sfps / fps
    speed = np.zeros(len(frames)); smear = []
    for i in range(1, len(frames)):
        a, b = frames[i - 1], frames[i]
        f = dis.calc(a, b, None)
        mag = np.hypot(f[..., 0], f[..., 1]); moving = mag > 0.5
        if moving.mean() < 0.002:
            continue
        g = b.astype(np.float32)
        gx = cv2.Sobel(g, cv2.CV_32F, 1, 0, ksize=3); gy = cv2.Sobel(g, cv2.CV_32F, 0, 1, ksize=3)
        edges = moving & (np.hypot(gx, gy) > 20)               # flow is trustworthy where there is an edge to follow
        speed[i] = float(np.median(mag[edges] if edges.sum() > 20 else mag[moving])) * norm
        if speed[i] >= fast:                                   # fast frame: is the changed content smeared along its motion?
            dx, dy = float(np.median(f[..., 0][moving])), float(np.median(f[..., 1][moving])); n = math.hypot(dx, dy)
            changed = moving & (np.abs(b.astype(np.int16) - a.astype(np.int16)) > 12)
            if n > 0.3 and changed.sum() > 20:
                ux, uy = dx / n, dy / n
                e_par = float(((gx * ux + gy * uy)[changed] ** 2).mean()); e_per = float(((-gx * uy + gy * ux)[changed] ** 2).mean())
                if e_per > 1.0:
                    smear.append(e_par / e_per)
    moves, k = [], 1
    while k < len(speed):
        if speed[k] < vmin:
            k += 1; continue
        a = k
        while k < len(speed) and speed[k] >= vmin:
            k += 1
        path = speed[a:k]; L = float(path.sum()) * fps / sfps     # px travelled: speeds are per 1/fps s, frames 1/sfps s apart
        if k - a >= 3 and L >= 40:
            k80 = int(np.searchsorted(np.cumsum(path), 0.8 * path.sum())) + 1
            moves.append({"t0": round(a / sfps, 2), "t1": round(k / sfps, 2), "path": round(L), "t80": round(k80 / (k - a), 2), "peak": round(float(path.max()))})
    total = sum(m["path"] for m in moves)
    med = None
    if moves:
        acc = 0.0
        for m in sorted(moves, key=lambda m: m["t80"]):
            acc += m["path"]
            if acc >= total / 2:
                med = m["t80"]; break
    return {"fps": fps, "sampled_fps": round(sfps, 3), "peak": round(float(speed.max())), "moves": moves, "t80_median": med,
            "soft_share": round(sum(m["path"] for m in moves if m["t80"] >= 0.55) / total, 2) if total else 0.0,
            "fast_frames": len(smear), "smear_median": round(float(np.median(smear)), 2) if smear else None}

def sheets(video, out, fps=4):
    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", video, "-vf", f"fps={fps},scale=426:-1,tile=6x4", f"{out}/sheet_%02d.png"], check=True)
    dur = float(subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", video], capture_output=True, text=True).stdout.strip())
    for i in range(9):
        t = dur * (i + 0.5) / 9
        subprocess.run(["ffmpeg", "-v", "error", "-y", "-ss", f"{t:.2f}", "-i", video, "-frames:v", "1", f"{out}/frame_{i:02d}.png"], check=True)
    return dur

def main():
    ap = argparse.ArgumentParser(); ap.add_argument("video"); ap.add_argument("--out", default="ana"); ap.add_argument("--no-flow", action="store_true"); a = ap.parse_args()
    os.makedirs(a.out, exist_ok=True)
    d, fps = energy(a.video, a.out); m = energy_map(d, fps); s = stats(d, fps)
    fl = None if a.no_flow else flow(a.video)
    if fl: s["flow"] = fl
    open(os.path.join(a.out, "energy.txt"), "w").write(m + "\n" + json.dumps({k: v for k, v in s.items() if k != "flow"}) + "\n")
    json.dump(s, open(os.path.join(a.out, "summary.json"), "w"), indent=1)
    sheets(a.video, a.out)
    print(m); print()
    print(f"still (<0.5): {s['still_ratio']}   low (<2): {s['low_ratio']}   longest quiet: {s['longest_quiet_s']} s")
    print(f"cuts at: {s['cuts']}"); print(f"bursts: {s['bursts']}")
    if fl:
        blur = "no fast frames" if fl["smear_median"] is None else f"smear {fl['smear_median']} over {fl['fast_frames']} fast frames ({'smeared along the motion: shutter blur' if fl['smear_median'] < SMEAR_BLUR else 'sharp: no shutter blur'})"
        med = "—" if fl["t80_median"] is None else fl["t80_median"]
        print(f"motion: peak {fl['peak']} px/frame @{fl['fps']} · {len(fl['moves'])} moves · median t80 {med} · soft curves {fl['soft_share'] * 100:.0f} % of travel · {blur}")
    elif not a.no_flow:
        print("motion: skipped (opencv-python not installed)")
    print(f"\nsheets + frames in {a.out}/ — look at them before writing the beat sheet")

if __name__ == "__main__":
    main()