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.

# demo.narratty.yaml
scenes:
  - id: intro
    narration: This is a quick tour of the repository layout.
    actions:
      - run: eza --tree --level=1 .

uv tool install narratty            # or: pipx install narratty
narratty build demo.narratty.yaml   # writes demo.mp4
narratty build demo.narratty.yaml -f cast  # demo.cast + demo.mp3 + demo.html

With Docker or Podman installed, the build runs in the ghcr.io/ditschi/narratty image and needs nothing else on the host. Without one, narratty doctor lists the tools native mode needs.

Documentation: https://ditschi.github.io/narratty/

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 (terminal.layout: editor), 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.

Development

uv sync --extra dev
uv run pre-commit install
nox                                 # all quality gates (NOX_CI=1 skips auto-formatting)

See the contributor guide.

License

MIT