An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
docs(shorts): a silent beat needs no timings entry or narration line; the scripts accept it
yzr127623cd1e6d
diff --git a/.claude/skills/papermorph/references/shorts.md b/.claude/skills/papermorph/references/shorts.mdindex 77f1a37..5e9e79c 100644--- a/.claude/skills/papermorph/references/shorts.md+++ b/.claude/skills/papermorph/references/shorts.md@@ -32,7 +32,7 @@ When the user wants a film that already exists recut as shorts (*Madness and Civ1. **The script, beat by beat, with the user.** Keep it in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (the narration, one line of what we see, and its rough length: words ÷ the voice's pace, about 2.6 words a second for an ElevenLabs narrator, plus about 1.4 s a beat for the engine's hold after the words, 0.6 s, and the camera's tail, 0.8 s in the worked example; a twelve-beat script ran 17 s longer than its words), and each number's and quote's source under it. Show it to the user a few beats at a time and rewrite as they answer. A background beat that comes out over about eight seconds is where the short will feel slow; shorten it before the voice is paid for. Once it is voiced, the length hides in the voice's own sentence pauses (0.4 to 1.0 s from ElevenLabs): `eleven.py --max-pause 0.3` shortens them before the marks are placed (one episode went from 112 s to 107 s). The beats' narration, with `[[mark]]` before each word a picture lands on, goes into `content/<book>/chNN/narration.en.json` (the kit's sample shows the format); keep the two in step.2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find, and a beat-by-beat plan is too coarse for it (one director pass asked for three new pictures the plan had missed). Who appears where: one figure per role, so that a figure coming back means something (a callback), not that the cast ran out. Note each picture's prompt or source and cost, quote the batch before paying, and show the user the pictures as they come. `prep.py`'s `full` treatment sizes full-bleed pictures for the stage. Episodes made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded by the episode after `img/art.js`), so no two of them edit the same line.3. **The folder.** `engine.py site/<book>` first (it starts `lib/` with the engine and a default `book.css`), then the kit's `lib/` over it, with the documentary kit's `fonts.css` and `fonts/`; `chNN/index.html` starts from the kit's `chapter.html` (the commands are in [site.md](site.md#a-short)). The film's own pieces (its cast's sizes in `MEME`, a series card) go in a second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`); a map or the globe is the map kit's, whose lines `chapter.html` carries commented out. Every episode but a series' last sets `CHAPTER.next` to the next one: the end card names the next episode, and the player offers it only when `next` is set.-4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. A series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) puts `"tempo": 1.1` in each narration file, or passes `eleven.py --tempo 1.1`: the clips are sped before they are levelled and aligned, and a rerun keeps it. A wordless beat (a series card, an end card) needs no clip: `{ dur: 2 }` in its fourth slot ([engine.md](engine.md#timing)). Every clip goes out at one level, −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the voice service gives about −23 LUFS, which sank one episode under its music); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. Check the marks on spoken numbers: the transcript writes "a hundred and twenty" as "120"; `eleven.py` matches the digits to the spoken words and prints the marks a rerun moved, but a number the matcher missed still lands late (seven marks in one episode, up to 0.75 s). A time only the page needs (an end card's) goes in the page, not in `timings.js`, which the next voice run rewrites.+4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. A series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) puts `"tempo": 1.1` in each narration file, or passes `eleven.py --tempo 1.1`: the clips are sped before they are levelled and aligned, and a rerun keeps it. A wordless beat (a series card, an end card) needs no clip, no `timings.js` entry and no narration line: `{ dur: 2 }` in its fourth slot ([engine.md](engine.md#timing)); `lint.py`, `export.py`, `music.py` and `check.py` take it as silence, and the music stays ducked under it. Every clip goes out at one level, −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the voice service gives about −23 LUFS, which sank one episode under its music); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. Check the marks on spoken numbers: the transcript writes "a hundred and twenty" as "120"; `eleven.py` matches the digits to the spoken words and prints the marks a rerun moved, but a number the matcher missed still lands late (seven marks in one episode, up to 0.75 s). A time only the page needs (an end card's) goes in the page, not in `timings.js`, which the next voice run rewrites.5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses. `music.py cut SRC site/<book>/chNN/audio/bgm/epN.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end instead of leaving the end card silent; `--end` sets it by hand) and levels the file to −16 LUFS; `--rests` splices out its rests, `--even` evens out its quiet phrase ends, and a generated (Lyria) track usually needs `--even` too, since its quiet passages fall into the voice's gaps just as a recording's do. `--lift T` raises a hole that neither fixes (a phrase end with no rest). The cut is made for one length: after any change to a beat's length, cut again (`gaps` says "recut"). A looping track is fine for a first cut. Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the engine's ducking to 30 %, a track at −16 LUFS sits at about −34 LUFS, 20 LU under a −14 LUFS voice, the level the user chose for episode 1 (its track −16.3 LUFS). The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …/<book>/` lists the bed's loudness in each voice-free gap and after the last word, and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much: two beats with the same voice can differ by what their tweens overrun. `?lengths` on the page prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.7. **Watch it yourself, then a director pass.** Contact sheets of every beat (`strip.py`), and the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage. Look at it with the platform's title, caption and buttons in mind (the safe area below). Measure what a script can: page errors, console warnings and beat lengths in both browsers (`check.py chNN --url …`), a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to see the tags the export will show). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut. A fresh agent on a strong model reviews the sheets against an approved episode without knowing how the beats were built ([documentary.md](documentary.md#review-rounds)); half of what it finds is usually the picture saying something other than the voice. Then a second round on the exported MP4 ([documentary.md](documentary.md#review-rounds)).