Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

docs: rewrite the README for textbooks and picture books

yzr26024e082053
diff --git a/.gitignore b/.gitignore
index 8a6f3e1..d8cee9c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,8 @@ __pycache__/
!/img/readme/logo_light.png
!/img/readme/papermorph-preview.gif
!/img/readme/papermorph-preview.mp4
+!/img/readme/physics-pulleys.webp
+!/img/readme/joke-collection.webp
/books/
/content/
/tools/
diff --git a/README.md b/README.md
index cdd49f0..430c318 100644
--- a/README.md
+++ b/README.md
@@ -7,108 +7,120 @@
</p>
<p align="center">
- <strong>A Skill that turns PDFs into animated interactive web books.</strong>
+ <strong>A Claude Code Skill that turns textbooks into narrated, interactive web lessons,<br>and stories into paper-puppet films.</strong>
</p>
-You've seen Opus 5.5 one-shot videos.
-This Skill takes it further: books you can explore, listen to, and interact with.
-
<p align="center">
- <a href="https://papermorph.diamonddoge.org/">Explore the live bookshelf →</a>
+ <a href="https://papermorph.diamonddoge.org/">Open the live bookshelf →</a>
·
- <a href=".claude/skills/papermorph/SKILL.md">Use the Skill</a>
+ <a href=".claude/skills/papermorph/SKILL.md">Read the Skill</a>
</p>
<p align="center">
- <a href="img/readme/papermorph-preview.mp4">
- <img src="img/readme/papermorph-preview.gif" alt="Real demo: bookshelf, animated lessons, and interactive quizzes" width="900">
+ <a href="https://papermorph.diamonddoge.org/">
+ <img src="img/readme/papermorph-preview.gif" alt="The bookshelf, an animated lesson and a quiz" width="900">
</a>
- <br>
- <a href="img/readme/papermorph-preview.mp4">Watch the full 75-second demo with narration</a>
</p>
-```text
-PDF -> A short conversation (style.json) -> Storyboards -> Narration -> Animation & quizzes -> Web book
-```
+## What you can make
-The Skill starts by asking: it finds your PDF, says what the book is, suggests a chapter to try and an animation tier, and offers options at every step, so you can just pick the recommended one. Your choices are saved in `style.json`, the style every later chapter is made against.
+| You give it | You get | On the shelf |
+|---|---|---|
+| A textbook PDF (maths) | Lessons where formulas and diagrams change step by step as the narration explains, with quick checks and chapter practice that grade the maths, not the string | [Elementary Algebra](https://papermorph.diamonddoge.org/elementary-algebra/) (68 chapters), [Elementary Mathematics](https://papermorph.diamonddoge.org/math-notebook/) (23) |
+| A textbook PDF (science) | Illustrated scenes with acting characters and camera work, plus the same quizzes | [Elementary Physics](https://papermorph.diamonddoge.org/science/) (9 chapters and a sample) |
+| A story, a joke or a fairy tale | A short film of paper puppets in front of sets drawn in code or painted by an image model, with voices, subtitles, sound effects and music | [Joke Collection](https://papermorph.diamonddoge.org/joke-collection/) (7 episodes), [Little Red Riding Hood](https://papermorph.diamonddoge.org/little-red-riding-hood/) |
-**Today:** Built with Opus 5.5, and tested with other models (see [Models](#models)). No image models, multilingual support, or BGM yet.
-
-## Roadmap
-
-- [x] **Math books:** formulas and diagrams that change step by step, with quizzes. Two books on the shelf.
-- [ ] **Physics books:** illustrated scenes, acting characters and camera work. Chapters 9–12 are on the shelf; chapter 12 was made by the new Skill.
-- [x] **Picture books:** short films of paper puppets from a story, a joke or a fairy tale; sets drawn in code or painted by an image model. *Little Red Riding Hood* and *Joke Collection* are on the shelf.
-- [ ] **Humanities documentaries:** history and social science titles.
+<p align="center">
+ <a href="https://papermorph.diamonddoge.org/science/ch12/"><img src="img/readme/physics-pulleys.webp" alt="Elementary Physics: one fixed pulley changes the direction of the pull; two pulleys halve the force" width="49%"></a>
+ <a href="https://papermorph.diamonddoge.org/joke-collection/ch03/"><img src="img/readme/joke-collection.webp" alt="Joke Collection: paper puppets on a painted farm, foreign lines with English subtitles" width="49%"></a>
+</p>
-Along the way, the bookshelf grows and new Skills are released.
+Everything is a static web page: no server, no database, no account. A book is a folder you can host anywhere.
## Get started
-Install in your project directory:
+Install the Skill in your project:
```bash
npx skills add DozenTwelve/Papermorph --skill papermorph --agent claude-code
```
-In Claude Code with Opus 5.5, run:
+Then, in Claude Code:
```text
/papermorph
```
-It looks for the PDF in your project, then asks the rest. Diagrams that change (tier 1) suit maths and other abstract topics; illustrated scenes (tier 2) suit physics and stories. For a picture book, bring a story instead of a PDF. Documentaries are coming.
+It finds the PDF in your project (or asks for your story), tells you what kind of book it is, suggests a chapter to try first and how much animation it needs, and offers a recommended option at every step. Your choices are saved in `style.json`, so every later chapter is made to the same style.
+
+You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`uv run --with playwright playwright install chromium firefox`). Narration uses Edge TTS (online) or Kokoro (local). Painted sets for picture books need an image-model API key; everything else runs without one.
-Before you review a chapter, `scripts/lint.py` catches broken names, missing audio and stale narration in under a second.
+## How it works
-## Player and engine
+**Textbooks:** the PDF is split into chapters → each chapter gets a beat plan and narration → the narration is voiced, and every word gets a time → the picture is laid out as a storyboard first, then animated in time with those words → quizzes go between the steps → the model watches its own output (contact sheets, overlap and blank-frame checks, end-to-end tests) and fixes what it sees.
-Every book plays in the same player: speed control (`<` `>`), click anywhere on a step to jump there, captions, keyboard shortcuts, and progress saved per book.
+**Picture books:** your telling becomes a script and a shot list → puppets and sets are built (or painted) once and reused across episodes → voices, mouth shapes, sound effects and music are made and joined per scene → scenes are filmed in parallel → review rounds (a director, picture reviewers and a sound reviewer) send scenes back until they hold up next to approved episodes.
-The player engine lives in [`engine/`](engine), apart from the Skill, so a fix reaches every book without touching the Skill. Fork it if you like, and point the Skill at your fork:
+Large chapters can be made by a team of subagents, each step on the model that suits it ([team.md](.claude/skills/papermorph/references/team.md)).
+
+## The player
+
+Every book plays in the same player: pause anywhere, step back and forth, click a step to jump there, speed control, captions, keyboard shortcuts, and progress saved per book. Interface text follows the book's language (`<html lang>`: English, Russian, Chinese and Japanese are built in); foreign lines in a film are subtitled. Formulas can be written in LaTeX (MathJax, copied only into the books that use it).
+
+The player engine lives in [`engine/`](engine), apart from the Skill, and every book keeps its own copy, so a book never breaks when the engine changes. To update the books, or to use your own fork:
```bash
+python3 .claude/skills/papermorph/scripts/engine.py site # sync every book in site/
python3 .claude/skills/papermorph/scripts/engine.py site --from you/your-fork@main
```
-## Export to video
+## Video and LMS export
-Any chapter can be rendered to MP4 (1080p) with an `.srt` for YouTube or Bilibili:
+With the site served locally, any chapter or episode renders to a 1080p MP4 with an `.srt`:
```bash
-uv run --with playwright .claude/skills/papermorph/scripts/export.py ch12 \
+uv run --with playwright --with numpy .claude/skills/papermorph/scripts/export.py ch12 \
--url http://localhost:8765/science/ --link https://papermorph.diamonddoge.org/science/ch12/
```
-Frames come straight from the lesson clock, so the video matches the page. Quizzes stay in the interactive version; the video ends by pointing there.
+Frames are rendered from the lesson clock, so the video matches the page exactly; quizzes stay in the interactive version, and the video ends by pointing there.
+
+For courses, a book can also be packaged for an LMS as SCORM 1.2 or 2004 (`scripts/scorm.py`), and a book can opt in to verified citation links and reviewed question banks ([authoring.md](.claude/skills/papermorph/references/authoring.md)). None of this is on by default.
-## Models
+## Models and cost
-The Skill is not tied to one model. Books on the shelf show the results:
+The Skill is not tied to one model: the books on the shelf were made with Opus 5.5, GPT-6.1-Sol and Sonnet 5.5.
-- **Opus 5.5:** most of the books, including the physics chapters.
-- **GPT-6.1-Sol:** runs the Skill well. See *Elementary Mathematics*, chapters 4–20.
-- **Sonnet 5.5:** works, with some rough edges. See *Elementary Mathematics*, chapters 21–22.
+An illustrated physics chapter costs about $10–18 of model usage. The painted sets of a picture-book episode cost under $0.20.
-## Official alternative
+## Roadmap
+
+- [x] **Maths books:** formulas and diagrams that change step by step, with quizzes.
+- [x] **Science books:** illustrated scenes, acting characters, camera work.
+- [x] **Picture books:** paper-puppet films from a story, a joke or a fairy tale.
+- [ ] **Choosing the model for every step**, with defaults that depend on how much animation a book needs.
+- [ ] **Documentaries:** history and social-science titles.
-Claude now offers official animated explainers ([Claude Motion](https://claude.com/resources/articles/dashboards-and-motion), in beta), which overlap with much of what this Skill does. For token efficiency, the official tool may be the better choice.
+## FAQ
-I will still finish Papermorph along its roadmap. Building it is worth it to me.
+**How is this different from Claude Motion?** [Claude Motion](https://claude.com/resources/articles/dashboards-and-motion) makes animated explainers. Papermorph makes whole books: many chapters in one consistent style, quizzes that are graded, progress that is saved, and a static site you own and can host anywhere.
+
+**Can I make a book from any PDF?** Yes, for your own use. The finished book contains new explanations and drawings, not the PDF's pages, but publishing a book based on someone else's textbook is your call to check.
## Contributing
-Fixes to the Skill and the player are welcome. Please do not open pull requests that add a book, its PDF, or generated lessons, audio or videos: those raise copyright issues.
+Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one.
## Try the examples locally
```bash
-git clone https://github.com/DozenTwelve/Papermorph.git
+git clone --depth 1 https://github.com/DozenTwelve/Papermorph.git
cd Papermorph
-python3 -m http.server 8765 -d site
+python3 .claude/skills/papermorph/scripts/serve.py 8765 site
```
-Open [localhost:8765](http://localhost:8765/)
+Then open [localhost:8765](http://localhost:8765/). (The full history is large; `--depth 1` skips it.)
+
+## License
-[MIT License](LICENSE)
+[MIT](LICENSE). The bundled MathJax (`engine/vendor/mathjax`) is under the Apache License 2.0.
diff --git a/img/readme/joke-collection.webp b/img/readme/joke-collection.webp
new file mode 100644
index 0000000..853bb8c
Binary files /dev/null and b/img/readme/joke-collection.webp differ
diff --git a/img/readme/physics-pulleys.webp b/img/readme/physics-pulleys.webp
new file mode 100644
index 0000000..9973ad7
Binary files /dev/null and b/img/readme/physics-pulleys.webp differ