/making-kinescript-videos

name: making-kinescript-videos
description: "Make an MP4 from a JSON scene file with Kinescript (drknowhow/kinescript, the `kine` CLI): text, shapes, charts, SVG, images, video clips, particles and 3D models on cue-based timing, with a checker that lints layout, contrast, reading time and the sound mix, and narration spoken by Kokoro TTS with word-level cues and captions, and avatars (drawn or glTF characters) that lip-sync to it. Covers setup in a Linux container (CPU backend, Python 3.12 venv for Kokoro), the write → voice → check → look → render loop, and controlling Kokoro's pronunciation, stress, pauses, pace and voice blends. Use for 'kine', 'Kinescript', 'kinescript scene', 'kine voice', 'narrated promo', 'explainer video', 'motion graphics video', 'video with voice-over and captions', 'Kokoro pronunciation', 'TTS says a name wrong', 'make the narrator emphasise', 'video thumbnail is blank', 'poster frame', 'talking avatar', 'presenter character', 'lip sync', or any video built from type, shapes and captured footage."
metadata:
  version: 0.3.2

Making videos with Kinescript

Kinescript renders a JSON scene to video with Skia and ffmpeg. Layers start and end on cues (`"at": "title.out+0.2"`) rather than on hand-summed seconds, and every frame is a pure function of the scene and the frame number. The `kine` CLI also lints the scene (`check`), draws labelled contact sheets (`look`) and speaks narration (`voice`). Its author is Dimitri (GitHub `drknowhow`). Oskar Austegard, who maintains this skill collection, contributes as a collaborator. Muninn is the name of the Claude agent that works for him.

This file was last checked against Kinescript 2.5.0 (2026-11-12), and upstream releases often. **`kine docs` is the authoritative reference for the installed version.** Read it before writing a scene, and don't rely on feature lists remembered from earlier sessions, this file included.

When NOT to use this skill

| Situation | Use instead | |---|---| | Real web UI in a phone frame, arbitrary DOM/CSS layout | `making-remotion-videos` | | AI-generated footage (Veo, Gemini video) | `creating-video` | | Trim, transcode or caption existing footage | `processing-video` | | Hand-drawn or p5.js character animation | `animating-with-code` |

Setup in a Linux container

sudo apt-get install -y ffmpeg libegl1 libgl1 libfontconfig1   # skia needs EGL even on the CPU backend
pip install kinescript "skia-python>=144"
kine doctor

• Pin skia-python ≥ 144. `pyproject.toml` allows ≥ 87, but 138.0 crashes.
• With no GPU, `KINE_BACKEND=cpu` is used. Kinescript 2.5.0 rendered a

2:12 1080p explainer (3,968 frames of text, shapes and captions) in 41 s at `-j 4` on 4 CPUs, 98 fps (`oaustegard/experiments/colbert-pooling-explainer`). Versions before 2.x managed 3–7 fps, so budget from a short `--from/--to` render rather than from memory.

• **In `oaustegard/claude-workspace` sessions**, that repo's rules require

third-party code to run inside its sandbox, `scripts/jail.sh` (no network, no secrets). Install from PyPI outside it and run `kine` through it.

Kokoro for `kine voice`

`kine voice` needs a voice plugin. Kokoro's, `kinescript-kokoro`, is not on PyPI: it lives in the Kinescript repo at `plugins/kinescript-kokoro`. Kokoro 0.9.4 and misaki 0.9.4, the latest releases (April 2025), require Python 3.10–3.12; on 3.13 pip falls back to kokoro 0.7.16. So give Kokoro its own 3.12 venv and point `KINE_VOICE_CMD` at it; `kine` stays in the system Python:

git clone --depth 1 https://github.com/drknowhow/kinescript ~/kinescript
uv python install 3.12 && uv venv -p 3.12 ~/kokoro-env
VIRTUAL_ENV=~/kokoro-env uv pip install --index-strategy unsafe-best-match \
  --extra-index-url https://download.pytorch.org/whl/cpu torch "kokoro==0.9.4" "misaki[en]==0.9.4" \
  https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl
export KINE_VOICE_CMD="env PYTHONPATH=$HOME/kinescript/plugins/kinescript-kokoro $HOME/kokoro-env/bin/python -m kinescript_kokoro"

The CPU torch index avoids a multi-GB CUDA download; the venv comes to 1.4 GB. Installing spaCy's model up front saves misaki's first-use download. The first `kine voice` run downloads the model (327 MB). With no network at voice time (a sandbox), fetch `hexgrad/Kokoro-82M` (`config.json`, `kokoro-v1_0.pth`, `voices/*.pt`) with `huggingface_hub.snapshot_download` beforehand and pass `HF_HOME` and `HF_HUB_OFFLINE=1` inside `KINE_VOICE_CMD`.

Procedure

1. **Read `kine docs`** for layer types, cue syntax, motions and the sound rules, and `kine docs 3d` as well when the scene uses depth, a camera or models. `kine new` writes a starter scene. 2. **Storyboard in writing**: scenes, their order, and the one thing the viewer must take from each. For anything longer than a few layers, generate the scene from a Python builder that holds one timeline array (the games promo's `kine/build_scene.py` is an example). Don't hand-edit 500 lines of JSON. 3. **Narration**: in the scene's `audio` list, give each voice sound a `text`, a `speaker` and a `rate`, then `kine voice scene.json`. It re-speaks only sounds whose text, speaker or rate changed. It writes the audio and a words file of word timings. Mark a word with `[[go]]` before it to cue a layer from it (`"at": "vo1:go"`). Before speaking anything, read [references/kokoro-speech.md](references/kokoro-speech.md), which covers names, numbers, stress, pauses, pace and blends. 4. **`kine check scene.json`**: fix every error, read every warning, run it again. The warnings for tiny text and reading time are worth acting on: they pushed the games promo's type to ≥ 44 px and its sublines to five words or fewer. 5. **`kine look scene.json --boxes`** (and `--audio` once there is sound): read the contact sheet image before rendering. `kine still` renders one frame. `kine probe --at