# praxinoscope

> Storyboard-driven animated explainer videos in pure Python. You write a YAML or JSON storyboard (ordered scenes, each a scene type with a few fields and a caption); praxinoscope checks it and renders it deterministically to MP4, WebM or GIF at 16:9, 9:16 or 1:1.

Fastest path for an agent:

```bash
praxinoscope example board.yaml      # starter storyboard (compact form)
praxinoscope scenes                  # every scene type and its fields
praxinoscope check board.yaml        # every problem, with fix hints; exit 1 if any
praxinoscope render board.yaml out.mp4 [--aspect 9:16] [--scale 0.5]
```

```python
import praxinoscope as px
px.check(board)                      # [] or list of problem strings; board = path, YAML text, dict or list
px.render(board, "out.mp4")
```

Compact storyboard: scene fields sit directly on the scene, `id` is optional, `caption: "..."` is the first-language caption, meta keys (`title`, `languages`, `aspect`) may sit at the top level.

```yaml
title: "My explainer"
scenes:
  - {type: title, title: "SAIL", subtitle: "A short explainer", caption: "One file in, one video out."}
  - {type: counter, value: 98, unit: seconds, caption: "The first episode ran 98 seconds."}
  - {type: merge, count: 27, unit: nations, result: "RED STORM", caption: "27 nations formed one mission."}
  - {type: end, lines: ["Made with praxinoscope"]}
```

## Docs

- [Agent guide](src/praxinoscope/data/GUIDE.md): the write, check, render loop, the compact form, caption limits, command reference. `praxinoscope guide` prints it with the generated scene reference appended.
- [README](README.md): install (needs Pango with GObject introspection and ffmpeg), architecture, writing scene types and themes.
- [AGENTS.md](AGENTS.md): working on this repository (setup, tests, conventions).
- [Example storyboard](examples/sail/storyboard.yaml): canonical form, bilingual (en + zh).

## Optional

- JSON Schema with typed per-scene fields: `praxinoscope schema` or `praxinoscope.json_schema()`.
- Canonical form of a compact storyboard: `praxinoscope expand board.yaml`.
