Skip to content

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

docs(skill): pandemic shorts lessons, the map kit, engine-v2.7

yzr2e985e101c1c
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index 2e9cbdd..f241898 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -55,7 +55,7 @@ A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `sto
A documentary adds `books/<book>/storyboard.md`, `art/` (`found/` with the downloaded pictures, the `prep.py` list, generated clips, `costs.tsv`) and `music/`, where `commons.py` keeps a `SOURCES.tsv` beside its downloads; its `site/<book>/lib/` holds `film.js`, `fonts.css` and `fonts/` from `assets/templates/documentary/` (its `book.css` too, with the film's colours) and, when the film uses them, `lines.js` (`trace.py`); `img/` holds the treated pictures with `art.js` (`prep.py`) and clip sheets with `frames.js` (`frames.py`); `index.html` is the series page with the credits; each film `chNN/` has `audio/<lang>/` and `audio/bgm/`.
-A series of shorts adds `books/<book>/chNN-script.md` (the outline, the beats with what we see, the sources), `art/` (generated and found pictures, `costs.tsv`) and `music/`; its `site/<book>/lib/` holds `shorts.js`, `book.css` and `icons.js` from `assets/templates/shorts/` with the documentary kit's fonts, and a second file of the series' own pieces loaded after `shorts.js`; each episode `chNN/` has `audio/<lang>/`, `audio/sfx/` and `audio/bgm/`.
+A series of shorts adds `books/<book>/chNN-script.md` (the outline, the beats with what we see, the sources), `art/` (generated and found pictures, `costs.tsv`) and `music/`; its `site/<book>/lib/` holds `shorts.js`, `book.css` and `icons.js` from `assets/templates/shorts/` with the documentary kit's fonts, and a second file of the series' own pieces loaded after `shorts.js`; `img/` holds the pictures with `art.js` (`prep.py`); a film with a map, in either tier, adds `map.js` and `globe.js` from `assets/templates/maps/lib/` and `img/geo-lite.js` (`geo.py`); each episode `chNN/` has `audio/<lang>/`, `audio/sfx/` and `audio/bgm/`.
`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, an OpenRouter key only for the paid steps the user chooses (`paint.py`, `eleven.py`, `video.py`; `paint_openai.py` takes an OpenAI key), 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).
@@ -96,14 +96,14 @@ Start with the questions in [shorts.md](references/shorts.md#questions-for-the-u
## Scripts
-All in `SKILL/scripts/`; each prints its usage with `--help`, run with the `uv run --with …` its docstring names (its first lines; without its packages even `--help` stops on the import). Packages: playwright for every script that opens a page (shot, strip, still, check, perf, safe, export, music, playlog, overlap, check_blank, bake_sets, bake_puppets), pillow for the ones that write pictures (shot, strip, still, playlog, bake_*, prep, frames, painted, sprites, trace), numpy for strip, export, `music.py gaps`, prep, frames, sfx and eleven, faster-whisper for eleven, pymupdf for outline and split_pages, scikit-image for trace, edge-tts or kokoro for tts; the rest need only Python and ffmpeg.
+All in `SKILL/scripts/`; each prints its usage with `--help`, run with the `uv run --with …` its docstring names (its first lines; without its packages even `--help` stops on the import). Packages: playwright for every script that opens a page (shot, strip, still, check, perf, safe, export, music, playlog, overlap, check_blank, bake_sets, bake_puppets), pillow for the ones that write pictures (shot, strip, still, playlog, bake_*, prep, frames, painted, sprites, trace, `geo.py --globe`), numpy for strip, export, `music.py gaps`, prep, frames, sfx and eleven, faster-whisper for eleven, pymupdf for outline and split_pages, scikit-image for trace, edge-tts or kokoro for tts; the rest need only Python and ffmpeg.
| 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 · `check.py` page errors, console warnings and beat lengths in Chromium and Firefox · `shot.py` beat screenshots · `strip.py` storyboard sheets and motion strips · `still.py` stretches where nothing moves · `perf.py` Firefox frame times, with the machine's load and a reference moment · `export.py` MP4 and `.srt` · `level.py` even loudness |
| Lessons | `outline.py` and `split_pages.py` page map and chapter text · `check_blank.py` empty openings · `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 · `playlog.py` sounds and captions against the picture · `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 |
-| Documentaries | `commons.py` public-domain pictures and recordings with their licences · `prep.py` print and line treatments · `trace.py` drawings that draw themselves on · `video.py` a clip from a still · `frames.py` a clip as treated frames · `eleven.py` ElevenLabs narration with word times and `--tempo` · `music.py` a music track cut to the film, and the bed in the voice's gaps and at the end · `safe.py` words outside an upright film's safe area |
+| Documentaries | `commons.py` public-domain pictures and recordings with their licences · `prep.py` print and line treatments · `trace.py` drawings that draw themselves on · `video.py` a clip from a still · `frames.py` a clip as treated frames · `eleven.py` ElevenLabs narration with word times and `--tempo` · `music.py` a music track cut to the film, and the bed in the voice's gaps and at the end · `safe.py` words outside an upright film's safe area · `geo.py` the map kit's countries, regions, cities and globe from Natural Earth |
| Course options | `refs.py` verified citations · `items.py` question bank · `scorm.py` LMS package |
`silence.py`, `ledger.py` (the one cost ledger: date, chapter, file, model, what, cost) and `browsers.py` are helpers the others import.
diff --git a/.claude/skills/papermorph/references/documentary.md b/.claude/skills/papermorph/references/documentary.md
index 0fd29bd..940e6fe 100644
--- a/.claude/skills/papermorph/references/documentary.md
+++ b/.claude/skills/papermorph/references/documentary.md
@@ -19,10 +19,10 @@ Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/
## The order of work
-1. **Research and the script.** Read the source, then write the narration (`content/<book>/chNN/narration.en.json` in the format of [authoring.md](authoring.md#narration), one beat per paragraph, `[[mark]]` before each word a picture lands on) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture). Show both to the user before anything is built. The hard part of a documentary is the argument and the storyboard, not the animation.
+1. **Research and the script.** Read the source, and trace every number and quote to where it was first said: a figure found on Wikipedia goes back to the speech or report Wikipedia cites, and that is the source to tag (Wikipedia's "low and middle-income" was the WHO's "low-income"). Read what each date counts, too: the day a virus arrived somewhere is not the day of its first confirmed case. Then write the narration (`content/<book>/chNN/narration.en.json` in the format of [authoring.md](authoring.md#narration), one beat per paragraph, `[[mark]]` before each word a picture lands on) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture). Show both to the user before anything is built. The hard part of a documentary is the argument and the storyboard, not the animation.
2. **The folder.** `engine.py` makes `site/<book>/lib/` first, then the kit's `lib/` is copied over it (its `book.css`, with the film's colours, replaces the default); `chNN/index.html` starts from the kit's `chapter.html`, and the book's `index.html` from the picture-book series page. The commands are in [site.md](site.md#a-documentary).
3. **Pictures.** Find them, record them, treat them (below).
-4. **Voice.** `tts.py` (Edge or Kokoro) or `eleven.py` (ElevenLabs) writes one clip per beat and `timings.js` with the marks; the page cannot tell them apart. `eleven.py` takes the voice and model from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`: the kit's file names an Edge voice), and a line with a `speaker` from that speaker's voice under `voices`. It levels every clip to −14 LUFS with its peak under −1.5 dBTP and prints the loudness it delivered (`--lufs` for another level, `--no-level` to leave the clips as the service sent them, about −23 LUFS), keeps paid clips cached (a rerun costs nothing, and a clip levelled in place by `level.py` stays levelled), prints the cost before paying (`--dry` stops there), and `--only beat,beat` makes a fresh, paid take of those beats and leaves the others alone. A line in another language takes a `sub`, as in `tts.py` ([sound.md](sound.md#voices)). Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now; `--help` has the rest.
+4. **Voice.** `tts.py` (Edge or Kokoro) or `eleven.py` (ElevenLabs) writes one clip per beat and `timings.js` with the marks; the page cannot tell them apart. `eleven.py` takes the voice and model from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`: the kit's file names an Edge voice), and a line with a `speaker` from that speaker's voice under `voices`. It levels every clip to −14 LUFS with its peak under −1.5 dBTP and prints the loudness it delivered (`--lufs` for another level, `--no-level` to leave the clips as the service sent them, about −23 LUFS), keeps paid clips cached (a rerun costs nothing, and a clip levelled in place by `level.py` stays levelled), prints the cost before paying (`--dry` stops there), and `--only beat,beat` makes a fresh, paid take of those beats and leaves the others alone. A voice sped up (`--tempo 1.1`, or `"tempo"` in the narration file) is sped before levelling and alignment, and stays sped on a rerun. A line in another language takes a `sub`, as in `tts.py` ([sound.md](sound.md#voices)). Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now; `--help` has the rest.
5. **Music.** Find recordings (`commons.py --audio`), bring them to one loudness (`level.py`), and give each part of the film its track with `music(file, beats, gain, fade)` ([engine.md](engine.md#player)).
6. **The beats**, built from the kit's helpers and timed to the marks.
7. **Review rounds** (below), then the user's viewing, then `export.py` for a video if the user wants one ([site.md](site.md#video-export-optional)). Putting the film on a bookshelf is a separate task.
@@ -35,7 +35,7 @@ Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/
- *line*: an engraving's dark lines turn into the ground's ink colour and the paper drops out, so the figure stands on the ground itself. Woodcuts and engravings with clean lines.
- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. It is striking once or twice; on every picture it becomes a tic.
- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up one that was interrupted. On the first film it worked best when rare.
-- **Maps.** A coastline from Natural Earth (public domain) as one SVG path in the film's box, a route drawn on with `along()`. There is no projection script: project the coastline's longitudes and latitudes into the box yourself (a few lines of code), or draw the path by hand. A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe).
+- **Maps** have their own kit ([below](#maps)).
## Building the beats
@@ -61,6 +61,14 @@ What made the Foucault film work:
- **The ending gathers the film.** Foucault ends with every era's Fool appearing in turn, and the opening epigraph returns.
- **Words on screen are few**: a key word, a quote being read, a year. Everything else is said.
+## Maps
+
+A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe, a virus leaving one city). The map kit `assets/templates/maps/` serves a documentary and a short alike, on either stage: `lib/map.js` draws a paper map (`paperMap()`) and `lib/globe.js` a night globe (`globeShot()`, three.js), both from one view `{ lon, lat, H }`, so a shot hands over from the globe to the map without a jump. Its data come from `geo.py`: `img/geo-lite.js` with the world's countries, capitals and big cities, plus only what the film shows, since each adds weight: `--regions CHN,ITA:region` (China's provinces, Italy's regions), `--detail Wuhan=114.27,30.58,1.5` (rivers, lakes and built-up areas around a city), `--cities`, and `--globe site/<book>/lib` for the globe (three.js and NASA's Black Marble as `img/night.webp`). Credit "Natural Earth, public domain" and "Black Marble 2016, NASA Earth Observatory, public domain" in the film's sources. The API is the comment at the top of `map.js`; `sample.html` plays every piece (`?wide` on the landscape stage).
+
+Colour says what kind of thing is on the map: `lit` and `region` fill in the subject's colour (`--map-hot`, the book's red), `hatch` and `areas` draw in ink what is not the subject (an order, a lockdown), so the red keeps one meaning. Move a map through its `view(t)` (`mapKeys()` for a camera through keys), never by scaling a group above it: Gecko re-rasters a canvas under a scaled parent. A map or globe draws only inside its `on` window (in a shorts `shot()`, the shot's), since Firefox pays for every drawn canvas, even a covered one. The colours come from `lib/book.css` (`--map-land`, `--map-sea`, `--map-ink`, …) when it sets them.
+
+Without the kit, a coastline from Natural Earth as one SVG path in the film's box, with a route drawn on by `along()`, is enough for one still map (Foucault's Europe).
+
## Interactive moments
A documentary can give the reader a few moments to act, where the story turns on a choice or a deed: in *Shooting an Elephant* the reader looks through the rifle's sight and fires, as Orwell did, and the film goes on from the shot. Open `site/shooting-an-elephant/ch01/index.html` and read `fireAsk` before writing one.
@@ -74,7 +82,9 @@ A documentary can give the reader a few moments to act, where the story turns on
## Review rounds
-After the first cut, an independent director pass: a fresh agent on a strong model, given contact sheets of every beat (`strip.py`) and the reference film, with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them places where the picture contradicted the narration (the wrong figure on screen while another was named). Fix, and show the user each fix on a contact sheet as it is made: a round is then quick to check. Then the user watches the whole film.
+After the first cut, an independent director pass: a fresh agent on a strong model, given contact sheets of every beat (`strip.py`) and the reference film, with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them places where the picture contradicted the narration (the wrong figure on screen while another was named). Fix, and show the user each fix on a contact sheet as it is made: a round is then quick to check.
+
+Then a second round on the exported MP4, by another fresh director who watches it as a viewer would: frames every half second on contact sheets, the first frame alone at full size, the audio transcribed with word times and its loudness measured, each against the script and its sources and against the approved films' exports. This round is the lever: on *The Pandemic*'s six shorts every first cut had passed its worker's own checks and still had one to three must-fix faults, most of them the picture saying something other than the voice ("even the vaccinated" drawn as protection). A director's measurement is checked before it is sent back as work: in that run a loudness reading that no other measurement matched, and a cut "a second late" that was only Whisper starting a word at the pause before it (check a lag against the clip's own silences, not the transcript alone). After the fixes, a quick look of your own at the new MP4's frames still found a wrong date and a dead frame; keep it. Then the user watches the whole film.
## Later
diff --git a/.claude/skills/papermorph/references/shorts.md b/.claude/skills/papermorph/references/shorts.md
index 0cd2ead..77f1a37 100644
--- a/.claude/skills/papermorph/references/shorts.md
+++ b/.claude/skills/papermorph/references/shorts.md
@@ -2,7 +2,7 @@
A short is a narrated film on an upright 900 × 1600 stage (`<html data-stage="portrait">`), made for YouTube Shorts, TikTok, Reels or X. It makes one point in one to three minutes, with a new picture every one to three seconds: full-bleed photographs or generated pictures, big words, cut-out figures, a number counting up, a chart, a map. It is a cousin of the [documentary](documentary.md) and shares its voice, pictures, export and review; what differs is the pace, the grammar of the picture and where it ends up. The worked example is episode 1 of *Madness and Civilization* (`site/madness-shorts/ch01/`, *The Ship*), the ten-minute [documentary](documentary.md) on the shelf (`site/madness/`) recut as a series of shorts: watch it before making one, and treat it as a level to match, not a format to copy.
-What is its own: the kit `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `style.json`; `lib/shorts.js`, `book.css`, `icons.js`; fonts from the documentary kit) and the order of work below. It needs an engine with the upright stage ([engine.md](engine.md#stage-and-state)); an upright chapter is a film without questions.
+What is its own: the kit `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `style.json`; `lib/shorts.js`, `book.css`, `icons.js`; fonts from the documentary kit) and the order of work below. A map or a globe comes from the map kit it shares with the documentary ([documentary.md](documentary.md#maps)). It needs an engine with the upright stage ([engine.md](engine.md#stage-and-state)); an upright chapter is a film without questions.
## What the viewer is doing
@@ -31,28 +31,28 @@ When the user wants a film that already exists recut as shorts (*Madness and Civ
1. **The script, beat by beat, with the user.** Keep it in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (the narration, one line of what we see, and its rough length: words ÷ the voice's pace, about 2.6 words a second for an ElevenLabs narrator, plus about 1.4 s a beat for the engine's hold after the words, 0.6 s, and the camera's tail, 0.8 s in the worked example; a twelve-beat script ran 17 s longer than its words), and each number's and quote's source under it. Show it to the user a few beats at a time and rewrite as they answer. A background beat that comes out over about eight seconds is where the short will feel slow; shorten it before the voice is paid for. Once it is voiced, the length hides in the voice's own sentence pauses (0.4 to 1.0 s from ElevenLabs): `eleven.py --max-pause 0.3` shortens them before the marks are placed (one episode went from 112 s to 107 s). The beats' narration, with `[[mark]]` before each word a picture lands on, goes into `content/<book>/chNN/narration.en.json` (the kit's sample shows the format); keep the two in step.
2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find, and a beat-by-beat plan is too coarse for it (one director pass asked for three new pictures the plan had missed). Who appears where: one figure per role, so that a figure coming back means something (a callback), not that the cast ran out. Note each picture's prompt or source and cost, quote the batch before paying, and show the user the pictures as they come. `prep.py`'s `full` treatment sizes full-bleed pictures for the stage. Episodes made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded by the episode after `img/art.js`), so no two of them edit the same line.
-3. **The folder.** `engine.py site/<book>` first (it starts `lib/` with the engine and a default `book.css`), then the kit's `lib/` over it, with the documentary kit's `fonts.css` and `fonts/`; `chNN/index.html` starts from the kit's `chapter.html` (the commands are in [site.md](site.md#a-short)). The film's own pieces (its cast's sizes in `MEME`, a series card, a map) go in a second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`). Every episode but a series' last sets `CHAPTER.next` to the next one: the end card names the next episode, and the player offers it only when `next` is set.
-4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. Every clip goes out at one level, −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the voice service gives about −23 LUFS, which sank one episode under its music); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. Check the marks on spoken numbers: a transcript that writes "1.4 billion" as digits misplaced two marks by 2.7 s.
-5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses. `music.py cut SRC site/<book>/chNN/audio/bgm/epN.mp3 --url …/<book>/chNN/` cuts a recording so its last note lands on the film's end and levels the file to −16 LUFS; `--rests` splices out its rests, `--even` evens out its quiet phrase ends. A looping track is fine for a first cut. Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the engine's ducking to 30 %, a track at −16 LUFS sits at about −34 LUFS, 20 LU under a −14 LUFS voice, the level the user chose for episode 1 (its track −16.3 LUFS). The gain is relative to the track's own loudness, so give both. `music.py gaps --url …` lists the bed's loudness in each voice-free gap and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.
-6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps.
-7. **Watch it yourself, then a director pass.** Contact sheets of every beat (`strip.py`), and the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage. Look at it with the platform's title, caption and buttons in mind (the safe area below). Measure what a script can: a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut. A fresh agent on a strong model reviews the sheets against an approved episode without knowing how the beats were built ([documentary.md](documentary.md#review-rounds)); half of what it finds is usually the picture saying something other than the voice.
+3. **The folder.** `engine.py site/<book>` first (it starts `lib/` with the engine and a default `book.css`), then the kit's `lib/` over it, with the documentary kit's `fonts.css` and `fonts/`; `chNN/index.html` starts from the kit's `chapter.html` (the commands are in [site.md](site.md#a-short)). The film's own pieces (its cast's sizes in `MEME`, a series card) go in a second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`); a map or the globe is the map kit's, whose lines `chapter.html` carries commented out. Every episode but a series' last sets `CHAPTER.next` to the next one: the end card names the next episode, and the player offers it only when `next` is set.
+4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. A series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) puts `"tempo": 1.1` in each narration file, or passes `eleven.py --tempo 1.1`: the clips are sped before they are levelled and aligned, and a rerun keeps it. A wordless beat (a series card, an end card) needs no clip: `{ dur: 2 }` in its fourth slot ([engine.md](engine.md#timing)). Every clip goes out at one level, −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the voice service gives about −23 LUFS, which sank one episode under its music); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. Check the marks on spoken numbers: the transcript writes "a hundred and twenty" as "120"; `eleven.py` matches the digits to the spoken words and prints the marks a rerun moved, but a number the matcher missed still lands late (seven marks in one episode, up to 0.75 s). A time only the page needs (an end card's) goes in the page, not in `timings.js`, which the next voice run rewrites.
+5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses. `music.py cut SRC site/<book>/chNN/audio/bgm/epN.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end instead of leaving the end card silent; `--end` sets it by hand) and levels the file to −16 LUFS; `--rests` splices out its rests, `--even` evens out its quiet phrase ends, and a generated (Lyria) track usually needs `--even` too, since its quiet passages fall into the voice's gaps just as a recording's do. `--lift T` raises a hole that neither fixes (a phrase end with no rest). The cut is made for one length: after any change to a beat's length, cut again (`gaps` says "recut"). A looping track is fine for a first cut. Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the engine's ducking to 30 %, a track at −16 LUFS sits at about −34 LUFS, 20 LU under a −14 LUFS voice, the level the user chose for episode 1 (its track −16.3 LUFS). The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …/<book>/` lists the bed's loudness in each voice-free gap and after the last word, and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.
+6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much: two beats with the same voice can differ by what their tweens overrun. `?lengths` on the page prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.
+7. **Watch it yourself, then a director pass.** Contact sheets of every beat (`strip.py`), and the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage. Look at it with the platform's title, caption and buttons in mind (the safe area below). Measure what a script can: page errors, console warnings and beat lengths in both browsers (`check.py chNN --url …`), a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to see the tags the export will show). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut. A fresh agent on a strong model reviews the sheets against an approved episode without knowing how the beats were built ([documentary.md](documentary.md#review-rounds)); half of what it finds is usually the picture saying something other than the voice. Then a second round on the exported MP4 ([documentary.md](documentary.md#review-rounds)).
8. **The user watches**, you fix, and `export.py chNN --url …/<book>/ --out books/<book>/export` writes a 1080 × 1920 MP4 and an `.srt` (on an upright film it shows the source and AI-illustration tags, since the video leaves the page that credits them; `--no-tags` leaves them out; a minute and a half took about twelve minutes). The user uploads it and ticks the platform's AI or synthetic-content box. A video over 25 MiB does not fit Cloudflare Pages; the web page itself is the light version. A series card's still is upright too: `shot.py … --webp 600` writes a 600 × 1067 WebP of the stage.
## The picture
`shorts.js` holds the grammar, every helper a pure function of the beat clock:
-- `shot()` a full-frame shot with a hard cut, `whip` (a sideways slide with motion blur) or `swipe` (the next clip rising as in a feed); `photo()` a full-bleed picture with a slow push, centred (a landscape picture whose subject is off-centre needs a camera that pans across it without showing an edge: the worked example's `wide()` in `site/madness-shorts/lib/madness.js`);
+- `shot()` a full-frame shot with a hard cut, `whip` (a sideways slide with motion blur) or `swipe` (the next clip rising as in a feed); `photo()` a full-bleed picture with a slow push, centred; `found()` the same for a found photograph, tagged with its source; `wide()` a camera across a landscape picture whose subject is off-centre, never showing an edge; `plate()` a picture placed whole on the ground (sizes from `img/art.js`). A picture whose point is its text (a sign, a headline) goes in whole with `plate()`: an upright crop of a shop sign left "Y. WE / RARY CLOS";
- `word()` big condensed capitals (a word wider than its `maxW`, 660, is set smaller, so it and its stroke stay in the safe area), `label()` and `band()` caps on solid blocks, `marker()` a highlighter sweep, `vlog()` white outlined overlay text, `srcTag()` a source or "AI illustration";
- `meme()` a cut-out figure rising in, `swarm()` one crossing then a crowd of them, `stamp()` a rubber stamp slammed on, `counter()` a number counting up, `priceTag()`, `phoneCard()`, `ico()` and `icons()` (Phosphor, MIT), `bar()`, `clipImg()`;
-- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` too when it wants a documentary helper (`pic()`, `say()`, `traced()`): load it before `shorts.js`;
+- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …, set in `lib/book.css` as `--dark`, `--red`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` too when it wants a documentary helper (`pic()`, `say()`, `traced()`): load it before `shorts.js`;
- `shortsBeat` turns a beat tuple into the engine's beat with every cue `LEAD` (0.22 s) early: a cut that lands on the word itself reads as late.
What made the first shorts work:
- **One idea per shot, one to three seconds a shot**, full bleed; words inside x 50–810, y 130–1290, since the platform draws its title, caption and buttons over the rest.
- **Say it literally.** When the narration describes a mechanism, draw each link as the voice names it. The "everyone is cheap" loop read as a vague circle until it became three people, each handing the next their product and its price, A to B, B to C, C back to A.
-- **Numbers move.** A count, a bar growing, a price tag swapped: a number on screen arrives the moment it is said.
+- **Numbers move.** A count, a bar growing, a price tag swapped: a number on screen arrives the moment it is said. A big denominator can be drawn literally: "2 in 100,000" as a field of 100,000 dots in one SVG `<pattern>` fill with the two real circles over it played at 17 ms a frame in both browsers.
- **A series says where it is.** A few seconds after the hook: the series card with this episode lit ("1 · The Ship"), then the argument.
- **The ending points on.** The last beat answers the hook and names the next episode.
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index 4bcf595..d6ebea2 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -92,11 +92,19 @@ cp -R "$SK"/lib/. "$BOOK_SITE/lib/"
cp -R "$DK/lib/fonts.css" "$DK/lib/fonts" "$BOOK_SITE/lib/"
cp "$SK/chapter.html" "$BOOK_SITE/ch01/index.html"
cp "$SK/narration.en.json" "content/$BOOK_ID/ch01/"
+echo 'window.ART = {};' > "$BOOK_SITE/img/art.js"
uv run --with edge-tts python "$SKILL/scripts/tts.py" "content/$BOOK_ID/ch01/narration.en.json" "$BOOK_SITE/ch01/audio/en"
uv run --with numpy python "$SKILL/scripts/sfx.py" "$BOOK_SITE/ch01/audio/sfx" whoosh bang tick thud
```
-Open `ch01/` to check the folder works: the kit's sample beat plays its line over `img/hook-picture.webp`, so until that picture exists the browser draws a broken image behind its words and the console shows one 404 (and `shot.py`, which stops on any page error, takes no screenshots). The music line in `chapter.html` is commented out until the episode has its track (`audio/bgm/ep1.mp3`). Then the script replaces the sample narration ([shorts.md](shorts.md#the-order-of-work)). Until the series has a page, the player's home button leads nowhere; a series of shorts can also live on its long film's series page (*Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there).
+Open `ch01/` to check the folder works: the kit's sample beat plays its line over `img/hook-picture.webp`, so until that picture exists the browser draws a broken image behind its words and the console shows one 404 (and `shot.py`, which stops on any page error, takes no screenshots). The music line in `chapter.html` is commented out until the episode has its track (`audio/bgm/ep1.mp3`), and so are the map kit's lines. Then the script replaces the sample narration ([shorts.md](shorts.md#the-order-of-work)). Until the series has a page, the player's home button leads nowhere; a series of shorts can also live on its long film's series page (*Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there).
+
+A series with a map adds the kit and its data (the regions, places and detail its films show: [documentary.md](documentary.md#maps)); a documentary does the same:
+
+```sh
+cp "$SKILL"/assets/templates/maps/lib/*.js "$BOOK_SITE/lib/"
+uv run --with pillow python3 "$SKILL/scripts/geo.py" "$BOOK_SITE/img" --globe "$BOOK_SITE/lib" # the globe too; without --globe, plain python3
+```
### Every book
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 532375a..6416f73 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -61,4 +61,14 @@ One **middle** worker per part then builds its beats, given the storyboard rows,
## Shorts
-An episode is short enough that the **strong** coordinator writes the script and the shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, and the series' own pieces in the second lib file. A **middle** worker makes or finds the pictures from the storyboard and records each prompt or source and its cost. One **middle** worker builds the beats (two, splitting the episode at a turn, when it is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean` ([shorts.md](shorts.md#the-order-of-work)). The director pass is **strong** and report-only, against an approved episode.
+An episode is short enough that the **strong** coordinator writes the script and the shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, and the series' own pieces in the second lib file. A **middle** worker makes or finds the pictures from the storyboard and records each prompt or source and its cost. One **middle** worker builds the beats (two, splitting the episode at a turn, when it is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean` ([shorts.md](shorts.md#the-order-of-work)). The director pass is **strong** and report-only, against an approved episode: a first round on the sheets, then one on the exported MP4, the round that finds most ([documentary.md](documentary.md#review-rounds)). Check what a director measured before sending it back as work, and after the round-2 fixes take a quick look yourself at the new MP4's frames: in *The Pandemic*'s shorts that look still found a wrong date and a dead frame.
+
+## Workers in parallel
+
+Several episodes or parts made at once each get their own git worktree, branch and preview port (one server per worker, serving its own worktree's `site/`, and that port in every `--url`). What trips them:
+
+- `books/` and `content/` are git-ignored, so a worktree has neither. `lint.py` finds them in the main checkout by itself; for everything else, give the brief's paths into them absolute, and no worker creates them in its worktree.
+- A shared file every worker appends to (one `img/SOURCES.md` for six episodes) conflicts at every merge. Give each worker its own (sources per episode, sizes per episode with `prep.py --art chNN-art.js`), joined once after the merge, and keep the shared files read-only for the workers.
+- The brief is the only rule book: one sentence each for the file names and the shared files, the same in the common brief and in each worker's go. One run said `img/chNN-*` in one place and `img/epN-*` in another, "do not edit SOURCES.md" and "add your block at the end".
+- Workers that share one paid balance make their pictures before their voice: `paint.py` stops while an OpenRouter balance is under $1.00, and whoever voices first can lock the others out of pictures.
+- Under load the machine is measured, not the page: with six workers exporting, a 16.7 ms beat read 48 to 109 ms in Firefox. `perf.py` prints the load average and warns above the core count, and `--ref CH:BEAT[@T]` times a known moment in the same run to read a number against; a loudness or timing that one worker or director reports under load is worth one more measurement before anyone acts on it. The frame time that decides goes on a quiet machine.
diff --git a/README.md b/README.md
index 6b7ff51..ca71de3 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,7 @@ python3 .claude/skills/papermorph/scripts/engine.py site
python3 .claude/skills/papermorph/scripts/engine.py site --from you/your-fork@main
```
-Engine versions are tags (`engine-v2`, `engine-v2.1`, …); a new major number means a book may need a change, described in its [release notes](https://github.com/DozenTwelve/Papermorph/releases). Outside this repository, `engine.py` syncs from the latest compatible release, now `engine-v2.6`. Since `engine-v2` the maths helpers (number lines, tiles, planes, the number-set diagram) are in `lib/math.js`: a chapter that uses them loads `../lib/math.js` right after `engine.js`, and `lint.py` names the chapters that need it. `--from DozenTwelve/Papermorph@engine-v1` keeps the earlier engine.
+Engine versions are tags (`engine-v2`, `engine-v2.1`, …); a new major number means a book may need a change, described in its [release notes](https://github.com/DozenTwelve/Papermorph/releases). Outside this repository, `engine.py` syncs from the latest compatible release, now `engine-v2.7`. Since `engine-v2` the maths helpers (number lines, tiles, planes, the number-set diagram) are in `lib/math.js`: a chapter that uses them loads `../lib/math.js` right after `engine.js`, and `lint.py` names the chapters that need it. `--from DozenTwelve/Papermorph@engine-v1` keeps the earlier engine.
## Video and LMS export
@@ -100,14 +100,14 @@ An illustrated physics chapter costs about $10–18 of model usage. The painted
## Roadmap
-Ticked items are in the Skill today. The Skill currently goes as far as widescreen documentaries.
+Ticked items are in the Skill today. The Skill currently goes as far as documentaries and their upright shorts.
- [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.
- [x] **Documentaries:** narrated films of public-domain pictures about a book or an idea. *Madness and Civilization* on the shelf is the reference film.
-- [ ] **Vertical shorts** of documentaries.
+- [x] **Vertical shorts** of documentaries: one point in under three minutes for a phone feed.
## FAQ