An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
docs: rewrite the README for textbooks and picture books
yzr26024e082053
diff --git a/.gitignore b/.gitignoreindex 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.mdindex 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:```bashnpx 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.gitcd 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.webpnew file mode 100644index 0000000..853bb8cBinary files /dev/null and b/img/readme/joke-collection.webp differdiff --git a/img/readme/physics-pulleys.webp b/img/readme/physics-pulleys.webpnew file mode 100644index 0000000..9973ad7Binary files /dev/null and b/img/readme/physics-pulleys.webp differ