kinescript 1.1.0__py3-none-any.whl

kinescript/scene.py

@@ -0,0 +1,362 @@
+"""Scene loading: theme variables, components, sequences, cue timing, compiled properties."""
+from __future__ import annotations
+
+import copy
+import json
+import re
+from pathlib import Path
+
+from . import components, media, models, schema
+from . import presets as P
+from .props import Ctx, Prop, compile_prop
+from .timing import Timeline
+
+LAYER_TYPES = {"rect", "circle", "ellipse", "path", "line", "arrow", "polygon", "text", "counter",
+               "image", "video", "group", "captions", "shader", "model"}
+STRUCT = {"id", "type", "at", "dur", "until", "enter", "exit", "children", "layers", "src", "trim",
+          "speed", "fit", "text", "cues", "d", "points", "font", "split", "format", "align", "anchor",
+          "blend", "clip", "mode", "volume", "hidden", "note", "words", "stops", "cap", "join", "loop",
+          "allowOffscreen", "style", "audio", "shadow", "box", "fx", "fill", "stroke", "emph", "active",
+          "sksl", "preset", "uniforms", "caret", "case", "italic", "smooth", "closed", "focus", "use",
+          "backface", "fixed", "sort", "shape", "detail", "parts", "light"}
+# Property defaults by name; everything not listed defaults to None.
+DEFAULTS = {"x": 0.0, "y": 0.0, "opacity": 1.0, "scale": 1.0, "scaleX": 1.0, "scaleY": 1.0, "rotate": 0.0,
+            "blur": 0.0, "draw": 1.0, "zoom": 1.0, "z": 0.0, "rotateX": 0.0, "rotateY": 0.0}
+DEPTH_PROPS = ("z", "rotateX", "rotateY")
+
+
+class SceneError(ValueError):
+    """A scene that cannot be built. `issues` lists every problem found, each with its layer id."""
+
+    def __init__(self, message: str, issues: list[dict] | None = None, layer: str | None = None):
+        super().__init__(message)
+        self.issues = issues or [{"level": "error", "code": "load", "layer": layer, "message": message, "fix": ""}]
+
+    @classmethod
+    def from_issues(cls, issues: list[dict]) -> "SceneError":
+        errs = [i for i in issues if i["level"] == "error"]
+        lines = [(f"layer '{i['layer']}': " if i.get("layer") else "") + i["message"] for i in errs]
+        msg = lines[0] if len(lines) == 1 else f"{len(lines)} problems:\n  " + "\n  ".join(lines)
+        return cls(msg, issues)
+
+
+class Layer:
+    __slots__ = ("id", "type", "raw", "t_in", "t_out", "props", "enter", "exit", "children", "parent",
+                 "index", "src", "video", "ctx")
+
+    def __init__(self, lid: str, ltype: str, raw: dict, parent: "Layer | None", index: int):
+        self.id, self.type, self.raw, self.parent, self.index = lid, ltype, raw, parent, index
+        self.t_in = self.t_out = 0.0
+        self.props: dict[str, Prop] = {}
+        self.enter = self.exit = None
+        self.children: list[Layer] = []
+        self.src: str | None = None
+        self.video: media.VideoSource | None = None
+        self.ctx: Ctx | None = None
+
+    @property
+    def dur(self) -> float:
+        return self.t_out - self.t_in
+
+    def get(self, name: str, t: float, T: float = 0.0, i: int = 0, default=None):
+        p = self.props.get(name)
+        if p is None:
+            return DEFAULTS.get(name, default)
+        return p.at(t, self.dur, T, i)
+
+    def visible(self, T: float) -> bool:
+        return self.t_in <= T < self.t_out and not self.raw.get("hidden")
+
+    def __repr__(self):
+        return f"<{self.type} {self.id} {self.t_in:.2f}-{self.t_out:.2f}>"
+
+
+class Scene:
+    def __init__(self, spec: dict, base_dir: str | Path = ".", notes: list[dict] | None = None):
+        spec, report = schema.normalize(spec)
+        self.issues: list[dict] = list(notes or []) + report.issues
+        self._raise_errors()
+        self.spec = spec
+        self.base = Path(base_dir)
+        cv = spec.get("canvas", {})
+        self.w = int(cv.get("w", cv.get("width", 1920)))
+        self.h = int(cv.get("h", cv.get("height", 1080)))
+        self.fps = float(cv.get("fps", 30))
+        self.ctx = Ctx(self.w, self.h, self.fps)
+        theme = dict(components.THEME, **spec.get("theme", {}))
+        self.theme = theme
+        self.bg = cv.get("bg", "#0a0c10")
+        self.markers = spec.get("markers", {})
+        self.grade = spec.get("grade") or {}
+        self.motion_blur = spec.get("motionBlur") or {}
+        self.audio = spec.get("audio", [])
+        raw_layers = _subst(copy.deepcopy(spec.get("layers", [])), theme)
+        self.bg = _subst(self.bg, theme)
+        user_comps = spec.get("components", {})
+        try:
+            raw_layers = [components.expand(l, user_comps, theme, self) for l in raw_layers]
+        except ValueError as e:
+            raise SceneError(str(e)) from e
+        raw_layers = [x for l in raw_layers for x in (l if isinstance(l, list) else [l])]
+        self._raise_errors()
+        self.timeline = Timeline(self.fps, self.markers)
+        self.layers: list[Layer] = []
+        self.by_id: dict[str, Layer] = {}
+        self._build(raw_layers, None, self.layers)
+        self.camera = self._camera(_subst(spec.get("camera"), theme))
+        self.light = _subst(spec.get("light"), theme)
+        self._check_media()
+        self._raise_errors()
+        try:
+            self.duration = self.timeline.solve(cv.get("duration"))
+        except ValueError as e:
+            lid = getattr(e, "layer", None)
+            raise SceneError((f"layer '{lid}': " if lid else "") + str(e), layer=lid) from e
+        for layer in self.by_id.values():
+            layer.t_in, layer.t_out = self.timeline.resolved[layer.id]
+        if self.camera is not None:
+            self.camera.t_out = self.duration
+        self.depth = {L.id for L in self.layers if uses_depth(L)}
+        self.is3d = self.camera is not None or bool(self.depth)
+        self.frames = max(1, round(self.duration * self.fps))
+        self._check_values()
+        self._raise_errors()
+
+    def note(self, level: str, code: str, layer, message: str, fix: str = ""):
+        self.issues.append({"level": level, "code": code, "layer": layer, "message": message, "fix": fix})
+
+    def _raise_errors(self):
+        if any(i["level"] == "error" for i in self.issues):
+            raise SceneError.from_issues(self.issues)
+
+    def _check_media(self):
+        """Missing files fail here, before any frame is rendered, with the path that was tried."""
+        def missing(src: str, owner, what: str) -> bool:
+            p = Path(src)
+            if p.exists():
+                return False
+            near = sorted(x.name for x in p.parent.iterdir()) if p.parent.is_dir() else []
+            close = schema.suggest(p.name, near) if near else None
+            fix = (f"did you mean '{close}'? " if close else "") + (
+                f"files in {p.parent}: {', '.join(near[:12])}" if near else f"folder {p.parent} does not exist")
+            self.note("error", "media-missing", owner, f"{what} not found: {p}",
+                      fix + " (paths are relative to the scene file)")
+            return True
+
+        for layer in self.all_layers():
+            if layer.src and not missing(layer.src, layer.id, f"{layer.type} src") and layer.type == "model":
+                try:
+                    models.load(layer.src)
+                except ValueError as e:
+                    self.note("error", "bad-model", layer.id, f"model src {e}",
+                              "export it again as glTF 2.0 (.glb) or .obj")
+        for i, a in enumerate(self.audio):
+            if isinstance(a, dict) and a.get("src") and not missing(self.path(a["src"]), f"audio[{i}]", "audio src"):
+                _check_trim(self, f"audio[{i}]", a.get("trim") or [0, None], media.probe(self.path(a["src"]))["duration"])
+
+    def _check_values(self):
+        """Evaluate every property at the start, middle and end of its layer, so a bad value is reported
+        now, with its layer and field, instead of as a Python error halfway through a render."""
+        for layer in self.all_layers():
+            d = layer.dur
+            for name, prop in layer.props.items():
+                if name.startswith("u_"):
+                    continue
+                for t in (0.0, d / 2, max(0.0, d - 1e-3), d):  # d: the last keyframe value itself
+                    try:
+                        v = prop.at(t, d, layer.t_in + t, 0)
+                    except Exception as e:  # noqa: BLE001 - any failure inside a user expression
+                        self.note("error", "bad-expression", layer.id, f"{name} failed at t={t:.2f}s: {e}")
+                        break
+                    if name in schema.COLOR_KEYS:
+                        if isinstance(v, str):
+                            self.note("error", "bad-colour", layer.id, f"{name} '{v}' is not a colour",
+                                      "use #rrggbb, #rrggbbaa, rgb(...) or a CSS colour name")
+                            break
+                    elif name in schema.SCALAR and (isinstance(v, bool) or not isinstance(v, (int, float))):
+                        self.note("error", "bad-value", layer.id, f"{name} is {v!r} at t={t:.2f}s; expected a number",
+                                  "use a number, a percentage like '50%', or an expression starting with '='")
+                        break
+
+    def path(self, src: str) -> str:
+        p = Path(src)
+        return str(p if p.is_absolute() else (self.base / p))
+
+    def _build(self, raws: list, parent: Layer | None, out: list):
+        prev = None
+        for idx, raw in enumerate(raws):
+            if not isinstance(raw, dict):
+                raise SceneError(f"layer #{idx} must be an object, got {type(raw).__name__}")
+            ltype = raw.get("type") or _infer_type(raw)
+            if ltype not in LAYER_TYPES:
+                raise SceneError(f"layer #{idx} ({raw.get('id', '?')}): unknown type '{ltype}'. "
+                                 f"Known: {', '.join(sorted(LAYER_TYPES))}")
+            lid = str(raw.get("id") or f"{ltype}{len(self.by_id) + 1}")
+            if lid in self.by_id:
+                raise SceneError(f"duplicate layer id '{lid}'")
+            if ltype == "captions":
+                raw = dict({"x": "50%", "y": "86%", "size": 46, "weight": 700}, **raw)
+            layer = Layer(lid, ltype, raw, parent, len(self.by_id))
+            self.by_id[lid] = layer
+            natural = None
+            if ltype in ("video", "image", "model") or (ltype == "captions" and raw.get("src")):
+                layer.src = self.path(raw["src"]) if raw.get("src") else None
+            if ltype == "video" and layer.src and Path(layer.src).exists():
+                info = media.probe(layer.src)
+                trim = raw.get("trim") or [0, None]
+                _check_trim(self, lid, trim, info["duration"])
+                end = trim[1] if len(trim) > 1 and trim[1] is not None else info["duration"]
+                end = min(float(end), info["duration"]) if info["duration"] else end
+                natural = max(0.04, (end - trim[0]) / float(raw.get("speed", 1)))
+            if ltype == "captions" and (raw.get("cues") or (layer.src and Path(layer.src).exists())):
+                raw = layer.raw = dict(raw, cues=components.load_cues(raw, layer.src))
+                if raw["cues"] and "dur" not in raw and "until" not in raw:
+                    natural = max(c[1] for c in raw["cues"])
+            try:
+                self.timeline.add(lid, raw.get("at", 0), raw.get("dur"), raw.get("until"), natural,
+                                  prev=prev, parent=parent.id if parent else None,
+                                  default_end=parent.id if parent else None)
+            except ValueError as e:
+                raise SceneError(f"layer '{lid}': {e}", layer=lid) from e
+            ctx = self.ctx
+            if ltype == "group" and ("w" in raw or "h" in raw):
+                ctx = Ctx(_num(raw.get("w"), self.w), _num(raw.get("h"), self.h), self.fps)
+            layer.ctx = ctx
+            pctx = parent.ctx if parent and parent.ctx else self.ctx
+            try:
+                for k, v in raw.items():
+                    if k in ("fill", "stroke", "emph", "active") and not isinstance(v, dict):
+                        layer.props[k] = compile_prop(k, v, pctx)
+                    elif k not in STRUCT:
+                        layer.props[k] = compile_prop(k, v, pctx)
+                for un, uv in (raw.get("uniforms") or {}).items():
+                    if not isinstance(uv, (int, float, str)) or (isinstance(uv, str) and uv.startswith("=")):
+                        layer.props["u_" + un] = compile_prop("u_" + un, uv, pctx)
+                layer.enter = P.parse(raw.get("enter"))
+                layer.exit = P.parse(raw.get("exit"))
+            except (ValueError, SyntaxError) as e:
+                raise SceneError(f"layer '{lid}': {e}", layer=lid) from e
+            out.append(layer)
+            kids = raw.get("children") or raw.get("layers")
+            if ltype == "group" and kids:
+                kids = [components.expand(k, self.spec.get("components", {}), self.theme, self) for k in kids]
+                kids = [x for k in kids for x in (k if isinstance(k, list) else [k])]
+                self._build(kids, layer, layer.children)
+            prev = lid
+
+    def _camera(self, raw) -> Layer | None:
+        """The camera as a layer that spans the scene, so its keys animate like any layer's."""
+        if raw is None:
+            return None
+        cam = Layer("camera", "camera", raw, None, -1)
+        try:
+            cam.props = {k: compile_prop(k, v, self.ctx) for k, v in raw.items()}
+        except (ValueError, SyntaxError) as e:
+            raise SceneError(f"camera: {e}", layer="camera") from e
+        return cam
+
+    def all_layers(self):
+        def walk(ls):
+            for layer in ls:
+                yield layer
+                yield from walk(layer.children)
+        return walk(self.layers)
+
+    def summary(self) -> dict:
+        return {"canvas": {"w": self.w, "h": self.h, "fps": self.fps, "duration": round(self.duration, 3),
+                           "frames": self.frames},
+                "layers": [{"id": l.id, "type": l.type, "in": round(l.t_in, 3), "out": round(l.t_out, 3),
+                            "parent": l.parent.id if l.parent else None} for l in self.all_layers()]}
+
+    def close(self):
+        for layer in self.all_layers():
+            if layer.video:
+                layer.video.close()
+
+
+def uses_depth(L: Layer) -> bool:
+    """True when the layer or anything inside it moves in depth."""
+    motions = [m for m in (L.enter, L.exit) if m]
+    return (L.type == "model" or any(k in L.props for k in DEPTH_PROPS) or any(P.DEPTH & set(m.names) for m in motions)
+            or any(uses_depth(c) for c in L.children))
+
+
+def _check_trim(scene: "Scene", owner, trim, length: float):
+    if not isinstance(trim, (list, tuple)) or not trim:
+        scene.note("error", "bad-trim", owner, f"trim must be [start, end] in source seconds, got {trim!r}")
+        return
+    a = float(trim[0])
+    b = trim[1] if len(trim) > 1 else None
+    if not length:
+        return
+    if a >= length:
+        scene.note("error", "bad-trim", owner, f"trim starts at {a:g}s but the source is only {length:.2f}s long",
+                   f"use a start below {length:.2f}")
+    elif b is not None and float(b) <= a:
+        scene.note("error", "bad-trim", owner, f"trim end {b} is not after its start {a:g}")
+    elif b is not None and float(b) > length + 0.05:
+        scene.note("warning", "trim-past-end", owner,
+                   f"trim ends at {float(b):g}s but the source is {length:.2f}s long, so it stops at {length:.2f}s",
+                   f"use [{a:g}, {length:.2f}] or leave out the end")
+
+
+def _num(v, ref):
+    if v is None:
+        return ref
+    if isinstance(v, str) and v.endswith("%"):
+        return float(v[:-1]) / 100 * ref
+    return float(v)
+
+
+def _infer_type(raw: dict) -> str:
+    for key, t in (("shape", "model"), ("parts", "model"), ("text", "text"), ("cues", "captions"), ("d", "path"),
+                   ("points", "path"), ("children", "group"), ("layers", "group"), ("r", "circle")):
+        if key in raw:
+            return t
+    if "src" in raw:
+        ext = Path(str(raw["src"])).suffix.lower()
+        return ("video" if ext in (".mp4", ".mov", ".webm", ".mkv", ".avi", ".m4v") else
+                "model" if ext in models.EXTENSIONS else "image")
+    return "rect"
+
+
+_VAR = re.compile(r"\$([A-Za-z_]\w*)")
+
+
+def _subst(v, theme: dict):
+    if isinstance(v, str):
+        if v.startswith("$") and v[1:] in theme:
+            return copy.deepcopy(theme[v[1:]])
+        if "$" in v and not v.startswith("="):
+            return _VAR.sub(lambda m: str(theme.get(m.group(1), m.group(0))), v)
+        return v
+    if isinstance(v, list):
+        return [_subst(x, theme) for x in v]
+    if isinstance(v, dict):
+        return {k: _subst(x, theme) for k, x in v.items()}
+    return v
+
+
+def load(src) -> Scene:
+    """Load a scene from a .json path, a JSON string or a dict."""
+    if isinstance(src, Scene):
+        return src
+    if isinstance(src, dict):
+        return Scene(src)
+    s = str(src)
+    if s.lstrip().startswith("{"):
+        text, base, name = s, Path("."), "scene"
+    else:
+        p = Path(s)
+        if not p.exists():
+            raise SceneError(f"scene file not found: {p}")
+        text, base, name = p.read_text(encoding="utf-8-sig"), p.parent, p.name
+    try:
+        spec, fixed = schema.loads(text)
+    except json.JSONDecodeError as e:
+        lines = text.splitlines()
+        line = lines[e.lineno - 1].strip()[:120] if 0 < e.lineno <= len(lines) else ""
+        raise SceneError(f"{name}: invalid JSON at line {e.lineno} col {e.colno}: {e.msg}. The line is: {line}") from e
+    notes = [{"level": "info", "code": "json", "layer": None, "message": f"the JSON had {', '.join(fixed)}; read anyway",
+              "fix": "write strict JSON"}] if fixed else []
+    return Scene(spec, base, notes)