wizz-method 2.11.1 → 2.12.0

package/src/skills-lib/wizz-video-effects/scripts/timeline.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+"""Read and write the timeline JSON every script shares.
+
+The shape is documented in references/data-contract.md. This module only
+normalizes it: absent lists become empty lists, never errors, and every
+instant comes back as a float in seconds.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class TimelineError(Exception):
+    """Timeline file missing or malformed."""
+
+
+def load(path: str | Path) -> dict:
+    p = Path(path)
+    if not p.exists():
+        raise TimelineError(f"timeline not found: {p}")
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise TimelineError(f"{p} is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise TimelineError(f"{p}: the timeline must be a JSON object")
+    return data
+
+
+def save(path: str | Path, data: dict) -> None:
+    Path(path).write_text(json.dumps(data, ensure_ascii=False, indent=1) + "\n",
+                          encoding="utf-8")
+
+
+def instants(items, key: str = "at") -> list[float]:
+    """A list of numbers OR of objects {key: ...} as sorted floats."""
+    if not items:
+        return []
+    return sorted(float(i[key]) if isinstance(i, dict) else float(i) for i in items)
+
+
+def transitions(scenes) -> list[float]:
+    """Scene starts with a real transition (not empty, not 'cut')."""
+    out = []
+    for s in scenes or []:
+        tr = s.get("transition")
+        if tr and tr != "cut" and "start" in s:
+            out.append(float(s["start"]))
+    return sorted(out)
+
+
+def duration(data: dict) -> tuple[float, bool]:
+    """(duration, derived). Uses `duration`; else the largest scene end."""
+    if data.get("duration"):
+        return float(data["duration"]), False
+    ends = [float(s["start"]) + float(s.get("dur", 0.0))
+            for s in (data.get("scenes") or []) if "start" in s]
+    return (max(ends), True) if ends else (0.0, True)
+
+
+def fps(data: dict, default: int) -> int:
+    return int(data.get("fps") or default)
+
+
+def sounds(data: dict) -> list[dict]:
+    """Every sound of the piece, sorted by `at`: sfx[] plus scene-level sfx
+    (a scene's `sfx` plays at the scene start)."""
+    out = [dict(s) for s in (data.get("sfx") or [])]
+    for sc in data.get("scenes") or []:
+        s = sc.get("sfx")
+        if isinstance(s, dict) and "start" in sc:
+            out.append({**s, "at": float(sc["start"]), "scene": True})
+    return sorted(out, key=lambda s: float(s["at"]))
+
+
+def effect_events(data: dict) -> dict[str, list[float]]:
+    """Visual effect instants by budget kind."""
+    return {
+        "punch": instants(data.get("punches")),
+        "shake": instants(data.get("shakes")),
+        "flash": instants(data.get("flashes")),
+        "interrupt": instants(data.get("interrupts")),
+        "transition": transitions(data.get("scenes")),
+    }