kinescript 1.1.0__py3-none-any.whl

kinescript/fonts/SpaceGrotesk-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

kinescript/mcp.py

@@ -0,0 +1,148 @@
+"""Minimal MCP server (JSON-RPC 2.0 over stdio, newline-delimited). No dependencies.
+
+Tools take `scene` as a path to a .json file or as the scene object itself.
+Look and still return the image inline, so an agent with vision sees the frames directly.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+
+from . import __version__
+
+_SCENE = {"description": "Path to a scene .json, or the scene object itself", "type": ["string", "object"]}
+TOOLS = [
+    {"name": "kine_docs", "description": "Kinescript scene reference: layer types, properties, timing, motions, "
+     "components, eases. Read once before writing a scene.", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "kine_check", "description": "Lint a scene: load errors, text off canvas or in the safe margin, overlapping "
+     "text, low contrast, tiny text, too little reading time. Returns issues with time ranges and fixes.",
+     "inputSchema": {"type": "object", "properties": {"scene": _SCENE, "base": {"type": "string"}}, "required": ["scene"]}},
+    {"name": "kine_look", "description": "Contact sheet: `count` frames in one labelled image. boxes=true outlines each "
+     "layer with its id. Use it to review motion and layout without watching video.",
+     "inputSchema": {"type": "object", "properties": {"scene": _SCENE, "base": {"type": "string"},
+                                                      "count": {"type": "integer", "default": 12},
+                                                      "times": {"type": "array", "items": {"type": "number"}},
+                                                      "boxes": {"type": "boolean", "default": False},
+                                                      "width": {"type": "integer", "default": 400}}, "required": ["scene"]}},
+    {"name": "kine_still", "description": "One full-size frame at time `at` (seconds), returned as an image.",
+     "inputSchema": {"type": "object", "properties": {"scene": _SCENE, "base": {"type": "string"}, "at": {"type": "number"},
+                                                      "scale": {"type": "number", "default": 0.5}},
+                     "required": ["scene", "at"]}},
+    {"name": "kine_probe", "description": "Resolved timeline (every layer's in/out) and, with `at`, every visible "
+     "layer's screen box, alpha and text at that time.",
+     "inputSchema": {"type": "object", "properties": {"scene": _SCENE, "base": {"type": "string"}, "at": {"type": "number"}},
+                     "required": ["scene"]}},
+    {"name": "kine_render", "description": "Render to a file (.mp4, .mov ProRes 4444 alpha, .webm VP9 alpha, .gif, or a "
+     ".png sequence). quality draft|standard|high; scale <1 for previews; from/to (s) for a range.",
+     "inputSchema": {"type": "object", "properties": {"scene": _SCENE, "base": {"type": "string"}, "out": {"type": "string"},
+                                                      "quality": {"type": "string", "enum": ["draft", "standard", "high"]},
+                                                      "scale": {"type": "number"}, "from": {"type": "number"},
+                                                      "to": {"type": "number"}}, "required": ["scene", "out"]}},
+]
+
+
+def _scene(args: dict):
+    from .scene import Scene, load
+    sc = args["scene"]
+    if isinstance(sc, dict):
+        return Scene(sc, args.get("base") or os.getcwd())
+    return load(sc)
+
+
+def _image(path: str) -> dict:
+    return {"type": "image", "mimeType": "image/png", "data": base64.b64encode(Path(path).read_bytes()).decode()}
+
+
+def _text(obj) -> dict:
+    return {"type": "text", "text": obj if isinstance(obj, str) else json.dumps(obj, indent=1, ensure_ascii=False)}
+
+
+def call(name: str, args: dict) -> list[dict]:
+    if name == "kine_docs":
+        from .docs import reference
+        return [_text(reference())]
+    if name == "kine_check":
+        from .verify import check
+        return [_text(check(_scene(args)))]
+    if name == "kine_probe":
+        from .verify import probe
+        return [_text(probe(_scene(args), args.get("at")))]
+    if name == "kine_look":
+        from .verify import contact_sheet
+        out = str(Path(tempfile.gettempdir()) / f"kine_look_{os.getpid()}.png")
+        info = contact_sheet(_scene(args), out, int(args.get("count", 12)), None, int(args.get("width", 400)),
+                             args.get("times"), bool(args.get("boxes")))
+        return [_image(out), _text(info)]
+    if name == "kine_still":
+        from .output import still
+        out = str(Path(tempfile.gettempdir()) / f"kine_still_{os.getpid()}.png")
+        still(_scene(args), float(args["at"]), out, float(args.get("scale", 0.5)))
+        return [_image(out)]
+    if name == "kine_render":
+        from .output import render
+        sc = args["scene"]
+        if isinstance(sc, dict):
+            sc = _scene(args)
+        res = render(sc, args["out"], args.get("quality", "standard"), None, float(args.get("scale", 1.0)),
+                     args.get("from"), args.get("to"))
+        return [_text(res)]
+    raise ValueError(f"unknown tool {name}")
+
+
+def _reply(id_, result=None, error=None):
+    msg = {"jsonrpc": "2.0", "id": id_}
+    if error is not None:
+        msg["error"] = error
+    else:
+        msg["result"] = result
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()
+
+
+def serve():
+    try:
+        _serve()
+    except OSError:  # the client closed its end of the pipe (BrokenPipeError, or EINVAL on Windows)
+        sys.stdout = open(os.devnull, "w")  # so the interpreter's final flush stays quiet
+
+
+def _serve():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            _reply(None, error={"code": -32700, "message": "parse error"})
+            continue
+        method, id_ = req.get("method"), req.get("id")
+        if id_ is None:
+            continue  # notification
+        if method == "initialize":
+            _reply(id_, {"protocolVersion": req.get("params", {}).get("protocolVersion", "2024-11-05"),
+                         "capabilities": {"tools": {}},
+                         "serverInfo": {"name": "kinescript", "version": __version__},
+                         "instructions": "Kinescript renders motion graphics and video edits from JSON scenes. "
+                                         "Call kine_docs first, then write a scene, kine_check it, kine_look at it, "
+                                         "and kine_render it."})
+        elif method == "tools/list":
+            _reply(id_, {"tools": TOOLS})
+        elif method == "tools/call":
+            p = req.get("params", {})
+            try:
+                _reply(id_, {"content": call(p.get("name"), p.get("arguments") or {})})
+            except (ValueError, RuntimeError, FileNotFoundError, KeyError) as e:
+                _reply(id_, {"content": [_text(f"error: {e}")], "isError": True})
+            except Exception as e:  # noqa: BLE001 - report unexpected failures to the client instead of dying
+                _reply(id_, {"content": [_text(f"internal error: {e}\n{traceback.format_exc()[-1500:]}")],
+                             "isError": True})
+        elif method == "ping":
+            _reply(id_, {})
+        else:
+            _reply(id_, error={"code": -32601, "message": f"method not found: {method}"})

kinescript/media.py

@@ -0,0 +1,220 @@
+"""Footage and image access through ffmpeg/ffprobe pipes."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import queue
+import subprocess
+import threading
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+import skia
+
+FFMPEG = shutil.which("ffmpeg") or "ffmpeg"
+FFPROBE = shutil.which("ffprobe") or "ffprobe"
+_NOWIN = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+
+class MediaError(RuntimeError):
+    pass
+
+
+def _version(src: str) -> tuple:
+    """(path, modification time, size): a cache key that changes when the file does, so the MCP server and
+    warm render workers read an edited file again."""
+    try:
+        st = os.stat(src)
+    except OSError:
+        return src, 0, -1
+    return src, st.st_mtime_ns, st.st_size
+
+
+def probe(src: str) -> dict:
+    """{'duration', 'w', 'h', 'fps', 'audio'} for a media file, probed once per file version."""
+    return _probe(*_version(src))
+
+
+@lru_cache(maxsize=128)
+def _probe(src: str, mtime: int, size: int) -> dict:
+    if not Path(src).exists():
+        raise MediaError(f"media not found: {src}")
+    out = subprocess.run([FFPROBE, "-v", "error", "-show_streams", "-show_format", "-of", "json", src],
+                         capture_output=True, text=True, creationflags=_NOWIN)
+    if out.returncode:
+        raise MediaError(f"ffprobe failed on {src}: {out.stderr.strip()[:300]}")
+    info = json.loads(out.stdout)
+    v = next((s for s in info.get("streams", []) if s.get("codec_type") == "video"), None)
+    a = any(s.get("codec_type") == "audio" for s in info.get("streams", []))
+    dur = float(info.get("format", {}).get("duration") or (v or {}).get("duration") or 0)
+    fps = 0.0
+    if v and v.get("avg_frame_rate", "0/0") != "0/0":
+        n, d = v["avg_frame_rate"].split("/")
+        fps = float(n) / float(d or 1)
+    return {"duration": dur, "w": int((v or {}).get("width", 0)), "h": int((v or {}).get("height", 0)),
+            "fps": fps, "audio": a, "image": bool(v) and fps == 0 and dur == 0,
+            "pix_fmt": (v or {}).get("pix_fmt", ""), "color_space": (v or {}).get("color_space", "")}
+
+
+def yuv_matrix(info: dict):
+    """Skia's YUV colour space for a probed clip: its tag, or, untagged, the rule players use
+    (BT.709 from 1280 wide or above 576 lines, else BT.601). All limited range."""
+    cs = info.get("color_space") or ""
+    if cs == "bt709":
+        return skia.kRec709_YUVColorSpace
+    if cs in ("smpte170m", "bt470bg", "fcc"):
+        return skia.kRec601_YUVColorSpace
+    if cs.startswith("bt2020"):
+        return skia.kBT2020_YUVColorSpace
+    return skia.kRec709_YUVColorSpace if info.get("w", 0) >= 1280 or info.get("h", 0) > 576 else skia.kRec601_YUVColorSpace
+
+
+def image(src: str) -> skia.Image:
+    """The decoded image, once per file version."""
+    return _image(*_version(src))
+
+
+@lru_cache(maxsize=64)
+def _image(src: str, mtime: int, size: int) -> skia.Image:
+    data = Path(src).read_bytes() if Path(src).exists() else None
+    if data is None:
+        raise MediaError(f"image not found: {src}")
+    img = skia.Image.MakeFromEncoded(skia.Data.MakeWithCopy(data))
+    if img is None:
+        raise MediaError(f"cannot decode image {src} (png, jpg, webp, gif, bmp are supported)")
+    return img
+
+
+class VideoSource:
+    """Delivers frames of one clip, already resampled to the scene fps and sized to the
+    layer box, so a sequential render reads each frame exactly once. Out-of-order access
+    (contact sheets, probes) reopens the pipe at the requested time."""
+
+    def __init__(self, src: str, w: int, h: int, fps: float, speed: float = 1.0, fit: str = "cover", ctx=None):
+        """ctx: a GPU context. With one, YUV clips without alpha arrive as yuv420p (1.5 bytes a pixel
+        instead of 4; ffmpeg converts nothing) and become RGB on the GPU at draw time."""
+        self.src, self.w, self.h, self.fps, self.speed, self.fit = src, max(2, w), max(2, h), fps, speed, fit
+        self.info = probe(src)
+        pf = self.info["pix_fmt"]
+        self.ctx = ctx if (ctx is not None and fit != "contain" and pf.startswith(("yuv", "nv", "p0"))
+                           and not pf.startswith("yuva")) else None
+        if self.ctx is not None:  # 4:2:0 planes need even sizes
+            self.w, self.h = max(2, self.w - self.w % 2), max(2, self.h - self.h % 2)
+            self.yuv_info = skia.YUVAInfo((self.w, self.h), skia.YUVAInfo.kY_U_V, skia.YUVAInfo.k420,
+                                          yuv_matrix(self.info))
+        self.proc: subprocess.Popen | None = None
+        self.t0 = 0.0
+        self.index = -1
+        self.frame: skia.Image | None = None
+        self.nbytes = self.w * self.h * 3 // 2 if self.ctx is not None else self.w * self.h * 4
+
+    def _vf(self) -> str:
+        w, h = self.w, self.h
+        if self.ctx is not None:  # cover or stretch, kept in YUV and limited range
+            fit = ":force_original_aspect_ratio=increase" if self.fit == "cover" else ""
+            crop = f",crop={w}:{h}" if self.fit == "cover" else ""
+            return f"setpts=(PTS-STARTPTS)/{self.speed},fps={self.fps},scale={w}:{h}{fit}:out_range=tv{crop},format=yuv420p"
+        # The same matrix the YUV path uses, so GPU and raster renders of a clip agree.
+        m = {skia.kRec709_YUVColorSpace: "bt709", skia.kRec601_YUVColorSpace: "bt601",
+             skia.kBT2020_YUVColorSpace: "bt2020"}[yuv_matrix(self.info)]
+        cm = f":in_color_matrix={m}" if self.info.get("pix_fmt", "").startswith(("yuv", "nv", "p0")) else ""
+        if self.fit == "contain":
+            size = (f"scale={w}:{h}{cm}:force_original_aspect_ratio=decrease,format=rgba,"
+                    f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color=0x00000000")
+        elif self.fit == "stretch":
+            size = f"scale={w}:{h}{cm},format=rgba"
+        else:
+            size = f"scale={w}:{h}{cm}:force_original_aspect_ratio=increase,crop={w}:{h},format=rgba"
+        return f"setpts=(PTS-STARTPTS)/{self.speed},fps={self.fps},{size}"
+
+    def _open(self, t: float):
+        self.close()
+        self.t0 = max(0.0, t)
+        cmd = [FFMPEG, "-v", "error", "-ss", f"{self.t0:.4f}", "-i", self.src, "-an", "-vf", self._vf(),
+               "-f", "rawvideo", "-pix_fmt", "yuv420p" if self.ctx is not None else "rgba", "-"]
+        self.proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                                     bufsize=self.nbytes * 2, creationflags=_NOWIN)
+        self.index = -1
+        # A reader thread keeps up to PREFETCH decoded frames waiting, so ffmpeg decodes the next
+        # frames while this process draws the current one instead of both taking turns.
+        self.queue = q = queue.Queue(maxsize=self.PREFETCH)
+        self.stopping = stop = threading.Event()
+        threading.Thread(target=self._pump, args=(self.proc, q, stop, self.nbytes), daemon=True).start()
+
+    PREFETCH = 6
+
+    @staticmethod
+    def _pump(proc, q, stop, nbytes):
+        try:
+            while not stop.is_set():
+                buf = proc.stdout.read(nbytes)
+                item = buf if len(buf) == nbytes else None
+                while not stop.is_set():
+                    try:
+                        q.put(item, timeout=0.1)
+                        break
+                    except queue.Full:
+                        continue
+                if item is None:
+                    return
+        except (OSError, ValueError):  # the pipe was closed by close()
+            return
+
+    def _read(self) -> bool:
+        buf = self.queue.get()
+        if buf is None:
+            self.queue.put(None)  # stay at end of stream for later calls
+            return False
+        # No copy: the image (or the planes) wrap the bytes object, which self._buf keeps alive.
+        self._buf = buf
+        if self.ctx is not None:
+            w, h, b = self.w, self.h, np.frombuffer(buf, np.uint8)
+            planes = (b[:w * h].reshape(h, w), b[w * h:w * h * 5 // 4].reshape(h // 2, w // 2),
+                      b[w * h * 5 // 4:].reshape(h // 2, w // 2))
+            pms = [skia.Pixmap(skia.ImageInfo.Make(a.shape[1], a.shape[0], skia.kGray_8_ColorType,
+                                                   skia.kOpaque_AlphaType), a, a.shape[1]) for a in planes]
+            self.frame = skia.Image.MakeFromYUVAPixmaps(
+                self.ctx, skia.YUVAPixmaps.FromExternalPixmaps(self.yuv_info, pms + [skia.Pixmap()]))
+        else:
+            arr = np.frombuffer(buf, np.uint8).reshape(self.h, self.w, 4)
+            self.frame = skia.Image.fromarray(arr, colorType=skia.kRGBA_8888_ColorType, copy=False)
+        self.index += 1
+        return True
+
+    def at(self, src_t: float) -> skia.Image | None:
+        """Frame showing source time src_t (seconds into the file)."""
+        dur = self.info["duration"]
+        if dur:
+            src_t = min(src_t, max(0.0, dur - 1.5 / max(self.info["fps"] or self.fps, 1)))
+        want = round((src_t - self.t0) / self.speed * self.fps)
+        if self.proc is None or want < self.index or want > self.index + int(self.fps * 2):
+            self._open(src_t)
+            want = 0
+        while self.index < want:
+            if not self._read():
+                break
+        return self.frame
+
+    def close(self):
+        if self.proc:
+            self.stopping.set()
+            try:
+                self.proc.stdout.close()  # type: ignore[union-attr]
+                self.proc.kill()
+                self.proc.wait(timeout=2)
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+            self.proc = None
+
+
+@lru_cache(maxsize=4)
+def grain_tiles(seed: int = 7, size: int = 256, count: int = 6) -> list[skia.Image]:
+    rng = np.random.default_rng(seed)
+    tiles = []
+    for _ in range(count):
+        g = rng.integers(0, 256, (size, size), dtype=np.uint8)
+        arr = np.dstack([g, g, g, np.full_like(g, 255)])
+        tiles.append(skia.Image.fromarray(np.ascontiguousarray(arr), colorType=skia.kRGBA_8888_ColorType))
+    return tiles