Metadata-Version: 2.5
Name: narratty
Version: 0.4.0
Summary: Turn a YAML script into a narrated terminal video with local TTS, VHS rendering and automatic voiceover sync.
Project-URL: Homepage, https://github.com/ditschi/narratty
Project-URL: Source, https://github.com/ditschi/narratty
Project-URL: Documentation, https://ditschi.github.io/narratty/
Author: ditschi
License: MIT
License-File: LICENSE
Keywords: cli,docs-as-code,screencast,terminal,text-to-speech,tts,vhs,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.12
Requires-Dist: kokoro-onnx>=0.6
Requires-Dist: pillow>=10.1
Requires-Dist: piper-tts>=1.8
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.12
Requires-Dist: rich>=13.7
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: segno>=1.6
Requires-Dist: typer>=0.12
Provides-Extra: code-quality
Requires-Dist: fawltydeps>=0.16; extra == 'code-quality'
Requires-Dist: pylint>=3.2; extra == 'code-quality'
Requires-Dist: vulture>=2.11; extra == 'code-quality'
Provides-Extra: dev
Requires-Dist: commitizen>=3.29; extra == 'dev'
Requires-Dist: fawltydeps>=0.16; extra == 'dev'
Requires-Dist: jsonschema>=4.22; extra == 'dev'
Requires-Dist: mike>=2.1; extra == 'dev'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: nox>=2024.4; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pylint>=3.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: vulture>=2.11; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.1; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: kokoro
Provides-Extra: lint
Requires-Dist: ruff>=0.6; extra == 'lint'
Provides-Extra: test
Requires-Dist: jsonschema>=4.22; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6; extra == 'test'
Requires-Dist: pytest>=8.2; extra == 'test'
Provides-Extra: type-check
Requires-Dist: mypy>=1.10; extra == 'type-check'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/ditschi/narratty/main/docs/assets/logo.svg" alt="narratty" width="320">
</p>

# narratty

Turn a YAML script into a narrated terminal video. narratty types your commands in a
real terminal ([VHS](https://github.com/charmbracelet/vhs)), speaks the narration with
local text-to-speech ([Kokoro](https://github.com/thewh1teagle/kokoro-onnx) or
[Piper](https://github.com/OHF-Voice/piper1-gpl)) and keeps voice and picture in
sync. It runs sandboxed in Docker or Podman, or natively.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
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

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

See the [contributor guide](docs/contributor-guide/dev-setup.md).

## License

[MIT](LICENSE)
