narratty

Turn a YAML script into a narrated terminal video. narratty types your commands in a real terminal (VHS), speaks the narration with local text-to-speech (Kokoro or Piper) and keeps voice and picture in sync. It runs sandboxed in Docker or Podman, or natively.

Features

• Spec to video: a .narratty.yaml file becomes an MP4, or an asciicast with narration and a player page (--format cast).
• Local voices: Kokoro (natural sounding, the default) or Piper (many languages), no cloud service. Narration and typing stay in sync, and audio is cached.
• Sandboxed by default: runs in Docker or Podman with no network unless the spec asks for it and you approve. The demo runs in a throwaway snapshot of your repository. Native mode is available too.
• Subtitles and drafts: SRT/VTT files, a soft track or burned-in text from the narration; --draft previews timing in seconds, without TTS.
• Overlays: chapter titles, file names and notes in a rounded box over the video, with reusable styles.
• Browser views: a web page or local HTML file as Chromium renders it, scrolling while the narration talks about it.
• Scripting: hidden setup scenes, waits for screen output, key presses and per-scene typing speed.
• Editor layout: a file explorer with preview above the shell, focus and reveal actions, and a diff of what the demo changed.
• Demo toolkit: bat, delta, eza, fd, ripgrep, jq, micro, yazi, file, tmux and zsh as static binaries, for the narratty image and, with one COPY line, for any dev container.
• Editor support: a JSON Schema for completion and inline errors, validate with line numbers, and shell completion.

Examples shows each feature in a short recording.

Quick start

uv tool install narratty            # or: pipx install narratty
narratty init                       # writes demo.narratty.yaml
narratty validate demo.narratty.yaml
narratty build demo.narratty.yaml   # writes demo.mp4

A minimal spec:

scenes:
  - id: intro
    narration: This is a quick tour of the repository layout.
    actions:
      - run: ls -la

Each scene lasts as long as its actions or its narration, whichever is longer. See Building a video for how timing works and the spec reference for every key.

Where it runs

Runtime	Needs	Chosen when
docker / podman	the container runtime	installed (default)
native	vhs, ttyd, ffmpeg, git	no container runtime, or --runtime native

narratty doctor checks what the selected runtime needs.