kinescript 1.1.0__py3-none-any.whl

kinescript/__init__.py

@@ -0,0 +1,6 @@
+"""Kinescript: motion graphics and video edits written as data, checked and rendered by agents."""
+from .output import render, still
+from .scene import Scene, SceneError, load
+
+__version__ = "1.1.0"
+__all__ = ["Scene", "SceneError", "load", "render", "still", "__version__"]

kinescript/cli.py

@@ -0,0 +1,167 @@
+"""kine: command line for Kinescript."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+
+STARTER = {
+    "canvas": {"w": 1920, "h": 1080, "fps": 30, "bg": "#0a0c10"},
+    "grade": {"vignette": 0.3},
+    "layers": [
+        {"id": "bg", "type": "shader", "preset": "mesh", "opacity": 0.35},
+        {"use": "titleCard", "id": "title", "title": "Your **title**", "subtitle": "a line of context",
+         "at": 0.3, "dur": 3.5},
+        {"use": "lowerThird", "id": "who", "title": "Name Surname", "subtitle": "Role", "at": "title.out+0.2", "dur": 3},
+    ],
+}
+
+
+def _emit(obj):
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="kine", description="Kinescript: motion graphics and video edits as data.")
+    ap.add_argument("--version", action="version", version=f"kinescript {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("render", help="render a scene to .mp4/.mov/.webm/.gif or a .png sequence")
+    r.add_argument("scene")
+    r.add_argument("-o", "--out")
+    r.add_argument("-q", "--quality", choices=["draft", "standard", "high"], default="standard")
+    r.add_argument("--scale", type=float, default=1.0, help="resolution multiplier, e.g. 0.5 for a fast preview")
+    r.add_argument("--from", dest="start", type=float)
+    r.add_argument("--to", dest="end", type=float)
+    r.add_argument("-j", "--workers", type=int)
+    r.add_argument("--transparent", action="store_true", help="drop the background (use .mov or .webm)")
+
+    s = sub.add_parser("still", help="render one frame to PNG/JPG")
+    s.add_argument("scene")
+    s.add_argument("--at", required=True, help='seconds; negative counts from the end; "end" is the last frame')
+    s.add_argument("-o", "--out")
+    s.add_argument("--scale", type=float, default=1.0)
+
+    lk = sub.add_parser("look", help="contact sheet: many frames in one image, for review")
+    lk.add_argument("scene")
+    lk.add_argument("-n", "--count", type=int, default=12)
+    lk.add_argument("--cols", type=int)
+    lk.add_argument("--width", type=int, default=480, help="width of each thumbnail")
+    lk.add_argument("--at", type=float, nargs="*", help="explicit times instead of even spacing")
+    lk.add_argument("--boxes", action="store_true", help="outline every layer with its id")
+    lk.add_argument("-o", "--out")
+
+    ck = sub.add_parser("check", help="lint layout, timing, contrast and reading time; prints JSON")
+    ck.add_argument("scene")
+    ck.add_argument("--step", type=float, default=0.25)
+
+    pr = sub.add_parser("probe", help="resolved timeline and layer boxes at --at; or, for a media file, "
+                                      "its duration, size, fps and audio")
+    pr.add_argument("scene")
+    pr.add_argument("--at", type=float)
+
+    sub.add_parser("docs", help="print the scene reference")
+    nw = sub.add_parser("new", help="write a starter scene")
+    nw.add_argument("path", nargs="?", default="scene.json")
+
+    w = sub.add_parser("watch", help="re-render a contact sheet whenever the scene file changes")
+    w.add_argument("scene")
+    w.add_argument("-n", "--count", type=int, default=12)
+
+    sub.add_parser("mcp", help="run the MCP server on stdio")
+    sub.add_parser("doctor", help="report ffmpeg, GPU and font availability")
+
+    a = ap.parse_args(argv)
+    try:
+        return _run(a)
+    except (ValueError, RuntimeError, FileNotFoundError) as e:
+        _emit({"ok": False, "error": str(e)})
+        return 2
+
+
+def _default_out(scene: str, suffix: str) -> str:
+    p = Path(scene)
+    return str(p.with_name(p.stem + suffix))
+
+
+def _run(a) -> int:
+    if a.cmd == "docs":
+        from .docs import reference
+        sys.stdout.write(reference())
+        return 0
+    if a.cmd == "new":
+        p = Path(a.path)
+        if p.exists():
+            raise ValueError(f"{p} exists; pick another name")
+        p.write_text(json.dumps(STARTER, indent=2), encoding="utf-8")
+        _emit({"ok": True, "out": str(p)})
+        return 0
+    if a.cmd == "mcp":
+        from .mcp import serve
+        serve()
+        return 0
+    if a.cmd == "doctor":
+        from . import media
+        from .render import gpu_context, Renderer
+        from .scene import Scene
+        info = {"version": __version__, "ffmpeg": media.FFMPEG, "gpu": gpu_context() is not None}
+        r = Renderer(Scene({"canvas": {"w": 64, "h": 64}, "layers": [{"type": "text", "text": "kine"}]}))
+        info["font"] = r._typeface(r.s.theme["font"], 600, False).getFamilyName()
+        _emit(info)
+        return 0
+    if a.cmd == "render":
+        from . import output
+        from .output import render
+        output.WARM = 0  # one render, then the process exits: shut the workers down inside it, as timed
+        out = a.out or _default_out(a.scene, ".mp4")
+        _emit(dict(ok=True, **render(a.scene, out, a.quality, a.workers, a.scale, a.start, a.end, a.transparent)))
+        return 0
+    if a.cmd == "still":
+        from .output import still
+        at = str(a.at)
+        out = a.out or _default_out(a.scene, f"_{at.lstrip('-')}{'s' if at != 'end' else ''}.png")
+        _emit(dict(ok=True, **still(a.scene, at, out, a.scale)))
+        return 0
+    if a.cmd == "look":
+        from .verify import contact_sheet
+        out = a.out or _default_out(a.scene, "_sheet.png")
+        _emit(dict(ok=True, **contact_sheet(a.scene, out, a.count, a.cols, a.width, a.at, a.boxes)))
+        return 0
+    if a.cmd == "check":
+        from .verify import check
+        res = check(a.scene, a.step)
+        _emit(res)
+        return 0 if res["ok"] else 1
+    if a.cmd == "probe":
+        from .verify import probe
+        if Path(a.scene).suffix.lower() != ".json" and Path(a.scene).exists():
+            from . import media
+            _emit(dict(ok=True, src=a.scene, **media.probe(a.scene)))
+            return 0
+        _emit(probe(a.scene, a.at))
+        return 0
+    if a.cmd == "watch":
+        from .verify import contact_sheet
+        p = Path(a.scene)
+        last = 0.0
+        out = _default_out(a.scene, "_sheet.png")
+        print(f"watching {p} -> {out} (Ctrl+C to stop)", file=sys.stderr)
+        while True:
+            m = p.stat().st_mtime
+            if m != last:
+                last = m
+                try:
+                    contact_sheet(a.scene, out, a.count)
+                    print(f"{time.strftime('%H:%M:%S')} updated", file=sys.stderr)
+                except (ValueError, RuntimeError) as e:
+                    print(f"{time.strftime('%H:%M:%S')} error: {e}", file=sys.stderr)
+            time.sleep(0.5)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kinescript/color.py

@@ -0,0 +1,89 @@
+"""Colour parsing and perceptual (OKLab) interpolation."""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+RGBA = tuple[float, float, float, float]
+
+NAMED = {
+    "black": "#000000", "white": "#ffffff", "transparent": "#00000000", "red": "#ff3b30",
+    "green": "#34c759", "blue": "#0a84ff", "yellow": "#ffd60a", "orange": "#ff9f0a",
+    "gray": "#8e8e93", "grey": "#8e8e93", "purple": "#bf5af2", "pink": "#ff375f", "cyan": "#64d2ff",
+}
+
+
+def is_color(v) -> bool:
+    return isinstance(v, str) and (v.startswith("#") or v.startswith("rgb") or v in NAMED)
+
+
+@lru_cache(maxsize=4096)
+def parse(c: str) -> RGBA:
+    c = NAMED.get(c, c).strip()
+    if c.startswith("#"):
+        h = c[1:]
+        if len(h) in (3, 4):
+            h = "".join(ch * 2 for ch in h)
+        if len(h) == 6:
+            h += "ff"
+        if len(h) != 8:
+            raise ValueError(f"bad colour {c!r}")
+        return tuple(int(h[i:i + 2], 16) / 255 for i in (0, 2, 4, 6))  # type: ignore[return-value]
+    m = re.fullmatch(r"rgba?\(([^)]*)\)", c)
+    if m:
+        parts = [float(p) for p in m.group(1).replace("/", ",").split(",") if p.strip()]
+        r, g, b = (p / 255 for p in parts[:3])
+        a = parts[3] if len(parts) > 3 else 1.0
+        return (r, g, b, a)
+    raise ValueError(f"bad colour {c!r} (use #rrggbb, #rrggbbaa, rgb(), rgba() or a name)")
+
+
+def to_argb_int(c: RGBA, alpha_mul: float = 1.0) -> int:
+    r, g, b, a = c
+    a = max(0.0, min(1.0, a * alpha_mul))
+    return (round(a * 255) << 24) | (round(r * 255) << 16) | (round(g * 255) << 8) | round(b * 255)
+
+
+def _lin(x: float) -> float:
+    return x / 12.92 if x <= 0.04045 else ((x + 0.055) / 1.055) ** 2.4
+
+
+def _gam(x: float) -> float:
+    x = max(0.0, min(1.0, x))
+    return 12.92 * x if x <= 0.0031308 else 1.055 * x ** (1 / 2.4) - 0.055
+
+
+def _to_oklab(c: RGBA):
+    r, g, b = (_lin(v) for v in c[:3])
+    l = (0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b) ** (1 / 3)
+    m = (0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b) ** (1 / 3)
+    s = (0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b) ** (1 / 3)
+    return (0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
+            1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
+            0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s)
+
+
+def _from_oklab(L: float, A: float, B: float):
+    l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3
+    m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3
+    s = (L - 0.0894841775 * A - 1.2914855480 * B) ** 3
+    return (_gam(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+            _gam(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+            _gam(-0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s))
+
+
+def mix(a: RGBA, b: RGBA, t: float) -> RGBA:
+    """Interpolate in OKLab so mid-tones stay vivid instead of going muddy."""
+    la, lb = _to_oklab(a), _to_oklab(b)
+    r, g, bl = _from_oklab(*(x + (y - x) * t for x, y in zip(la, lb)))
+    return (r, g, bl, a[3] + (b[3] - a[3]) * t)
+
+
+def luminance(c: RGBA) -> float:
+    r, g, b = (_lin(v) for v in c[:3])
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast(l1: float, l2: float) -> float:
+    hi, lo = max(l1, l2), min(l1, l2)
+    return (hi + 0.05) / (lo + 0.05)

kinescript/components.py

@@ -0,0 +1,272 @@
+"""Reusable building blocks: {"use": "lowerThird", "title": "...", ...} expands into plain layers.
+
+Scene files may also declare their own under "components" with {{param}} placeholders.
+"""
+from __future__ import annotations
+
+import copy
+import re
+from pathlib import Path
+
+THEME = {
+    # Brand palette ("Kinetic Score"), plus the short names components use.
+    "void": "#0a0c10", "sheet": "#f2f0e8", "track": "#242832", "cue": "#ff633f", "key": "#b9f45d",
+    "annotation": "#9299a8",
+    "ink": "#0a0c10", "paper": "#f2f0e8", "accent": "#ff633f", "accent2": "#b9f45d", "muted": "#9299a8",
+    "font": "Space Grotesk", "mono": "IBM Plex Mono",
+}
+
+
+def _lower_third(p, th):
+    title, sub = p.get("title", "Title"), p.get("subtitle", "")
+    x, y = p.get("x", "6%"), p.get("y", "78%")
+    accent = p.get("accent", th["accent"])
+    plate = p.get("plate", "#0a0c10d0")
+    box = {"fill": plate, "pad": [8, 16], "radius": 6} if plate else None
+    kids = [
+        {"id": f"{p['id']}-bar", "type": "rect", "x": 0, "y": 0, "w": 8, "h": 124 if sub else 72,
+         "anchor": "topleft", "fill": accent, "radius": 4, "enter": {"name": "wipe-down", "dur": 0.35},
+         "exit": {"name": "fade", "dur": 0.3}},
+        {"id": f"{p['id']}-title", "type": "text", "text": title, "x": 28, "y": 0, "anchor": "topleft",
+         "align": "left", "size": p.get("size", 54), "weight": 700, "fill": p.get("color", th["paper"]),
+         "at": 0.12, "enter": {"name": "left", "dur": 0.45, "dist": 30}, "exit": {"name": "fade", "dur": 0.3},
+         "shadow": {"y": 3, "blur": 12, "color": "#00000088"}, "box": box},
+    ]
+    if sub:
+        kids.append({"id": f"{p['id']}-sub", "type": "text", "text": sub, "x": 28, "y": 76, "anchor": "topleft",
+                     "align": "left", "size": round(p.get("size", 54) * 0.55), "weight": 500,
+                     "fill": p.get("subColor", th["muted"]), "at": 0.3,
+                     "enter": {"name": "left", "dur": 0.45, "dist": 20}, "exit": {"name": "fade", "dur": 0.3},
+                     "box": box})
+    return {"type": "group", "x": x, "y": y, "children": kids}
+
+
+def _title_card(p, th):
+    kids = []
+    if p.get("kicker"):
+        kids.append({"id": f"{p['id']}-kicker", "type": "text", "text": p["kicker"], "y": -110, "size": 30,
+                     "weight": 600, "fill": p.get("accent", th["accent"]), "letterSpacing": 6,
+                     "enter": {"name": "track", "dur": 0.8}, "exit": "fade"})
+    kids.append({"id": f"{p['id']}-title", "type": "text", "text": p.get("title", "Title"), "size": p.get("size", 128),
+                 "weight": 800, "fill": p.get("color", th["paper"]), "split": "chars", "at": 0.15,
+                 "enter": {"name": "rise+blur", "dur": 0.6, "stagger": 0.035, "dist": 60},
+                 "exit": {"name": "fade", "dur": 0.4}, "maxWidth": "86%"})
+    if p.get("subtitle"):
+        kids.append({"id": f"{p['id']}-sub", "type": "text", "text": p["subtitle"], "y": 120, "size": 40,
+                     "weight": 400, "fill": th["muted"], "at": 0.6, "enter": "rise", "exit": "fade"})
+    kids.append({"id": f"{p['id']}-rule", "type": "line", "points": [[-160, 0], [160, 0]], "y": 70 if not p.get("subtitle") else 76,
+                 "stroke": p.get("accent", th["accent"]), "strokeWidth": 6, "cap": "round", "at": 0.45,
+                 "enter": {"name": "draw", "dur": 0.7}, "exit": "fade"})
+    return {"type": "group", "x": p.get("x", "50%"), "y": p.get("y", "50%"), "children": kids}
+
+
+def _callout(p, th):
+    r = p.get("r", 60)
+    accent = p.get("accent", th["accent"])
+    side = p.get("side", "right")
+    lx = r + 40 if side == "right" else -(r + 40)
+    kids = [
+        {"id": f"{p['id']}-ring", "type": "circle", "r": r, "stroke": accent, "strokeWidth": 6,
+         "enter": {"name": "draw", "dur": 0.5}, "exit": "fade"},
+        {"id": f"{p['id']}-pulse", "type": "circle", "r": r, "stroke": accent, "strokeWidth": 3,
+         "scale": "=1 + (t % 1.2) / 1.2 * 0.5", "opacity": "=0.8 * (1 - (t % 1.2) / 1.2)", "at": 0.5},
+    ]
+    if p.get("label"):
+        kids.append({"id": f"{p['id']}-label", "type": "text", "text": p["label"], "x": lx, "size": p.get("size", 36),
+                     "weight": 700, "fill": th["ink"], "anchor": "left" if side == "right" else "right",
+                     "align": "left" if side == "right" else "right",
+                     "box": {"fill": p.get("boxColor", th["paper"]), "pad": [14, 22], "radius": 10},
+                     "at": 0.25, "enter": {"name": "pop", "dur": 0.45}, "exit": "fade"})
+    return {"type": "group", "x": p.get("x", "50%"), "y": p.get("y", "50%"), "children": kids}
+
+
+def _focus(p, th):
+    """Highlight a region of footage: dim everything else and draw a frame around it."""
+    x, y, w, h = p.get("x", 0), p.get("y", 0), p.get("w", 400), p.get("h", 300)
+    return {"type": "group", "children": [
+        {"id": f"{p['id']}-frame", "type": "rect", "x": x, "y": y, "w": w, "h": h, "anchor": "topleft",
+         "radius": p.get("radius", 12), "stroke": p.get("accent", th["accent"]), "strokeWidth": 5,
+         "enter": {"name": "draw", "dur": 0.6}, "exit": "fade", "dimOutside": p.get("dim", 0.55)},
+    ]}
+
+
+def _progress(p, th):
+    h = p.get("h", 8)
+    return {"type": "rect", "x": 0, "y": p.get("y", "100%"), "anchor": "bottomleft", "h": h,
+            "w": "=W * p", "fill": p.get("color", th["accent"])}
+
+
+def _kinetic(p, th):
+    """Big words, one after another: {"use": "kinetic", "words": ["Write", "Check", "Render"], "every": 0.6}."""
+    every = float(p.get("every", 0.6))
+    kids = []
+    for i, word in enumerate(p.get("words", [])):
+        kids.append({"id": f"{p['id']}-w{i}", "type": "text", "text": word, "at": round(i * every, 4), "dur": every,
+                     "size": p.get("size", 180), "weight": 900, "fill": p.get("color", th["paper"]),
+                     "enter": {"name": p.get("motion", "pop"), "dur": min(0.35, every * 0.6)},
+                     "exit": {"name": "fade", "dur": min(0.12, every * 0.2)}})
+    return {"type": "group", "x": p.get("x", "50%"), "y": p.get("y", "50%"), "dur": every * len(kids) or 1,
+            "children": kids}
+
+
+# Parameters a builder reads only in some branches (so a single call may not touch them).
+PARAMS = {"lowerThird": ("title", "subtitle", "x", "y", "accent", "size", "plate", "color", "subColor"),
+          "titleCard": ("title", "subtitle", "kicker", "size", "accent", "color", "x", "y"),
+          "callout": ("x", "y", "r", "label", "side", "accent", "size", "boxColor"),
+          "focus": ("x", "y", "w", "h", "dim", "accent", "radius"),
+          "progress": ("color", "h", "y"),
+          "kinetic": ("words", "every", "size", "motion", "color", "x", "y")}
+
+BUILTIN = {"lowerThird": _lower_third, "titleCard": _title_card, "callout": _callout, "focus": _focus,
+           "progress": _progress, "kinetic": _kinetic}
+COMPONENT_DOCS = {
+    "lowerThird": "title, subtitle, x [\"6%\"], y [\"78%\"] (top-left of its accent bar), accent, size [54], "
+                  "color, subColor, plate (box colour, or false for none)",
+    "titleCard": "title, subtitle, kicker (small line above), x, y [\"50%\"] (centre), size [128], accent, color",
+    "callout": "x, y (centre of the ring), r [60], label, side [right] (left|right), accent, size, boxColor",
+    "focus": "x, y, w, h (top-left and size of the region to highlight), dim [0.55], accent, radius",
+    "progress": "color, h [8], y [\"100%\"] (a bar along the bottom edge that fills over the whole scene)",
+    "kinetic": "words [list], every [0.6] (seconds per word), size [180], motion [pop], color, x, y [\"50%\"] (centre)",
+}
+_PASS = ("id", "at", "dur", "until", "enter", "exit", "opacity", "scale", "rotate", "hidden", "z", "rotateX", "rotateY",
+         "fixed")
+
+
+class Params(dict):
+    """Component parameters that remember which names the builder asked for, so a parameter
+    nobody reads (a typo such as "subtitel") is reported instead of silently dropped."""
+
+    def __init__(self, *a, **kw):
+        super().__init__(*a, **kw)
+        self.read: set[str] = set()
+
+    def get(self, k, default=None):
+        self.read.add(k)
+        return super().get(k, default)
+
+    def __getitem__(self, k):
+        self.read.add(k)
+        return super().__getitem__(k)
+
+    def __contains__(self, k):
+        self.read.add(k)
+        return super().__contains__(k)
+
+
+def _unused(name: str, raw: dict, known: set[str], scene):
+    from .schema import COMMENT, suggest
+    for k in raw:
+        if k in known or k in _PASS or k in COMMENT or k in ("use", "type", "x", "y") or str(k).startswith(("_", "//")):
+            continue
+        close = suggest(k, sorted(known - set(_PASS) - {"id"}))
+        msg = (f"component '{name}' has no parameter '{k}'." + (f" Did you mean '{close}'?" if close else "")
+               + f" Its parameters: {', '.join(sorted(known - {'id'})) or 'none'}")
+        if scene is None:
+            raise ValueError(msg)
+        scene.note("error", "unknown-param", raw.get("id"), msg, f"rename or remove '{k}'")
+
+
+def _fill_template(v, params):
+    if isinstance(v, str):
+        m = re.fullmatch(r"\{\{(\w+)\}\}", v)
+        if m:
+            return copy.deepcopy(params.get(m.group(1), v))
+        return re.sub(r"\{\{(\w+)\}\}", lambda mm: str(params.get(mm.group(1), mm.group(0))), v)
+    if isinstance(v, list):
+        return [_fill_template(x, params) for x in v]
+    if isinstance(v, dict):
+        return {k: _fill_template(x, params) for k, x in v.items()}
+    return v
+
+
+_counter = [0]
+
+
+def expand(raw, user: dict, theme: dict, scene=None):
+    if not isinstance(raw, dict):
+        return raw
+    if raw.get("type") == "sequence":
+        return _sequence(raw)
+    name = raw.get("use")
+    if not name:
+        return raw
+    _counter[0] += 1
+    params = Params(raw)
+    params.setdefault("id", f"{name}{_counter[0]}")
+    if name in user:
+        comp = user[name]
+        merged = dict(comp.get("params", {}), **params)
+        body = _fill_template(copy.deepcopy(comp.get("layers", [])), merged)
+        names = set(comp.get("params", {})) | set(re.findall(r"\{\{(\w+)\}\}", repr(comp.get("layers", []))))
+        _unused(name, raw, names, scene)
+        for i, k in enumerate(body):
+            k.setdefault("id", f"{params['id']}-{i}")
+            k["id"] = f"{params['id']}-{k['id']}" if not str(k["id"]).startswith(params["id"]) else k["id"]
+        out = {"type": "group", "x": raw.get("x", 0), "y": raw.get("y", 0), "children": body}
+    elif name in BUILTIN:
+        out = BUILTIN[name](params, theme)
+        _unused(name, raw, params.read | set(PARAMS.get(name, ())), scene)
+    else:
+        raise ValueError(f"unknown component '{name}'. Built-in: {', '.join(BUILTIN)}; scene: {', '.join(user) or 'none'}")
+    for k in _PASS:
+        if k in raw:
+            out[k] = raw[k]
+    out.setdefault("id", params["id"])
+    return out
+
+
+def _sequence(raw: dict) -> list[dict]:
+    """Cut list -> back-to-back video layers. "transition": {"type": "fade", "dur": 0.4} overlaps them."""
+    tr = raw.get("transition") or {}
+    overlap = float(tr.get("dur", 0)) if tr else 0.0
+    kind = tr.get("type", "fade") if tr else "none"
+    base = raw.get("id", "seq")
+    out = []
+    for i, clip in enumerate(raw.get("clips", [])):
+        c = dict(clip) if isinstance(clip, dict) else {"src": clip}
+        c.setdefault("type", "video")
+        c.setdefault("id", f"{base}-{i + 1}")
+        for k in ("fit", "volume", "w", "h", "x", "y", "anchor"):
+            if k in raw and k not in c:
+                c[k] = raw[k]
+        if i == 0:
+            c.setdefault("at", raw.get("at", 0))
+        else:
+            prev_id = out[-1]["id"]
+            c.setdefault("at", f"{prev_id}.out-{overlap}" if overlap else f"{prev_id}.out")
+            if overlap and kind != "cut":
+                c.setdefault("enter", {"name": {"fade": "fade", "wipe": "wipe-right", "slide": "left",
+                                                "zoom": "zoom", "blur": "blur"}.get(kind, "fade"),
+                                       "dur": overlap, "ease": "inOutSine", "dist": 120})
+        out.append(c)
+    return out
+
+
+def _ts(s: str) -> float:
+    h, m, rest = s.strip().replace(",", ".").split(":") if s.count(":") == 2 else ["0", *s.strip().replace(",", ".").split(":")]
+    return int(h) * 3600 + int(m) * 60 + float(rest)
+
+
+def load_cues(raw: dict, src: str | None) -> list[list]:
+    cues = raw.get("cues")
+    if cues:
+        out = []
+        for c in cues:
+            if isinstance(c, dict):
+                out.append([float(c.get("at", c.get("start", 0))), float(c.get("end")), str(c.get("text", ""))])
+            else:
+                out.append([float(c[0]), float(c[1]), str(c[2])])
+        return out
+    if not src:
+        return []
+    text = Path(src).read_text(encoding="utf-8-sig")
+    out = []
+    for block in re.split(r"\n\s*\n", text.replace("\r", "")):
+        lines = [l for l in block.strip().split("\n") if l.strip()]
+        for j, line in enumerate(lines):
+            if "-->" in line:
+                a, b = line.split("-->")
+                body = " ".join(lines[j + 1:])
+                out.append([_ts(a), _ts(b.split()[0]), re.sub(r"<[^>]+>", "", body)])
+                break
+    return out