kinescript 1.1.0__py3-none-any.whl

kinescript/output.py

@@ -0,0 +1,370 @@
+"""Encoding: frames piped to ffmpeg, split across worker processes, audio mixed alongside them."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+
+from . import media
+from .render import Renderer
+from .scene import Scene, load
+
+QUALITY = {  # crf, x264 preset
+    "draft": (30, "ultrafast"),
+    "standard": (20, "veryfast"),
+    "high": (16, "medium"),
+}
+
+
+def _video_args(fmt: str, quality: str, fps: float, threads: int = 0) -> list[str]:
+    crf, preset = QUALITY.get(quality, QUALITY["standard"])
+    # Each worker runs its own encoder; left to auto-threading, eight of them oversubscribe the CPU.
+    thr = ["-threads", str(threads)] if threads else []
+    if fmt == "mov":  # ProRes 4444 with alpha, for compositing in an NLE
+        return ["-c:v", "prores_ks", "-profile:v", "4444", "-pix_fmt", "yuva444p10le", "-vendor", "apl0", *thr]
+    if fmt == "webm":
+        return ["-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "0", "-crf", str(crf + 10),
+                "-row-mt", "1", "-deadline", "realtime" if quality == "draft" else "good", "-cpu-used", "4", *thr]
+    if fmt == "gif":  # intermediate for the palette pass; a near-lossless one keeps grain and doubles the GIF
+        return ["-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-pix_fmt", "yuv420p", *thr]
+    # x264's own GOP defaults (keyint 250, 3 B-frames, scene-cut keyframes): same PSNR as -g 2s -bf 2
+    # in 10-12% fewer bytes on the examples.
+    return ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", *thr]
+
+
+# HD video is BT.709. Untagged files are read as 709 by browsers and players, but ffmpeg's default
+# RGB->YUV matrix is BT.601, which shifts saturated colours; so convert with 709 and say so.
+# The tags go on the frames (setparams): ffmpeg 8 drops -color_primaries / -color_trc output options
+# when the frames themselves say "unknown".
+TAG_709 = "setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv"
+TO_709 = "scale=out_color_matrix=bt709:out_range=tv"
+
+
+def _encoder(path: str, w: int, h: int, fps: float, fmt: str, quality: str, threads: int = 0, yuv: bool = False):
+    """yuv: frames arrive as BT.709 I420 (Renderer.frame_i420) and pass to the encoder unconverted."""
+    pix, vf = ("yuv420p", TAG_709) if yuv else ("rgba", f"{TO_709},{TAG_709}")
+    cmd = [media.FFMPEG, "-y", "-v", "error", "-f", "rawvideo", "-pix_fmt", pix, "-s", f"{w}x{h}",
+           "-r", f"{fps}", "-i", "-", "-vf", vf, *_video_args(fmt, quality, fps, threads), "-an", path]
+    # stderr goes to a file: a pipe nobody reads until the end can fill and stall the encoder.
+    log = tempfile.TemporaryFile()
+    return subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=log, creationflags=media._NOWIN), log
+
+
+def _render_range(args) -> dict:
+    spec, base, start, end, path, fmt, quality, scale, transparent, threads = args
+    scene = Scene(spec, base)
+    if transparent:
+        scene.bg = None
+    r = Renderer(scene, scale=scale, even=fmt in ("mp4", "webm", "gif"))
+    yuv = r.yuv and fmt in ("mp4", "gif")
+    enc, log = _encoder(path, r.w, r.h, scene.fps, fmt, quality, threads, yuv)
+    grab = r.frame_i420 if yuv else r.frame
+    t0 = time.perf_counter()
+    try:
+        for n in range(start, end):
+            enc.stdin.write(grab(n).data)  # type: ignore[union-attr]
+    except BrokenPipeError:
+        pass  # ffmpeg quit early; its own message is reported below
+    finally:
+        scene.close()
+        try:
+            enc.stdin.close()  # type: ignore[union-attr]
+        except OSError:
+            pass
+        enc.wait()
+        log.seek(0)
+        err = log.read().decode(errors="replace")
+        log.close()
+    if enc.returncode:
+        raise RuntimeError(f"ffmpeg failed on frames {start}-{end}: {err.strip()[:400]}")
+    return {"frames": end - start, "seconds": time.perf_counter() - t0}
+
+
+def _audio_inputs(scene: Scene) -> list[dict]:
+    """Every audible source as {src, at, trim0, trim1, gain_db, fade_in, fade_out, speed}."""
+    out = []
+    for layer in scene.all_layers():
+        if layer.type != "video" or not layer.src:
+            continue
+        vol = layer.raw.get("volume", 1)
+        if not vol or not media.probe(layer.src)["audio"]:
+            continue
+        trim = layer.raw.get("trim") or [0, None]
+        speed = float(layer.raw.get("speed", 1))
+        fi = layer.enter.dur if layer.enter else 0
+        fo = layer.exit.dur if layer.exit else 0
+        out.append(dict(src=layer.src, at=layer.t_in, trim0=float(trim[0]), dur=layer.dur * speed, gain=float(vol),
+                        fade_in=fi, fade_out=fo, speed=speed))
+    for a in scene.audio:
+        src = scene.path(a["src"])
+        at = scene.timeline._time(a.get("at", 0), "audio", 0.0)
+        trim = a.get("trim") or [0, None]
+        total = media.probe(src)["duration"]
+        end = trim[1] if len(trim) > 1 and trim[1] is not None else total
+        dur = min(end - trim[0], scene.duration - at)
+        gain = 10 ** (float(a.get("gain", 0)) / 20) if "gain" in a else float(a.get("volume", 1))
+        out.append(dict(src=src, at=at, trim0=float(trim[0]), dur=max(0.01, dur), gain=gain,
+                        fade_in=float(a.get("fadeIn", 0)), fade_out=float(a.get("fadeOut", 0)), speed=1.0))
+    return out
+
+
+def _copy(video_in: list[str], out: str):
+    """Write the video input (one segment, or the concat list of several) to out without re-encoding."""
+    if video_in[0] == "-i":
+        shutil.move(video_in[1], out)
+        return
+    res = subprocess.run([media.FFMPEG, "-y", "-v", "error", *video_in, "-c", "copy", out], capture_output=True,
+                         text=True, creationflags=media._NOWIN)
+    if res.returncode:
+        raise RuntimeError(f"concat failed: {res.stderr.strip()[:400]}")
+
+
+def _start_audio(scene: Scene, out: str):
+    """Start mixing the scene's audio to an AAC file `out`, in its own ffmpeg process so it runs while the
+    frames render; it took 0.7 s of the launch video's 3.8 s when it ran after them. None if silent."""
+    ins = _audio_inputs(scene)
+    if not ins:
+        return None
+    cmd = [media.FFMPEG, "-y", "-v", "error"]
+    chains = []
+    for k, a in enumerate(ins):
+        cmd += ["-i", a["src"]]
+        f = [f"atrim=start={a['trim0']:.4f}:duration={a['dur']:.4f}", "asetpts=PTS-STARTPTS"]
+        if a["speed"] != 1:
+            f.append(f"atempo={max(0.5, min(2.0, a['speed'])):.4f}")
+        if a["fade_in"]:
+            f.append(f"afade=t=in:d={a['fade_in']:.3f}")
+        if a["fade_out"]:
+            f.append(f"afade=t=out:st={max(0, a['dur'] / a['speed'] - a['fade_out']):.3f}:d={a['fade_out']:.3f}")
+        f.append(f"volume={a['gain']:.4f}")
+        ms = int(round(a["at"] * 1000))
+        f.append(f"adelay={ms}|{ms}")
+        chains.append(f"[{k}:a]{','.join(f)}[a{k}]")
+    mix = "".join(f"[a{k}]" for k in range(len(ins)))
+    graph = ";".join(chains) + f";{mix}amix=inputs={len(ins)}:normalize=0:dropout_transition=0,alimiter=limit=0.95,atrim=duration={scene.duration:.4f}[aout]"
+    cmd += ["-filter_complex", graph, "-map", "[aout]", "-c:a", "aac", "-b:a", "192k", out]
+    log = tempfile.TemporaryFile()  # as in _encoder: an unread stderr pipe can stall ffmpeg
+    return subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stderr=log, creationflags=media._NOWIN), log, out
+
+
+def _mux(video_in: list[str], audio, out: str):
+    """Put the mixed audio under the video, both copied; the segments are joined on the way when video_in
+    is a concat list."""
+    proc, log, path = audio
+    proc.wait()
+    log.seek(0)
+    err = log.read().decode(errors="replace")
+    log.close()
+    if proc.returncode:
+        raise RuntimeError(f"audio mix failed: {err.strip()[:400]}")
+    res = subprocess.run([media.FFMPEG, "-y", "-v", "error", *video_in, "-i", path, "-map", "0:v", "-map", "1:a",
+                          "-c", "copy", "-shortest", out], capture_output=True, text=True, creationflags=media._NOWIN)
+    if res.returncode:
+        raise RuntimeError(f"audio mux failed: {res.stderr.strip()[:400]}")
+
+
+def render(src, out: str, quality: str = "standard", workers: int | None = None, scale: float = 1.0,
+           start: float | None = None, end: float | None = None, transparent: bool = False) -> dict:
+    """Render a scene to a file. Format from the extension: .mp4, .mov (ProRes 4444 alpha), .webm (VP9 alpha),
+    .gif, or a directory / pattern ending in .png for a frame sequence."""
+    scene = load(src)
+    spec, base = scene.spec, str(scene.base.resolve())  # warm workers keep the directory they started in
+    fps = scene.fps
+    f0 = 0 if start is None else max(0, int(round(start * fps)))
+    f1 = scene.frames if end is None else min(scene.frames, int(round(end * fps)))
+    if f1 <= f0:
+        raise ValueError("nothing to render: end is before start")
+    out_p = Path(out)
+    ext = out_p.suffix.lower()
+    t0 = time.perf_counter()
+    if ext == ".png" or out.endswith(("/", "\\")):
+        return _render_pngs(scene, out_p, f0, f1, scale, transparent)
+    fmt = {".mov": "mov", ".webm": "webm", ".gif": "gif"}.get(ext, "mp4")
+    transparent = transparent or fmt in ("mov", "webm") and spec.get("canvas", {}).get("bg") in (None, "transparent")
+    if fmt == "gif":  # render no larger than the GIF will be (long side GIF_SIDE), not full size then shrink
+        scale = min(scale, GIF_SIDE / max(scene.w, scene.h))
+    n = f1 - f0
+    cpu = os.cpu_count() or 4
+    workers = workers or _workers(scene, n, cpu, fmt)
+    threads = max(1, cpu // workers)
+    tmp = Path(tempfile.mkdtemp(prefix="kine-"))
+    audio = None
+    mix = fmt == "mp4" and start is None and end is None
+    try:
+        seg_ext = ".mov" if fmt == "mov" else ".webm" if fmt == "webm" else ".mp4"
+        bounds = [f0 + n * k // workers for k in range(workers + 1)]
+        jobs = [(spec, base, bounds[k], bounds[k + 1], str(tmp / f"seg{k:03d}{seg_ext}"), fmt, quality, scale,
+                 transparent, threads)
+                for k in range(workers) if bounds[k + 1] > bounds[k]]
+        if len(jobs) == 1:
+            audio = _start_audio(scene, str(tmp / "audio.m4a")) if mix else None
+            stats = [_render_range(jobs[0])]
+        else:
+            ex, failed = _pool(len(jobs)), True
+            try:
+                pending = ex.map(_render_range, jobs)  # submitted now; the audio mix starts behind them
+                audio = _start_audio(scene, str(tmp / "audio.m4a")) if mix else None
+                stats = list(pending)
+                failed = False
+            finally:
+                _rest(failed)
+        if len(jobs) == 1:
+            video_in = ["-i", jobs[0][4]]
+        else:
+            listing = tmp / "list.txt"
+            listing.write_text("".join(f"file '{j[4]}'\n" for j in jobs))
+            video_in = ["-f", "concat", "-safe", "0", "-i", str(listing)]
+        out_p.parent.mkdir(parents=True, exist_ok=True)
+        final = str(tmp / f"final{seg_ext}")
+        if ext == ".gif":
+            _to_gif(video_in, str(out_p), fps)
+        elif audio:
+            _mux(video_in, audio, final)
+        else:
+            _copy(video_in, final)
+        if ext != ".gif":
+            shutil.move(final, str(out_p))
+    finally:
+        if audio and audio[0].poll() is None:  # the frames failed while the mix was still running
+            audio[0].kill()
+            audio[0].wait()
+        if audio:
+            audio[1].close()
+        shutil.rmtree(tmp, ignore_errors=True)
+        scene.close()
+    wall = time.perf_counter() - t0
+    w, h = max(2, round(scene.w * scale)), max(2, round(scene.h * scale))
+    if fmt in ("mp4", "webm", "gif"):
+        w, h = w - w % 2, h - h % 2
+    return {"out": str(out_p), "w": w, "h": h, "fps": min(fps, GIF_FPS) if fmt == "gif" else fps, "frames": n,
+            "seconds": round(n / fps, 3), "wall": round(wall, 2), "fps_rendered": round(n / wall, 1),
+            "workers": len(jobs), "size_mb": round(out_p.stat().st_size / 1e6, 2) if out_p.exists() else None}
+
+
+# Render processes stay up for WARM seconds after a render, so the next one in the same process (the MCP
+# server, a script rendering several scenes) skips starting them: each imports Skia and opens a GL context.
+# Repeat renders of examples/model.json took 1.7 s instead of 2.45 s, the launch video 2.2 s instead of
+# 2.6 s (2026-10-30). What they cache is keyed on file versions (media, models) or on parameters (meshes,
+# eases, colours), so nothing they keep goes stale. 0 shuts them down at the end of each render.
+WARM = 120.0
+_POOL: dict = {"busy": 0, "gen": 0}
+_POOL_LOCK = threading.Lock()
+
+
+def _pool(n: int) -> ProcessPoolExecutor:
+    """The warm pool, new when it has fewer than n processes or KINE_BACKEND changed since it started."""
+    key = os.environ.get("KINE_BACKEND", "")
+    with _POOL_LOCK:
+        if "ex" in _POOL and (_POOL["key"] != key or _POOL["size"] < n):
+            _drop()
+        if "ex" not in _POOL:
+            _POOL.update(ex=ProcessPoolExecutor(max_workers=n), key=key, size=n)
+        _POOL["busy"] += 1
+        _POOL["gen"] += 1
+        return _POOL["ex"]
+
+
+def _rest(failed: bool):
+    """After a render: a failed pool shuts down now (its other jobs finish first), an idle one after WARM s."""
+    with _POOL_LOCK:
+        _POOL["busy"] -= 1
+        if failed or WARM <= 0:
+            _drop()
+            return
+        gen = _POOL["gen"]
+    t = threading.Timer(WARM, _idle, (gen,))
+    t.daemon = True
+    t.start()
+
+
+def _idle(gen: int):
+    with _POOL_LOCK:
+        if _POOL["gen"] == gen and not _POOL["busy"]:
+            _drop()
+
+
+def _drop():
+    ex = _POOL.pop("ex", None)
+    if ex is not None:
+        ex.shutdown(wait=True, cancel_futures=True)
+
+
+def _workers(scene: Scene, frames: int, cpu: int, fmt: str = "mp4") -> int:
+    """Render processes for a render. On the GPU every process opens its own GL context on the same
+    GPU and its own video decoders, so past a few they slow each other down. Measured on a 20-thread
+    CPU with one GPU (2026-10-29): 1038 vector frames were fastest with 4-6 workers (3.2 s against
+    4.8 s with one); 126 frames, and 312 frames with two video layers, were fastest with one. The
+    raster (CPU) backend is bound by the CPU and keeps one worker per 1.5 s of frames. VP9 and
+    ProRes encode slower than the GPU draws, so .webm/.mov take up to 4 workers, one per 60 frames
+    (1038-frame promo as .webm: 18.7 s with one worker, 10.9 s with four, 11.3 s with eight)."""
+    from .render import gpu_context
+    if fmt in ("webm", "mov"):
+        return max(1, min(4, frames // 60))
+    if gpu_context() is None:
+        return max(1, min(cpu - 1, 8, frames // int(scene.fps * 1.5) or 1))
+    layers = list(scene.all_layers())
+    if any(L.type == "model" for L in layers):
+        # Model frames spend their time in numpy and in building Skia's vertex lists, not on the GPU,
+        # so they spread over processes: examples/model.json (180 frames, ~11k triangles drawn a
+        # frame) took 4.2 s with one worker, 2.3 s with six and 2.2 s with eight (2026-10-30).
+        return max(1, min(6, frames // 30))
+    video = any(L.type in ("video", "sequence") for L in layers)
+    return max(1, min(4, frames // (500 if video else 250)))
+
+
+GIF_SIDE, GIF_FPS = 720, 15  # a 6 s portrait GIF at full width and 20 fps ran past 10 MB
+
+
+def _to_gif(video_in: list[str], out: str, fps: float):
+    gfps = min(fps, GIF_FPS)
+    # 128 colours with ordered dither and changed-rectangle updates: about half the size of error
+    # diffusion on moving gradients (6.6 -> 3.5 MB on a 6 s portrait clip) with no visible loss.
+    vf = (f"scale=in_color_matrix=bt709:in_range=tv,format=rgb24,fps={gfps},split[a][b];[a]palettegen=stats_mode=diff:max_colors=128[p];"
+          "[b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle")
+    res = subprocess.run([media.FFMPEG, "-y", "-v", "error", *video_in, "-vf", vf, out], capture_output=True, text=True,
+                         creationflags=media._NOWIN)
+    if res.returncode:
+        raise RuntimeError(f"gif failed: {res.stderr.strip()[:400]}")
+
+
+def _render_pngs(scene: Scene, out: Path, f0: int, f1: int, scale: float, transparent: bool) -> dict:
+    import skia
+    if transparent:
+        scene.bg = None
+    folder = out if out.suffix.lower() != ".png" else out.parent
+    stem = "frame" if out.suffix.lower() != ".png" else out.stem
+    folder.mkdir(parents=True, exist_ok=True)
+    r = Renderer(scene, scale=scale)
+    t0 = time.perf_counter()
+    for n in range(f0, f1):
+        r.frame(n)
+        r.snapshot().save(str(folder / f"{stem}_{n:05d}.png"), skia.kPNG)
+    scene.close()
+    return {"out": str(folder), "frames": f1 - f0, "wall": round(time.perf_counter() - t0, 2)}
+
+
+def still(src, at, out: str, scale: float = 1.0) -> dict:
+    """One frame to PNG/JPG. `at` is seconds, negative seconds from the end, or "end" (the last frame)."""
+    import skia
+    scene = load(src)
+    if str(at).strip().lower() == "end":
+        n = scene.frames - 1
+    else:
+        t = float(at)
+        n = int(round((scene.duration + t if t < 0 else t) * scene.fps))
+    n = max(0, min(scene.frames - 1, n))
+    r = Renderer(scene, scale=scale)
+    r.frame(n)
+    r.snapshot().save(out, skia.kPNG if out.lower().endswith(".png") else skia.kJPEG)
+    scene.close()
+    return {"out": out, "frame": n, "at": round(n / scene.fps, 3), "w": r.w, "h": r.h}
+
+
+def dump_json(obj) -> str:
+    return json.dumps(obj, indent=2, ensure_ascii=False)

kinescript/presets.py

@@ -0,0 +1,170 @@
+"""Enter/exit motions. "enter": "rise", "rise+blur", or {"name": "pop", "dur": 0.4, "ease": "outBack"}.
+
+Each preset maps progress p (0 = absent, 1 = fully present) onto modifiers that the
+renderer composes with the layer's own properties.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from . import ease as E
+
+
+@dataclass
+class Mods:
+    alpha: float = 1.0
+    dx: float = 0.0
+    dy: float = 0.0
+    scale: float = 1.0
+    rotate: float = 0.0
+    blur: float = 0.0
+    reveal: float = 1.0      # typewriter / draw-on / wipe amount
+    wipe: str = ""           # direction when a wipe is active
+    track: float = 0.0       # extra letter spacing (px)
+    rx: float = 0.0          # added to rotateX, rotateY (degrees) and z (px)
+    ry: float = 0.0
+    dz: float = 0.0
+
+    def combine(self, o: "Mods") -> "Mods":
+        return Mods(self.alpha * o.alpha, self.dx + o.dx, self.dy + o.dy, self.scale * o.scale,
+                    self.rotate + o.rotate, self.blur + o.blur, min(self.reveal, o.reveal),
+                    o.wipe or self.wipe, self.track + o.track, self.rx + o.rx, self.ry + o.ry, self.dz + o.dz)
+
+
+IDENT = Mods()
+
+
+def _fade(p, o):
+    return Mods(alpha=p)
+
+
+def _move(dx, dy):
+    def f(p, o):
+        dist = o.get("dist", 48)
+        return Mods(alpha=min(1.0, p * 1.6), dx=(1 - p) * dist * dx, dy=(1 - p) * dist * dy)
+    return f
+
+
+def _pop(p, o):
+    return Mods(alpha=min(1.0, p * 2), scale=o.get("from", 0.4) + (1 - o.get("from", 0.4)) * p)
+
+
+def _zoom(p, o):
+    return Mods(alpha=p, scale=o.get("from", 1.25) + (1 - o.get("from", 1.25)) * p)
+
+
+def _blur(p, o):
+    return Mods(alpha=p, blur=(1 - p) * o.get("amount", 24))
+
+
+def _spin(p, o):
+    return Mods(alpha=p, rotate=(1 - p) * o.get("deg", -90), scale=0.6 + 0.4 * p)
+
+
+def _wipe(direction):
+    return lambda p, o: Mods(reveal=p, wipe=direction)
+
+
+def _reveal(p, o):
+    return Mods(reveal=p)
+
+
+def _snap(p, o):
+    """Hard cut in: visible within the first fifth, settling from a slight overscale. No blur."""
+    return Mods(alpha=1.0 if p >= 0.2 else p / 0.2, scale=1 + (1 - p) * o.get("amount", 0.06))
+
+
+def _track(p, o):
+    return Mods(alpha=p, track=(1 - p) * o.get("amount", 40))
+
+
+def _flip(p, o):
+    return Mods(alpha=min(1.0, p * 4), ry=(1 - p) * o.get("deg", 90))
+
+
+def _flip_up(p, o):
+    return Mods(alpha=min(1.0, p * 4), rx=(1 - p) * o.get("deg", 90))
+
+
+def _tumble(p, o):
+    return Mods(alpha=min(1.0, p * 2), rx=(1 - p) * -70, ry=(1 - p) * o.get("deg", 160),
+                dz=(1 - p) * -o.get("dist", 400))
+
+
+def _push(p, o):
+    return Mods(alpha=p, dz=(1 - p) * -o.get("dist", 600))
+
+
+PRESETS = {
+    "none": lambda p, o: IDENT, "fade": _fade,
+    "rise": _move(0, 1), "drop": _move(0, -1), "left": _move(1, 0), "right": _move(-1, 0),
+    "slide-up": _move(0, 1), "slide-down": _move(0, -1),
+    "pop": _pop, "zoom": _zoom, "blur": _blur, "spin": _spin, "track": _track,
+    "wipe": _wipe("right"), "wipe-right": _wipe("right"), "wipe-left": _wipe("left"),
+    "wipe-up": _wipe("up"), "wipe-down": _wipe("down"),
+    "type": _reveal, "draw": _reveal, "snap": _snap,
+    "flip": _flip, "flip-up": _flip_up, "tumble": _tumble, "push": _push,
+}
+# Motions that turn or move a layer in depth; a scene using one gets a camera.
+DEPTH = {"flip", "flip-up", "tumble", "push"}
+DEFAULT_EASE = {"pop": "outBack", "spin": "outBack", "type": "linear", "draw": "inOutCubic", "snap": "outQuart",
+                "flip": "outBack", "flip-up": "outBack"}
+
+
+# Names other tools use for the same motions. Keys are lower case without dashes.
+ALIASES = {"typewriter": "type", "typing": "type", "slide": "left", "scale": "pop", "grow": "pop", "bounce": "pop",
+           "appear": "snap", "cut": "snap", "dissolve": "fade", "opacity": "fade", "up": "rise", "riseup": "rise",
+           "down": "drop", "fall": "drop", "blurin": "blur", "focus": "blur", "rotate": "spin", "reveal": "wipe",
+           "write": "draw", "stroke": "draw", "build": "draw", "assemble": "draw", "letterspacing": "track", "tracking": "track",
+           "flipy": "flip", "flipx": "flip-up", "rotatey": "flip", "rotatex": "flip-up", "dolly": "push",
+           "fly": "push"}
+
+
+def canonical(name: str) -> str | None:
+    """'fadeIn' -> 'fade', 'slideUp' -> 'slide-up', 'typewriter' -> 'type'; None when nothing fits."""
+    if name in PRESETS:
+        return name
+    s = re.sub(r"(?<=[a-z])(?=[A-Z])", "-", str(name).strip()).lower().replace("_", "-").replace(" ", "-")
+    for cand in (s, re.sub(r"-?(in|out)$", "", s)):
+        if cand in PRESETS:
+            return cand
+        sq = cand.replace("-", "")
+        if sq in ALIASES:
+            return ALIASES[sq]
+        for p in PRESETS:
+            if p.replace("-", "") == sq:
+                return p
+    return None
+
+
+@dataclass
+class Motion:
+    names: list[str]
+    dur: float = 0.5
+    ease: str = ""
+    stagger: float = 0.0
+    opts: dict = field(default_factory=dict)
+
+    def mods(self, p: float) -> Mods:
+        out = IDENT
+        for n in self.names:
+            e = E.get(self.ease or DEFAULT_EASE.get(n, "outCubic"))
+            out = out.combine(PRESETS[n](e(max(0.0, min(1.0, p))), self.opts))
+        return out
+
+
+def parse(spec, default_dur: float = 0.5) -> Motion | None:
+    if not spec:
+        return None
+    if isinstance(spec, str):
+        spec = {"name": spec}
+    names = []
+    for n in (n.strip() for n in str(spec.get("name", "fade")).split("+") if n.strip()):
+        c = canonical(n)
+        if c is None:
+            from .schema import unknown
+            raise ValueError(unknown("motion", n, PRESETS))
+        names.append(c)
+    opts = {k: v for k, v in spec.items() if k not in ("name", "dur", "ease", "stagger")}
+    return Motion(names, float(spec.get("dur", default_dur)), spec.get("ease", ""), float(spec.get("stagger", 0)), opts)