Skip to content

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

fix(skill): scripts and documents after the review; engine-v2.4.2

yzrf78362d2c133
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index b552b21..eb3c97f 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -55,6 +55,8 @@ 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/`.
+
`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).
## Lessons
@@ -86,11 +88,11 @@ Start with the story intake in [stories.md](references/stories.md#intake-for-a-s
## Documentaries
-Start with the intake in [documentary.md](references/documentary.md#intake) whenever `books/<book>/style.json` does not exist yet. Then follow [the order of work](references/documentary.md#the-order-of-work): research, the script and storyboard shown to the user, the folder from `assets/templates/documentary/` ([site.md](references/site.md#a-documentary)), pictures found and treated, voice, music, the beats, [review rounds](references/documentary.md#review-rounds) and the user's viewing. *Madness and Civilization* on the shelf is the approved reference.
+Start with the intake in [documentary.md](references/documentary.md#intake) whenever `books/<book>/style.json` does not exist yet. Then follow [the order of work](references/documentary.md#the-order-of-work): research, the script and storyboard shown to the user, the folder from `assets/templates/documentary/` ([site.md](references/site.md#a-documentary)), pictures found and treated, voice, music, the beats, [review rounds](references/documentary.md#review-rounds) and the user's viewing. *Madness and Civilization* on the shelf is the approved reference; *Shooting an Elephant* (`site/shooting-an-elephant/`) is the interactive one, where the reader fires the rifle ([interactive moments](references/documentary.md#interactive-moments)).
## Shorts
-Start with the questions in [shorts.md](references/shorts.md#questions-for-the-user) whenever `books/<book>/style.json` does not exist yet; the user's outline comes before any script. Then follow [the order of work](references/shorts.md#the-order-of-work): the script written beat by beat with the user, the cast, the folder from `assets/templates/shorts/` on the upright stage, voice and music levels, the beats, a director pass and the user's viewing, then `export.py` for a 1080 × 1920 video. *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/`), is the worked example.
+Start with the questions in [shorts.md](references/shorts.md#questions-for-the-user) whenever `books/<book>/style.json` does not exist yet; the user's outline comes before any script (a long film being recut as shorts is the outline: [from a long film](references/shorts.md#from-a-long-film)). Then follow [the order of work](references/shorts.md#the-order-of-work): the script written beat by beat with the user, the storyboard and the pictures, the folder from `assets/templates/shorts/` on the upright stage, voice and music levels, the beats, a director pass and the user's viewing, then `export.py` for a 1080 × 1920 video. *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/`), is the worked example.
## Scripts
@@ -98,9 +100,9 @@ All in `SKILL/scripts/`; each prints its usage with `--help` (run it with the `u
| 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 · `still.py` stretches where nothing moves · `perf.py` Firefox frame times · `export.py` MP4 and `.srt` |
+| 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 · `still.py` stretches where nothing moves · `perf.py` Firefox frame times · `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 · `level.py` even loudness · `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 |
+| 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 |
| Course options | `refs.py` verified citations · `items.py` question bank · `scorm.py` LMS package |
diff --git a/.claude/skills/papermorph/assets/templates/chapter.html b/.claude/skills/papermorph/assets/templates/chapter.html
index c6cf316..de21f37 100644
--- a/.claude/skills/papermorph/assets/templates/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/chapter.html
@@ -56,7 +56,7 @@ const BEATS = [
['final1', 'Chapter practice', () => { panel(0); }, { ask: done => quiz(SCREEN, [{
id: 'p-one', prompt: ['Practice that covers the whole chapter.'],
build: choice([['right answer'], ['tempting wrong answer']], 0, 'Why it is right.', [null, 'What this mistake misunderstands.']),
- }], done, 'Chapter practice 1 of 1') }],
+ }], done, 'Chapter practice') }],
['finish', 'Finished', () => { panel(0); }, { ask: finishCard }],
].map(([id, title, run, extra]) => ({ id, title, run, ...extra }));
diff --git a/.claude/skills/papermorph/assets/templates/documentary/chapter.html b/.claude/skills/papermorph/assets/templates/documentary/chapter.html
index 91b76e8..7fb0e69 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/documentary/chapter.html
@@ -30,8 +30,10 @@ const BEATS = [
const p = panel(0);
const ti = key(p, 'FILM TITLE', 800, 420, .5, { size: 96 });
hide(ti, OPEN_PRE - .9, .6);
- const g = pic(p, 'first-picture', { x: 800, y: 420, h: 600, at: OPEN_PRE - .6 }); // clear of the line typed under it
- push(g, OPEN_PRE, D); // a slow push-in while it is talked about
+ if (ART['first-picture']) { // the kit's sample picture: until prep.py has written one by that name into img/art.js, the title stands alone
+ const g = pic(p, 'first-picture', { x: 800, y: 420, h: 600, at: OPEN_PRE - .6 }); // clear of the line typed under it
+ push(g, OPEN_PRE, D); // a slow push-in while it is talked about
+ }
say(p, ['The first line, typed as it is spoken.'], 800, 820, m('first'), m('first') + 2, { size: 48, anchor: 'middle' });
}, { pre: OPEN_PRE }],
].map(([id, title, run, extra]) => ({ id, title, run, ...extra }));
diff --git a/.claude/skills/papermorph/assets/templates/documentary/style.json b/.claude/skills/papermorph/assets/templates/documentary/style.json
index ec17df0..85163c7 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/style.json
+++ b/.claude/skills/papermorph/assets/templates/documentary/style.json
@@ -15,7 +15,7 @@
"voice": { "engine": "edge", "voice": "en-GB-RyanNeural", "rate": "-4%" },
"music": "public-domain classical recordings, one per part of the film, changing at the turns",
"pacing": { "minutes": 10, "turns": "one argument with five or six turns; one idea or picture every two to four seconds" },
- "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.1" },
+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.2" },
"models": { "script": "claude-opus-5-5", "pictures": "claude-sonnet-5-5", "beats": "claude-sonnet-5-5", "checks": "claude-haiku-5-5", "director": "claude-opus-5-5" },
"approved": [{ "chapter": "ch01", "why": "close-ups on what is named; few words on screen" }]
}
diff --git a/.claude/skills/papermorph/assets/templates/picture-book/style.json b/.claude/skills/papermorph/assets/templates/picture-book/style.json
index 0ad301f..a9c9419 100644
--- a/.claude/skills/papermorph/assets/templates/picture-book/style.json
+++ b/.claude/skills/papermorph/assets/templates/picture-book/style.json
@@ -17,6 +17,7 @@
"budget": "under $1 of pictures per episode",
"cast": [{ "name": "Bo", "look": "round face, school uniform", "file": "site/jokes/lib/cast.js" }]
},
+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.2" },
"models": { "script": "claude-opus-5-5", "kit": "claude-opus-5-5", "scenes": "claude-sonnet-5-5", "sound": "claude-haiku-5-5", "director": "claude-opus-5-5", "reviewers": "claude-sonnet-5-5" },
"approved": [{ "chapter": "ch01", "why": "set-up before the punchline; a close-up on whoever speaks" }]
}
diff --git a/.claude/skills/papermorph/assets/templates/shorts/chapter.html b/.claude/skills/papermorph/assets/templates/shorts/chapter.html
index 5928f08..90d9e48 100644
--- a/.claude/skills/papermorph/assets/templates/shorts/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/shorts/chapter.html
@@ -36,8 +36,9 @@ const BEATS = [
}, { pre: OPEN_PRE }],
].map(shortsBeat);
-// One track for the whole film, cut to its timeline; ?bgm= sets its level by ear (gain under the ducking to 30 %)
-music('audio/bgm/ep1.mp3', undefined, +(new URLSearchParams(location.search).get('bgm') || .5), .05);
+// One track for the whole film, cut to its timeline; ?bgm= sets its level by ear (gain under the ducking to 30 %).
+// Uncomment once audio/bgm/ep1.mp3 is in place.
+// music('audio/bgm/ep1.mp3', undefined, +(new URLSearchParams(location.search).get('bgm') || .4), .05);
startShorts();
</script>
</body>
diff --git a/.claude/skills/papermorph/assets/templates/shorts/narration.en.json b/.claude/skills/papermorph/assets/templates/shorts/narration.en.json
new file mode 100644
index 0000000..1a72900
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/shorts/narration.en.json
@@ -0,0 +1,8 @@
+{
+ "engine": "edge",
+ "voice": "en-US-AndrewNeural",
+ "rate": "+4%",
+ "beats": {
+ "hook": "The first line is the point itself, said over a picture that is [[big]]already moving."
+ }
+}
diff --git a/.claude/skills/papermorph/assets/templates/shorts/style.json b/.claude/skills/papermorph/assets/templates/shorts/style.json
new file mode 100644
index 0000000..49b3193
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/shorts/style.json
@@ -0,0 +1,29 @@
+{
+ "schema": 1,
+ "tier": "shorts",
+ "book": { "title": "Series title", "slug": "series", "language": "en", "readers": "who the feed is: an overseas English feed, no background needed", "pilot": "ch01" },
+ "platform": "YouTube Shorts first; 1080 x 1920 export",
+ "source": "where the argument comes from: the user's outline, or a long film this series remakes (its checked quotes, pictures, voice and music carry over)",
+ "words": [
+ "The user's own words about the point, the outline and the look, verbatim.",
+ "ch01 feedback: later words that changed the bar, with the episode they came from."
+ ],
+ "series": {
+ "name": "Series title",
+ "episodes": [
+ { "chapter": "ch01", "title": "Episode title", "point": "the one thing a viewer believes or wonders about at the end" },
+ { "chapter": "ch02", "title": "Next episode", "point": "what the ending of ch01 hands on to" }
+ ]
+ },
+ "look": {
+ "palette": { "ground": "#ece4d3", "ink": "#1f1b16", "accent": "#c8281e" },
+ "fonts": { "key words": "Oswald 600", "quotes": "EB Garamond italic" },
+ "pictures": "full-bleed generated or found pictures, a new one every one to three seconds; how real people appear"
+ },
+ "voice": { "engine": "edge", "voice": "en-US-AndrewNeural", "rate": "+4%", "level": "-14 LUFS, peak -1.5" },
+ "music": { "ch01": "one track under the whole episode, and where it came from" },
+ "sources": "which numbers and quotes need a source on screen, and how strict to be about anonymous reports",
+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.2" },
+ "models": { "script": "claude-opus-5-5", "pictures": "claude-sonnet-5-5", "beats": "claude-sonnet-5-5", "checks": "claude-haiku-5-5", "director": "claude-opus-5-5" },
+ "approved": [{ "chapter": "ch01", "why": "what the user liked: the hook's first frame, the pace, the ending" }]
+}
diff --git a/.claude/skills/papermorph/assets/templates/style.json b/.claude/skills/papermorph/assets/templates/style.json
index 764b8c8..dc1cda8 100644
--- a/.claude/skills/papermorph/assets/templates/style.json
+++ b/.claude/skills/papermorph/assets/templates/style.json
@@ -14,7 +14,7 @@
},
"voice": { "engine": "edge", "voice": "en-US-AndrewNeural", "rate": "-4%" },
"pacing": { "minutes": [6, 10], "checks": "one or two quick checks inside the lesson, practice at the end" },
- "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.1" },
+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4.2" },
"models": { "extract": "claude-haiku-5-5", "narration": "claude-sonnet-5-5", "picture": "claude-opus-5-5", "checks": "claude-haiku-5-5", "review": "claude-sonnet-5-5", "rework": "claude-opus-5-5", "register": "claude-haiku-5-5" },
"scenes": {
"art": "pixel scenes on a dark board, characters about a third of the stage tall",
diff --git a/.claude/skills/papermorph/references/authoring.md b/.claude/skills/papermorph/references/authoring.md
index 81910ac..c7fccd7 100644
--- a/.claude/skills/papermorph/references/authoring.md
+++ b/.claude/skills/papermorph/references/authoring.md
@@ -10,7 +10,7 @@ Chapters have run 5–18 minutes with 5–40 second beats; a long chapter can ho
| lesson beats | One idea each, built up in the picture while the narration explains it. |
| `q1`, `q2`, … | A check of already taught content, separated from the next check by a lesson beat. |
| `wrap` | Three or four numbered takeaways. |
-| `final1` … | Full-screen practice covering the whole chapter. With several sets, label them like `'Chapter practice, set 1 of 2 · question'` (the engine appends "k of n"). |
+| `final1` … | Full-screen practice covering the whole chapter. With several sets, label them like `'Chapter practice · set 1 of 2'` (the engine appends "· question k of n"). |
| `finish` | Score card (`finishCard`): first-try results for quick checks and practice. |
Beat ids are shared by the page (`BEATS`) and the narration file; a beat with `ask` waits for the answers before moving on.
diff --git a/.claude/skills/papermorph/references/courses.md b/.claude/skills/papermorph/references/courses.md
index 756e662..c5e47ec 100644
--- a/.claude/skills/papermorph/references/courses.md
+++ b/.claude/skills/papermorph/references/courses.md
@@ -6,7 +6,7 @@ Three options for books used in a course, usually at a college: verified citatio
Each work named on screen (an author–year, a quoted study, a book title) can be a live link to it. Links come from a verified list, never from memory.
-1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields).
+1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields; a group author such as the World Health Organization is `{"org": "World Health Organization"}`).
2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: pick the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository). If none exists, keep the citation as plain text and note it in the chapter file.
3. **Verify.** `python3 SKILL/scripts/refs.py verify books/<book>/refs.json --write` resolves every DOI or ISBN, checks it against the entry, fills in missing metadata and stamps `verified`. Fix every `FAIL`.
4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`, and uncomment the `refs.js` line in `index.html` and each chapter: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
diff --git a/.claude/skills/papermorph/references/diagrams.md b/.claude/skills/papermorph/references/diagrams.md
index 4ae4cd5..3a15363 100644
--- a/.claude/skills/papermorph/references/diagrams.md
+++ b/.claude/skills/papermorph/references/diagrams.md
@@ -1,6 +1,6 @@
# Symbols and diagrams that change
-For abstract and procedural ideas (the maths books on the showcase site). The picture explains through change: things are rearranged, split, balanced, counted and compared while the narration says why. The change is the argument, so each move must be one the idea allows.
+For abstract and procedural ideas (the maths books on the showcase site, `site/elementary-algebra/` and `site/math-notebook/`). The picture explains through change: things are rearranged, split, balanced, counted and compared while the narration says why. The change is the argument, so each move must be one the idea allows.
- **One reading line.** A derivation or a procedure reads in one direction, each step under or beside the last, aligned on what stays the same (the `=` sign, the place values). The eye never searches for the next step.
- **Change the thing, don't replace it.** Tokens that combine move together and collapse into the result (`tokens`, `collapse`); a tile pair cancels where it stands; a dot hops along the number line. A fresh line of text is a weaker picture than the old one transforming.
diff --git a/.claude/skills/papermorph/references/documentary.md b/.claude/skills/papermorph/references/documentary.md
index ebce5f6..865770e 100644
--- a/.claude/skills/papermorph/references/documentary.md
+++ b/.claude/skills/papermorph/references/documentary.md
@@ -1,6 +1,6 @@
# Documentaries: from a book or an idea to a film
-A documentary is a narrated film about a book, an idea or a stretch of history: two minutes for one idea, ten or fifteen for a book's argument. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. There are no questions; the reader watches. The published example is *Madness and Civilization* (after Foucault, ten minutes) on the shelf at https://papermorph.diamonddoge.org/. It is the approved reference for this kind of film: when in doubt, open it and match its level.
+A documentary is a narrated film about a book, an idea or a stretch of history: two minutes for one idea, ten or fifteen for a book's argument. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. Usually the reader just watches; a film can also hand them the action at a few moments ([Interactive moments](#interactive-moments)). The published example is *Madness and Civilization* (after Foucault, ten minutes) on the shelf at https://papermorph.diamonddoge.org/. It is the approved reference for this kind of film: when in doubt, open it and match its level. *Shooting an Elephant* (after Orwell, nine minutes, https://papermorph.diamonddoge.org/shooting-an-elephant/) is the interactive one: the reader fires the rifle.
It shares the engine, the player, captions, previews, `export.py` and the team with every other book. What is its own: the kit `assets/templates/documentary/` (`chapter.html`, `narration.en.json`, `style.json`, `lib/film.js`, `lib/book.css`, `lib/fonts.css` and the fonts), the picture scripts (`commons.py`, `prep.py`, `trace.py`, `frames.py`, `video.py`), the voice script `eleven.py`, and the order of work below.
@@ -11,8 +11,8 @@ The same spirit as [intake.md](intake.md): a short conversation, choices to clic
1. **The subject and the angle.** What the film is about, and the one thing a viewer should leave with (Foucault: madness was not always locked up; each age decided what to do with it). Ask what must be in it: a scene, a quote, a person, an ending. What the user stresses is a theme to carry, not a thing to repeat: in the first film's first cut the two epigraphs appeared four times, which was overdone; they belong at the start and the end, with light echoes between.
2. **Length and audience.** Ten minutes holds one argument with five or six turns; a two-minute film holds one turn.
3. **The look.** One ground colour for the whole film (burgundy `#5a0e16` for Foucault, chosen from four tested with the actual pictures on them), two fonts (a condensed sans for key words, a serif for quotes and captions), and how found pictures are treated (below). Offer a ground test: three or four grounds with real pictures on them, side by side, before anything is built. The colours live in the book's `lib/book.css`, which `film.js` reads; pictures are baked to match with `prep.py --ink/--paper`.
-4. **The voice.** The narrator carries the film, so the user picks it by ear. Offer both kinds: free voices (Edge TTS through `tts.py`, online, or Kokoro, local) and ElevenLabs (`elevenlabs/eleven-v4` through OpenRouter, with `eleven.py`: paid, an OpenRouter key). Play a few short samples of each in the film's own words. On the first film ElevenLabs was chosen over Edge. Characters can have their own voices (the Fool's giggle, a king's edict); ElevenLabs' v4 audio tags such as `[cackles]` are acted, not read.
-5. **Music.** Classical music suits found pictures: one recording per part of the film, changing at the turns, never abruptly, at a level that never covers the narrator. Open with something short and rhythmic so the start is not slow.
+4. **The voice.** The narrator carries the film, so the user picks it by ear. Offer both kinds: free voices (Edge TTS through `tts.py`, online, or Kokoro, local) and ElevenLabs (`elevenlabs/eleven-v4` through OpenRouter, with `eleven.py`: paid, an OpenRouter key). Play a few short samples of each in the film's own words. On the first film ElevenLabs was chosen over Edge. Characters can have their own voices (the Fool's giggle, a king's edict); ElevenLabs' v4 audio tags such as `[cackles]` are acted, not read, and left out of the captions and of `lint.py`'s comparison of narration and page.
+5. **Music.** Classical music suits found pictures: one recording per part of the film, changing at the turns, never abruptly, at a level that never covers the narrator. Open with something short and rhythmic so the start is not slow. A composition can be centuries old while its recording is still protected: Commons marks some 1950s–60s recordings public domain under EU rules that the US does not follow (protected there until 2067). Prefer recordings their performers released (PDM-owner, CC0), Musopen, or US military bands (`commons.py --help`); `commons.py`'s licence check cannot see this.
6. **Budget.** Edge and Kokoro voices cost nothing; ElevenLabs about $0.65 for ten minutes (`eleven.py --dry` prints the characters and the estimate before anything is paid; quote it). A five-second clip from a still costs about $0.42. Pictures from Wikimedia Commons cost nothing.
Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/style.json` from the kit's `style.json`: `tier: "documentary"`, the user's words, the angle, the look, the voice and the models.
@@ -22,14 +22,14 @@ Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/
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.
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 the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`: the kit's file names an Edge voice), keeps paid clips cached (a rerun costs nothing), 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 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.
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.
## Pictures
-- **Find, then record.** `commons.py` searches Wikimedia Commons and downloads only public-domain and CC0 files, logging each in `SOURCES.tsv` beside the downloads (`books/<book>/art/found/` in its examples): name, Commons title, licence, author, source URL, and any use restriction such as a trademark, which it warns about. The book page's credits come from it. One subagent with it found all twenty storyboard pictures for Foucault in thirteen minutes. Other good sources: the Library of Congress, Old Book Illustrations, the Internet Archive; record those by hand the same way.
+- **Find, then record.** `commons.py` searches Wikimedia Commons and downloads only public-domain and CC0 files, logging each in `SOURCES.tsv` beside the downloads (`books/<book>/art/found/` in its examples), under a header row: name, Commons title, licence, author, source URL, any use restriction such as a trademark (which it warns about), the credit line (often the holding collection), the licence URL and the work's date. The book page's credits come from it. One subagent with it found all twenty storyboard pictures for Foucault in thirteen minutes. Other good sources: the Library of Congress, Old Book Illustrations, the Internet Archive; record those by hand the same way.
- **Two treatments**, made by `prep.py`, which also writes `img/art.js` with each picture's size:
- *print*: the picture keeps its paper, with a border and a soft shadow, like a photograph laid on the ground. Paintings, photographs, title pages.
- *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.
@@ -48,6 +48,8 @@ Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/
Add the film's own recurring pieces at the end of the book's `film.js` (Foucault's guide peeking up from the bottom edge, the Europe map). The kit's chapter sets `lead: false`: every opening is timed by hand.
+A film can stretch the kit where its story asks. *Shooting an Elephant* added a red overprint to `say()` (`mark`), a band to `closeups()`, a `clip()` that plays a `<video>` (`img/moulmein-live.mp4`) on the beat clock, and silhouette puppets in the manner of Lotte Reiniger (`lib/puppets.js`). A live `<video>` is the quicker way to a moving shot, at a cost: the export seeks frame by frame without waiting for the video to decode, so an exported clip can lag a frame, where a `frames.py` sheet agrees exactly; check the export, and turn the clip into frames if it shows (the comment on `clip()` in that book's `lib/film.js` says so).
+
Look at your own frames while you build, not only at the end: after each few beats, `shot.py` or `?beat=N&t=S` at the moments a picture lands, and a `strip.py` contact sheet of the beat against its storyboard row ([review.md](review.md)). Ask what a viewer sees while each word is said: is the thing named on screen, does a word or label sit on a face, is the screen sparse. The first film's worst defects were pictures that contradicted the narration, and they show on a contact sheet at once.
What made the Foucault film work:
@@ -59,6 +61,17 @@ 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.
+## 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.
+
+- `CHAPTER.film = true` keeps the chapter a film although some beats ask something: its sound effects and music play, the cover offers Play and the film's length instead of a lesson, and the help leaves out the question keys ([engine.md](engine.md#player)).
+- The moment is a beat whose `ask` is the chapter's own `done => { … }` rather than a `quiz()`. The engine calls it as the beat starts; once the narration and the beat's tweens are over, `P.waiting` turns true and the page waits. The handler listens on the stage (a click, a key), acts only while `P.waiting`, answers at once (a flash, a bang) and calls `done()` once, after which the next beat plays.
+- A reader can step back or replay the beat while the handler is still listening. Note `P.gen` when the handler starts and compare it in every listener and timer: when it has changed, that start of the beat is over, so remove the listeners and do nothing (the engine already ignores a stale `done()` *(v2.4.1)*, but not the handler's own flash or sound).
+- While the page waits, the music plays on and rises to 70 %, so choose a track that can carry an open-ended pause.
+- `export.py` cannot click: it holds the beat's last picture for its `hold` seconds (`{ ask: fireAsk(1, 'p5b'), hold: 1.5 }` in the fourth slot, 1.5 by default; the engine ignores it), then plays the next beat as if the reader had acted. Whatever the act does on the page (the shot's bang), the next beat also does on its own clock for the video; *Shooting an Elephant* silences that copy when the reader fired.
+- Check it as a reader: `?beat=N` stops on the moment; see that the prompt appears only once the narration ends, that a click acts at once and the film goes on, that stepping back and replaying mid-wait leaves no second flash or extra shot, and that the exported video holds and goes on without a gap.
+
## 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.
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index 2028e40..d0c6015 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -2,7 +2,7 @@
A chapter page loads the engine and its `audio/<lang>/timings.js`, defines `CHAPTER` (including `language` when different from `en`: the audio folder), drawing helpers, `BEATS` and questions, then calls `boot()`. The engine provides the stage, drawing, timeline, question types, guide and player. Use the code's signatures if they differ from this reference. The interface text (buttons, help, cover, finish card) follows `<html lang>`: English, Russian, Chinese and Japanese are in the engine's `TRANSLATIONS`; another language needs a block there.
-Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `math.js`, `volume.*`, `contents.*`, `units.*`), so the book runs on its own. The engine is not part of this skill: it lives in the `engine/` folder of the Papermorph repository (or a fork). `python3 SKILL/scripts/engine.py site` copies it into every book from the repository's `engine/` when it is at hand, otherwise from GitHub (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source, by default the latest compatible release, `engine-v2.4.1`; `@main` takes the newest, a tag or commit pins it, and `engine-v1` is the last engine with the maths helpers inside `engine.js`); a book's copy is not edited by hand. This reference describes `engine-v2.4.1`; what an older copy lacks is marked *(v2.1)*, *(v2.2)*, *(v2.3)*, *(v2.4)* or *(v2.4.1)*, and syncing the book brings it. An engine bug is fixed at the source, then synced. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
+Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `math.js`, `volume.*`, `contents.*`, `units.*`), so the book runs on its own. The engine is not part of this skill: it lives in the `engine/` folder of the Papermorph repository (or a fork). `python3 SKILL/scripts/engine.py site` copies it into every book from the repository's `engine/` when it is at hand, otherwise from GitHub (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source, by default the latest compatible release, `engine-v2.4.2`; `@main` takes the newest, a tag or commit pins it, and `engine-v1` is the last engine with the maths helpers inside `engine.js`); a book's copy is not edited by hand. This reference describes `engine-v2.4.2`; what an older copy lacks is marked *(v2.1)*, *(v2.2)*, *(v2.3)*, *(v2.4)*, *(v2.4.1)* or *(v2.4.2)*, and syncing the book brings it. An engine bug is fixed at the source, then synced. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
The maths helpers (number lines, tiles, fraction rows, planes, chance objects, the number-set diagram, `pickPoint`, `sorter`) are in `lib/math.js`. A chapter that uses one loads `<script src="../lib/math.js"></script>` right after `engine.js`: it reads the engine's globals as it loads, so never before it and never `async`. `lint.py` names a chapter that uses one without loading it. Use the helpers that fit; draw the rest in the chapter, and move what several chapters use into the book's element library (`lib/<name>.js`, [assets.md](assets.md)) rather than into the engine copy.
@@ -14,13 +14,15 @@ The maths helpers (number lines, tiles, fraction rows, planes, chance objects, t
- Scale and rotation are about the element's own origin: draw around (0,0) and place with `x/y`.
- `S` holds objects shared across beats (`S.panel`, `S.line`, …). `reset()` clears it, so anything a later beat needs must be stored on `S`.
- Palette `COL`: `chalk dim faint task good bad board` plus six hues named `nat whole int rat irr real` (from the algebra book; give them the book's own meanings in `style.json` `look.meaning`, e.g. `const FORCE = COL.…`). Fonts: `UI` (text), `MATH` (serif unless the book's `--math-font` says otherwise).
-- **Board colour** *(v2.1)*. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, the cards, the player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture.
+- **Board colour** *(v2.1)*. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, the cards, the player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture. `site/physics-notebook/` is a light book made this way (`lib/book.css` and `lib/notebook.js`).
## Drawing
| Function | Use |
| --- | --- |
| `G(parent, {x,y,s,r,o})` | group |
+| `mk(tag, attrs, parent)` | any raw SVG element (`'rect'`, `'circle'`, `'image'`, `'foreignObject'` …) with its attributes; it carries no state until `put` or a tween gives it one |
+| `put(e, {x,y,s,r,o,…})` | set an element's state at once, without a tween (to place a piece drawn around its own origin) |
| `path(parent, d, attrs, {d:0})` | path; `{d: 0}` makes it ready to be drawn on with `draw()`. A `transform` in `attrs` holds until the state moves the element (`x y s r`), which then owns the transform: to place a shape that also moves, put it in a `G()` |
| `T(parent, str, {x,y,size,fill,font,weight,anchor,o})` | text |
| `cite(parent, key, {str,x,y,size,fill,weight,anchor,o})` | a citation from `REFS` (`../refs.js`, a course option: [courses.md](courses.md)), drawn as an underlined link that opens the source in a new tab and listed on the finish card ([courses.md](courses.md#citations)) |
@@ -35,6 +37,7 @@ The maths helpers (number lines, tiles, fraction rows, planes, chance objects, t
| `h(tag, cls, kids)` | an HTML element for a card (a table, a list): kids are strings, nodes or `rich(...)`; put it in a prompt or a message as it is |
| `texPart(el, name)` | the part `\class{name}{…}` of a TeX formula inside `el`, for `tw`/`fx` on `c_color` and `o` |
| `panel(t0)` | fade the current scene group and start a new one; call it at the start of a beat that changes the picture |
+| `header(p, str, t0, x, y)` | a small dim heading over the picture (default at 1000, 170 on the wide stage) |
Topic helpers in `math.js`: number lines (`numberLine`, `move`, `landDot`, `brace`, on the engine's `X(v)`, `Y0`, `tick`, `dot`, `AXIS`), signed tiles (`tile`, `tiles`, `cancelPairs`), algebra tiles (`atile`, `tileRow`, `cancel`, `popIn`, sizes in `TS`), fraction rows (`fracRow`, `reduce`), a decimal point that hops (`pointRow`), a balance (`balance`), inequality graphs (`ray`, `segment`), a coordinate plane (`plane`: `PX/PY`, `dot`, `walk`, `line`, `arrow`, `stair`, `region`, `half`, `fn` for y = f(x); set `P.layer = panel(0)` so marks clear with the beat), scaled axes (`axes`), dot plots (`dataLine`), chance objects (`die`, `coin`, `spinner`, `outline`), area grids (`areaGrid` with `.cell`, `.ring`; `arc`), rectangles (`rect`, `bracketH`), vertical scales (`vAxis`, `thermometer`), the number-set diagram (`RINGS`, `buildVenn`, `regionAt`). Read the function in math.js before first use.
@@ -59,9 +62,10 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accen
- `m('name', offset)` is the start time of the word after `[[name]]`; `D` is the clip's length. Use marks for actions tied to speech; scene entrances and transitions can use fixed offsets.
- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show(e, t0, dur, ease)`, `hide`, `draw` (same arguments), `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`, `soft`. Continuous motion and cameras: see below.
-- A lesson beat ends after its narration and its last tween, and holds that picture `HOLD` (0.6 s) before the next starts; an `ask` beat waits for `done()`. A `done()` kept from an earlier start of the same beat (the reader stepped back and replayed it) no longer counts *(v2.4.1)*; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.
+- A lesson beat ends after its narration and its last tween, and holds that picture `HOLD` (0.6 s) before the next starts; an `ask` beat waits for `done()`. An `ask` is any `done => …` that calls `done()` once; `quiz()` is the usual one, and a film's own handler can listen on the stage instead ([documentary.md](documentary.md#interactive-moments)). A `done()` kept from an earlier start of the same beat (the reader stepped back and replayed it) no longer counts *(v2.4.1)*; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.
- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and no element is revealed (faded, scaled or drawn in from nothing) within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s, so the narration never runs over an empty board. It looks only at reveals: a beat that lays out part of its picture visible at once (axes, empty boxes, a set) and reveals the rest on later words still has that first group pulled to 0.4 s. When those words matter, or a camera shows a picture from the first frame, give the beat `{ lead: false }` in its fourth slot; when every opening in the chapter is timed by hand (a documentary), set `CHAPTER.lead = false` *(v2.2)* instead. To see where a beat's reveals land, put marks on a contact sheet: `strip.py chNN OUT idea:0.4,label,label+0.3,end --sheet storyboard --url http://localhost:8765/<book>/` (a mark plus an offset is the moment the action is timed to).
- **`pre`** in the fourth slot (`{ pre: 1.2 }`) runs the picture that many seconds before the narration starts: an action, then the line. Picture books use it on every scene.
+- **`hold`** in the fourth slot of an `ask` beat in a film (`CHAPTER.film`) is read only by `export.py`: the seconds the video holds the waiting picture before it plays on as if the reader had acted (1.5 by default). The page ignores it.
- **The end of a film**: a chapter whose last beat asks nothing (a picture book) is finished when that beat ends: it is marked done and, with `CHAPTER.next`, offers the next chapter (Enter).
- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly. Make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.
- Constants used in a `BEATS` literal are evaluated when it is defined, so define them above `BEATS`. Data used only inside an `ask` closure may sit below.
@@ -96,7 +100,7 @@ Firefox repaints SVG on the main thread and is the slowest common browser for th
quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'], build: blanks([...]) }, …], done, 'Quick check')
```
-- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; the label names the set in the book's language, and the engine appends k of n when a quiz has several questions), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.
+- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; the label names the set in the book's language, such as `'Chapter practice · set 1 of 2'`, and the engine appends "· question k of n" when a quiz has several questions), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.
- `choice(options, right, why, wrongWhys[], onRight?)` — number keys.
- `mcq(id, onRight?)` — (course option, [courses.md](courses.md)) a whole quiz entry (`{id, prompt, build: choice(...)}`) from the chapter's item bank: `quiz(TOPR, [mcq('c-attrib'), mcq('c-cause')], done)`. Needs `items.js` (built by `scripts/items.py`) loaded after `engine.js`; an unknown id throws.
- `blanks(rows)` — rows `{parts: [..., {box: '21'}, ...], why, hint?, fx?, test?}`; accepts −5, 3/4, 2 1/4, 0.75 as exact values and, *(v2.1)*, with a currency sign ($60, 5 €) and thousands grouped by spaces of any kind (1 250, as [authoring.md](authoring.md) shows numbers) or, where the decimal sign is a point, by commas (1,250); `{box, lowest: true}` demands lowest terms; `test(values)` judges the whole row (e.g. two factors in either order). `hint` is one message for any wrong value in its row; when different mistakes need their own answers, split the step into rows or ask it as a `choice` with `wrongWhys`. Tab moves between boxes, Enter checks, Esc leaves a box.
@@ -108,9 +112,9 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'
## Player
-Space play/pause, and once the chapter has ended replay *(v2.1)*, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions (a question's narration is captioned too, above its band or beside its corner card, until the narration ends), `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen, ? help. Clicking a step segment jumps to that point of the beat (`seekInto(i, frac)`); the next beat's clip preloads while one plays. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. In a hidden tab (another tab or window in front) a timer keeps the clock going, so the chapter plays on from beat to beat *(v2.3.1; an older engine stops at the end of the beat until the tab is shown again)*. `?beat=N&t=S` in the URL opens a frozen frame for review, without captions (N is kept within the chapter's steps); on a question step the answer box takes focus only once Space starts the lesson. With `?review` in the URL, N pauses and asks for a note on the current moment and Shift+N copies the chapter's notes, one line each with the `?beat=N&t=S` that reopens it, so a reviewer can collect notes while watching and hand them over at once. After the end, on the finish card or a film's last frame, Enter opens `CHAPTER.next` (replays when there is none) and R replays.
+Space play/pause, and once the chapter has ended replay *(v2.1)*, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions (a question's narration is captioned too, above its band or beside its corner card, until the narration ends); a beat's last caption clears a second after its narration, so it does not sit on a closing title *(v2.4.2)*; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off *(v2.4.1)*, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen, ? help. Clicking a step segment jumps to that point of the beat (`seekInto(i, frac)`); the next beat's clip preloads while one plays. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. In a hidden tab (another tab or window in front) a timer keeps the clock going, so the chapter plays on from beat to beat *(v2.3.1; an older engine stops at the end of the beat until the tab is shown again)*. `?beat=N&t=S` in the URL opens a frozen frame for review, without captions (N is kept within the chapter's steps); on a question step the answer box takes focus only once Space starts the lesson. With `?review` in the URL, N pauses and asks for a note on the current moment and Shift+N copies the chapter's notes, one line each with the `?beat=N&t=S` that reopens it, so a reviewer can collect notes while watching and hand them over at once. After the end, on the finish card or a film's last frame, Enter opens `CHAPTER.next` (replays when there is none) and R replays.
-**Sound effects and music** *(v2.2)*, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true` *(v2.3)*: a film with interactive moments (a documentary where the reader fires a rifle). There, while a question beat waits for the reader after its narration, the music plays on (it rises to 70 %, as in a lead-in) and is not pulled back for the time it ran on, and a click on its step bar seeks into it like any other beat; the next beat's tracks take over as usual (`fade` 0 is a cut). `sfx(beat, t, name, vol)` plays `audio/sfx/<name>.mp3` when that beat's clock passes `t` in normal playback (a seek past it fires nothing), at half volume (vol 2 is full); one still loading when it is due plays late, from its start, for up to a second. A long ambience listed in `SFX_BED` with its length (`SFX_BED.birds = 10`) is joined part-way after a seek. `music(file, beats, gain, fade)` is a looping track under the listed beats (all of them by default). Its place is the length of its earlier beats as they really ran plus the clock; a beat under music gives back from its closing hold the time the clock stood still (a clip getting going), so the film keeps the music's time. It ducks to 30 % for the whole beat, voice or not, and rises to 70 % only in the `pre` lead-in of the beats in `window.MUSIC_UP_IN_PRE` (`true` for all); it crossfades over `fade` s (0.8; 0 is a cut), and `window.MUSIC_OFF = { beat: t => true }` fades it out for a moment. Both go through one Web Audio graph started by the reader's first touch, click or key, so ducks, fades and the volume slider reach them on phones too (on iOS the slider does not reach the narration). A pause holds the music's level and a seek stops the effects. When a clip loading or buffering holds the clock, the music runs on, then eases back (5 % slower or faster), or jumps back once if it is more than a second out. Safari and every iOS browser stall a media element at each speed change, so there the music keeps the film's speed and is put back by a seek once it is a quarter second out, aimed ahead by the lag it showed after the last one *(v2.4.1)*. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.
+**Sound effects and music** *(v2.2)*, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true` *(v2.3)*: a film with interactive moments (a documentary where the reader fires a rifle). There, while a question beat waits for the reader after its narration, the music plays on (it rises to 70 %, as in a lead-in) and is not pulled back for the time it ran on, and a click on its step bar seeks into it like any other beat; the next beat's tracks take over as usual (`fade` 0 is a cut). `sfx(beat, t, name, vol)` plays `audio/sfx/<name>.mp3` when that beat's clock passes `t` in normal playback (a seek past it fires nothing), at half volume (vol 2 is full); one still loading when it is due plays late, from its start, for up to a second. A long ambience listed in `SFX_BED` with its length (`SFX_BED.birds = 10`) is joined part-way after a seek. `music(file, beats, gain, fade)` is a looping track under the listed beats (all of them by default). Its place is the length of its earlier beats as they really ran plus the clock; a beat under music gives back from its closing hold the time the clock stood still (a clip getting going), so the film keeps the music's time *(v2.4)*. It ducks to 30 % for the whole beat, voice or not, and rises to 70 % only in the `pre` lead-in of the beats in `window.MUSIC_UP_IN_PRE` (`true` for all); it crossfades over `fade` s (0.8; 0 is a cut), and `window.MUSIC_OFF = { beat: t => true }` fades it out for a moment. Both go through one Web Audio graph started by the reader's first touch, click or key, so ducks, fades and the volume slider reach them on phones too (on iOS the slider does not reach the narration). A pause holds the music's level and a seek stops the effects. When a clip loading or buffering holds the clock, the music runs on, then eases back (5 % slower or faster), or jumps back once if it is more than a second out. Safari and every iOS browser stall a media element at each speed change, so there the music keeps the film's speed and is put back by a seek once it is a quarter second out, aimed ahead by the lag it showed after the last one *(v2.4.1)*. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.
Progress is saved under `animebook:progress:<book-path>`; the cover and a picture book's series page read the same key. A book can set another key with `--progress-key` in `lib/book.css`; its cover must then read that key. Books served in different folders have separate saved places and completion lists.
@@ -126,7 +130,7 @@ Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head
- A `prog` or `clockRun` that redraws only when a key changes (a 12 fps frame number, a step index) must draw from the key's own value (`f / FPS`), not the exact `t` that crossed it: playing, seeking and `?beat=N&t=S` reach the same key at different `t`, and must show the same picture.
- In a JS string, double each TeX backslash (`'\\frac{a}{b}'`) or use `` String.raw`\frac{a}{b}` ``: `'\text'` is a tab followed by "ext".
- Write a formula wholly in TeX, an `eqLine` sign included (`sym: TX('\\le')`): TeX glyphs are smaller and lighter than `M()` text.
-- Prefix chapter-specific helpers when their names might collide with engine globals (`rect`, `popIn`, `eqLine`, `slot` from math.js when the chapter loads it; `fit`, `Y0`, `OV`, `HOLD`, `camera`, `soft`, `clockRun`, `retire`, `seeking`, `BOOK`, `bookSetting`, `TX`, `texPart`, …); a redeclaration stops the page script. `lint.py` lists every clash.
+- Prefix chapter-specific helpers when their names might collide with engine globals (`rect`, `popIn`, `eqLine`, `slot` from math.js when the chapter loads it; `fit`, `Y0`, `OV`, `HOLD`, `camera`, `soft`, `clockRun`, `retire`, `seeking`, `BOOK`, `bookSetting`, `TX`, `texPart`, …); a redeclaration stops the page script. `lint.py` lists every clash, each name of a `const a = 1, b = 2` included.
- Drag handling: re-parent (append) the element before `setPointerCapture`; moving a node drops its capture.
- A card whose content is too long for `BAND` should become several `blanks` rows in a wider side card.
- When a question beat is continued early, the engine finishes the beat's pending tweens first; don't rely on half-finished fades.
diff --git a/.claude/skills/papermorph/references/intake.md b/.claude/skills/papermorph/references/intake.md
index 1958df8..ed76a2e 100644
--- a/.claude/skills/papermorph/references/intake.md
+++ b/.claude/skills/papermorph/references/intake.md
@@ -15,7 +15,7 @@ The conversation should feel light: the user tries one chapter first and decides
Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop if none are found) and ask "Is it this one?", listing up to four candidates. If none are found, offer to search another folder or to take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.
-When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book: go to [stories.md](stories.md), which has its own short intake, and come back here for the models (§5) and `style.json` (§6).
+When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book: go to [stories.md](stories.md), which has its own short intake, and come back here for the models (§5) and `style.json` (§6). A documentary ([documentary.md](documentary.md#intake)) and a short ([shorts.md](shorts.md#questions-for-the-user)) have their own questions too, and come back the same way.
## 2. What this book is
@@ -27,8 +27,8 @@ If the book is for a course, notice it here: when it cites other works (author
Offer the animation tiers as reference points; the books at https://papermorph.diamonddoge.org/ show each of them (and the picture books); link them.
-1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books). The lightest; a smaller model can do most steps.
-2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book). Several times the work of tier 1 per chapter, and the picture step wants a strong model.
+1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books, `site/elementary-algebra/` and `site/math-notebook/`). The lightest; a smaller model can do most steps.
+2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book, `site/science/`). Several times the work of tier 1 per chapter, and the picture step wants a strong model.
3. **Custom**: the user describes what they want; you judge which abilities it needs and say so.
Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.
@@ -50,25 +50,25 @@ Then start the book folder ([site.md](site.md#start-a-book-folder)): the look is
Which model does which step is the user's choice. Users run the Skill with different models and providers, and a book can mix them. Show the defaults for the chosen tier as one table, one row per step in [team.md](team.md#steps), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
-| Step | Tier 1 | Tier 2 | Picture book | Documentary |
-|---|---|---|---|---|
-| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) |
-| Narration and beats | middle | middle | strong (voices, the episode kit) | middle (pictures found and treated) |
-| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene | middle, one worker per part of the film |
-| Checks | small | small | small (sound effects too) | small |
-| Review | middle | middle | strong director, middle picture and sound reviewers | strong director |
-| Rework | strong | strong | middle, per scene | middle, per part |
-| Register | small | small | small | small |
+| Step | Tier 1 | Tier 2 | Picture book | Documentary | Shorts |
+|---|---|---|---|---|---|
+| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) | strong (the script and storyboard with the user; then voice and music) |
+| Narration and beats | middle | middle | strong (voices, the episode kit) | middle (pictures found and treated) | middle (pictures generated or found) |
+| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene | middle, one worker per part of the film | middle (the beats) |
+| Checks | small | small | small (sound effects too) | small | small |
+| Review | middle | middle | strong director, middle picture and sound reviewers | strong director | strong director |
+| Rework | strong | strong | middle, per scene | middle, per part | middle |
+| Register | small | small | small | small | small |
-**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`, keyed by step as in the [course](../assets/templates/style.json) or [picture-book](../assets/templates/picture-book/style.json) template (a picture book's keys name its roles: `script`, `kit`, `scenes`, `sound`, `director`, `reviewers`; a [documentary](../assets/templates/documentary/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
+**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`, keyed by step as in the [course](../assets/templates/style.json) or [picture-book](../assets/templates/picture-book/style.json) template (a picture book's keys name its roles: `script`, `kit`, `scenes`, `sound`, `director`, `reviewers`; a [documentary](../assets/templates/documentary/style.json)'s and a [short](../assets/templates/shorts/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
## 6. style.json
-Start from [the template](../assets/templates/style.json). Blocks are grouped by ability, not by tier; a tier is just which blocks are present:
+Start from [the template](../assets/templates/style.json), or for a picture book, a documentary or a short from its kit's own `style.json`. Blocks are grouped by ability, not by tier; a tier is just which blocks are present:
| Block | What it holds | Present in |
|---|---|---|
-| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"`, `"picture"` or `"documentary"`; title, slug, language, readers, pilot chapter | all |
+| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"`, `"picture"`, `"documentary"` or `"shorts"`; title, slug, language, readers, pilot chapter | all |
| `words` | the user's own words about the look, verbatim, with later feedback that changed the bar | all |
| `look` | palette, what each colour means, text and maths fonts, notation and rounding | all |
| `voice` | TTS engine (`edge`, or `kokoro` when Edge is unavailable or local audio is wanted; a documentary may choose `eleven`, paid: [documentary.md](documentary.md#intake)), voice, rate | all |
@@ -79,6 +79,9 @@ Start from [the template](../assets/templates/style.json). Blocks are grouped by
| `images` | where images may come from, credit rules | tier 2 |
| `models` | the model for each step, as agreed in §5 | all |
| `illustration` | a picture book's look, budget, cast and sets ([stories.md](stories.md#intake-for-a-story)) | picture books |
+| `angle` | the one thing a viewer leaves with, and what must be in the film | documentaries |
+| `music` | the music and where it came from | documentaries, shorts |
+| `platform`, `source`, `series`, `sources` | the feed and export size; where the argument comes from (the user's outline or a long film); the series' name and each episode's point; how strict to be about sources ([shorts.md](shorts.md#questions-for-the-user)) | shorts |
| `courses` | the course options chosen ([courses.md](courses.md)) | when chosen |
| `approved` | chapters the user approved and what each shows well | filled as chapters are approved |
diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.md
index 057ac6e..51b7bf3 100644
--- a/.claude/skills/papermorph/references/painting.md
+++ b/.claude/skills/papermorph/references/painting.md
@@ -22,7 +22,7 @@ Everything that comes out goes through `painted.py` (manifest `books/<book>/art/
Money is the user's, so the user sets a ceiling and sees every cent:
- `paint.py --q` is `low` or `medium` (the default; high is refused). Try `--q low` first: in these books low was often good enough for the final set (about $0.016 a picture with one reference, about $0.026 with the style picture as a second; medium about $0.02–0.03; high cost five times as much and, once used in a film, looked the same).
-- `paint.py` reads the OpenRouter key from `~/.config/openrouter/key` or `$OPENROUTER_API_KEY`. Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`; `paint.py --total books/<book>/art/costs.tsv` sums it); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider (OpenRouter's credits page, or `GET https://openrouter.ai/api/v1/credits` with the key), not an estimate; it can lag a batch by some minutes, so read it again before reporting. OpenRouter refuses any image request when the balance is under one dollar.
+- `paint.py` reads the OpenRouter key from `~/.config/openrouter/key` or `$OPENROUTER_API_KEY`. Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`; `paint.py --total books/<book>/art/costs.tsv` sums it); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider (OpenRouter's credits page, or `GET https://openrouter.ai/api/v1/credits` with the key), not an estimate; it can lag a batch by some minutes, so read it again before reporting. OpenRouter refuses any image request when the balance is under one dollar. `paint.py` will not write over a picture that already exists (it may be an approved, paid one); `--force` replaces it.
- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `$OPENAI_API_KEY`, `--env FILE` or `~/.config/papermorph/.env`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own, so the user sees each stage.
diff --git a/.claude/skills/papermorph/references/scenes.md b/.claude/skills/papermorph/references/scenes.md
index fcafadb..8f26689 100644
--- a/.claude/skills/papermorph/references/scenes.md
+++ b/.claude/skills/papermorph/references/scenes.md
@@ -1,6 +1,6 @@
# Illustrated scenes
-For physical, spatial and narrative ideas: people and things act out the idea, the camera shows what matters, and the words live inside the picture (the science book on the showcase site).
+For physical, spatial and narrative ideas: people and things act out the idea, the camera shows what matters, and the words live inside the picture (the science book on the showcase site, `site/science/`).
## Each moment is one picture
diff --git a/.claude/skills/papermorph/references/shorts.md b/.claude/skills/papermorph/references/shorts.md
index 12e1b96..2f1e11a 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`; `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. 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
@@ -15,30 +15,34 @@ After that they stay as long as each moment gives them something new and the arg
The short is the user's argument; the Skill's work is to make it land. Ask, offering choices to click and skipping what the request already settles:
1. **The point.** What should a viewer believe or wonder about at the end? Who is the viewer (an overseas feed, a home audience), and which platform?
-2. **The outline.** Ask for the user's outline before writing anything: the hook, the steps, the ending. If there is none, build the outline together; do not invent the argument. A series: its name, the episode's number, and how this episode hands on to the next.
+2. **The outline.** Ask for the user's outline before writing anything: the hook, the steps, the ending. If there is none, build the outline together; do not invent the argument. A series: its name, how many episodes and where the material divides (propose a split, each episode with its one point, as options to click), and how each episode hands on to the next. When the argument comes from a long film, see *From a long film* below.
3. **People.** How real people appear: period pictures for the dead, cut-out figures or drawings for the living, never photographs of living people's faces.
-4. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…").
-5. **Voice and music.** The narrator (ElevenLabs v4 through OpenRouter was the accepted voice; Edge TTS is the free option): play short samples and let the user pick. Music: generated (Lyria) or a public-domain recording ([documentary.md](documentary.md#intake) has the licence traps).
-6. **Pictures and budget.** Generated pictures, found ones, or both; what each costs per episode (voice about $0.07 a minute; 94 generated pictures at low quality cost $0.84 for one three-episode series).
+4. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…"). Look at the argument itself too: where the field disputes a claim the hook states as fact, say so and offer ways to put it (Foucault's ships of fools are doubted by historians; "Foucault went looking for real ones" kept the line and the truth).
+5. **Voice and music.** The narrator (ElevenLabs v4 through OpenRouter was the accepted voice; Edge TTS is the free option): play short samples and let the user pick. Music: a public-domain recording ([documentary.md](documentary.md#intake) has the licence traps), or generated (Lyria, made outside the Skill for now).
+6. **Pictures and budget.** Generated pictures, found ones, or both; what each costs per episode (voice about $0.07 a minute; 94 generated pictures at low quality cost $0.84 for one three-episode series; a picture made from a reference picture, to keep a figure or a style, costs about four times as much, since the reference counts as input: $0.016 against $0.004 at low).
-Then agree the models ([intake.md](intake.md#5-models): writing the script with the user is strong-model work, building beats middle, checks small) and write `style.json` with `tier: "shorts"`, the user's words, the look, the voice, the series and the models.
+Then agree the models ([intake.md](intake.md#5-models): writing the script with the user is strong-model work, building beats middle, checks small) and write `books/<book>/style.json` from the kit's [style.json](../assets/templates/shorts/style.json): `tier: "shorts"`, the platform, the user's words, the series with each episode's point, the look, the voice, the music and the models.
+
+## From a long film
+
+When the user wants a film that already exists recut as shorts (*Madness and Civilization* became four), the argument is there: its script is the outline, and its checked quotes, found pictures, voice and music carry over. The first questions change: how many episodes, where the film's turns divide them, and what each episode's one point is. Propose the split and episode 1's outline together, then go on as below. Read the film's `style.json`, its narration and its `SOURCES.tsv` before asking anything they already answer. Where a short's habits and the film's differ, ask the user: the documentary's one Fool through the centuries is a recurring figure, which the short's rule of one figure per role would break.
## The order of work
-1. **The script, beat by beat, with the user.** One beat per sentence or two, written into `content/<book>/chNN/narration.en.json` with `[[mark]]` before each word a picture lands on, and beside each beat one line of what we see. Show it to the user a few beats at a time and rewrite as they answer; list each number's source under the script as you go, so the script file reads: the user's outline, the beats, the sources.
-2. **The cast and the pictures**, planned from the script: 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.
+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), 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. 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.
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`).
4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. Bring every clip to one level with `level.py --lufs -14 --peak -1.5` (one episode came out of the voice service at −23 LUFS and sank under its music). 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. A track cut to the film's length can end on the last word; a looping one is fine for a first cut. Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4, which with the engine's ducking put the music about 16 LU under a −14 LUFS voice and was the level the user chose. 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`), the first frame on its own, a phone-sized screenshot with the platform's buttons in mind. 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.
-8. **The user watches**, you fix, and `export.py chNN --url …/<book>/` writes a 1080 × 1920 MP4 and an `.srt` (`--query tags` to show the source and AI-illustration tags). 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.
+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 over three seconds, a number that lands after it is said, words outside the safe area (`word()` takes any size; its `_w` is the width to check against x 50–810). 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.
+8. **The user watches**, you fix, and `export.py chNN --url …/<book>/ --out books/<book>/export` writes a 1080 × 1920 MP4 and an `.srt` (`--query tags` to show the source and AI-illustration tags; 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;
+- `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`);
- `word()` big condensed capitals, `label()` and `band()` caps on solid blocks, `marker()` a highlighter sweep, `vlog()` white outlined overlay text, `tag()` 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()`;
- `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.
@@ -53,4 +57,4 @@ What made the first shorts work:
## Later
-Scripts to come: cutting one music track to an episode's timeline (beats on the music's own beat, the end on the last word), generating music with Lyria, and measuring voice against music the way `export.py` mixes them.
+Scripts to come: cutting one music track to an episode's timeline (beats on the music's own beat, the end on the last word; each beat's length on screen is the page's `P.end`, not its clip's `dur`), generating music with Lyria, and measuring voice against music the way `export.py` mixes them.
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index ffc921f..4bcf595 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -75,6 +75,8 @@ cp "$DK/narration.en.json" "content/$BOOK_ID/ch01/"
echo 'window.ART = {};' > "$BOOK_SITE/img/art.js"
```
+`prep.py` fills `img/art.js` as pictures are treated. The kit's sample beat shows a picture named `first-picture` once there is one; until then it shows the title alone. Voice the sample with `uv run --with edge-tts python "$SKILL/scripts/tts.py" "content/$BOOK_ID/ch01/narration.en.json" "$BOOK_SITE/ch01/audio/en"` and open `ch01/` to check the folder works, then replace the narration with the film's script ([documentary.md](documentary.md#the-order-of-work)).
+
### A short
Like a documentary: `engine.py` first, then the shorts kit's `lib/` over it, with the documentary kit's fonts. Each episode is a chapter; its sound effects come from `sfx.py`. The commands for an empty book (a series page and shelf registration come later, as for any book):
@@ -89,10 +91,12 @@ python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"
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/"
+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
```
-The chapter loads `../img/art.js`, which `prep.py` fills as pictures are treated; until then the kit's sample beat needs one picture named `first-picture`. Voice the sample with `uv run --with edge-tts python "$SKILL/scripts/tts.py" "content/$BOOK_ID/ch01/narration.en.json" "$BOOK_SITE/ch01/audio/en"` to check the folder works, then replace the narration with the film's script ([documentary.md](documentary.md#the-order-of-work)).
+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).
### Every book
@@ -110,7 +114,7 @@ A chapter returns to its book's index. Preserve cover → contents → chapter n
## Cover and contents (`index.html`)
-A textbook's cover and contents; a picture book or a documentary uses the series page instead ([stories.md](stories.md#delivering), [above](#a-documentary)).
+A textbook's cover and contents; a picture book, a documentary or a series of shorts uses the series page instead ([stories.md](stories.md#delivering), [above](#a-documentary)).
One page: no hash or `#book` shows the cover, `#references` the reference list, `#contents` or `#chNN` the contents; a lesson's home button returns to `#chNN`, and the card grows into the lesson frame through a view transition.
@@ -149,4 +153,4 @@ Narration and on-screen text are written in one language first. A second languag
## Video export (optional)
-`uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <lesson URL>` renders the beats to `OUT/chNN.mp4` (1080p, 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, and in a picture book its effects and music), so the video matches the page; question beats are left out and a lesson's video ends on a card pointing to the interactive lesson (in a film with `CHAPTER.film`, they stay in: each holds its picture for `hold` s, then the next beat plays as if the reader had acted). It takes about 1.6× the video's length. Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
+`uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <lesson URL>` renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright stage; 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, and in a picture book its effects and music), so the video matches the page; question beats are left out and a lesson's video ends on a card pointing to the interactive lesson (in a film with `CHAPTER.film`, they stay in: each holds its picture for the beat's `hold` s, with the music up at 70 % as the page plays it while it waits, then the next beat plays as if the reader had acted; [documentary.md](documentary.md#interactive-moments)). A mix that would clip is turned down as a whole, and the run says by how much; odd sizes are cut to even ones (an upright `--height 720` gives 404 × 720). The video is written beside the old one and renamed when done, so a failed run leaves an earlier `chNN.mp4` alone. How long it takes depends on the frame size and the machine: a 98.5 s upright short at 1080 × 1920 took 11 min 42 s (about 7× its length); `--height 720 --fps 10` makes a quick check copy. Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.md
index 72b47a0..225b23b 100644
--- a/.claude/skills/papermorph/references/sound.md
+++ b/.claude/skills/papermorph/references/sound.md
@@ -4,7 +4,7 @@ Voices carry the story; everything else sits under them. In early cuts the music
## Voices
-- **One voice per character.** List them under `voices` in `narration.<lang>.json` and write each line as `{"speaker": name, "text": …}`; `tts.py` synthesizes every line (Edge voices, with rate and pitch: children were adult voices sped up and pitched up). The narrator is a voice too.
+- **One voice per character.** List them under `voices` in `narration.<lang>.json` and write each line as `{"speaker": name, "text": …}` (a line without a speaker takes the file's own `voice`; a speaker missing from `voices` stops the run, naming it); `tts.py` synthesizes every line (Edge voices, with rate and pitch: children were adult voices sped up and pitched up). The narrator is a voice too.
- **Lines in other languages** are spoken in their own language by a native voice (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language. The caption shows both: the original and the translation in brackets. Write it as the beat's `"sub"`; `tts.py` marks such a line (its voice's locale differs from the narration file's language) so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue (engine v2.4.1; an older engine shows it only for a picture book joined by `join.py`).
- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the shape for the frame. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.
- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration; scene authors time actions against it (the beat clock adds the scene's `pre`).
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 9a44614..532375a 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -58,3 +58,7 @@ A fresh session as coordinator matters even more here: contact sheets are large,
The same shape as a picture book, split by part of the film (a turn of the argument, often one music track) instead of by scene. The **strong** coordinator researches and writes the script and storyboard with the user, then builds what every part shares: the voice and `timings.js`, the music, and the film's own recurring pieces at the end of `film.js`. A **middle** worker finds and treats the pictures from the storyboard (`commons.py`, `prep.py`, and `trace.py` or `frames.py` where the storyboard asks), recording each source.
One **middle** worker per part then builds its beats, given the storyboard rows, the marks to land on, the kit's API (to read, not to edit), the first and last frame of the parts beside it, and how to look at its own frames ([documentary.md](documentary.md#building-the-beats)); it replies with contact sheets of its beats and what they showed. The director pass ([documentary.md](documentary.md#review-rounds)) is **strong** and report-only; the coordinator merges its findings and sends parts back to their workers.
+
+## 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.
diff --git a/.claude/skills/papermorph/scripts/commons.py b/.claude/skills/papermorph/scripts/commons.py
index f8c5da0..4db7ea6 100644
--- a/.claude/skills/papermorph/scripts/commons.py
+++ b/.claude/skills/papermorph/scripts/commons.py
@@ -10,8 +10,9 @@
Only public domain and CC0 are downloaded: the licence (Commons' LicenseShortName) must start with "public domain",
"cc0" or "pd" (PDM-owner counts), else the script refuses. A file with restrictions (trademarked, personality rights)
is downloaded with a WARN: free to copy is not free to show a logo or a living person. Each download writes a row to
-the sources log (--sources, default OUT/SOURCES.tsv; a new download of the same name replaces its row): file, Commons
-title (and page), licence, author, file page URL, restrictions. Commons serves only standard widths: JPEG, PNG, GIF and
+the sources log (--sources, default OUT/SOURCES.tsv, with a header row; a new download of the same name replaces its
+row): file, Commons title (and page), licence, author (or credit), file page URL, restrictions, credit (often the
+holding collection), licence URL, date of the work. Commons serves only standard widths: JPEG, PNG, GIF and
WebP up to 1920 px come as the original, wider ones as a 1920 px rendering; SVG, DjVu and PDF come as a 1920 px
rendering (--page picks a page of a scan), TIFF as the largest standard width it has (1280 px for a 1500 px TIFF).
The name's extension must be the served one (.png for an SVG; leave it off to have it added). Recordings come as the
@@ -48,6 +49,7 @@ IMG = dict(prop="imageinfo", iiprop="url|size|extmetadata|mime", iiurlwidth=1920
AUD = dict(prop="imageinfo", iiprop="url|size|extmetadata|mime|mediatype")
RAW = ("image/jpeg", "image/png", "image/gif", "image/webp") # served as the original up to 1920 px
VECTOR = ("image/svg+xml", "image/vnd.djvu", "application/pdf") # rendered at 1920 px whatever their nominal size
+HEAD = "file\ttitle\tlicence\tauthor\tsource\trestrictions\tcredit\tlicence url\tdate\n" # the sources log's columns
NOTE = "(a PD composition is not a PD recording: check the performer and year, see --help)"
@@ -102,9 +104,10 @@ def get(title, name, out, sources, page, audio):
fetch(url, path, 300 if audio else 120)
log = sources or os.path.join(out, "SOURCES.tsv")
rows = [l for l in open(log, encoding="utf-8")] if os.path.exists(log) else []
- rows = [l for l in rows if l.split("\t", 1)[0] != name] # a new download of a name replaces its row
+ rows = [HEAD] + [l for l in rows if l.split("\t", 1)[0] not in (name, "file")] # a new download of a name replaces its row
rows.append("\t".join([name, p["title"] + (f" (page {page})" if page else ""), lic,
- strip(meta(ii, "Artist") or meta(ii, "Credit"), 200) or "?", ii.get("descriptionurl", ""), rights]) + "\n")
+ strip(meta(ii, "Artist") or meta(ii, "Credit"), 200) or "?", ii.get("descriptionurl", ""), rights,
+ strip(meta(ii, "Credit"), 200), meta(ii, "LicenseUrl"), strip(meta(ii, "DateTimeOriginal"), 60)]) + "\n")
with open(log, "w", encoding="utf-8") as f:
f.writelines(rows)
if audio:
diff --git a/.claude/skills/papermorph/scripts/eleven.py b/.claude/skills/papermorph/scripts/eleven.py
index e45b0c2..2e8dd4e 100644
--- a/.claude/skills/papermorph/scripts/eleven.py
+++ b/.claude/skills/papermorph/scripts/eleven.py
@@ -5,9 +5,10 @@
... [--model elevenlabs/eleven-v4] [--voice george] [--only beat,beat] [--dry] [--ledger books/<book>/art/costs.tsv]
Same input and output as tts.py: the narration file's beats with [[mark]] tags in, <beat>.mp3 and timings.js
-({dur, marks, cues} per beat) out, so the page cannot tell the two apart. The voice and model come from the
-narration file ("voice", "model"), else from the flags (default george, eleven-v4); OpenRouter offers 21 preset
-voices. A beat may be {"speaker": name, "text": ...} with the speaker's "voice" under the file's "voices", as in tts.py,
+({dur, marks, cues} per beat) out, so the page cannot tell the two apart. The voice and model come from the flags,
+else from the narration file ("voice", "model"), else george and eleven-v4; OpenRouter offers 21 preset voices. A beat
+may be {"speaker": name, "text": ...} with the speaker's "voice" under the file's "voices", as in tts.py (no speaker:
+the file's voice),
and a "sub": a line in another language, whose subtitle is its one caption cue, shown even with captions off (forced);
Whisper detects that line's language.
@@ -18,16 +19,17 @@ sentence and per clause after a colon ("Mr." and "e.g." do not end one, as in tt
v4 audio tags such as [cackles] or [whispers] act: they are performed, not read aloud, and left out of captions.
Price: about $0.00008 per character (about $0.65 for a ten-minute film). Before paying, the run prints the characters
-it will synthesize and their estimated cost; --dry stops there. --ledger appends the run's estimate to the ledger
-paint.py writes (OpenRouter reports no cost for speech).
+it will synthesize and their estimated cost; --dry stops there. --ledger appends the characters the run synthesized
+(also when it stops partway) and their estimated cost to the ledger paint.py writes (OpenRouter reports no cost for
+speech).
Each beat's clip is cached beside the narration as .eleven/<beat>.<hash>.mp3 (hash of model, voice and text), so
moving marks or rerunning never pays twice. --only takes the listed beats again (a fresh, paid take, even with the
text unchanged) and leaves the others' mp3 and timings as they are. A clip levelled in place (level.py) is kept by
-later runs until its take changes: .eleven/takes.json records which take each output clip was copied from.
+later runs until its take changes: .eleven/takes.json records which take each output clip (by its folder and name, en/open.mp3) was copied from.
The key is read from ~/.config/openrouter/key or $OPENROUTER_API_KEY.
"""
-import argparse, datetime, hashlib, json, pathlib, re, subprocess, sys, urllib.error, urllib.request
+import argparse, atexit, datetime, hashlib, json, pathlib, re, subprocess, sys, urllib.error, urllib.request
from paint import key
from tts import ABBREV, split_marks, mark_times, duration, write_atomic
@@ -62,7 +64,7 @@ def speak(text, voice, dst):
sys.exit(f"{e.code} {e.read().decode(errors='replace').replace(k, '***')[:500]}")
if not data.startswith(b"ID3") and not (data[:1] == b"\xff" and len(data) > 1 and data[1] & 0xE0 == 0xE0):
sys.exit(f"not audio: {data[:300]!r}")
- dst.write_bytes(data)
+ tmp = dst.with_suffix(".part"); tmp.write_bytes(data); tmp.replace(dst) # a half-written take is never a cached one
norm = lambda w: re.sub(r"\W", "", w.lower())
@@ -72,10 +74,14 @@ old = {}
if tf.exists():
t = tf.read_text(encoding="utf-8"); old = json.loads(t[t.index("{"):t.rindex("}") + 1])
tk = cache / "takes.json" # output clip -> the cached take it was copied from
-takes = json.loads(tk.read_text()) if tk.exists() else {}
+clip_key = lambda f: "/".join(pathlib.Path(f).parts[-2:]) # en/open.mp3: the same in any clone (older runs: the full path)
+takes = {clip_key(k): v for k, v in json.loads(tk.read_text()).items()} if tk.exists() else {}
beats = []
for beat, raw in spec["beats"].items():
- voice = spec["voices"][raw["speaker"]]["voice"] if isinstance(raw, dict) else a.voice or spec.get("voice", "george")
+ who = raw.get("speaker") if isinstance(raw, dict) else None
+ if who is not None and who not in spec.get("voices", {}):
+ sys.exit(f"{beat}: speaker {who!r} is not under the narration file's \"voices\"")
+ voice = spec["voices"][who]["voice"] if who is not None else a.voice or spec.get("voice", "george")
sub = raw.get("sub") if isinstance(raw, dict) else None # a foreign line's subtitle, its one cue
raw = raw["text"] if isinstance(raw, dict) else raw
clean, marks = split_marks(raw) # clean keeps audio tags: they go to the voice
@@ -86,10 +92,17 @@ todo = sum(len(b[3]) for b in beats if b[6])
print(f"{sum(b[6] for b in beats)} beats to synthesize, {todo} characters, about ${todo * PRICE:.2f}", flush=True)
if a.dry:
sys.exit()
-if a.ledger and todo:
- led = pathlib.Path(a.ledger); led.parent.mkdir(parents=True, exist_ok=True)
- with led.open("a", encoding="utf-8") as f: f.write(f"{datetime.date.today()}\t{a.out}\t{model}\ttts{todo}c\t{todo * PRICE:.4f}\n")
timings, spent = {}, 0
+
+
+def charge():
+ """Log what was paid for, once the takes are made: a run stopped partway logs only its finished takes."""
+ if a.ledger and spent:
+ led = pathlib.Path(a.ledger); led.parent.mkdir(parents=True, exist_ok=True)
+ with led.open("a", encoding="utf-8") as f: f.write(f"{datetime.date.today()}\t{a.out}\t{model}\ttts{spent}c\t{spent * PRICE:.4f}\n")
+
+
+atexit.register(charge) # at the end, or when a later step (a failed take, Whisper) stops the run
for beat, voice, sub, clean, marks, cached, fresh in beats:
if only and beat not in only and beat in old:
timings[beat] = old[beat]; continue # --only leaves the other beats alone
@@ -98,8 +111,8 @@ for beat, voice, sub, clean, marks, cached, fresh in beats:
if fresh:
speak(clean, voice, cached); spent += len(clean); print(beat, "synthesized")
mp3 = out / f"{beat}.mp3"
- if fresh or not mp3.exists() or takes.get(str(mp3.resolve())) != cached.name: # else keep it: perhaps levelled since
- mp3.write_bytes(cached.read_bytes()); takes[str(mp3.resolve())] = cached.name
+ if fresh or not mp3.exists() or takes.get(clip_key(mp3)) != cached.name: # else keep it: perhaps levelled since
+ mp3.write_bytes(cached.read_bytes()); takes[clip_key(mp3)] = cached.name
m = "base" if sub or lang != "en" else "base.en"
if m not in asr:
import numpy as np
diff --git a/.claude/skills/papermorph/scripts/engine.py b/.claude/skills/papermorph/scripts/engine.py
index 9cb3e93..d5f1d24 100644
--- a/.claude/skills/papermorph/scripts/engine.py
+++ b/.claude/skills/papermorph/scripts/engine.py
@@ -20,7 +20,7 @@ with lib/mathjax.js keeps it in step like the rest.
import argparse, filecmp, io, shutil, sys, tarfile, tempfile, urllib.request
from pathlib import Path
-DEFAULT = 'DozenTwelve/[email protected]' # follows the latest compatible release
+DEFAULT = 'DozenTwelve/[email protected]' # follows the latest compatible release
OWN = 'book.css'
LATEX = {'vendor/mathjax/tex-svg-full.js': 'mathjax.js', 'vendor/mathjax/LICENSE': 'mathjax-LICENSE.txt'}
diff --git a/.claude/skills/papermorph/scripts/export.py b/.claude/skills/papermorph/scripts/export.py
index 36b4e50..739b5a4 100644
--- a/.claude/skills/papermorph/scripts/export.py
+++ b/.claude/skills/papermorph/scripts/export.py
@@ -10,8 +10,12 @@ each beat's clip from its `pre` on, and in a film (a picture book or a documenta
of their scene, as a scene change stops them) and the BGM tracks with their crossfades, ducking and MUSIC_OFF. Question beats (quick
checks and practice) are left out, and then the video ends on a card saying they are in the interactive lesson
(--link adds its address); in a film with interactive moments (CHAPTER.film, e.g. the reader fires a rifle) they stay in,
-each holding its last picture for its `hold` seconds (1.5 by default) before the next beat plays as if the reader had acted. Captions are not burned in: upload OUT/chNN.srt with the video. Needs ffmpeg; serve the
-site over HTTP first.
+each holding its last picture for its `hold` seconds (1.5 by default, the music up at 70 % as the page plays it while
+it waits) before the next beat plays as if the reader had acted. With --link and no question beats left out, the end
+card shows the title and the link only. A mix that would clip is turned down as a whole (the run prints by how much).
+Odd sizes (an upright --height 720 is 405 wide) are cut to even ones, as H.264 needs. The video is written to
+OUT/chNN.tmp.mp4 and renamed when done, so a failed run leaves an earlier OUT/chNN.mp4 alone. Captions are not burned
+in: upload OUT/chNN.srt with the video. Needs ffmpeg; serve the site over HTTP first.
"""
import argparse, asyncio, functools, json, shutil, subprocess, sys, tempfile, wave
import numpy as np
@@ -22,7 +26,7 @@ from browsers import exe
END_SECONDS = 4
FLAT = '#frame { border-radius: 0 !important; box-shadow: none !important; }' # square corners in the video
-END_CARD = """(link) => {
+END_CARD = """([link, asks]) => {
const d = document.createElement('div');
d.id = 'exportEnd';
d.style.cssText = 'position:absolute;left:0;top:0;width:'+SW+'px;height:'+SH+'px;display:flex;flex-direction:column;' +
@@ -30,7 +34,7 @@ END_CARD = """(link) => {
'font-family:inherit;text-align:center;z-index:50';
d.innerHTML = `<div style="font-size:30px;opacity:.65;letter-spacing:.08em;text-transform:uppercase">${translate('chapterNumber', { n: CHAPTER.label ?? CHAPTER.number })}</div>
<div style="font-size:64px;font-weight:600;max-width:${SW - 300}px">${CHAPTER.title}</div>
- <div style="font-size:34px;opacity:.85;margin-top:30px">${translate('checksInLesson')}</div>
+ ${asks ? `<div style="font-size:34px;opacity:.85;margin-top:30px">${translate('checksInLesson')}</div>` : ''}
${link ? `<div style="font-size:30px;opacity:.65">${link}</div>` : ''}`;
document.getElementById('frame').append(d);
}"""
@@ -100,14 +104,14 @@ async def main(a):
box = await pg.locator('#stage').bounding_box()
clip = {k: box[k] for k in ('x', 'y', 'width', 'height')}
audio_dir = Path(tempfile.mkdtemp(prefix='export-'))
- video = out / f'{a.chapter}.mp4'
+ video, part = out / f'{a.chapter}.mp4', out / f'{a.chapter}.tmp.mp4' # renamed to video when the encoder is done
# Pass 1: the sound track and the captions, beat by beat at the beat's length on screen.
end_s = END_SECONDS if asks or a.link else 0 # a picture book ends on its own last scene
- lengths, starts, counts, music_off, cues, offset = [], [], [], [], [], 0.0
+ lengths, starts, counts, music_off, cues, offset, waits = [], [], [], [], [], 0.0, {}
for i, bid in beats:
await open_beat(pg, base, i)
end, T = await pg.evaluate('[P.end, TIMINGS[BEATS[P.i].id]]')
- if info['beats'][i]['ask']: end += info['beats'][i]['hold']
+ if info['beats'][i]['ask']: waits[bid] = end; end += info['beats'][i]['hold'] # from P.end the page waits
# a scene lists its sfx() when its beat is built, so they are collected beat by beat
for e in await pg.evaluate(SFX_JS):
if e not in info['sfx']:
@@ -132,7 +136,7 @@ async def main(a):
put(track, o + e['at'], decode(e['src']), .5 * e['vol'], o + lengths[k])
# music: the engine's music player (soundTick), frame by frame: crossfades of the track's `fade` (0.8 s by default), ducked to 30 % in a
# scene with voices; with MUSIC_UP_IN_PRE (true, or a list of beat ids) the music comes up to 70 % while a beat's
- # picture runs before its narration
+ # picture runs before its narration, and in a film while the page waits for the reader (the hold)
fps, n = a.fps, sum(len(m) for m in music_off)
frames_id = [bid for k, (_, bid) in enumerate(beats) for _ in music_off[k]]
frames_t = [f / fps for m in music_off for f in range(len(m))]
@@ -147,7 +151,7 @@ async def main(a):
current = bid in m['beats'] and not frames_off[f]
v = max(0.0, min(1.0, v + (1 if current else -1) / fps / m['fade'])) if m['fade'] > 0 else float(current) # 0: a cut
up = info['upInPre']
- want = .7 if up and (up is True or bid in up) and t < beat_pre[bid] else .3
+ want = .7 if (up and (up is True or bid in up) and t < beat_pre[bid]) or t >= waits.get(bid, 1e9) else .3
duck += max(-1 / fps, min(1 / fps, want - duck))
if current: pos = sum(beat_len.get(b, 0) for b in m['beats'][:m['beats'].index(bid)]) + t
else: pos += 1 / fps
@@ -157,39 +161,47 @@ async def main(a):
i = round(f * step); seg = np.take(song, np.arange(at[f], at[f] + round(step)), axis=0, mode='wrap')
put(track, i / RATE, seg, gain[f])
peak = float(np.abs(track).max())
+ if peak > 1: track *= .98 / peak # a mix that would clip, turned down as a whole
wav = audio_dir / 'track.wav'
with wave.open(str(wav), 'wb') as w:
w.setnchannels(2); w.setsampwidth(2); w.setframerate(RATE)
w.writeframes((np.clip(track, -1, 1) * 32767).astype('<i2').tobytes())
# Pass 2: frames, piped into the encoder with the audio track.
enc = subprocess.Popen(['ffmpeg', '-v', 'error', '-y', '-f', 'image2pipe', '-framerate', str(a.fps), '-c:v', 'mjpeg',
- '-i', '-', '-i', str(wav), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20',
- '-preset', 'medium', '-c:a', 'aac', '-b:a', '160k', '-shortest', str(video)],
+ '-i', '-', '-i', str(wav), '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', # H.264 wants even sizes
+ '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20',
+ '-preset', 'medium', '-c:a', 'aac', '-b:a', '160k', '-shortest', str(part)],
stdin=subprocess.PIPE)
frames = 0
- for k, (i, bid) in enumerate(beats):
- await open_beat(pg, base, i)
- n = counts[k]
- for f in range(n):
- await pg.evaluate('t => { P.t = t; evalTo(t); }', f / a.fps)
- enc.stdin.write(await pg.screenshot(clip=clip, type='jpeg', quality=92))
- frames += 1
- print(f'{bid}: {n} frames', flush=True)
- if end_s:
- await pg.evaluate(END_CARD, a.link or '')
- end = await pg.screenshot(clip=clip, type='jpeg', quality=92)
- for _ in range(end_s * a.fps):
- enc.stdin.write(end)
- enc.stdin.close(); enc.wait()
+ try:
+ for k, (i, bid) in enumerate(beats):
+ await open_beat(pg, base, i)
+ n = counts[k]
+ for f in range(n):
+ await pg.evaluate('t => { P.t = t; evalTo(t); }', f / a.fps)
+ enc.stdin.write(await pg.screenshot(clip=clip, type='jpeg', quality=92))
+ frames += 1
+ print(f'{bid}: {n} frames', flush=True)
+ if end_s:
+ await pg.evaluate(END_CARD, [a.link or '', asks])
+ end = await pg.screenshot(clip=clip, type='jpeg', quality=92)
+ for _ in range(end_s * a.fps):
+ enc.stdin.write(end)
+ enc.stdin.close()
+ except BrokenPipeError: # the encoder stopped: its error is printed above
+ pass
+ enc.wait()
shutil.rmtree(audio_dir, ignore_errors=True)
await b.close()
with open(out / f'{a.chapter}.srt', 'w', encoding='utf-8') as f:
for k, (t0, t1, line) in enumerate(cues, 1):
f.write(f'{k}\n{srt_time(t0)} --> {srt_time(t1)}\n{line}\n\n')
if errs or enc.returncode:
+ part.unlink(missing_ok=True)
sys.exit(f'failed: {errs[:3]} encoder {enc.returncode}')
+ part.replace(video)
print(f'{video} ({total / 60:.1f} min, {frames} frames, {len(beats)} beats{"; question beats left out" if asks else ""}; '
- f'sound peak {peak:.2f}{" (clipped)" if peak > 1 else ""}) and {a.chapter}.srt')
+ f'sound peak {peak:.2f}{f" turned down to 0.98 (x{.98 / peak:.2f}) so as not to clip" if peak > 1 else ""}) and {a.chapter}.srt')
if __name__ == '__main__':
@@ -205,4 +217,5 @@ if __name__ == '__main__':
ap.add_argument('--query', default='', help='extra page query, e.g. tags (the source and AI-illustration tags)')
args = ap.parse_args()
QUERY = args.query + '&' if args.query else ''
+ args.url = args.url.rstrip('/') + '/'
asyncio.run(main(args))
diff --git a/.claude/skills/papermorph/scripts/join.py b/.claude/skills/papermorph/scripts/join.py
index 9ce8f17..9fec78b 100644
--- a/.claude/skills/papermorph/scripts/join.py
+++ b/.claude/skills/papermorph/scripts/join.py
@@ -22,12 +22,12 @@ if len(sys.argv) < 3 or sys.argv[1] in ('-h', '--help'):
print(__doc__); sys.exit(0 if sys.argv[1:2] in (['-h'], ['--help']) else 2)
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(';'))
+d = pathlib.Path(sys.argv[1]); T = json.loads((d / 'timings.js').read_text(encoding='utf-8').split('=', 1)[1].rstrip().rstrip(';'))
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]
-WB = json.loads(words.with_suffix('.timings.json').read_text()) if words else {} # per-beat word times, to place caption ends
+WB = json.loads(words.with_suffix('.timings.json').read_text(encoding='utf-8')) if words else {} # per-beat word times, to place caption ends
def silence(path, sec):
subprocess.run(['ffmpeg', '-v', 'error', '-y', '-f', 'lavfi', '-i', 'anullsrc=r=24000:cl=mono', '-t', str(sec), '-b:a', '64k', str(path)], check=True)
out, H = {}, {} # H: every shot's holes, for the mouths
@@ -59,7 +59,7 @@ for arg in args:
gap = pathlib.Path(tmp) / 'gap.mp3'; silence(gap, GAP)
lst = pathlib.Path(tmp) / 'list.txt'
q = lambda f: "file '" + str(f).replace("'", "'\\''") + "'\n" # the concat list's quoting: ' becomes '\''
- lst.write_text(''.join(''.join(q(f) for f in piece(b)) + (q(gap) if i < len(beats) - 1 else '') for i, b in enumerate(beats)))
+ lst.write_text(''.join(''.join(q(f) for f in piece(b)) + (q(gap) if i < len(beats) - 1 else '') for i, b in enumerate(beats)), encoding='utf-8')
subprocess.run(['ffmpeg', '-v', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', str(lst), '-c:a', 'libmp3lame', '-b:a', '64k', str(d / f'{shot}.mp3')], check=True)
parts, cues, marks, at = {}, [], {}, 0
for b in beats:
@@ -84,18 +84,18 @@ for arg in args:
H.update(holes)
out[shot] = {'dur': round(dur, 3), 'marks': marks, 'cues': cues, 'parts': parts}
# a clip with holes gets its mouth cues moved the same way (and shut at each hole), after mouths.js in the page
-mp = d / 'mouths.js'; M = json.loads(mp.read_text().split('=', 1)[1].rstrip().rstrip(';')) if mp.exists() else {}
+mp = d / 'mouths.js'; M = json.loads(mp.read_text(encoding='utf-8').split('=', 1)[1].rstrip().rstrip(';')) if mp.exists() else {}
sh = lambda b, t: t + sum(sec for at, sec in H[b] if t >= at)
moved = {b: sorted([[round(sh(b, t), 3), k] for t, k in M[b]] + [[round(sh(b, at - 1e-3), 3), 'X'] for at, _ in H[b]])
for b in H if H[b] and b in M}
(d / 'shots.js').write_text(''.join(f'TIMINGS.{k} = {json.dumps(v)};\n' for k, v in out.items()) + ''.join(f'MOUTHS.{b} = {json.dumps(v)};\n' for b, v in moved.items()))
if words: # every word where it is heard in its scene clip
- W, lines = json.loads(words.with_suffix('.timings.json').read_text()), []
+ W, lines = json.loads(words.with_suffix('.timings.json').read_text(encoding='utf-8')), []
for sc, v in out.items():
lines.append(f"{sc} dur {v['dur']} (scene-clip times; the beat clock adds the scene's pre)")
for b, p in v['parts'].items():
hs = ' '.join(f'[hole {round(p + sh(b, at - 1e-6), 2)}…{round(p + sh(b, at - 1e-6) + sec, 2)}]' for at, sec in H.get(b, []))
ws = W.get(b, {}).get('words', [])
lines.append(f" {b} @{p} {hs} | " + (' '.join(f'{w}@{round(p + sh(b, t) + LAG, 2)}' for t, w in ws) or '(silence)'))
- words.with_suffix('.words.txt').write_text('\n'.join(lines) + '\n')
+ words.with_suffix('.words.txt').write_text('\n'.join(lines) + '\n', encoding='utf-8')
print({k: (v['dur'], v['parts']) for k, v in out.items()})
diff --git a/.claude/skills/papermorph/scripts/ledger.py b/.claude/skills/papermorph/scripts/ledger.py
index cf3d371..624cc72 100644
--- a/.claude/skills/papermorph/scripts/ledger.py
+++ b/.claude/skills/papermorph/scripts/ledger.py
@@ -14,7 +14,7 @@ def print_total(path, note=""):
by = {}
for r in rs:
by[r[2]] = by.get(r[2], 0) + float(r[4])
- tail = f" ({len(rs)} pictures{', ' + note if note else ''})"
+ tail = f" ({len(rs)} rows{', ' + note if note else ''})"
for m, c in sorted(by.items()):
print(f"{m:40s} {c:8.4f} USD")
print(f"{'total':40s} {sum(by.values()):8.4f} USD{tail}")
diff --git a/.claude/skills/papermorph/scripts/lint.py b/.claude/skills/papermorph/scripts/lint.py
index 06f0086..20c22df 100644
--- a/.claude/skills/papermorph/scripts/lint.py
+++ b/.claude/skills/papermorph/scripts/lint.py
@@ -6,8 +6,9 @@
python3 lint.py site/<book> --content content/<book> --brief books/<book>
Errors (exit status 1):
- global a top-level name in the chapter or a lib file it loads is also declared by the engine or another of
- its scripts; a second const/let/class stops the page script, a second function silently replaces one
+ global a top-level name in the chapter or a lib file it loads (every name of const a = 1, b = 2) is also
+ declared by the engine or another of its scripts; a second const/let/class stops the page script, a
+ second function silently replaces one
math the chapter uses a maths helper from lib/math.js but does not load it after engine.js
beat a beat id has no entry in audio/<lang>/timings.js or no MP3
mark m('name') is not a mark of any beat
@@ -15,17 +16,21 @@ Errors (exit status 1):
style style.json is not valid JSON or lacks schema, tier, book, words, look or voice
Warnings: a beat's m('name') not among that beat's own marks (beats built by shared helpers can mislead this);
no beats recognised in a chapter; no narration file to check against.
---content defaults to content/<book> (content/ for the first book's legacy layout), --brief to books/<book>.
+--content defaults to content/<book> (content/ when that is missing and content/chNN exists: the first book's legacy
+layout), --brief to books/<book>. ElevenLabs audio tags such as [whispers] are not counted as narration text.
"""
import argparse, json, re, sys
from pathlib import Path
DECL = re.compile(r'(?<![\w$.])(?:async\s+)?(function\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)')
+KW = re.compile(r'(?<![\w$.])(const|let|var)\s+')
+NEXT = re.compile(r',\s*([A-Za-z_$][\w$]*)\s*=(?!=)') # a later declarator: , name =
SRC = re.compile(r'<script\s+src="([^"]+)"')
INLINE = re.compile(r'<script>(.*?)</script>', re.S)
BEAT = re.compile(r"\[\s*'(\w+)'\s*,\s*(['\"`])(?:\\.|(?!\2).)*\2\s*,\s*(?:\(\s*(?:m\b|\))|m\s*=>)") # ['id', 'title', (m, D) =>
MCALL = re.compile(r"(?<![\w$.])m\(\s*'(\w+)'\s*[,)]")
MARK = re.compile(r'\[\[(\w+)\]\]')
+TAG = re.compile(r'(?<!\[)\[[^\[\]]+\](?!\])') # an ElevenLabs v4 audio tag, [whispers]: performed, not in captions (eleven.py's)
ENGINE_FILES = {'engine.js', 'math.js', 'volume.js', 'contents.js', 'units.js'}
LOCAL = re.compile(r'[,(]\s*([A-Za-z_$][\w$]*)\s*=(?![=>])') # a, name = … or (p, name = 1): declared in a list
PARAMS = re.compile(r'function\s*[\w$]*\s*\(([^)]*)\)|\(([^()]*)\)\s*=>|([A-Za-z_$][\w$]*)\s*=>') # parameters
@@ -93,10 +98,19 @@ def depth0(text):
def decls(text):
- """Top-level declarations of a script: name, kind and line."""
+ """Top-level declarations of a script: name, kind and line, every declarator of const a = 1, b = 2 included."""
code, top = depth0(text)
- return [(m.group(2), m.group(1), code.count('\n', 0, m.start()) + 1)
- for m in DECL.finditer(code) if top[m.start()]]
+ out = [(m.group(2), m.group(1), m.start()) for m in DECL.finditer(code) if top[m.start()]]
+ for m in KW.finditer(code):
+ if not top[m.start()]:
+ continue
+ i, n = m.end(), len(code) # to the statement's end: ';' at depth 0, or a line break not ending in ',' or an operator
+ while i < n and not (top[i] and (code[i] == ';' or code[i] == '\n' and not code[m.end():i].rstrip().endswith(
+ (',', '=', '?', ':', '(', '+', '-', '&&', '||')))):
+ i += 1
+ seg = ''.join(c if top[k] else ' ' for k, c in enumerate(code[m.end():i], m.end())) # nested code blanked
+ out += [(d.group(1), m.group(1), m.end() + d.start(1)) for d in NEXT.finditer(seg)]
+ return [(name, kind, code.count('\n', 0, at) + 1) for name, kind, at in sorted(out, key=lambda d: d[2])]
def timings(path):
@@ -110,7 +124,7 @@ def timings(path):
def words(s):
- return re.sub(r'[^\w]+', ' ', MARK.sub('', s)).lower().split()
+ return re.sub(r'[^\w]+', ' ', TAG.sub(' ', MARK.sub('', s))).lower().split()
def lint_chapter(ch, content, out):
@@ -151,7 +165,7 @@ def lint_chapter(ch, content, out):
if used:
err('math', f"uses {', '.join(used)} from lib/math.js: load ../lib/math.js right after engine.js")
# beats, audio, marks
- lang = (re.search(r"language:\s*'(\w+)'", inline) or [None, 'en'])[1]
+ lang = (re.search(r"""language:\s*['"](\w+)['"]""", inline) or [None, 'en'])[1]
tpath = ch / 'audio' / lang / 'timings.js'
if not tpath.exists():
return err('beat', f'no audio/{lang}/timings.js')
@@ -178,12 +192,13 @@ def lint_chapter(ch, content, out):
if nar.exists():
N = json.loads(nar.read_text(encoding='utf-8-sig')).get('beats', {})
for b, text in N.items():
+ said = text['text'] if isinstance(text, dict) else text # the marks are in what is said
if isinstance(text, dict): # a beat with a speaker; its caption is the subtitle when it has one
text = text.get('sub') or text['text']
if b not in T:
err('stale', f'narration beat {b} has no timings')
continue
- if set(MARK.findall(text)) != set(T[b].get('marks', {})):
+ if set(MARK.findall(said)) != set(T[b].get('marks', {})):
err('stale', f'beat {b}: narration marks differ from timings.js')
cues = ' '.join(c[1] for c in T[b].get('cues', []))
if cues and words(text) != words(cues):
@@ -213,7 +228,8 @@ def main():
ap.add_argument('--brief', type=Path)
a = ap.parse_args()
root, slug = a.book.resolve().parent.parent, a.book.resolve().name
- content = a.content or next((c for c in (root / 'content' / slug, root / 'content') if c.is_dir()), root / 'content' / slug)
+ legacy = not (root / 'content' / slug).is_dir() and any((root / 'content').glob('ch[0-9]*')) # the first book's content/chNN
+ content = a.content or root / 'content' / ('' if legacy else slug)
chs = [a.book / c for c in a.chapters] if a.chapters else sorted(a.book.glob('ch[0-9]*'))
out = []
for ch in chs:
diff --git a/.claude/skills/papermorph/scripts/mouths.py b/.claude/skills/papermorph/scripts/mouths.py
index b0d328b..3e5153a 100644
--- a/.claude/skills/papermorph/scripts/mouths.py
+++ b/.claude/skills/papermorph/scripts/mouths.py
@@ -16,7 +16,7 @@ import json, re, subprocess, sys, pathlib
if len(sys.argv) < 3 or sys.argv[1] in ('-h', '--help'):
print(__doc__); sys.exit(0 if sys.argv[1:2] in (['-h'], ['--help']) else 2)
src, out = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])
-cache = json.loads(src.with_suffix('.timings.json').read_text())
+cache = json.loads(src.with_suffix('.timings.json').read_text(encoding='utf-8'))
RULES = [('oo', 'F'), ('ou', 'F'), ('ow', 'F'), ('th', 'B'), ('ee', 'C'), ('ea', 'C'), ('ai', 'C'), ('ay', 'C'),
('m', 'A'), ('b', 'A'), ('p', 'A'), ('f', 'G'), ('v', 'G'), ('w', 'F'), ('u', 'F'), ('o', 'E'), ('a', 'D'),
('e', 'C'), ('i', 'C'), ('y', 'C'), ('l', 'H')]
diff --git a/.claude/skills/papermorph/scripts/overlap.py b/.claude/skills/papermorph/scripts/overlap.py
index 4afcb23..80a73b7 100644
--- a/.claude/skills/papermorph/scripts/overlap.py
+++ b/.claude/skills/papermorph/scripts/overlap.py
@@ -51,7 +51,7 @@ MEASURE = r"""
const m = inv.multiply(el.getScreenCTM()), sc = Math.hypot(m.a, m.b);
const q = [[b.x + 1, top], [b.x + b.width - 1, top], [b.x + b.width - 1, bot], [b.x + 1, bot]].map(([x, y]) => f(x, y));
const xs = q.map(p => p[0]), ys = q.map(p => p[1]);
- if (Math.max(...xs) < 0 || Math.min(...xs) > 1600 || Math.max(...ys) < 0 || Math.min(...ys) > 900) continue;
+ if (Math.max(...xs) < 0 || Math.min(...xs) > SW || Math.max(...ys) < 0 || Math.min(...ys) > SH) continue; // off the stage (upright too)
// q: the ink box corners on stage (rotated text stays a rotated box); mi maps stage points back to text space
texts.push({ s, q, mi: m.inverse(), x0: b.x + 1, x1: b.x + b.width - 1, top, bot, sc });
}
diff --git a/.claude/skills/papermorph/scripts/paint.py b/.claude/skills/papermorph/scripts/paint.py
index bf5541b..53d2f9e 100644
--- a/.claude/skills/papermorph/scripts/paint.py
+++ b/.claude/skills/papermorph/scripts/paint.py
@@ -13,7 +13,8 @@ account balance is below $1.00, so top up before a batch.
Each call prints the cost OpenRouter reports and appends one line to the ledger (date, file, model, quality, cost, tab
separated; the ledger and its folder are created). Test the cheapest quality first and total the ledger before and
-after a batch, so the spend is known.
+after a batch, so the spend is known. An existing OUT is never replaced (it may be an approved, paid picture) unless
+--force is given.
"""
import argparse, base64, datetime, json, mimetypes, os, pathlib, sys, urllib.request, urllib.error
@@ -38,9 +39,12 @@ def main():
ap.add_argument("--bg", default="auto", choices=["auto", "transparent", "opaque"])
ap.add_argument("--model", default="openai/gpt-image-2.5-flare")
ap.add_argument("--ledger", required=True, help="tab-separated cost log, e.g. books/<book>/art/costs.tsv")
+ ap.add_argument("--force", action="store_true", help="replace an existing OUT")
a = ap.parse_args()
if a.q == "high":
raise SystemExit("quality high is refused: use low or medium")
+ if pathlib.Path(a.out).exists() and not a.force:
+ raise SystemExit(f"{a.out} exists: give a new name, or --force to replace it")
body = {"model": a.model, "prompt": a.prompt, "aspect_ratio": a.ar, "output_format": "png"}
if a.model.startswith("openai/"):
body.update(quality=a.q, background=a.bg)
@@ -56,14 +60,18 @@ def main():
except urllib.error.HTTPError as e:
err = e.read().decode(errors="replace").replace(k, "***")[:500] # redact the whole body, then trim
raise SystemExit(f"{e.code} {err}")
- out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)
- out.write_bytes(base64.b64decode(r["data"][0]["b64_json"]))
usage = r.get("usage") or {}
cost = usage.get("cost", 0) or 0
print(a.out, f"cost {cost} USD", json.dumps(usage))
led = pathlib.Path(a.ledger); led.parent.mkdir(parents=True, exist_ok=True)
- with led.open("a", encoding="utf-8") as f:
+ with led.open("a", encoding="utf-8") as f: # logged first: the call is paid for even if no picture came back
f.write(f"{datetime.date.today()}\t{a.out}\t{a.model}\t{a.q}\t{cost}\n")
+ try:
+ png = base64.b64decode(r["data"][0]["b64_json"])
+ except (KeyError, IndexError, TypeError):
+ raise SystemExit(f"no picture in the answer: {json.dumps(r).replace(k, '***')[:500]}")
+ out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)
+ out.write_bytes(png)
if __name__ == "__main__":
diff --git a/.claude/skills/papermorph/scripts/playlog.py b/.claude/skills/papermorph/scripts/playlog.py
index 166b243..9006e93 100644
--- a/.claude/skills/papermorph/scripts/playlog.py
+++ b/.claude/skills/papermorph/scripts/playlog.py
@@ -68,6 +68,7 @@ async def main(a):
url = f"{a.url}{a.chapter}/index.html"
await pg.goto(url); await pg.wait_for_timeout(1000)
ids = await pg.evaluate("BEATS.map(b => b.id)")
+ cw, ch = 400, round(400 * await pg.evaluate("SH / SW")) # a frame 400 wide, in the stage's shape (upright too)
def beat(s):
if s.isdigit() and int(s) < len(ids): return int(s)
if s in ids: return ids.index(s)
@@ -92,18 +93,18 @@ async def main(a):
await pg.evaluate(f"seek({e['i']}, false)")
await pg.evaluate(f"P.t = {e['t']}; evalTo({e['t']})"); await pg.wait_for_timeout(120)
r = await pg.evaluate("(() => { const r = document.getElementById('stage').getBoundingClientRect(); return {x: r.x, y: r.y, width: r.width, height: r.height}; })()")
- shots.append((e, Image.open(io.BytesIO(await pg.screenshot(clip=r))).convert("RGB").resize((400, 225))))
+ shots.append((e, Image.open(io.BytesIO(await pg.screenshot(clip=r))).convert("RGB").resize((cw, ch))))
await b.close()
lines = [f"{ids[e['i']]:10} {e['t']:6.2f} {e['kind']:5} {e['what']}" + (f" vol {e['vol']:.2f}" if e['kind'] == 'sfx' else '') for e, _ in shots]
if afail: lines.append("note: sound did not play in this browser; the clock ran on wall time")
(a.out / f"{a.chapter}_playlog.txt").write_text("\n".join(lines) + "\n", encoding="utf-8")
print("\n".join(lines))
if shots:
- S = Image.new("RGB", (1600, 225 * ((len(shots) + 3) // 4)), (20, 30, 27))
+ S = Image.new("RGB", (4 * cw, ch * ((len(shots) + 3) // 4)), (20, 30, 27))
for k, (e, im) in enumerate(shots):
d = ImageDraw.Draw(im); label = f"{ids[e['i']]} {e['t']:.2f} {e['kind']} {e['what'][:40]}"
d.rectangle((0, 0, 7 * len(label) + 8, 16), fill=(0, 0, 0)); d.text((4, 3), label, fill=(255, 230, 120))
- S.paste(im, ((k % 4) * 400, (k // 4) * 225))
+ S.paste(im, ((k % 4) * cw, (k // 4) * ch))
S.save(a.out / f"{a.chapter}_playlog.jpg", quality=84)
print(f"{len(shots)} events | log and frames in {a.out}" + (f" | PAGE ERRORS: {errs[:5]}" if errs else ""))
return 1 if errs else 0
diff --git a/.claude/skills/papermorph/scripts/refs.py b/.claude/skills/papermorph/scripts/refs.py
index 2a80c0b..b3b1bfd 100644
--- a/.claude/skills/papermorph/scripts/refs.py
+++ b/.claude/skills/papermorph/scripts/refs.py
@@ -9,6 +9,7 @@ refs.json is the book's source list, one entry per cited work (fields after "cit
[{"key": "scheper-hughes-lock-1987", "cite": "Scheper-Hughes & Lock (1987)",
"authors": ["Scheper-Hughes, Nancy", "Lock, Margaret M."], "year": 1987,
"title": "The mindful body", "type": "article"}, ...]
+A group author is {"org": "World Health Organization"} in authors (a plain string is split into family and initials).
"type" is article, book, chapter or web. Optional: container, volume, issue, pages, publisher,
editors, edition ("4th ed."), doi, isbn, nolink (why no reliable record exists), url (a trusted academic page, used only when there is no DOI or ISBN), and
match: other on-screen spellings of the citation (e.g. "Robert Crawford (1980)", "Cobb 1958"); the
@@ -78,7 +79,7 @@ def norm(s):
def surname(a):
"""Family name of 'Family, Given' / 'Given Family' / Crossref author dict."""
if isinstance(a, dict):
- return a.get("family") or a.get("name") or ""
+ return a.get("family") or a.get("name") or a.get("org") or ""
return a.split(",")[0] if "," in a else a.split()[-1]
@@ -274,7 +275,9 @@ SUFFIX = re.compile(r",?\s*\b(Jr|Sr|II|III|IV)\.?\s*$", re.I)
def split_name(a):
- """'Family, Given[, Jr.]' or 'Given Family' -> (family, initials, suffix)."""
+ """'Family, Given[, Jr.]', 'Given Family' or {"org": name} -> (family, initials, suffix)."""
+ if isinstance(a, dict): # {"org": "World Health Organization"}: a group author, written as it is
+ return a.get("org", "").strip(), "", ""
suf, a = "", a.strip()
m = SUFFIX.search(a)
if m:
@@ -313,6 +316,7 @@ def apa_authors(names):
def apa(e):
au = apa_authors(e.get("authors", []))
+ au = au and (au if au.endswith(".") else au + ".") # a group author or a bare name ends with a full stop too
yr = f"({e.get('year', 'n.d.')})."
t = e.get("title", "").rstrip(".")
end = lambda s: s if s.endswith((".", "?", "!")) else s + "."
diff --git a/.claude/skills/papermorph/scripts/shot.py b/.claude/skills/papermorph/scripts/shot.py
index af1db1e..ecf4969 100644
--- a/.claude/skills/papermorph/scripts/shot.py
+++ b/.claude/skills/papermorph/scripts/shot.py
@@ -14,11 +14,12 @@ TIME is seconds on the beat clock, open (1.2 s), mid (half the beat) or end (the
the picture the next beat cuts from). Writes OUT/chNN_bII_T.png and OUT/chNN_sheet_T_K.png (2x2, half size; open
the sheets first). --out is required: give each review its own folder (books/<book>/review/...).
- --clean the stage alone: no player bar, captions, cards or notes, cropped to the 1600x900 stage
+ --clean the stage alone: no player bar, captions, cards or notes, cropped to the stage (1600x900, or 900x1600
+ for a book with <html data-stage="portrait">)
--cuts [BEAT ...] a cut sheet, OUT/chNN_cuts.jpg: for every beat boundary, the last frame of the beat beside the
first frame of the next (clean), one boundary a row; with beats, only the boundaries into and out of
them (OUT/chNN_cuts_BEAT.jpg). Look for jumps in place, pose, light and screen direction
- --webp W also write each shot as a W-wide 16:9 WebP (implies --clean): a series-page still or a cover
+ --webp W also write each shot as a W-wide WebP of the stage's shape (implies --clean): a series-page still or a cover
(stories.md: 1400 wide); --name NAME names it OUT/NAME.webp (one moment only)
Uses ?beat=N&t=0, then sets the beat clock to the moment, as playback would reach it. The page runs with reduced
@@ -50,6 +51,8 @@ async def main(a):
if errs:
print("page errors:", errs); await b.close(); return 1
ids = await pg.evaluate("BEATS.map(b => b.id)")
+ SW, SH = await pg.evaluate("[SW, SH]") # 1600 x 900, or 900 x 1600 upright
+ await pg.set_viewport_size({"width": SW + 40, "height": SH + 100}) # the page then draws the stage at scale 1
async def grab(i, t, clean):
"""The picture of beat i at t (seconds, open, mid, end) as an RGB image, and the time used."""
@@ -62,7 +65,7 @@ async def main(a):
await pg.wait_for_timeout(450)
clip = await pg.evaluate("(() => { const r = document.getElementById('stage').getBoundingClientRect(); return {x: r.x, y: r.y, width: r.width, height: r.height}; })()") if clean else None
im = Image.open(io.BytesIO(await pg.screenshot(clip=clip))).convert("RGB")
- return (im.resize((1600, 900), Image.LANCZOS) if clean else im), sec # stage pixels = stage coordinates
+ return (im.resize((SW, SH), Image.LANCZOS) if clean else im), sec # stage pixels = stage coordinates
def beat(s):
if s.isdigit() and int(s) < len(ids): return int(s)
@@ -81,19 +84,19 @@ async def main(a):
groups.setdefault(t, []).append(f)
if a.webp:
w = a.out / f"{a.name or f.stem}.webp"
- im.resize((a.webp, round(a.webp * 9 / 16)), Image.LANCZOS).save(w, quality=88); print("still", w)
+ im.resize((a.webp, round(a.webp * SH / SW)), Image.LANCZOS).save(w, quality=88); print("still", w)
if a.cuts is not None:
- rows, only = [], {beat(s) for s in a.cuts}
+ rows, only, cw, chh = [], {beat(s) for s in a.cuts}, SW // 2, SH // 2 # each frame at half size
for i in range(len(ids) - 1):
if only and not only & {i, i + 1}: continue
(x, tx), (y, ty) = await grab(i, "end", True), await grab(i + 1, "0.05", True)
- pair = Image.new("RGB", (1608, 450), (20, 30, 27))
+ pair = Image.new("RGB", (2 * cw + 8, chh), (20, 30, 27))
for k, (im, label) in enumerate(((x, f"{ids[i]} end t={tx:.2f}"), (y, f"{ids[i + 1]} start t={ty:.2f}"))):
- pair.paste(im.resize((800, 450)), (k * 808, 0)); ImageDraw.Draw(pair).text((k * 808 + 8, 6), label, fill=(255, 230, 120))
+ pair.paste(im.resize((cw, chh)), (k * (cw + 8), 0)); ImageDraw.Draw(pair).text((k * (cw + 8) + 8, 6), label, fill=(255, 230, 120))
rows.append(pair)
if rows:
- S = Image.new("RGB", (1608, 458 * len(rows)), (20, 30, 27))
- for k, r in enumerate(rows): S.paste(r, (0, k * 458))
+ S = Image.new("RGB", (2 * cw + 8, (chh + 8) * len(rows)), (20, 30, 27))
+ for k, r in enumerate(rows): S.paste(r, (0, k * (chh + 8)))
f = a.out / f"{a.chapter}_cuts{''.join('_' + ids[i] for i in sorted(only))}.jpg"
S.save(f, quality=86); print("cut sheet", f)
# pieces a picture book bakes in the browser: missing from img/puppets/baked.js (key hash = its file name there)
@@ -106,10 +109,11 @@ async def main(a):
for h, box, svg in live: print(f" {h} {box:18} {svg}")
for t, fs in groups.items():
if len(fs) < 2: continue
+ w, h = (d // 2 for d in Image.open(fs[0]).size) # half size
for k in range(0, len(fs), 4):
- sheet = Image.new("RGB", (1600, 960), "black")
+ sheet = Image.new("RGB", (2 * w, 2 * h), "black")
for j, f in enumerate(fs[k:k + 4]):
- im = Image.open(f); sheet.paste(im.resize((800, 800 * im.height // im.width)), ((j % 2) * 800, (j // 2) * 480))
+ sheet.paste(Image.open(f).resize((w, h)), ((j % 2) * w, (j // 2) * h))
sheet.save(a.out / f"{a.chapter}_sheet_{t}_{k // 4}.png")
print("errors:", sorted(set(errs))[:8] or "none", "| shots in", a.out)
return 1 if errs else 0
@@ -130,7 +134,7 @@ if __name__ == "__main__":
ap.add_argument("--clean", action="store_true", help="the stage alone, no player UI")
ap.add_argument("--cuts", nargs="*", metavar="BEAT", help="cut sheet: each beat's last frame beside the next one's first; "
"with beats, only the cuts into and out of them")
- ap.add_argument("--webp", type=int, metavar="W", help="also save each shot as a W-wide 16:9 WebP (clean)")
+ ap.add_argument("--webp", type=int, metavar="W", help="also save each shot as a W-wide WebP of the stage's shape (clean)")
ap.add_argument("--name", help="file name (without .webp) for the one --webp still")
a = ap.parse_args()
a.url = a.url if a.url.endswith("/") else a.url + "/"
diff --git a/.claude/skills/papermorph/scripts/split_pages.py b/.claude/skills/papermorph/scripts/split_pages.py
index 81938ed..8036de8 100644
--- a/.claude/skills/papermorph/scripts/split_pages.py
+++ b/.claude/skills/papermorph/scripts/split_pages.py
@@ -13,8 +13,8 @@ cheaper than an image). Scanned books have no text layer, so text.md comes out e
Files are named page_NNNN.png by PDF page order (from 1), never by printed page numbers.
The script refuses a map with gaps or overlaps, and refuses to overwrite existing images
-unless --overwrite is given. The pages are a private reference for the author; they are
-never published with the site.
+or text.md (which may hold hand-typed text) unless --overwrite is given. The pages are a
+private reference for the author; they are never published with the site.
"""
import argparse
import json
@@ -78,7 +78,9 @@ def main():
d = a.out / s["folder"]
d.mkdir(parents=True, exist_ok=True)
text = [f"## page {p}\n\n{doc[p - 1].get_text().strip()}\n" for p in range(s["start"], s["end"] + 1)]
- (d / "text.md").write_text(f"# {s['title']}\n\n" + "\n".join(text), encoding="utf-8")
+ md = d / "text.md" # kept unless --overwrite: it may hold text typed in by hand (a scanned book)
+ if a.overwrite or not md.exists():
+ md.write_text(f"# {s['title']}\n\n" + "\n".join(text), encoding="utf-8")
if a.text_only:
continue
for p in range(s["start"], s["end"] + 1):
diff --git a/.claude/skills/papermorph/scripts/strip.py b/.claude/skills/papermorph/scripts/strip.py
index 4b01bc7..b5ecd3c 100644
--- a/.claude/skills/papermorph/scripts/strip.py
+++ b/.claude/skills/papermorph/scripts/strip.py
@@ -61,6 +61,8 @@ async def main(a):
pg = await b.new_page(viewport={"width": 1600, "height": 960}, reduced_motion="reduce") # no wall-clock CSS motion
errs = []; pg.on("pageerror", lambda e: errs.append(str(e)))
await pg.goto(f"{a.url}{a.chapter}/?beat=0&t=0"); await pg.wait_for_timeout(800)
+ sw, sh = await pg.evaluate("[SW, SH]") # the stage at scale 1, 1600 x 900 or 900 x 1600 upright
+ await pg.set_viewport_size({"width": sw + 40, "height": sh + 100})
at = {"i": -1, "t": 0.0}
cam = {"off": False}
async def shot(t, scale):
diff --git a/.claude/skills/papermorph/scripts/tts.py b/.claude/skills/papermorph/scripts/tts.py
index 758fc0e..e22562f 100644
--- a/.claude/skills/papermorph/scripts/tts.py
+++ b/.claude/skills/papermorph/scripts/tts.py
@@ -10,7 +10,7 @@ voices start with the accent's letter (am_michael, af_heart: American; bm_george
timings cover English. Both need ffmpeg/ffprobe.
A book with several speakers lists them under "voices" ({name: {"voice", "rate", "pitch"}}) and writes a
-beat as {"speaker": name, "text": ...}; plain string beats use the file's own voice. Pitch is Edge only ("+20Hz").
+beat as {"speaker": name, "text": ...}; plain string beats (and beats without a speaker) use the file's own voice. Pitch is Edge only ("+20Hz").
Narration text may contain [[mark]] tags placed before a word. The output
timings.js records each clip's duration and the time (seconds) at which the
@@ -227,7 +227,10 @@ async def main(src, out_dir):
if {"dur", "marks", "cues"} <= v.keys() and (out_dir / f"{b}.mp3").exists()}
timings_path = out_dir / "timings.js"
for beat, raw in spec["beats"].items():
- who = voices[raw["speaker"]] if isinstance(raw, dict) else spec
+ name = raw.get("speaker") if isinstance(raw, dict) else None
+ if name is not None and name not in voices:
+ raise SystemExit(f"{beat}: speaker {name!r} is not under the narration file's \"voices\"")
+ who = voices[name] if name is not None else spec # no speaker: the file's own voice
sub = raw.get("sub") if isinstance(raw, dict) else None # the line's subtitle, one cue for the whole clip
raw = raw["text"] if isinstance(raw, dict) else raw
voice, rate, pitch = who["voice"], who.get("rate", "+0%"), who.get("pitch", "+0Hz")
diff --git a/.claude/skills/papermorph/scripts/video.py b/.claude/skills/papermorph/scripts/video.py
index 2e965c4..99bb24d 100644
--- a/.claude/skills/papermorph/scripts/video.py
+++ b/.claude/skills/papermorph/scripts/video.py
@@ -37,7 +37,8 @@ if not jid:
img = f"data:{mimetypes.guess_type(a.frame)[0] or 'image/png'};base64," + base64.b64encode(pathlib.Path(a.frame).read_bytes()).decode()
body = {"model": a.model, "prompt": a.prompt, "duration": a.duration, "resolution": a.resolution, "aspect_ratio": a.aspect,
"generate_audio": False, "frame_images": [{"type": "image_url", "image_url": {"url": img}, "frame_type": "first_frame"}]}
- jid = json.load(call("https://openrouter.ai/api/v1/videos", body))["id"]
+ r = json.load(call("https://openrouter.ai/api/v1/videos", body)); jid = r.get("id")
+ if not jid: raise SystemExit(f"no job id in the answer: {json.dumps(r).replace(k, '***')[:500]}")
print(a.model, "job", jid, flush=True)
t0, fails = time.time(), 0
while True:
diff --git a/README.md b/README.md
index 8d4c41c..ac9a831 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.4.1`. 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.4.2`. 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