kinescript 1.1.0__tar.gz

kinescript-1.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Dr. Know How
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The fonts in kinescript/fonts/ (Space Grotesk, IBM Plex Mono) are not covered by
+this license. They are distributed under the SIL Open Font License 1.1; see the
+-OFL.txt files next to them.

kinescript-1.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: kinescript
+Version: 1.1.0
+Summary: Motion graphics and video edits written as JSON, checked by agents, rendered on the GPU.
+Author: Dr. Know How
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drknowhow/kinescript
+Project-URL: Source, https://github.com/drknowhow/kinescript
+Project-URL: Issues, https://github.com/drknowhow/kinescript/issues
+Project-URL: Changelog, https://github.com/drknowhow/kinescript/blob/main/CHANGELOG.md
+Keywords: video,motion graphics,animation,skia,ffmpeg,mcp,agents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: GPU
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: kinescript/fonts/IBMPlexMono-OFL.txt
+License-File: kinescript/fonts/SpaceGrotesk-OFL.txt
+Requires-Dist: skia-python>=87
+Requires-Dist: numpy>=1.24
+Requires-Dist: glfw>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+<p align="center"><img src="https://raw.githubusercontent.com/drknowhow/kinescript/main/brand/logo-dark.png" width="460" alt="kinescript"></p>
+
+<p align="center"><b>Video you can diff.</b><br>Motion graphics and video edits written as JSON, checked by agents, rendered on the GPU.</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/drknowhow/kinescript/main/docs/hero.gif" width="720" alt="The Kinescript launch video, rendered by Kinescript"></p>
+
+Kinescript turns a JSON scene into video. Every layer, keyframe and cut is a line of data, so a scene can be
+generated, reviewed in a pull request, and changed by a script or an agent. The renderer is a pure function of
+the frame number: any frame renders on its own, which makes previews instant and lets a render split across
+processes.
+
+The launch video in `docs/promo.mp4` is a Kinescript scene (`marketing/promo.json`). It is 35 seconds of 1080p
+and renders, with audio, in about 3.5 seconds on the development machine.
+
+## What it does
+
+- **Cue timing.** Start and end times can name other layers: `"at": "title.out+0.2"`. Lengthen one layer and
+  everything cued after it moves. Cycles and missing references are reported with the ids involved.
+- **Animate anything.** Numbers and colours take constants, keyframes (`[[0, 0], [0.6, 1, "outBack"]]`, with
+  negative times counted from the layer's end), a tween object, or an expression such as `"=540 + sin(t*3)*40"`.
+  Colours interpolate in OKLab.
+- **Text that moves per letter.** `"split": "chars"` with a staggered enter motion, typewriter reveal with a caret,
+  `**emphasis**` markup, per-unit expressions (`"unitY": "=sin(T*4 + i)*12"` for a wave).
+- **Footage.** Video layers with trim, speed, loop, cover/contain fit, punch-in `zoom` around a `focus` point, and
+  rounded picture-in-picture. A `sequence` turns a cut list into clips with fade, wipe, slide, zoom or blur
+  transitions. Clip audio and music beds are mixed automatically.
+- **Captions** from `.srt`/`.vtt` or inline cues, with karaoke and pop modes.
+- **Depth.** Any layer takes `z`, `rotateX` and `rotateY`; a scene `camera` pans, dollies and orbits with real
+  perspective; `flip`, `flip-up`, `tumble` and `push` motions; two-sided cards with `"backface": "hidden"`.
+- **3D models.** Lit cubes, spheres, cylinders, cones, tori and planes, or several merged as `parts`, with
+  shine, metal, rim light and toon bands; light presets; `explode` and a `build` motion. 3D text and extruded
+  SVG paths (filled or stroked) with an optional bevel. Models from `.glb`, `.gltf` and `.obj` files, and a soft
+  `ground` shadow under any model.
+- **Shaders.** SkSL layers with `mesh`, `aurora`, `grid` and `score` presets, or your own source.
+- **Finishing.** Per-layer blur, shadow, blend modes and colour adjustments; a scene grade with vignette and film
+  grain; optional motion blur.
+- **Components.** `lowerThird`, `titleCard`, `callout`, `focus` (dim everything but a region), `progress`,
+  `kinetic`, plus your own with `{{param}}` placeholders.
+- **Outputs.** H.264 `.mp4`, ProRes 4444 `.mov` and VP9 `.webm` with alpha for compositing, `.gif`, PNG sequences.
+
+## Built for agents
+
+An agent cannot watch a video, so Kinescript gives it things it can read:
+
+| Command | What the agent gets |
+|---|---|
+| `kine docs` | the full scene reference, short enough to keep in context |
+| `kine check scene.json` | JSON issues with layer ids and time ranges: unknown keys (with the intended name first), bad values, missing media and out-of-range trims, text off canvas or in the safe margin, overlapping text, contrast under 3:1 against what is actually behind it, tiny text, too little reading time. Every problem is listed at once. Common names from other tools (`color`, `fontSize`, `duration`, `position`) are read and reported as info notes. |
+| `kine look scene.json --boxes` | one PNG of many labelled frames, with every layer outlined and named |
+| `kine probe scene.json --at 3.2` | resolved in/out of every layer and each visible layer's screen box |
+| `kine still` / `kine render` | a frame, a range (`--from/--to`), a draft (`-q draft --scale 0.5`) or the final file |
+
+The same tools are available over MCP (`kine mcp`), and `kine_look` / `kine_still` return images inline.
+
+```json
+{
+  "mcpServers": {
+    "kinescript": {"command": "kine", "args": ["mcp"]}
+  }
+}
+```
+
+## Install
+
+Requires Python 3.10+ and ffmpeg on `PATH`.
+
+```bash
+pip install kinescript
+kine doctor        # ffmpeg path, GPU availability, default font
+```
+
+From a checkout: `pip install -e .`
+
+Dependencies are `skia-python`, `numpy` and `glfw`. Space Grotesk and IBM Plex Mono (both SIL Open Font License)
+ship with the package, so default text looks the same on every machine.
+
+## Quick start
+
+```bash
+kine new scene.json
+kine check scene.json
+kine look scene.json --boxes
+kine render scene.json -o scene.mp4
+```
+
+```json
+{
+  "canvas": {"w": 1920, "h": 1080, "fps": 30, "bg": "#0a0c10"},
+  "grade": {"vignette": 0.35, "grain": 0.04},
+  "layers": [
+    {"id": "dot", "type": "circle", "x": "50%", "y": "50%", "r": 26, "fill": "$accent", "dur": 1.1,
+     "enter": {"name": "pop", "dur": 0.4}, "exit": "fade"},
+    {"id": "title", "type": "text", "text": "Motion, **written.**", "x": "50%", "y": "46%", "size": 140,
+     "weight": 700, "split": "chars", "at": "dot.out-0.1", "dur": 3.2,
+     "enter": {"name": "snap", "stagger": 0.03}, "exit": "fade"},
+    {"id": "sub", "type": "text", "text": "scenes as data", "x": "50%", "y": "62%", "size": 40,
+     "fill": "$muted", "at": "title.in+0.6", "until": "title.out", "enter": "rise"}
+  ]
+}
+```
+
+More in `examples/`: `hello.json` (title animation) and `edit.json` (a cut list with a punch-in, crossfade,
+lower third, callout, karaoke captions and a music bed). Run `python examples/make_media.py` first to generate the
+sample footage.
+
+## Performance
+
+Measured on the development machine (Intel Core Ultra 7 265, 20 threads, NVIDIA RTX 5060 Ti, Windows 11),
+2026-10-30:
+
+| Workload | Result |
+|---|---|
+| Drawing one 1080p frame of the launch video on the GPU, converted to I420 and read back as a render does | median 2.7 ms, p95 3.3 ms (all 1038 frames) |
+| Launch video, 34.6 s at 1080p30, `-q high`, with audio | 3.5 s wall, about 300 frames/s (median of 5 runs) |
+| `examples/edit.json`, 10.4 s with two decoded video clips | 2.05 s wall, 152 frames/s (median of 5 runs) |
+
+`python bench/stages.py` splits the time per frame into drawing, conversion and readback, and writing to
+ffmpeg for several workloads, and times whole renders.
+
+Rendering uses Skia on the GPU through a hidden OpenGL context, one per worker process. Frames are split into
+chunks, encoded in parallel and joined without re-encoding, while another ffmpeg process mixes the audio.
+Within one process, such as the MCP server, the workers stay warm for two minutes between renders.
+
+## Limits
+
+- Without a usable GPU, Kinescript falls back to Skia's CPU rasteriser. With the Windows `skia-python` wheel this is
+  very slow (about 0.65 s per 1080p frame for the launch video); use `--scale 0.5` for previews on such machines.
+  `KINE_BACKEND=cpu` forces this path.
+- 3D is drawn by Skia with a depth sort, not a GL pipeline: models have no image textures, skeletal animation or
+  shadows cast on each other, and separate model layers do not hide each other per pixel (merge touching
+  objects as `parts` of one model).
+- Audio is mixing (trim, gain, fades, speed), not editing or effects.
+- Video is decoded and resampled by ffmpeg to the scene frame rate. Jumping backwards or far ahead reopens the
+  decoder, which is slower than sequential playback.
+- Text layout is single-script left-to-right with greedy wrapping. No shaping for complex scripts or bidi.
+- Expressions are limited to arithmetic and the listed helpers; attribute access and other names are rejected.
+
+## Project layout
+
+```
+kinescript/   engine: timing, props, presets, render, output, verify (check/look/probe), mcp, cli
+examples/     scenes and the generator for sample media
+marketing/    the launch video, as a scene and its builder script
+brand/        logo files, generated art and the brand guide
+content/      launch post and social copy
+site/         landing page
+tests/        pytest suite
+```
+
+## License
+
+MIT, see `LICENSE`. The bundled fonts are under the SIL Open Font License 1.1; their notices are in
+`kinescript/fonts/`.

kinescript-1.1.0/README.md

@@ -0,0 +1,153 @@
+<p align="center"><img src="https://raw.githubusercontent.com/drknowhow/kinescript/main/brand/logo-dark.png" width="460" alt="kinescript"></p>
+
+<p align="center"><b>Video you can diff.</b><br>Motion graphics and video edits written as JSON, checked by agents, rendered on the GPU.</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/drknowhow/kinescript/main/docs/hero.gif" width="720" alt="The Kinescript launch video, rendered by Kinescript"></p>
+
+Kinescript turns a JSON scene into video. Every layer, keyframe and cut is a line of data, so a scene can be
+generated, reviewed in a pull request, and changed by a script or an agent. The renderer is a pure function of
+the frame number: any frame renders on its own, which makes previews instant and lets a render split across
+processes.
+
+The launch video in `docs/promo.mp4` is a Kinescript scene (`marketing/promo.json`). It is 35 seconds of 1080p
+and renders, with audio, in about 3.5 seconds on the development machine.
+
+## What it does
+
+- **Cue timing.** Start and end times can name other layers: `"at": "title.out+0.2"`. Lengthen one layer and
+  everything cued after it moves. Cycles and missing references are reported with the ids involved.
+- **Animate anything.** Numbers and colours take constants, keyframes (`[[0, 0], [0.6, 1, "outBack"]]`, with
+  negative times counted from the layer's end), a tween object, or an expression such as `"=540 + sin(t*3)*40"`.
+  Colours interpolate in OKLab.
+- **Text that moves per letter.** `"split": "chars"` with a staggered enter motion, typewriter reveal with a caret,
+  `**emphasis**` markup, per-unit expressions (`"unitY": "=sin(T*4 + i)*12"` for a wave).
+- **Footage.** Video layers with trim, speed, loop, cover/contain fit, punch-in `zoom` around a `focus` point, and
+  rounded picture-in-picture. A `sequence` turns a cut list into clips with fade, wipe, slide, zoom or blur
+  transitions. Clip audio and music beds are mixed automatically.
+- **Captions** from `.srt`/`.vtt` or inline cues, with karaoke and pop modes.
+- **Depth.** Any layer takes `z`, `rotateX` and `rotateY`; a scene `camera` pans, dollies and orbits with real
+  perspective; `flip`, `flip-up`, `tumble` and `push` motions; two-sided cards with `"backface": "hidden"`.
+- **3D models.** Lit cubes, spheres, cylinders, cones, tori and planes, or several merged as `parts`, with
+  shine, metal, rim light and toon bands; light presets; `explode` and a `build` motion. 3D text and extruded
+  SVG paths (filled or stroked) with an optional bevel. Models from `.glb`, `.gltf` and `.obj` files, and a soft
+  `ground` shadow under any model.
+- **Shaders.** SkSL layers with `mesh`, `aurora`, `grid` and `score` presets, or your own source.
+- **Finishing.** Per-layer blur, shadow, blend modes and colour adjustments; a scene grade with vignette and film
+  grain; optional motion blur.
+- **Components.** `lowerThird`, `titleCard`, `callout`, `focus` (dim everything but a region), `progress`,
+  `kinetic`, plus your own with `{{param}}` placeholders.
+- **Outputs.** H.264 `.mp4`, ProRes 4444 `.mov` and VP9 `.webm` with alpha for compositing, `.gif`, PNG sequences.
+
+## Built for agents
+
+An agent cannot watch a video, so Kinescript gives it things it can read:
+
+| Command | What the agent gets |
+|---|---|
+| `kine docs` | the full scene reference, short enough to keep in context |
+| `kine check scene.json` | JSON issues with layer ids and time ranges: unknown keys (with the intended name first), bad values, missing media and out-of-range trims, text off canvas or in the safe margin, overlapping text, contrast under 3:1 against what is actually behind it, tiny text, too little reading time. Every problem is listed at once. Common names from other tools (`color`, `fontSize`, `duration`, `position`) are read and reported as info notes. |
+| `kine look scene.json --boxes` | one PNG of many labelled frames, with every layer outlined and named |
+| `kine probe scene.json --at 3.2` | resolved in/out of every layer and each visible layer's screen box |
+| `kine still` / `kine render` | a frame, a range (`--from/--to`), a draft (`-q draft --scale 0.5`) or the final file |
+
+The same tools are available over MCP (`kine mcp`), and `kine_look` / `kine_still` return images inline.
+
+```json
+{
+  "mcpServers": {
+    "kinescript": {"command": "kine", "args": ["mcp"]}
+  }
+}
+```
+
+## Install
+
+Requires Python 3.10+ and ffmpeg on `PATH`.
+
+```bash
+pip install kinescript
+kine doctor        # ffmpeg path, GPU availability, default font
+```
+
+From a checkout: `pip install -e .`
+
+Dependencies are `skia-python`, `numpy` and `glfw`. Space Grotesk and IBM Plex Mono (both SIL Open Font License)
+ship with the package, so default text looks the same on every machine.
+
+## Quick start
+
+```bash
+kine new scene.json
+kine check scene.json
+kine look scene.json --boxes
+kine render scene.json -o scene.mp4
+```
+
+```json
+{
+  "canvas": {"w": 1920, "h": 1080, "fps": 30, "bg": "#0a0c10"},
+  "grade": {"vignette": 0.35, "grain": 0.04},
+  "layers": [
+    {"id": "dot", "type": "circle", "x": "50%", "y": "50%", "r": 26, "fill": "$accent", "dur": 1.1,
+     "enter": {"name": "pop", "dur": 0.4}, "exit": "fade"},
+    {"id": "title", "type": "text", "text": "Motion, **written.**", "x": "50%", "y": "46%", "size": 140,
+     "weight": 700, "split": "chars", "at": "dot.out-0.1", "dur": 3.2,
+     "enter": {"name": "snap", "stagger": 0.03}, "exit": "fade"},
+    {"id": "sub", "type": "text", "text": "scenes as data", "x": "50%", "y": "62%", "size": 40,
+     "fill": "$muted", "at": "title.in+0.6", "until": "title.out", "enter": "rise"}
+  ]
+}
+```
+
+More in `examples/`: `hello.json` (title animation) and `edit.json` (a cut list with a punch-in, crossfade,
+lower third, callout, karaoke captions and a music bed). Run `python examples/make_media.py` first to generate the
+sample footage.
+
+## Performance
+
+Measured on the development machine (Intel Core Ultra 7 265, 20 threads, NVIDIA RTX 5060 Ti, Windows 11),
+2026-10-30:
+
+| Workload | Result |
+|---|---|
+| Drawing one 1080p frame of the launch video on the GPU, converted to I420 and read back as a render does | median 2.7 ms, p95 3.3 ms (all 1038 frames) |
+| Launch video, 34.6 s at 1080p30, `-q high`, with audio | 3.5 s wall, about 300 frames/s (median of 5 runs) |
+| `examples/edit.json`, 10.4 s with two decoded video clips | 2.05 s wall, 152 frames/s (median of 5 runs) |
+
+`python bench/stages.py` splits the time per frame into drawing, conversion and readback, and writing to
+ffmpeg for several workloads, and times whole renders.
+
+Rendering uses Skia on the GPU through a hidden OpenGL context, one per worker process. Frames are split into
+chunks, encoded in parallel and joined without re-encoding, while another ffmpeg process mixes the audio.
+Within one process, such as the MCP server, the workers stay warm for two minutes between renders.
+
+## Limits
+
+- Without a usable GPU, Kinescript falls back to Skia's CPU rasteriser. With the Windows `skia-python` wheel this is
+  very slow (about 0.65 s per 1080p frame for the launch video); use `--scale 0.5` for previews on such machines.
+  `KINE_BACKEND=cpu` forces this path.
+- 3D is drawn by Skia with a depth sort, not a GL pipeline: models have no image textures, skeletal animation or
+  shadows cast on each other, and separate model layers do not hide each other per pixel (merge touching
+  objects as `parts` of one model).
+- Audio is mixing (trim, gain, fades, speed), not editing or effects.
+- Video is decoded and resampled by ffmpeg to the scene frame rate. Jumping backwards or far ahead reopens the
+  decoder, which is slower than sequential playback.
+- Text layout is single-script left-to-right with greedy wrapping. No shaping for complex scripts or bidi.
+- Expressions are limited to arithmetic and the listed helpers; attribute access and other names are rejected.
+
+## Project layout
+
+```
+kinescript/   engine: timing, props, presets, render, output, verify (check/look/probe), mcp, cli
+examples/     scenes and the generator for sample media
+marketing/    the launch video, as a scene and its builder script
+brand/        logo files, generated art and the brand guide
+content/      launch post and social copy
+site/         landing page
+tests/        pytest suite
+```
+
+## License
+
+MIT, see `LICENSE`. The bundled fonts are under the SIL Open Font License 1.1; their notices are in
+`kinescript/fonts/`.

kinescript-1.1.0/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-1.1.0/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-1.1.0/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)