Skip to content

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

docs(skill): documentaries reviewed: folder order, models, kit, README

yzr64ee8d12d9cc
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index a0bed78..ce1a7b3 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -5,12 +5,13 @@ description: Make or edit animated, narrated, interactive web books from referen
# Papermorph
-Papermorph makes two kinds of book on one machine:
+Papermorph makes three kinds of book on one machine:
- **Lessons**, from a textbook PDF: each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture.
- **Picture books**, from a story, a joke or a fairy tale: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music.
+- **Documentaries**, from a book or an idea: narrated films of found public-domain pictures, words and maps moved in step with the voice, with music.
-Both are a 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included).
+All are a 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included).
What the picture should be depends on the book and on the user, so the work starts with a conversation that ends in `style.json`: the user's words, the look they chose, the voices, which model does which step, and later the approved chapters. Every chapter is made against it; how each beat is laid out and choreographed is yours to judge against it and the approved chapters. User requests override defaults. Re-create explanations, examples and drawings; keep source PDFs, page images and extracted text outside the static output folder and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`). Deliver a self-contained book folder with local preview instructions.
@@ -34,7 +35,7 @@ books/<book>/
style.json the agreed style every chapter anchors to (assets/templates/style.json)
chapters.md chapter map and status
chapters/chNN.md storyboard, errata, feedback
- images/ inbox, SOURCES.md, image-requests.md, processing scripts
+ images/ inbox, SOURCES.md (where each image came from), image-requests.md, processing scripts
review/chNN/ storyboard sheets, strips, check output
content/<book>/chNN/ narration.<lang>.json and TTS cache
tools/<book>/ tests and evidence scripts
@@ -50,7 +51,9 @@ site/<book>/ the static book (only this is delivered)
A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`); its `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`, which needs engine-v2.2 or later: `sfx()` and `music()` are in the engine) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `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, 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).
+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/`.
+
+`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
@@ -81,7 +84,7 @@ 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/`, 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.
## Scripts
@@ -99,7 +102,7 @@ All in `SKILL/scripts/`; each prints its usage with `--help` (run it with the `u
## Context
-- Talk with the user from the main conversation: intake, and every sheet and choice of the pilot. When subagents are available, chapters are made as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another; a picture book splits by scene instead. The main conversation coordinates the pilot, since the user sees its sheets; later chapters are best coordinated from a fresh session ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.
+- Talk with the user from the main conversation: intake, and every sheet and choice of the pilot. When subagents are available, chapters are made as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another; a picture book splits by scene instead, a documentary by part of the film. The main conversation coordinates the pilot, since the user sees its sheets; later chapters are best coordinated from a fresh session ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.
- A worker needs little besides this Skill and `style.json`: the user's words, the look, the approved chapters to watch and read, the element library. A brief adds the chapter, its pages, the step's inputs and outputs and any current user request. Workers reply in a few lines; the coordinator registers the chapter.
- Use the engine API and inspect individual functions when needed; copy assets rather than reading their full source as instructions.
- Keep `style.json` current and short. Chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.
diff --git a/.claude/skills/papermorph/assets/templates/documentary/chapter.html b/.claude/skills/papermorph/assets/templates/documentary/chapter.html
index ded6ac7..91b76e8 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/documentary/chapter.html
@@ -8,8 +8,8 @@
<link rel="expect" href="#bar" blocking="render">
</head>
<body>
-<!-- A documentary chapter: one beat per paragraph of the script. Copy lib/ (film.js, book.css with the ground colours,
- fonts.css and fonts/) into site/<book>/lib/ next to the engine, and this file to site/<book>/chNN/index.html. img/art.js (prep.py) lists the
+<!-- A documentary chapter: one beat per paragraph of the script. After engine.py has made site/<book>/lib/, copy lib/
+ (film.js, book.css with the film's colours, fonts.css and fonts/) over it, and this file to site/<book>/chNN/index.html. img/art.js (prep.py) lists the
found pictures; add lib/lines.js (trace.py) and img/frames.js (frames.py) when the film uses traced drawings or clips. -->
<script src="../lib/engine.js"></script>
<script src="../lib/film.js"></script>
@@ -30,7 +30,7 @@ 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: 470, h: 640, at: OPEN_PRE - .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
say(p, ['The first line, typed as it is spoken.'], 800, 820, m('first'), m('first') + 2, { size: 48, anchor: 'middle' });
}, { pre: OPEN_PRE }],
diff --git a/.claude/skills/papermorph/assets/templates/documentary/lib/book.css b/.claude/skills/papermorph/assets/templates/documentary/lib/book.css
index 25e4beb..84e1379 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/lib/book.css
+++ b/.claude/skills/papermorph/assets/templates/documentary/lib/book.css
@@ -1,5 +1,7 @@
-/* The film's ground and ink (here Madness and Civilization's burgundy and cream): --board is the ground, --chalk the ink.
- Imported by engine.css; engine.py never overwrites it. Keep film.js's colours in step. */
+/* The film's colours (here Madness and Civilization's burgundy and cream): --board is the ground, --chalk the ink on it,
+ --dim captions; --accent, and an old document's --paper, --paper-ink and --stamp, are read by film.js. Bake pictures
+ to match (prep.py and frames.py --ink is --chalk, prep.py --paper the paper). Imported by engine.css; engine.py never
+ overwrites it. */
@import url("fonts.css");
:root {
--page: #2a060a; --board: #5a0e16; --panel: #4a0b12; --edge: #7a2a30;
@@ -8,4 +10,5 @@
--vignette: rgba(20, 0, 4, .45);
--rule: #6e2028; --track: #6a1a22; --track-ask: #6a1a22;
--bar-edge: #6a1a22; --hover: #6e1e26; --veil: #22050a;
+ --accent: #f08a4b; --paper: #f3ede0; --paper-ink: #3a2a24; --stamp: #7a1a20;
}
diff --git a/.claude/skills/papermorph/assets/templates/documentary/lib/film.js b/.claude/skills/papermorph/assets/templates/documentary/lib/film.js
index 5be03b5..acc2430 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/lib/film.js
+++ b/.claude/skills/papermorph/assets/templates/documentary/lib/film.js
@@ -1,5 +1,5 @@
/* film.js — the documentary kit: found pictures, line drawings, words and maps on the engine's beat clock.
- This is the book's own copy: set its look here (fonts in lib/fonts.css, colours below) and add the film's recurring
+ This is the book's own copy: its look is set in lib/book.css (colours) and lib/fonts.css; add the film's recurring
pieces at the end. Every helper is a pure function of the beat clock, so pause, seek, ?beat=N&t=S and export.py agree.
Pictures are img/<name>.webp with their sizes in ART (img/art.js, from prep.py); traced drawings are LINES (lib/lines.js,
from trace.py); clips are FRAMES (img/frames.js, from frames.py). The fonts must be loaded before boot(): words are
@@ -7,7 +7,10 @@
'use strict';
/* ---------- the look ---------- */
const KEY = '"Oswald", "Arial Narrow", sans-serif', SER = '"EB Garamond", Georgia, serif'; // titles and key words; quotes and captions
-const CREAM = '#f3ede0', HOT = '#f08a4b', SOFT = '#d9b9b0', INK = '#3a2a24'; // ink on the ground, the accent, captions, ink on paper
+// colours from lib/book.css (read by the engine into COL, or with bookSetting): ink on the ground, the accent, captions,
+// a document's paper, ink on paper, a document's heading
+const CREAM = COL.chalk, SOFT = COL.dim, HOT = bookSetting('--accent') || '#f08a4b', PAPER = bookSetting('--paper') || CREAM,
+ INK = bookSetting('--paper-ink') || '#3a2a24', STAMP = bookSetting('--stamp') || '#7a1a20';
// a picture from img/: centred on (x, y), h or w in stage px; `at` makes it enter (from offset dx, dy) at that time
function pic(p, name, { x = 800, y = 450, h = 600, w, r = 0, s = 1, at, from = [0, 40], dur = .9, o = 1, back = false } = {}) {
@@ -57,18 +60,19 @@ function strike(p, e, x, y, t0, size, anchor = 'middle') {
const x0 = anchor === 'middle' ? x - e._w / 2 : anchor === 'end' ? x - e._w : x;
return line(p, `M${x0 - 16} ${y - size * .32}H${x0 + e._w + 16}`, t0, .4, Math.max(5, size / 12), { stroke: HOT });
}
-// serif lines typed word by word between t0 and t1
+// serif lines typed word by word between t0 and t1 (Chinese, Japanese and Korean characters one by one)
+const CJK = /[⺀-鿿가-힯豈-﫿＀-￯]|[^⺀-鿿가-힯豈-﫿＀-￯]+/g;
function say(p, lines, x, y, t0, t1, { size = 44, fill = CREAM, italic = true, anchor = 'start', lh = 1.3, weight = 400 } = {}) {
const g = G(p, {}), style = italic ? 'italic' : '', words = [];
const sp = wid(' ', size, SER, style, weight);
lines.forEach((ln, i) => {
- const ws = ln.split(' '), W = wid(ln, size, SER, style, weight);
+ const W = wid(ln, size, SER, style, weight);
let cx = anchor === 'middle' ? x - W / 2 : anchor === 'end' ? x - W : x;
- ws.forEach(w => {
+ ln.split(' ').forEach(word => (word.match(CJK) || ['']).forEach((w, j, ws) => {
const e = T(g, w, { x: cx, y: y + i * size * lh, size, fill, font: SER, weight, o: 0 });
if (italic) e.setAttribute('font-style', 'italic');
- words.push(e); cx += wid(w, size, SER, style, weight) + sp;
- });
+ words.push(e); cx += wid(w, size, SER, style, weight) + (j === ws.length - 1 ? sp : 0);
+ }));
});
const chars = words.map(e => e.textContent.length + 1), all = chars.reduce((a, b) => a + b, 0);
let acc = 0;
@@ -151,15 +155,15 @@ function anim(p, name, { x = 800, y = 450, size = 600, at = 0, t0 = at, D, o = 1
tw(g, { o }, at, .8);
return g;
}
-// an old document: cream paper, lines of ink, a label
+// an old document: paper, lines of ink, a label
function doc(p, label, x, y, r, t0, seed) {
const R = rng(seed), g = G(p, { x: x - 700, y, r, o: 0 });
- mk('rect', { x: -150, y: -200, width: 300, height: 400, fill: CREAM, stroke: '#cdbfa6' }, g);
+ mk('rect', { x: -150, y: -200, width: 300, height: 400, fill: PAPER, stroke: '#cdbfa6' }, g);
for (let i = 0; i < 13; i++) {
const yy = -130 + i * 24, ww = 160 + R() * 70;
path(g, `M-118 ${yy}q${ww / 4} ${-3 + R() * 6} ${ww / 2} 0t${ww / 2} 0`, { stroke: INK, 'stroke-width': 2, opacity: .7 });
}
- T(g, label.toUpperCase(), { y: -160, size: 22, font: KEY, weight: 600, fill: '#7a1a20', anchor: 'middle' }).setAttribute('letter-spacing', '.06em');
+ T(g, label.toUpperCase(), { y: -160, size: 22, font: KEY, weight: 600, fill: STAMP, anchor: 'middle' }).setAttribute('letter-spacing', '.06em');
tw(g, { x, o: 1 }, t0, .8, out);
g._x = x; g._y = y;
return g;
diff --git a/.claude/skills/papermorph/assets/templates/documentary/lib/fonts.css b/.claude/skills/papermorph/assets/templates/documentary/lib/fonts.css
index bc8f044..6f0e95d 100644
--- a/.claude/skills/papermorph/assets/templates/documentary/lib/fonts.css
+++ b/.claude/skills/papermorph/assets/templates/documentary/lib/fonts.css
@@ -1,4 +1,4 @@
-/* Oswald and EB Garamond (SIL Open Font License 1.1), latin subsets, from Google Fonts */
+/* Oswald and EB Garamond (SIL Open Font License 1.1), latin and latin-ext subsets, from Google Fonts */
@font-face {
font-family: 'EB Garamond';
font-style: italic;
diff --git a/.claude/skills/papermorph/assets/templates/documentary/narration.en.json b/.claude/skills/papermorph/assets/templates/documentary/narration.en.json
new file mode 100644
index 0000000..285d970
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/documentary/narration.en.json
@@ -0,0 +1,8 @@
+{
+ "engine": "edge",
+ "voice": "en-GB-RyanNeural",
+ "rate": "-4%",
+ "beats": {
+ "open": "[[first]]The first line, typed as it is spoken."
+ }
+}
diff --git a/.claude/skills/papermorph/assets/templates/documentary/style.json b/.claude/skills/papermorph/assets/templates/documentary/style.json
new file mode 100644
index 0000000..c331c2a
--- /dev/null
+++ b/.claude/skills/papermorph/assets/templates/documentary/style.json
@@ -0,0 +1,21 @@
+{
+ "schema": 1,
+ "tier": "documentary",
+ "book": { "title": "Film title", "slug": "madness", "language": "en", "readers": "curious adults, no background needed", "pilot": "ch01" },
+ "words": [
+ "The user's own words about the subject, the angle and the look, verbatim.",
+ "ch01 feedback: later words that changed the bar, with the film they came from."
+ ],
+ "angle": "The one thing a viewer should leave with, and what must be in the film (a scene, a quote, an ending)",
+ "look": {
+ "palette": { "ground": "#5a0e16", "ink": "#f3ede0", "captions": "#d9b9b0", "accent": "#f08a4b" },
+ "fonts": { "key words": "Oswald 600", "quotes and captions": "EB Garamond italic" },
+ "pictures": "print for paintings and photographs, line for clean engravings; a drawing that draws itself on once or twice"
+ },
+ "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.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/lib/shared.js b/.claude/skills/papermorph/assets/templates/picture-book/lib/shared.js
index c280127..5be267f 100644
--- a/.claude/skills/papermorph/assets/templates/picture-book/lib/shared.js
+++ b/.claude/skills/papermorph/assets/templates/picture-book/lib/shared.js
@@ -1,4 +1,4 @@
-/* shared.js — what every scene of the book uses: timing helpers, painted props, and the sound effects. Put the book's
+/* shared.js — what every scene of the book uses: timing helpers and painted props. Put the book's
recurring places and props here too (a classroom or a street built the same way whenever it appears, so the staging
matches across cuts): a function like `function room(p) { const cam = paperCam(p, 'room'); … return { cam, … }; }`. */
'use strict';
diff --git a/.claude/skills/papermorph/assets/templates/style.json b/.claude/skills/papermorph/assets/templates/style.json
index 2dbd145..57e7b97 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-AndrewMultilingualNeural", "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.1" },
+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.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/documentary.md b/.claude/skills/papermorph/references/documentary.md
index 26e91e1..abaa377 100644
--- a/.claude/skills/papermorph/references/documentary.md
+++ b/.claude/skills/papermorph/references/documentary.md
@@ -1,65 +1,67 @@
# Documentaries: from a book or an idea to a film
-A documentary is a narrated film of five to fifteen minutes about a book, an idea or a stretch of history. 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/. The user signed it off as the 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. 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.
-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`, `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.
+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.
## Intake
The same spirit as [intake.md](intake.md): a short conversation, choices to click, the user's words kept. Settle, skipping what the request already settles:
-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 cut the two epigraphs appeared four times and the user said it was overdone; they belong at the start and the end, with light echoes between.
+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.
-4. **The voice.** The narrator carries the film. ElevenLabs (`elevenlabs/eleven-v4` through OpenRouter) gave the voice the user accepted; Edge TTS was rejected for this film. Ask for the key, play a few short samples, and let the user pick. Characters can have their own voices (the Fool's giggle, a king's edict); v4 audio tags such as `[cackles]` are acted, not read.
+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.
-6. **Budget.** Voices cost about $0.65 for ten minutes; a five-second clip from a still about $0.42. Pictures from Wikimedia Commons cost nothing.
+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 `style.json` with `tier: "documentary"`, the user's words, the look, the voice and the models.
+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.
## The order of work
-1. **Research and the script.** Read the source, then write the narration (`content/<book>/chNN/narration.en.json`, 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.** `site/<book>/lib/` gets the kit's `lib/` (`film.js`, `book.css` with the ground and ink colours, `fonts.css`, `fonts/`) and then the engine (`engine.py`); `chNN/index.html` starts from the kit's `chapter.html`.
+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.** `eleven.py` (or `tts.py`) writes one clip per beat and `timings.js` with the marks. It takes the voice and model from the narration file's `voice` and `model`, keeps paid clips cached (a rerun costs nothing), and `--only beat,beat` redoes some beats without touching the others. Its word alignment (local Whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now.
+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.
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 and registering the film on the shelf ([site.md](site.md)).
+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` (title, author, licence, URL). 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): 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.
- **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.
- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. It is striking once or twice; on every picture it becomes a tic.
-- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. The user liked this most when it was rare.
-- **Maps.** A coastline from Natural Earth (public domain) as one SVG path in the film's box, a route drawn on with `along()`. A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe).
+- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up one that was interrupted. On the first film it worked best when rare.
+- **Maps.** A coastline from Natural Earth (public domain) as one SVG path in the film's box, a route drawn on with `along()`. There is no projection script: project the coastline's longitudes and latitudes into the box yourself (a few lines of code), or draw the path by hand. A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe).
## Building the beats
`film.js` holds the helpers, all pure functions of the beat clock:
-- `pic()` places a picture with an entrance; `leave()`, `push()` (a slow Ken Burns move), `dissolve()` (one picture turning into another in place);
-- `key()` big words in the condensed font, `strike()` a line through one, `say()` a quote typed word by word as it is spoken, `tag()` a small caption, `dateChip()` the year and place at the top left;
-- `closeups()` pushes into a print onto each thing as it is named, with a label, and back out;
+- `pic()` places a picture with an entrance; `leave()`, `push()` (a slow Ken Burns move), which work on what `pic()`, `traced()` and `doc()` return (they remember where they were put), and `dissolve()` (one picture turning into another in place);
+- `key()` big words in the condensed font, `strike()` a line through one, `say()` a quote typed word by word as it is spoken (Chinese and Japanese character by character; the kit's fonts are Latin only, so such a film adds a CJK font to `fonts.css`), `tag()` a small caption, `dateChip()` the year and place at the top left;
+- `closeups()` pushes into a print onto each thing as it is named, with a label, and back out to the whole picture when given its `home` (`{ x, y }`); without it the camera stays on the last close-up;
- `epigraph()`, `doc()` (an old document), `balloon()`, `dots()`, `water()` and `bob()`, `anim()`, `along()`.
-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). Set the chapter's `lead: false`: every opening is timed by hand.
+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.
+
+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:
- **One idea or element every two to four seconds**, in step with the voice, on a sparse screen: one to three things on the ground.
- **Close-ups on what is named.** When the narration names "the greedy" and "the vain" aboard the ship of fools, the camera goes to each in the woodcut, with the words as a label.
-- **A host, used sparingly.** The author as a cut-out guide works at the key points; fifteen appearances was too many, and the user asked for fewer.
+- **A host, used sparingly.** The author as a cut-out guide works at the key points; fifteen appearances were too many and were cut back.
- **Characters get voices** for a line or a laugh, short: the jester's laugh at the end of a section, not over it.
- **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.
## 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, then show each fix on a contact sheet at once, which is how the user liked to review. Then the user watches the whole film.
+After the first cut, an independent director pass: a fresh agent on a strong model, given contact sheets of every beat (`strip.py`) and the reference film, with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them places where the picture contradicted the narration (the wrong figure on screen while another was named). Fix, and show the user each fix on a contact sheet as it is made: a round is then quick to check. Then the user watches the whole film.
## Later
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index 13441e7..4df2281 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -59,7 +59,7 @@ 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()`.
-- **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, give the beat `{ lead: false }` in its fourth slot, or the whole chapter `CHAPTER.lead = false` *(v2.2)* when every opening is timed by hand (a documentary); a camera that shows a picture from the first frame is the same case. 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).
+- **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.
- **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.
@@ -109,7 +109,7 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'
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`. `?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)*. `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). 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. It ducks to 30 % under the voice, or 70 % in the music-only `pre` of the beats in `window.MUSIC_UP_IN_PRE` (`true` for all), crossfades over `fade` s (0.8), 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 click or key, so ducks, fades and the volume slider work on phones too; a pause holds them and a seek stops the effects. `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. `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, joined part-way, 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. 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. `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.
diff --git a/.claude/skills/papermorph/references/intake.md b/.claude/skills/papermorph/references/intake.md
index 881ab6c..1958df8 100644
--- a/.claude/skills/papermorph/references/intake.md
+++ b/.claude/skills/papermorph/references/intake.md
@@ -50,17 +50,17 @@ 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 |
-|---|---|---|---|
-| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) |
-| Narration and beats | middle | middle | strong (voices, the episode kit) |
-| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene |
-| Checks | small | small | small (sound effects too) |
-| Review | middle | middle | strong director, middle picture and sound reviewers |
-| Rework | strong | strong | middle, per scene |
-| Register | 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`). 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.
+| 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 |
+
+**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.
## 6. style.json
@@ -68,10 +68,10 @@ Start from [the template](../assets/templates/style.json). Blocks are grouped by
| Block | What it holds | Present in |
|---|---|---|
-| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"` or `"picture"`; title, slug, language, readers, pilot chapter | all |
+| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"`, `"picture"` or `"documentary"`; 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), voice, rate | 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 |
| `pacing` | minutes per chapter, where checks and practice go | all |
| `engine` | engine source and version used to build the book | all |
| `scenes` | art style, cast, how storyboards are reviewed | tier 2 |
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index 7694592..9e4f435 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -57,6 +57,26 @@ uv run --with playwright --with pillow python "$SKILL/scripts/bake_sets.py" "$BO
uv run --with playwright --with pillow python "$SKILL/scripts/bake_puppets.py" "$BOOK_SITE" --url "http://localhost:8765/$BOOK_ID/"
```
+### A documentary
+
+Instead of the first block, like a picture book's. `engine.py` runs first, on the new folder: it refuses a `lib/` that already holds files but no engine. The kit's `lib/` then goes over it, its `book.css` replacing the default one. The book's `index.html` is the picture-book series page, given the film's colours and fonts and a credits section listing every picture and recording from `SOURCES.tsv` (as *Madness and Civilization* does); a single film is a series of one.
+
+```sh
+BOOK_ID=film
+BOOK_SITE="site/$BOOK_ID"
+BOOK_WORK="books/$BOOK_ID"
+DK="$SKILL/assets/templates/documentary"
+mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img" "$BOOK_SITE/ch01" "$BOOK_WORK/art/found" "content/$BOOK_ID/ch01" "tools/$BOOK_ID"
+python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"
+cp -R "$DK"/lib/. "$BOOK_SITE/lib/"
+cp "$DK/chapter.html" "$BOOK_SITE/ch01/index.html"
+cp "$SKILL/assets/templates/picture-book/series.html" "$BOOK_SITE/index.html"
+cp "$DK/narration.en.json" "content/$BOOK_ID/ch01/"
+echo 'window.ART = {};' > "$BOOK_SITE/img/art.js"
+```
+
+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)).
+
### Every book
Use the pilot chapter's number in place of `ch01` when the pilot is not the first chapter. Use the agreed primary language: rename the narration source, load `audio/<lang>/timings.js` (a picture-book chapter also loads `mouths.js` and `shots.js` from that folder), and set `CHAPTER.language` to match (default `en`, it picks the audio folder). A chapter's minutes appear on its title screen (`CHAPTER.minutes`), its contents card and a series card; write the same number in each: the length of its audio (the `dur`s in `timings.js`) plus about 15 s for each question, rounded to whole minutes and never below 1. Set `<html lang>` in `index.html` and every chapter to the same language: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built into the engine; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` for each narration file from `style.json`, and translate the template's own visible text (titles, lede, prompts) before the pilot.
@@ -73,7 +93,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 uses its series page instead ([stories.md](stories.md#delivering)).
+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)).
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.
diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.md
index 1eaf284..29faa1a 100644
--- a/.claude/skills/papermorph/references/sound.md
+++ b/.claude/skills/papermorph/references/sound.md
@@ -22,7 +22,7 @@ Voices carry the story; everything else sits under them. In early cuts the music
## Music
-Music is optional and goes under everything: `music('audio/bgm/theme.mp3', [scene ids], gain, fade)` in the chapter page, one call per track. It sits at 30 % of its own level for the whole of a scene with voices (its silent opening and tail too, so it does not swell between lines); `window.MUSIC_UP_IN_PRE = ['scene']` lifts it to 70 % in that scene's music-only opening. Tracks crossfade over `fade` seconds (0.8 by default). Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades it out for a stare. Don't let music stop dead in the middle of a scene; carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place. Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them.
+Music is optional and goes under everything: `music('audio/bgm/theme.mp3', [scene ids], gain, fade)` in the chapter page, one call per track. It sits at 30 % of its own level for the whole of every scene, with voices or without (its silent opening and tail too, so it does not swell between lines); `window.MUSIC_UP_IN_PRE = ['scene']` lifts it to 70 % in that scene's `pre`, its music-only opening. Tracks crossfade over `fade` seconds (0.8 by default; 0 is a cut). Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades it out for a stare. Don't let music stop dead in the middle of a scene; carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place. Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them.
## Captions
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 39150cd..9a44614 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -52,3 +52,9 @@ Review comes in rounds ([stories.md](stories.md#review-rounds) says what to look
- **Closing**: the next round starts by checking which findings were fixed; a last read-only pass counts them as fixed, partly fixed, not fixed or worse. Two or three rounds made the best episodes. The rounds come before the user watches, and what the user says then still decides.
A fresh session as coordinator matters even more here: contact sheets are large, and a long conversation rereads them at every step. An episode made in one night from a bedtime telling, before the review rounds existed, took about 22 million tokens, most of them the coordinator rereading its own context.
+
+## Documentaries
+
+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.
diff --git a/README.md b/README.md
index 9f41399..7e035a7 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
</p>
<p align="center">
- <strong>A Claude Code Skill that turns textbooks into narrated, interactive web lessons,<br>and stories into paper-puppet films.</strong>
+ <strong>A Claude Code Skill that turns textbooks into narrated, interactive web lessons,<br>stories into paper-puppet films, and books into narrated documentaries.</strong>
</p>
<p align="center">
@@ -29,6 +29,7 @@
| A textbook PDF (maths) | Lessons where formulas and diagrams change step by step as the narration explains, with quick checks and chapter practice that grade the maths, not the string | [Elementary Algebra](https://papermorph.diamonddoge.org/elementary-algebra/) (68 chapters), [Elementary Mathematics](https://papermorph.diamonddoge.org/math-notebook/) (23) |
| A textbook PDF (science) | Illustrated scenes with acting characters and camera work, plus the same quizzes | [Elementary Physics](https://papermorph.diamonddoge.org/science/) (9 chapters and a sample) |
| A story, a joke or a fairy tale | A short film of paper puppets in front of sets drawn in code or painted by an image model, with voices, subtitles, sound effects and music | [Joke Collection](https://papermorph.diamonddoge.org/joke-collection/) (7 episodes), [Little Red Riding Hood](https://papermorph.diamonddoge.org/little-red-riding-hood/) |
+| A book or an idea | A narrated documentary of public-domain engravings, paintings and maps, moved in step with the voice, with music | [Madness and Civilization](https://papermorph.diamonddoge.org/madness/) (10 minutes) |
<p align="center">
<a href="https://papermorph.diamonddoge.org/science/ch12/"><img src="img/readme/physics-pulleys.webp" alt="Elementary Physics: one fixed pulley changes the direction of the pull; two pulleys halve the force" width="49%"></a>
@@ -53,7 +54,7 @@ Then, in Claude Code:
It finds the PDF in your project (or asks for your story), tells you what kind of book it is, suggests a chapter to try first and how much animation it needs, and offers a recommended option at every step. Your choices are saved in `style.json`, so every later chapter is made to the same style.
-You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`uv run --with playwright playwright install chromium firefox`). Narration uses Edge TTS (online) or Kokoro (local). Painted sets for picture books need an image-model API key; everything else runs without one.
+You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`uv run --with playwright playwright install chromium firefox`). Narration uses Edge TTS (online) or Kokoro (local), free. A few steps are paid, optional and need an API key: painted sets for picture books (OpenRouter or OpenAI), and ElevenLabs narration and clips made from a still for documentaries ([OpenRouter](https://openrouter.ai/)). Everything else runs without one.
## How it works
@@ -61,6 +62,8 @@ You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`u
**Picture books:** your telling becomes a script and a shot list → puppets and sets are built (or painted) once and reused across episodes → voices, mouth shapes, sound effects and music are made and joined per scene → scenes are filmed in parallel → review rounds (a director, picture reviewers and a sound reviewer) send scenes back until they hold up next to approved episodes.
+**Documentaries:** the source becomes an argument, a script and a storyboard → public-domain pictures are found, their licences recorded, and treated to one look → the narration is voiced and music laid under it → the beats are built in step with the words → a director pass checks every beat against the narration.
+
Large chapters can be made by a team of subagents, each step on the model that suits it ([team.md](.claude/skills/papermorph/references/team.md)).
## The player
@@ -74,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.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.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
@@ -97,13 +100,14 @@ An illustrated physics chapter costs about $10–18 of model usage. The painted
## Roadmap
-Ticked items are in the Skill today. The Skill currently goes as far as picture books.
+Ticked items are in the Skill today. The Skill currently goes as far as widescreen documentaries.
- [x] **Maths books:** formulas and diagrams that change step by step, with quizzes.
- [x] **Science books:** illustrated scenes, acting characters, camera work.
- [x] **Picture books:** paper-puppet films from a story, a joke or a fairy tale.
- [ ] **Choosing the model for every step**, with defaults that depend on how much animation a book needs.
-- [ ] **Documentaries:** history and social-science titles, wide films and vertical shorts. *Madness and Civilization* on the shelf is a hand-made sample. The Skill can't make one yet.
+- [x] **Documentaries:** narrated films of public-domain pictures about a book or an idea. *Madness and Civilization* on the shelf is the reference film.
+- [ ] **Vertical shorts** of documentaries.
## FAQ