Skip to content

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

docs(skill): SKILL.md routes to two paths, with a table of the scripts

yzr021e054db307
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index 959aab8..163e304 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -5,13 +5,24 @@ description: Make or edit animated, narrated, interactive web books from referen
# Papermorph
-Each chapter is a short animated lesson film: the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included). Technically a chapter is one 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions.
+Papermorph makes two kinds of book on one machine:
-What the picture should be depends on the book and on the user, so the work starts with a conversation ([intake.md](references/intake.md)) that ends in `style.json`, the book's agreed style. Every chapter is made against it. `style.json` fixes the atoms (palette and meanings, fonts, voice, cast, shared components, approved chapters); composition stays free, so how each beat is laid out and choreographed is yours to judge against it and the approved chapters. Then read the reference for the technique in use: [diagrams.md](references/diagrams.md) (symbols and diagrams that change), [scenes.md](references/scenes.md) (illustrated scenes, actors, camera), [assets.md](references/assets.md) (shared components, images, sprites), [authoring.md](references/authoring.md) (chapter shape, narration, questions), [engine.md](references/engine.md), [review.md](references/review.md), [site.md](references/site.md), [team.md](references/team.md) (making chapters with subagents), [courses.md](references/courses.md) (options for course books).
+- **Lessons**, from a textbook PDF: each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture.
+- **Picture books**, from a story, a joke or a fairy tale: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music.
-**Picture books** are the same machine pointed at a story: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music. When the user brings a story, a joke or a fairy tale instead of a textbook, follow [stories.md](references/stories.md) (with [puppets.md](references/puppets.md), [painting.md](references/painting.md) and [sound.md](references/sound.md)) in place of the PDF steps. The engine, previews and team work the same; a film is reviewed in rounds as [stories.md](references/stories.md#review-rounds) describes, and [site.md](references/site.md#a-picture-book) starts its folder.
+Both are a 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included).
-Follow the pipeline forward, entering at the requested stage for existing work. User requests override defaults. Re-create explanations, examples and drawings; keep source PDFs, page images and extracted text outside the static output folder and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`). Deliver a self-contained book folder with a cover, contents, chapters and local preview instructions.
+What the picture should be depends on the book and on the user, so the work starts with a conversation that ends in `style.json`: the user's words, the look they chose, the voices, which model does which step, and later the approved chapters. Every chapter is made against it; how each beat is laid out and choreographed is yours to judge against it and the approved chapters. User requests override defaults. Re-create explanations, examples and drawings; keep source PDFs, page images and extracted text outside the static output folder and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`). Deliver a self-contained book folder with local preview instructions.
+
+## Which path
+
+| The user brings | Path | Read |
+|---|---|---|
+| A textbook PDF | [Lessons](#lessons) | [intake.md](references/intake.md), then [diagrams.md](references/diagrams.md) (tier 1) or [scenes.md](references/scenes.md) (tier 2), [authoring.md](references/authoring.md), [assets.md](references/assets.md), [review.md](references/review.md) |
+| A story, a joke, a fairy tale, or a story book's PDF | [Picture books](#picture-books) | [stories.md](references/stories.md), [puppets.md](references/puppets.md), [sound.md](references/sound.md), [painting.md](references/painting.md) for a painted look |
+| A course book (cites works, reviewed questions, an LMS) | Lessons plus options | [courses.md](references/courses.md), only when the book calls for them |
+
+Both paths share [site.md](references/site.md) (the book folder, cover or series page, preview, video export), [engine.md](references/engine.md) (the player and drawing API), [team.md](references/team.md) (making chapters with subagents) and the models step of [intake.md](references/intake.md#5-models). Read only the reference the current step needs.
## Project layout
@@ -39,7 +50,9 @@ A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `sto
`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`), github.com for `engine.py` when the repository's `engine/` folder is not at hand, and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
-## Pipeline
+## Lessons
+
+### Pipeline
Start with intake whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given.
@@ -51,7 +64,7 @@ Start with intake whenever `books/<book>/style.json` does not exist yet; reuse a
A course book may also want verified citation links, a reviewed question bank or a SCORM package for an LMS; offer them only when the book calls for them ([courses.md](references/courses.md)).
-## Chapter loop
+### Chapter loop
1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach.
2. **Beats and narration**: list beats in `chapters/chNN.md` with what each says and which word triggers which action ([authoring.md](references/authoring.md)). Write `content/<book>/chNN/narration.<lang>.json`, then `uv run --with edge-tts SKILL/scripts/tts.py content/<book>/chNN/narration.<lang>.json site/<book>/chNN/audio/<lang>` (for `"engine": "kokoro"`: `uv run --python 3.12 --with kokoro …`).
@@ -60,9 +73,26 @@ A course book may also want verified citation links, a reviewed question bank or
5. **Delivery pass**: watch your output in motion and judge it as a viewer would, against the storyboard; then run the checks in [review.md](references/review.md). Correct what you find, recheck, deliver; report unresolved problems.
6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. The coordinator owns this step when using subagents.
+## Picture books
+
+Start with the story intake in [stories.md](references/stories.md#intake-for-a-story) whenever `books/<book>/style.json` does not exist yet; agree the models ([intake.md](references/intake.md#5-models)) and write `style.json`. Then follow [the order of work](references/stories.md#the-order-of-work): the script and storyboard shown to the user before anything is built, the book folder ([site.md](references/site.md#a-picture-book)), sound, sets, scenes, [review rounds](references/stories.md#review-rounds), and the user's viewing of the first cut. Each episode is a chapter (`chNN`); a series shares its cast, sets and series page.
+
+## Scripts
+
+All in `SKILL/scripts/`; each prints its usage with `--help` (run it with the `uv run --with …` its docstring names).
+
+| For | Scripts |
+|---|---|
+| Every book | `serve.py` preview without caching · `engine.py` sync the engine into books · `tts.py` narration and word times · `lint.py` static checks · `shot.py` beat screenshots · `strip.py` storyboard sheets and motion strips · `check_blank.py` empty openings · `still.py` stretches where nothing moves · `perf.py` Firefox frame times · `export.py` MP4 and `.srt` |
+| Lessons | `outline.py` and `split_pages.py` page map and chapter text · `overlap.py` arrows through text · `sprites.py` image processing steps |
+| Picture books | `mouths.py` mouth shapes · `join.py` one clip per scene · `sfx.py` synthesized effects · `bake_sets.py` set layers · `bake_puppets.py` puppet bitmaps · `paint.py` / `paint_openai.py` image-model pictures · `painted.py` place them in the book |
+| Course options | `refs.py` verified citations · `items.py` question bank · `scorm.py` LMS package |
+
+`silence.py`, `ledger.py` and `browsers.py` are helpers the others import.
+
## Context
-- Keep intake and the pilot in the main conversation. Afterwards, when subagents are available, coordinate each chapter as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.
+- Keep intake and the pilot in the main conversation. Afterwards, when subagents are available, coordinate each chapter as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another ([team.md](references/team.md)); a picture book splits by scene instead ([team.md](references/team.md#picture-books)). Without subagents, run the same loop in the current agent with file-based state.
- A worker needs little besides this Skill and `style.json`: the user's words, the look, the approved chapters to watch and read, the element library. A brief adds the chapter, its pages, the step's inputs and outputs and any current user request. Workers reply in a few lines; the coordinator registers the chapter.
-- Read only the reference needed for the current step. Use the engine API and inspect individual functions when needed; copy assets rather than reading their full source as instructions.
+- Use the engine API and inspect individual functions when needed; copy assets rather than reading their full source as instructions.
- Keep `style.json` current and short. Chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.
diff --git a/.claude/skills/papermorph/references/puppets.md b/.claude/skills/papermorph/references/puppets.md
index 13ab38e..762690f 100644
--- a/.claude/skills/papermorph/references/puppets.md
+++ b/.claude/skills/papermorph/references/puppets.md
@@ -25,7 +25,13 @@ Two cast styles are on the shelf, both on the same `paper.js`: round-headed figu
## Performance
-Paper filters are expensive live. Every finished piece is baked to a bitmap: sets with `bake_sets.py` (SVG sketches) or `painted.py` (painted pictures), puppet and prop pieces with `bake_puppets.py`, which seeks every episode to its end, in Chromium and in Firefox, so each piece is asked for once, and writes `img/puppets/<hash>.webp` with `baked.js`. The parts that change every frame (eyes, mouths, brows, fingers) stay live. In a series every episode's pieces share one folder: `bake_puppets.py` encodes only pieces it has not baked before and keeps the others, and `--clean` (after changing the paper filter itself) re-encodes them all and removes only what no episode asks for any more, so leave the folder to it (a hand-written prune once deleted a published episode's pieces; git brought them back). Rebake after changing any piece or adding an episode; a piece missing from `baked.js` is baked in the browser and costs a stall, and `shot.py` says how many pieces a chapter still bakes live. Full-frame effects that change every frame (the flicker) live outside the SVG so the picture isn't redrawn each frame.
+Paper filters are expensive live, so every finished piece is baked to a bitmap; the parts that change every frame (eyes, mouths, brows, fingers) stay live.
+
+- Sets: `bake_sets.py` (SVG sketches) or `painted.py` (painted pictures).
+- Puppet and prop pieces: `bake_puppets.py` seeks every episode to its end, in Chromium and in Firefox, so each piece is asked for once, and writes `img/puppets/<hash>.webp` with `baked.js`.
+- In a series every episode's pieces share one folder. `bake_puppets.py` encodes only pieces it has not baked before and keeps the others; `--clean` (after changing the paper filter itself) re-encodes them all and removes only what no episode asks for any more. Leave the folder to it: a hand-written prune once deleted a published episode's pieces.
+- Rebake after changing any piece or adding an episode. A piece missing from `baked.js` is baked in the browser and costs a stall; `shot.py` says how many pieces a chapter still bakes live.
+- Full-frame effects that change every frame (the flicker) live outside the SVG, so the picture isn't redrawn each frame.
## Seeing your own work
diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.md
index 92334c1..3a34b47 100644
--- a/.claude/skills/papermorph/references/sound.md
+++ b/.claude/skills/papermorph/references/sound.md
@@ -14,7 +14,11 @@ Voices carry the story; everything else sits under them. In early cuts the music
## Sound effects
-`sfx.py` synthesizes effects (knock, door, creak, latch, bell, chop, bang, bonk, thud, clang, crash, coin, beep, rain, wind, room tone, surf, gulls, crickets, steps and more; `--list` names them all) as small MP3s, free and consistent. Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain. An effect is placed on the scene clock with `sfx(scene, t, name, volume)` and plays at half volume under the voices; a pause holds it and the next scene stops it. Cut an effect to its shot: a six-second rain under a one-second shot spills into the next. A long bed (wind, room tone) is listed in `SFX_BED` with its length, so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second, and room tone runs under the silences too, where its absence is heard first.
+`sfx.py` synthesizes effects as small MP3s, free and consistent (knock, door, creak, bell, chop, crash, coin, rain, wind, room tone, surf, gulls, crickets, steps, a dog and more; `--list` names them all). Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain.
+
+- Place an effect on the scene clock with `sfx(scene, t, name, volume)`; it plays at half volume under the voices, a pause holds it and the next scene stops it.
+- Cut an effect to its shot: a six-second rain under a one-second shot spills into the next.
+- A long bed (wind, room tone) is listed in `SFX_BED` with its length, so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second, and room tone runs under the silences too, where its absence is heard first.
## Music
diff --git a/.claude/skills/papermorph/scripts/join.py b/.claude/skills/papermorph/scripts/join.py
index 0417365..9ce8f17 100644
--- a/.claude/skills/papermorph/scripts/join.py
+++ b/.claude/skills/papermorph/scripts/join.py
@@ -23,17 +23,7 @@ if len(sys.argv) < 3 or sys.argv[1] in ('-h', '--help'):
GAP = .35
LAG = .12 # Edge's word times run ~0.12–0.25 s ahead of the sound: captions (and mouths.py's cues) start this much later
d = pathlib.Path(sys.argv[1]); T = json.loads((d / 'timings.js').read_text().split('=', 1)[1].rstrip().rstrip(';'))
-def speech_end(f): # where a clip's sound stops (the start of its trailing silence), in seconds
- err = subprocess.run(['ffmpeg', '-v', 'info', '-i', str(f), '-af', 'silencedetect=n=-40dB:d=0.15', '-f', 'null', '-'], capture_output=True, text=True).stderr
- starts = [float(x) for x in re.findall(r'silence_start: ([\d.]+)', err)]
- ends = [float(x) for x in re.findall(r'silence_end: ([\d.]+)', err)]
- dur = float(subprocess.run(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', str(f)], capture_output=True, text=True).stdout)
- # the last silence runs to the end of the file (ffmpeg may print its end there, just inside
- # the mp3's priming padding): an end well before the file's duration is a pause inside the clip
- return starts[-1] if starts and (len(ends) < len(starts) or ends[-1] > dur - .2) and starts[-1] > 0 else dur
-def pauses(f): # start of every pause of 0.45 s or more inside a clip: a caption ends at the pause after its words
- err = subprocess.run(['ffmpeg', '-v', 'info', '-i', str(f), '-af', 'silencedetect=n=-40dB:d=0.45', '-f', 'null', '-'], capture_output=True, text=True).stderr
- return [float(x) for x in re.findall(r'silence_start: ([\d.]+)', err)]
+from silence import speech_end, pauses # a caption ends at the pause after its words
args, words = sys.argv[2:], None
if '--words' in args:
k = args.index('--words'); words = pathlib.Path(args[k + 1]); del args[k:k + 2]
diff --git a/.claude/skills/papermorph/scripts/mouths.py b/.claude/skills/papermorph/scripts/mouths.py
index a41610e..b0d328b 100644
--- a/.claude/skills/papermorph/scripts/mouths.py
+++ b/.claude/skills/papermorph/scripts/mouths.py
@@ -30,14 +30,7 @@ def shapes(word):
out = [x for j, x in enumerate(s) if j == 0 or x != s[j - 1]]
return out or ['B']
LAG = .12 # Edge's word times run ahead of the sound (join.py has the same)
-def speech_end(f): # where the clip's sound stops: the mouth shuts there, not .55 s after the last word starts
- err = subprocess.run(['ffmpeg', '-v', 'info', '-i', str(f), '-af', 'silencedetect=n=-40dB:d=0.15', '-f', 'null', '-'], capture_output=True, text=True).stderr
- starts = [float(x) for x in re.findall(r'silence_start: ([\d.]+)', err)] # paired with ends; a leading silence is skipped below
- ends = [float(x) for x in re.findall(r'silence_end: ([\d.]+)', err)]
- dur = float(subprocess.run(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', str(f)], capture_output=True, text=True).stdout or 0)
- # only a silence that never ends (or runs to the file's end, inside mp3 priming padding) is
- # trailing: an internal silence means speech resumes after it, and the mouth cues past it must stay
- return starts[-1] if starts and (len(ends) < len(starts) or ends[-1] > dur - .2) and starts[-1] > .2 else dur
+from silence import speech_end # the mouth shuts where the sound stops, not .55 s after the last word starts
res = {}
for beat, e in cache.items():
words, dur, cues = e['words'], e['dur'], []
diff --git a/.claude/skills/papermorph/scripts/silence.py b/.claude/skills/papermorph/scripts/silence.py
new file mode 100644
index 0000000..6eb7f9f
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/silence.py
@@ -0,0 +1,23 @@
+"""Where speech stops and pauses in a narration clip, from ffmpeg's silencedetect; shared by join.py and mouths.py."""
+import re, subprocess
+
+
+def _detect(f, d):
+ err = subprocess.run(['ffmpeg', '-v', 'info', '-i', str(f), '-af', f'silencedetect=n=-40dB:d={d}', '-f', 'null', '-'],
+ capture_output=True, text=True).stderr
+ return [float(x) for x in re.findall(r'silence_start: ([\d.]+)', err)], [float(x) for x in re.findall(r'silence_end: ([\d.]+)', err)]
+
+
+def speech_end(f):
+ """Where the clip's sound stops: the start of its trailing silence, in seconds (the clip's length without one).
+ Only a silence that never ends, or ends at the file's end (just inside the mp3's priming padding), is trailing;
+ an internal silence means speech resumes after it. A silence in the first 0.2 s is the lead-in, not an end."""
+ starts, ends = _detect(f, .15)
+ dur = float(subprocess.run(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', str(f)],
+ capture_output=True, text=True).stdout or 0)
+ return starts[-1] if starts and (len(ends) < len(starts) or ends[-1] > dur - .2) and starts[-1] > .2 else dur
+
+
+def pauses(f):
+ """The start of every pause of 0.45 s or more inside a clip."""
+ return _detect(f, .45)[0]