kinescript 1.5.1

Video you can diff.
Motion graphics, video edits and voice-over written as JSON, checked by agents, rendered on the GPU.

Documentation · Source · Changelog · Launch video

Kinescript turns a JSON scene into video. Every layer, keyframe, cut and sound is a line of data, so a scene can be generated, reviewed in a pull request, and changed by a script or an agent. A voice-over can start as a line of text. 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.

pip install kinescript
kine doctor

It needs Python 3.10 or newer and ffmpeg on your PATH (details).

The launch video is a Kinescript scene, marketing/promo.json. It is 35 seconds of 1080p and renders, with audio, in about 3.3 seconds on the development machine. The project site shows more demos, each next to the scene file it was rendered from.

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" (or words, or lines) with a staggered enter motion, a typewriter reveal with a caret, **emphasis** markup, and 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.
• Sound on the same timeline. Voice-over, music and effects are cues like layers, a voice's words are cues too, a voice can be spoken from text, and sounds with a role are levelled and ducked for you (Sound).
• Captions from .srt/.vtt, inline cues or a voice's word times, with karaoke and pop modes.
• 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.

3D

Depth and models are drawn by the same Skia renderer as everything else, with no extra dependency. Scenes that use no depth draw exactly as before.

• Camera and depth on any layer. Every layer takes z, rotateX, rotateY and backface. A top-level camera pans, dollies, orbits and rolls with perspective, looks at and follows a target point or layer, can shake like a handheld camera, and pulls focus with depth of field (aperture, focus); fixed layers ignore its moves, and a group with "sort": "depth" draws its children far to near. The flip, flip-up, tumble and push motions work on whole layers and per letter with split. A two-sided card is a group with "backface": "hidden" on each side. fog fades far layers into the background colour, or a colour of your own.
• Stages. A group with "sort": "pixel" draws each child with an image of its depth and shows the nearest at each pixel, so models and cards pass through each other with a clean edge, and a model's ground shadow lies on a floor layer. With "shadows": true its models cast shadows from the key light onto the floor, walls and each other.
• Model layers. "type": "model" draws a lit cube (r rounds it), sphere, cylinder, cone, capsule, torus or plane, a lathe turned from a profile, a tube along a path (its draw grows it), or several shapes merged as parts so their triangles are depth-sorted together; part keys animate like layer keys. repeat draws copies of a model merged into one mesh, each placed and coloured by an expression of its number i: a waving grid of 100 cubes is one layer. Materials take fill, shine, metal, rim, bands (toon steps), glow, transparency (see-through, the far side showing) and texture, wrapped round the shape with the texture's repeat and offset: an image, a video that plays on the model, or "#groupId", a group of layers drawn on it at each frame's time, such as an app on a phone's screen. light, for the scene or one model, takes studio, soft, dramatic or flat, or your own amounts, and every amount, its azimuth, elevation and colour animate. It follows the camera, or with "follow": "world" stays in the scene as the camera orbits. lights adds up to three more, directional or point, and env gives shiny and metal models an environment to reflect. edges draws lines along creases and the outline, or along every edge as a wireframe, hidden where something is in front of them. explode sends faces outward and the build motion assembles a model.
• Extruded text and SVG paths. "shape": "text" extrudes letters in any font and "shape": "path" extrudes SVG path data, filled, or stroked with strokeWidth for line icons. Both take a depth and a 45-degree bevel.
• Model files. src reads .glb and .gltf (glTF 2.0) and .obj with its .mtl: node transforms, base colours and base colour textures, emission (emissiveFactor and emissiveTexture, or Ke and map_Ke), transparency (alphaMode BLEND, or d and Tr), and metallic and roughness as metal and shine. Meshopt-compressed and quantized files (gltfpack -c) are read as they are; Draco-compressed ones with pip install "kinescript[draco]". animation plays a glTF file's clips on the layer's clock: node movement, morph target weights and skins, with speed, loop and start. ground puts a soft shadow under any model, straight down or, with "from": "light", cast along its key light.

A 3D title that builds in and turns to face the camera:

{"id": "title3d", "type": "model", "shape": "text", "text": "LAUNCH",
 "x": "50%", "y": "50%", "size": 240, "weight": 800, "depth": 70, "bevel": 5,
 "rotateY": [[0, -40], [2.4, 0, "outCubic"]], "rotateX": [[0, 18], [2.4, 0, "outCubic"]],
 "shine": 0.6, "enter": {"name": "build", "dur": 1.2}}

Sound

Sounds are a top-level audio list, timed like layers and mixed by ffmpeg while the frames render.

• Cues both ways. "at": "vo1.out+0.3" starts a layer 0.3 s after the voice ends, and a sound can start at "title.in". A layer's "sound": "pop.wav" plays when it appears and moves when it moves. A voice stretches an auto duration so it is never cut off.
• Words are cues. A words file next to a voice (vo1.words.json, or Whisper's JSON as it is) times each word: "at": "vo1:render" starts a layer as the voice says "render", and {"type": "captions", "voice": "vo1"} captions it, lighting each word as it is said.
• Voice-over from text. Write what a voice says in text and kine voice speaks it through a plugin, writing the file and its word times: Kokoro (local, fast), Chatterbox (local, cloned voices) or ElevenLabs (cloud, needs an API key), picked per sound with backend. [[go]] in the text names the next word, so a cue to vo1:go survives a rewrite of the line. Only a line whose text, speaker, rate, backend or options changed is spoken again, and rendering never calls a speech engine.
• Delivery tags. [whispers], [laughs] or [sighs] in the text tell ElevenLabs how to say what follows. Chatterbox takes them too but acts them only some of the time: in test takes it made a sound where [laughs] goes in six of nine and whispered in none of seven. Tags are not words, so cues, marks and captions skip them, and Kokoro says the line without them.
• A mix without listening. Give a sound a role and it is set to that role's level: voice -18 LUFS, music -16, ambience -30, effects peaking at -6 dBFS. Music and ambience dip 14 dB while a voice speaks, an effect's leading silence is skipped so it lands on its cue, and the whole mix ends at -16 LUFS with peaks under -1.5 dBTP. A top-level mix changes the targets. Sounds without a role are mixed as given.
• Checked and drawn. kine check mixes and measures the sound and reports a voice cut off or masked by the music, an effect that lands late, silence, and a mix off its targets. kine look --audio draws the sound under the frames on the same time axis.
• Everywhere. Gain takes keyframes and expressions like any property; sounds loop and pan; the mix goes into MP4, MOV, WebM and --from/--to renders, and -o mix.wav renders the sound alone.

A narrated beat with a click on a marked word, over music that ducks under the voice:

"audio": [
  {"id": "vo", "role": "voice", "at": 0.6, "text": "Each word it says is a [[hit]]cue."},
  {"id": "bed", "role": "music", "src": "bed.m4a", "loop": true, "until": "end", "fadeOut": 1.5}
],
"layers": [
  {"id": "cue", "type": "text", "text": "Cue", "size": 200, "at": "vo:hit", "sound": "click.wav", "enter": "pop"},
  {"id": "cc", "type": "captions", "voice": "vo", "mode": "karaoke"}
]

kine voice scene.json speaks it once. The voice demo on the project site plays the result with sound, next to its scene file. Install the plugin for the voice you want next to Kinescript:

pip install kinescript-kokoro       # local and fast; Python 3.10 to 3.12
pip install kinescript-chatterbox   # local, copies a voice from a clip, tags hit or miss; installs PyTorch
pip install kinescript-elevenlabs   # ElevenLabs' API, acts on tags; needs ELEVENLABS_API_KEY

A plugin can also live in another Python, for Kokoro on Python 3.13 or newer or to keep PyTorch out of Kinescript's environment: point KINE_VOICE_CMD, or KINE_VOICE_CMD_<NAME> for one backend, at it. Each plugin's README has the details: Kokoro, Chatterbox, ElevenLabs.

Built for agents

An agent cannot watch a video, so Kinescript gives it things it can read:

kine check reports unknown keys and bad values, missing media and out-of-range trims, text off the canvas or in the safe margin, overlapping text, contrast under 3:1 against what is actually behind the text, tiny text and too little reading time. When the scene has sound it mixes and measures it, without drawing a frame, while the frames are checked, and reports a voice cut off by the scene end, two voices at once, music less than 10 LU under a voice, an effect whose first sound comes late, a silent sound, and a mix off its loudness target or at its peak ceiling. An unknown key names the intended key first. Common names from other tools (color, fontSize, duration, position) are read and reported as info notes. It exits with status 1 while there are errors.

The same tools are available over MCP (kine mcp) as kine_docs, kine_check, kine_look, kine_still, kine_probe, kine_render and kine_voice. They take a scene as a file path or as the JSON object itself, and kine_look and kine_still return images inline.

{
  "mcpServers": {
    "kinescript": {"command": "kine", "args": ["mcp"]}
  }
}

Install

Requires Python 3.10+ and ffmpeg on PATH (for example winget install Gyan.FFmpeg, brew install ffmpeg or sudo apt install ffmpeg). On Linux, skia-python also loads the system's EGL, GL and fontconfig libraries, even with KINE_BACKEND=cpu. A bare container or server needs sudo apt install libegl1 libgl1 libfontconfig1, or importing Kinescript fails with libEGL.so.1: cannot open shared object file.

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

kine new scene.json
kine check scene.json
kine look scene.json --boxes
kine render scene.json -o scene.mp4

{
  "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 scenes in examples/:

• hello.json: a title animation, 4.2 s.
• edit.json: a cut list with a punch-in, a transition, a lower third, a callout, karaoke captions and a music bed, 10.4 s.
• 3d.json: a camera move past layers at several depths and a card that turns over, 6 s.
• model.json: lit primitives and a ring around a ball that builds in and flies apart, 6 s.
• title3d.json: the brand mark as an extruded SVG path and the wordmark as extruded text, 5 s.
• import.json: a glTF rocket on a ground shadow, 6 s.
• stage.json: a ring through a panel and a ball that comes through it, on a floor, in a stage, 6 s.
• lights.json: a ringed planet under a key light that stays in the scene as the camera orbits, a blue light from the side, a warm point light below and a glowing ring, 6 s.
• reflections.json: chrome, gold and gloss reflecting their environments as the camera turns, 6 s.
• fog.json: a hall of pillars fading into fog as the camera walks in and a ball comes out of it, 6 s.
• shadows.json: a cone, a ring and a cube in a stage, their shadows swinging across the floor and up the wall as the key light moves, 6 s.
• camera.json: a handheld camera that follows a ring past posts at several depths, orbiting it, then pans to a word, 6 s.
• focus.json: focus pulls from a cone to a ring to a cube in a stage, each pixel blurred by its own depth, 6 s.
• textures.json: boards on a crate, a label on a can and a map on a globe, on a tiled floor, as the camera swings round, 6 s.
• screens.json: an animated app on a phone's screen and footage round a turning drum: a group and a video as textures, 6 s.
• edges.json: a toon-shaded rocket with outlines, a hidden-line wireframe ring and extruded letters with their creases drawn, 6 s.
• glass.json: a ball and a ring inside a glass case, and a ring that turns see-through, its inside showing, 6 s.
• product.json: a glTF can, its label a texture inside the file, turning on a table under a studio light and environment, with its shadow on the table and two more cans out of focus behind it, 6 s.
• cubes.json: a ripple through a grid of 144 cubes, one model layer with repeat, each copy placed and coloured by an expression of its number, 6 s.
• shapes.json: a rounded box, a capsule, a lathed vase and cup, and a tube that draws a route between them, 6 s.
• character.json: a skinned glTF figure playing its walk and wave clips: two walk across a floor with their shadows while a third waves, 6 s.
• voiceover.json: titles cued from the words of a voice-over, karaoke captions of it, and a music bed that dips under it, 5.4 s.
• narrated.json: the same idea with a voice written as text, a marked word and a click on it. Run kine voice examples/narrated.json first.

edit.json, import.json, textures.json, screens.json, edges.json, product.json, voiceover.json and narrated.json read sample media: run python examples/make_media.py first to generate it.

Performance

Measured on the development machine (Intel Core Ultra 7 265, 20 threads, NVIDIA RTX 5060 Ti, Windows 11), 2026-10-31:

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. python bench/stress.py generates 26 scenes that each push one thing far past the examples (2000 layers, 60 cuts, 4K, 120 s, 16-sample motion blur with alpha, 600 caption cues, a stage of 16 layers, a textured model of 102,400 triangles and more), then checks, renders and probes each one in its own process and reports time, peak memory and whether the output holds every frame.

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 cast shadows on each other only inside a stage, and a skinned vertex follows at most four joints. Separate layers hide each other per pixel only inside a stage, and parts of one model that cut through each other meet at a stepped seam. A textured model is drawn solid whatever its transparency. Draco-compressed model files need the draco extra.
• Audio is mixing and levelling (trim, gain over time, fades, speed, loop, pan, role levels, ducking, a loudness target), with no effects such as EQ, compression of single sounds or reverb.
• Kinescript does not speak by itself: kine voice needs a plugin or a command. The Kokoro plugin times words for English voices only and needs Python 3.10 to 3.12; the Chatterbox plugin speaks and times English only; the ElevenLabs plugin needs an API key and a network connection.
• 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, scene, components, render (Skia), space, render3d,
              mesh and models (3D), output (encoding and the audio mix),
              verify (check, look, probe), schema, docs, mcp, cli
examples/     example scenes and the generator for sample media
plugins/      voices for kine voice, each installed on its own: kinescript-kokoro, kinescript-chatterbox,
              kinescript-elevenlabs
marketing/    the launch video as a scene and its builder; build_site.py renders the site
site/         the project site: demo scenes next to the videos rendered from them
brand/        logo files, generated art and the brand guide
bench/        per-stage timing of frames and whole renders
content/      launch post and social copy
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/.