kinescript

A voice from a line of text.

Write what the voice says in the scene. kine voice speaks it with a plugin and writes the time of every word, so "at": "vo:text" starts a layer on that word and captions follow the voice. Tags such as [whispers] or [laughs] in the text say how to deliver the line. Give sounds a role and the mix is levelled for you. Rendering never calls the speech engine.

Narration that cues the picture

A Kokoro voice spoken from the scene's text. Five of its words each start a layer, and each layer's sound plays a click as it appears. The captions are lit from the word times, and the music dips 14 dB while the voice speaks. [[pic]] in the text names the word after it, so vo:pic stays on that word if the line is rewritten. Turn the sound on.

0.0 s
  1. b0
  2. b1
  3. b2
  4. b3
  5. b4
  6. cc
  7. progress
  8. vo
  9. bed
voice.json1920 x 1080, 9.95 s
{  "canvas": {"w": 1920, "h": 1080, "fps": 30, "duration": "auto", "bg": "$void"},  "audio": [    {"id": "vo", "role": "voice", "at": 0.6, "speaker": "af_heart",     "text": "This voice began as a line of text. Each word it says is a cue, so the picture [[pic]]follows it, and the music [[duck]]dips while it speaks."},    {"id": "bed", "role": "music", "src": "sound/bed.m4a", "loop": true, "until": "end", "fadeIn": 1, "fadeOut": 1.5}  ],  "components": {    "beat": {"params": {"word": "", "cue": ""}, "layers": [      {"type": "text", "text": "{{word}}", "x": "50%", "y": "42%", "size": 220, "weight": 800,       "enter": {"name": "pop", "dur": 0.35}, "exit": "fade"},      {"type": "text", "text": "at {{cue}}", "font": "IBM Plex Mono", "x": "50%", "y": "60%", "size": 44,       "fill": "$muted", "at": 0.1, "enter": "rise", "exit": "fade"}    ]}  },  "layers": [    {"use": "beat", "id": "b0", "word": "Voice", "cue": "vo:voice", "at": "vo:voice", "until": "vo:text-0.1",     "sound": "sound/click.wav"},    {"use": "beat", "id": "b1", "word": "Text", "cue": "vo:text", "at": "vo:text", "until": "vo:cue-0.1",     "sound": "sound/click.wav"},    {"use": "beat", "id": "b2", "word": "Cue", "cue": "vo:cue", "at": "vo:cue", "until": "vo:pic-0.1",     "sound": "sound/click.wav"},    {"use": "beat", "id": "b3", "word": "Picture", "cue": "vo:pic", "at": "vo:pic", "until": "vo:duck-0.1",     "sound": "sound/click.wav"},    {"use": "beat", "id": "b4", "word": "Mix", "cue": "vo:duck", "at": "vo:duck", "until": "vo.out+1.2",     "sound": "sound/click.wav"},    {"id": "cc", "type": "captions", "voice": "vo", "mode": "karaoke", "active": "$key"},    {"use": "progress", "id": "progress", "color": "$key", "h": 6}  ]}

One line, three backends

The same line, tags included, spoken by each plugin. Only ElevenLabs acts the tags: it whispers the first sentence and laughs. Kokoro leaves tags out. Chatterbox's Turbo model takes them, but here it speaks the whisper in its normal voice and leaves a silent pause for the laugh. In test takes it made a sound where the laugh goes in six of nine and whispered in none of seven. Each card's time is how long kine voice --force took for that one sound, as the median of three runs. Each run is a new process that loads the model or calls the API. Measured with bench/voices.py on an Intel Core Ultra 7 265 with a GeForce RTX 5060 Ti, Windows 11, October 2026. Turn the sound on.

0.0 s
  1. bg
  2. kicker
  3. title
  4. line
  5. k
  6. c
  7. e
  8. end
  9. end-code
  10. progress
  11. vo-k
  12. vo-c
  13. vo-e
  14. bed
voices.json1920 x 1080, 22.18 s
{  "canvas": {"w": 1920, "h": 1080, "fps": 30, "duration": "auto", "bg": "$void"},  "theme": {"panel": "#12151b", "lit": "#1a1e26"},  "audio": [    {"id": "vo-k", "role": "voice", "backend": "kokoro", "speaker": "af_heart", "at": 3.0,     "text": "[whispers] Same line, three [[voices]]voices. [laughs] [[guess]]Guess which one costs [[money]]money."},    {"id": "vo-c", "role": "voice", "backend": "chatterbox", "at": "vo-k.out+0.8",     "text": "[whispers] Same line, three [[voices]]voices. [laughs] [[guess]]Guess which one costs [[money]]money."},    {"id": "vo-e", "role": "voice", "backend": "elevenlabs", "speaker": "George", "at": "vo-c.out+0.8",     "text": "[whispers] Same line, three [[voices]]voices. [laughs] [[guess]]Guess which one costs [[money]]money."},    {"id": "bed", "role": "music", "src": "sound/bed.m4a", "loop": true, "until": "end", "fadeIn": 1, "fadeOut": 1.5}  ],  "components": {    "card": {"params": {"name": "", "sub": "", "vo": "", "made": 0, "speech": "", "on": "$key", "ink": "$void", "tags": "",                        "clone": "", "words": "", "cost": "", "hi": "$key"},     "layers": [      {"id": "box", "type": "group", "anchor": "topleft", "x": -280, "y": -320, "w": 560, "h": 640, "radius": 24, "fill": "$panel", "children": [        {"id": "edge", "type": "rect", "x": "50%", "y": "50%", "w": 560, "h": 640, "radius": 24, "stroke": "$track",         "strokeWidth": 2},        {"id": "live", "type": "rect", "x": "50%", "y": "50%", "w": 560, "h": 640, "radius": 24, "stroke": "$cue",         "strokeWidth": 4, "at": "{{vo}}.in-0.15", "until": "{{vo}}.out+0.25", "enter": {"name": "fade", "dur": 0.2},         "exit": {"name": "fade", "dur": 0.3}, "sound": "sound/click.wav"},        {"id": "dot", "type": "circle", "x": 516, "y": 46, "r": 9, "fill": "$cue", "at": "{{vo}}.in", "until": "{{vo}}.out",         "scale": "=1 + 0.25 * sin(t * 9)", "enter": "pop", "exit": "fade"},        {"id": "name", "type": "text", "text": "{{name}}", "x": "50%", "y": 62, "size": 60, "weight": 700},        {"id": "sub", "type": "text", "text": "{{sub}}", "font": "IBM Plex Mono", "x": "50%", "y": 110, "size": 26,         "weight": 500, "fill": "$muted"},        {"id": "wait", "type": "text", "text": "made in  -", "font": "IBM Plex Mono", "x": "50%", "y": 180, "size": 46,         "weight": 500, "fill": "$muted", "until": "{{vo}}.in"},        {"id": "made", "type": "counter", "font": "IBM Plex Mono", "x": "50%", "y": 180, "size": 46, "weight": 600,         "format": "made in {:.1f} s", "value": {"from": 0, "to": "{{made}}", "dur": 0.9}, "at": "{{vo}}.in"},        {"id": "track", "type": "rect", "x": 48, "y": 226, "anchor": "left", "w": 464, "h": 10, "radius": 5, "fill": "$lit"},        {"id": "bar", "type": "rect", "x": 48, "y": 226, "anchor": "left", "w": "={{made}} / 18 * 464", "h": 10, "radius": 5,         "fill": "$sheet", "at": "{{vo}}.in", "enter": {"name": "wipe", "dur": 0.9}},        {"id": "speech", "type": "text", "text": "for {{speech}} s of speech", "font": "IBM Plex Mono", "x": "50%", "y": 264,         "size": 26, "weight": 500, "fill": "$muted", "at": "{{vo}}.in+0.5", "enter": "fade"},        {"id": "cc", "type": "captions", "voice": "{{vo}}", "mode": "karaoke", "active": "$key", "x": "50%", "y": 334,         "size": 32, "maxWidth": 500, "box": {"fill": "$panel", "pad": [0, 0]}},        {"id": "t1", "type": "text", "text": "[whispers]", "font": "IBM Plex Mono", "x": "30%", "y": 396, "size": 28,         "weight": 500, "fill": "$muted", "box": {"fill": "$lit", "pad": [8, 16], "radius": 999}, "until": "{{vo}}.in"},        {"id": "t1-on", "type": "text", "text": "[whispers]", "font": "IBM Plex Mono", "x": "30%", "y": 396, "size": 28,         "weight": 600, "fill": "{{ink}}", "box": {"fill": "{{on}}", "pad": [8, 16], "radius": 999},         "at": "{{vo}}.in", "until": "{{vo}}:voices.out", "enter": {"name": "pop", "dur": 0.25}},        {"id": "t1-done", "type": "text", "text": "[whispers]", "font": "IBM Plex Mono", "x": "30%", "y": 396, "size": 28,         "weight": 500, "fill": "$muted", "box": {"fill": "$lit", "pad": [8, 16], "radius": 999}, "at": "{{vo}}:voices.out"},        {"id": "t2", "type": "text", "text": "[laughs]", "font": "IBM Plex Mono", "x": "70%", "y": 396, "size": 28,         "weight": 500, "fill": "$muted", "box": {"fill": "$lit", "pad": [8, 16], "radius": 999}, "until": "{{vo}}:voices.out"},        {"id": "t2-on", "type": "text", "text": "[laughs]", "font": "IBM Plex Mono", "x": "70%", "y": 396, "size": 28,         "weight": 600, "fill": "{{ink}}", "box": {"fill": "{{on}}", "pad": [8, 16], "radius": 999},         "at": "{{vo}}:voices.out", "until": "{{vo}}:guess.in+0.2", "enter": {"name": "pop", "dur": 0.25}},        {"id": "t2-done", "type": "text", "text": "[laughs]", "font": "IBM Plex Mono", "x": "70%", "y": 396, "size": 28,         "weight": 500, "fill": "$muted", "box": {"fill": "$lit", "pad": [8, 16], "radius": 999}, "at": "{{vo}}:guess.in+0.2"},        {"id": "r1", "type": "text", "text": "tags", "font": "IBM Plex Mono", "x": 48, "y": 462, "anchor": "left",         "size": 26, "weight": 500, "fill": "$muted"},        {"id": "v1", "type": "text", "text": "{{tags}}", "font": "IBM Plex Mono", "x": 512, "y": 462, "anchor": "right",         "size": 26, "weight": 500},        {"id": "r2", "type": "text", "text": "copies a voice", "font": "IBM Plex Mono", "x": 48, "y": 506, "anchor": "left",         "size": 26, "weight": 500, "fill": "$muted"},        {"id": "v2", "type": "text", "text": "{{clone}}", "font": "IBM Plex Mono", "x": 512, "y": 506, "anchor": "right",         "size": 26, "weight": 500},        {"id": "r3", "type": "text", "text": "word times", "font": "IBM Plex Mono", "x": 48, "y": 550, "anchor": "left",         "size": 26, "weight": 500, "fill": "$muted"},        {"id": "v3", "type": "text", "text": "{{words}}", "font": "IBM Plex Mono", "x": 512, "y": 550, "anchor": "right",         "size": 26, "weight": 500},        {"id": "r4", "type": "text", "text": "cost", "font": "IBM Plex Mono", "x": 48, "y": 594, "anchor": "left",         "size": 26, "weight": 500, "fill": "$muted"},        {"id": "v4", "type": "text", "text": "{{cost}}", "font": "IBM Plex Mono", "x": 512, "y": 594, "anchor": "right",         "size": 26, "weight": 500, "until": "vo-e:money"},        {"id": "v4-on", "type": "text", "text": "{{cost}}", "font": "IBM Plex Mono", "x": 512, "y": 594, "anchor": "right",         "size": 26, "weight": 700, "fill": "{{hi}}", "at": "vo-e:money", "enter": {"name": "pop", "dur": 0.35}}      ]}    ]}  },  "layers": [    {"id": "bg", "type": "shader", "preset": "score", "opacity": 0.35},    {"id": "kicker", "type": "text", "text": "kine voice, one backend per sound", "font": "IBM Plex Mono", "x": "50%",     "y": 74, "size": 30, "weight": 500, "fill": "$muted", "at": 0.2, "until": "vo-e.out+0.2", "enter": "fade",     "exit": "fade"},    {"id": "title", "type": "text", "text": "One line, three voices.", "x": "50%", "y": 140, "size": 84, "weight": 700,     "at": 0.3, "until": "vo-e.out+0.2", "enter": {"name": "rise", "dur": 0.5}, "exit": "fade"},    {"id": "line", "type": "text", "text": "**[whispers]** Same line, three voices. **[laughs]** Guess which one costs money.",     "font": "IBM Plex Mono", "x": "50%", "y": 240, "size": 34, "weight": 500, "fill": "$sheet", "emph": "$key",     "at": 0.9, "until": "vo-e.out+0.2", "enter": {"name": "type", "dur": 1.4}, "exit": "fade"},    {"use": "card", "id": "k", "x": 345, "y": 660, "at": 1.6, "enter": {"name": "rise", "dur": 0.6},     "name": "Kokoro", "sub": "82M, on the CPU", "vo": "vo-k", "made": 9.47, "speech": "4.0", "on": "$panel", "ink": "$track",     "tags": "left out", "clone": "no, blends", "words": "built in", "cost": "free"},    {"use": "card", "id": "c", "x": 960, "y": 660, "at": 1.75, "enter": {"name": "rise", "dur": 0.6},     "name": "Chatterbox", "sub": "Turbo, on the GPU", "vo": "vo-c", "made": 17.89, "speech": "5.0", "on": "$panel", "ink": "$track",     "tags": "not acted", "clone": "5 s clip", "words": "wav2vec2", "cost": "free"},    {"use": "card", "id": "e", "x": 1575, "y": 660, "at": 1.9, "enter": {"name": "rise", "dur": 0.6},     "name": "ElevenLabs", "sub": "Eleven v4, over the API", "vo": "vo-e", "made": 1.97, "speech": "5.1",     "tags": "acted", "clone": "your voices", "words": "from the API", "cost": "credits", "hi": "$cue"},    {"id": "end", "type": "text", "text": "Pick one per sound.", "x": "50%", "y": 140, "size": 84, "weight": 700,     "at": "vo-e.out+0.35", "dur": 3.2, "enter": {"name": "rise", "dur": 0.5}},    {"id": "end-code", "type": "text", "text": "\"backend\": \"kokoro\" | \"chatterbox\" | \"elevenlabs\"", "font": "IBM Plex Mono",     "x": "50%", "y": 240, "size": 34, "weight": 500, "fill": "$key", "at": "end.in+0.4", "until": "end.out",     "enter": {"name": "type", "dur": 1.0}},    {"use": "progress", "id": "progress", "color": "$key", "h": 6}  ]}
terminal
kine voice voice.json   # speak the text, time the words
kine check voice.json   # also mixes and measures it
kine look voice.json --audio
kine render voice.json -o voice.mp4

kine voice speaks a line again only when its text, speaker, rate, backend or options changed, and kine check says when one is missing or out of date; --only vo2 speaks just that one and --force speaks it again anyway. Each sound picks its plugin with backend: Kokoro runs locally and fast, on Python 3.10 to 3.12, and says the line without its tags; Chatterbox runs locally and copies a voice from a clip, and takes tags that it acts only some of the time; ElevenLabs acts on tags through its API and needs a key. Each is pip install kinescript-<name>, and any other engine can be a plugin or a command.

  • voice-18 LUFS, and the music and ambience dip 14 dB under it
  • music-16 LUFS, looped to the end of the scene
  • sfxpeaks at -6 dBFS; leading silence skipped, so it lands on its cue
  • mixbrought to -16 LUFS, peaks under -1.5 dBTP, in MP4, MOV and WebM

Roles and targets are defaults; a top-level mix changes them. A layer's sound moves when the layer moves. Scenes whose sounds have no role are mixed as given.

kine look voice.json --audio

An agent cannot hear the mix, so it reads it. Under the frames, on the same time axis: a lane for each role and one for the mix, each word the voice says, where the music dips, each click on its cue, and any problem in red. The JSON that comes with it gives each sound's loudness before and after the mix.

A contact sheet of eight frames from the voice demo with the sound drawn under them: a voice lane with each spoken word marked, a music lane that dips while the voice speaks, an effects lane with five clicks, and the mix.
The actual output for the voice demo above. The mix measures -16.0 LUFS with a true peak of -1.9 dBTP. Open the image for full size.