storyshot 0.7.3 → 0.8.0

package/README.md

@@ -143,8 +143,12 @@ After your next release, re-render it and you have an up-to-date video.
 |---|---|---|
 | a promo / launch / landing-page clip | `pitch` | short and tightly cut: intro card, the app in a browser frame, music, captions |
 | a how-to or onboarding video | `tutorial` | paced to follow along: one narrated action per step, the camera following each click, part cards, a second example, a recap; `.srt` + chapters |
-| a lesson or explainer | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
+| a lesson | `course` | explains the *why*: concept cards, the idea shown in the app, question cards, a recap, no music; `.srt` + chapters |
 | help-center snippets | `docs` | silent per-step GIFs and PNGs cropped to the action, plus a ready-to-paste Markdown article |
+| an animated explainer of how something works | `explainer` | no web app: every step is a **scene**, an animation the agent writes and times to the narration (a mechanism, a diagram that grows, a number); calm music, subtitles, chapters |
+
+Tutorials and lessons can use scenes too: a `scene:` step between recorded
+steps explains an idea the app can't show, then the video goes back to the app.
 
 Length follows the purpose and the content, not a target: a promo is as short as
 its message, a tutorial as long as the workflow takes to explain.
@@ -199,6 +203,8 @@ from `storyshot guide`.
 | `init_storyboard` | Writes a starter storyboard with verified targets. |
 | `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file, and narration that sounds machine-written ("not just X, but Y", "seamless", 赋能…) or runs on without a breath. |
 | `render_video` / `render_status` | Renders in the background and returns the MP4 path, warnings, a per-step speed log and the preview image. If the render isn't done within 45 s, it returns a `job_id`, so client tool timeouts never kill a render. |
+| `scene_cues` | For scene steps: synthesizes the narration and returns when each phrase is spoken (the times `S.at(k)` gives the scene). |
+| `preview_scene` | Stills of one scene a beat into each phrase, plus HyperFrames lint and its layout check, in 20–40 s, without rendering the video. |
 
 Any other MCP client: run `npx -y storyshot mcp` (stdio), and point the agent at the playbook (`storyshot guide`). When run from a git
 checkout, `setup` points to `node /path/to/checkout/bin/storyshot.mjs mcp` instead.
@@ -222,6 +228,9 @@ Everything the agent does is also a command:
 | `storyshot render videos/acme-promo.yaml [--draft]` | Record, then compose the video and soundtrack. |
 | `storyshot compose videos/acme-promo.yaml [--draft]` | Rebuild from the last recording, in seconds. |
 | `storyshot record videos/acme-promo.yaml` | Only record. |
+| `storyshot init --purpose explainer --topic "how a TaqMan probe works" [--lang zh] [--portrait]` | Write an explainer storyboard of scene steps and a starter scene file for each (`videos/scenes/`). |
+| `storyshot cues videos/<name>.yaml` | When each phrase of each scene's narration is spoken. |
+| `storyshot scene videos/<name>.yaml --step 2 [--at 1.5,4] [--no-check]` | Preview one scene: stills, lint and layout check. |
 | `storyshot guide` | Print the playbook and the reference. |
 | `storyshot setup <agent>` (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf`, `cline`) | Set up the MCP server and the skill in this project, and install or check what Storyshot needs. |
 | `storyshot doctor` | Check Node, ffmpeg (and the filters and encoders Storyshot uses), Chromium and voices; install Chromium if it's missing. |
@@ -268,7 +277,8 @@ pace: slow                                      # fast (pitch) | normal (docs) |
 follow: true                                    # tutorial/course default: the camera zooms in on what each step touches and pans between steps (a step's own zoom wins; follow: false on a step skips it); or { scale: 1.8 }
 article: { title: Export a drawing, intro: … }  # docs: heading and first paragraph of <out>-steps/README.md
 lang: es                                        # language of built-in labels ("Pause and think", chapter "Introduction", "Downloaded"): en, zh, es, pt, fr, de, ja; default: zh if the steps contain Chinese, else en
-cards: auto                                     # intro/section/end cards: auto follows the frame (dark frames get dark cards), or light | dark
+cards: auto                                     # intro/section/end cards: auto follows the film's ground, or light | dark
+ground: auto                                    # is the film light or dark overall? light | dark; auto reads it from the scenes' backgrounds, else from the frame. It sets the colour of burned-in subtitles (ink letters with a white outline on a light film, white letters with an ink outline on a dark one) and the cards' ground
 frame: aurora                                   # the recording sits in a browser window on a backdrop: aurora (dark, grain; pitch default), studio (light, grain; tutorial and course default), dark, pastel, blur (the page itself, blurred); false = full frame; or { style, background: <css>, window, title, icon }
                                                 # window: app draws an installed app's window (its icon and name in the title bar, no address bar) for a PWA or desktop web app; title and icon come from the page's web app manifest unless given
 chapters: false                                 # write <out>.chapters.txt for YouTube
@@ -475,6 +485,52 @@ usually shouldn't.
 | `say` | Voiceover line played over the end card. |
 | `emblem` | With `hyperframes`: one to three short monospace lines over the title (an alignment, a formula, a line of code); `false` for none. On HyperFrames cards, text too long for the frame (a title, subtitle, emblem or call to action) wraps and then shrinks until it fits. |
 
+### Scenes
+
+A `scene:` step plays an animation you write instead of a recording: one
+[HyperFrames](https://hyperframes.heygen.com) composition (a `<template>` with a
+root whose `id` equals its `data-composition-id`, and one paused GSAP timeline
+registered as `window.__timelines['<id>']`). It is as long as the step's `say:`
+line needs, and reads its timing from `window.__storyshot`: `S.at(k)` is when
+phrase `k` of the line is spoken (phrases end at sentence ends and commas),
+`S.end(k)` when it ends, `S.cues` all of them. It also gets `S.duration`, the
+frame size, `S.safeBottom` (the room the burned-in subtitles take) and the theme
+as CSS variables (`--accent`, `--ink`, `--font`). Media go in `assets/` next to
+the scene file.
+
+```yaml
+purpose: explainer          # scenes only: no url, nothing recorded
+voice: { provider: qwen, voice: dylan }
+subtitles: burn
+steps:
+  - scene: scenes/question.html                       # or { file, title, lead: 0.5, tail: 0.8 }
+    say: An intact probe carries a dye. Why doesn't it glow?
+  - scene: { file: scenes/fret.html, title: Quenching }
+    say: The quencher sits right next to the dye, and takes its energy before it can become light.
+```
+
+Files every scene shares (a palette, drawing helpers) are listed once:
+`scenes: { css: scenes/kit.css, js: scenes/kit.js }` loads them before each
+scene. A scene's narration may be a whole paragraph: it is spoken in chunks of
+whole sentences, and `voice.maxPause` caps the pauses inside a line (0.55 s in
+an explainer).
+
+Every scene of a film shares one look, and the look belongs to the subject and
+the audience: a dark instrument panel suits a mechanism explained to specialists,
+a warm paper poster suits civics explained to nine-year-olds. Say which ground
+you chose with `ground: light | dark`, and the burned-in subtitles and the cards
+follow it. The playbook's "The look follows the subject" has the styles and what
+each ground costs.
+
+`lead` is how long the scene plays before the voice starts (default 0.5 s), and
+`tail` is how long it holds after the voice ends (default 0.8 s). Consecutive
+scenes cut into each other. Scenes are cached like cards, so `compose`
+re-renders only the ones that changed. `storyshot check` validates the
+contract, and `storyshot scene` runs the full HyperFrames lint and layout check
+on one scene. The playbook's "Scenes and explainers" says how to write scenes
+that explain. `music: { style: calm }` (the explainer default) is a soft pad
+with no drums.
+
 ### HyperFrames cards
 
 Tutorials and lessons render their intro, section and end cards with

package/bin/storyshot.mjs

@@ -11,6 +11,9 @@ Usage:
   storyshot init <url> [--purpose pitch|tutorial|course|docs] [--topic export-pdf] [--storage <site>-login.json]
                                     write a starter storyboard using verified targets from the page,
                                     named by type: videos/<site>-promo|tutorial|lesson|docs[-<topic>].yaml
+  storyshot init --purpose explainer --topic "how a TaqMan probe works" [--lang zh] [--portrait]
+                                    a concept explained with animated scenes (no web app): a storyboard
+                                    of scene steps + starter scene files in videos/scenes/
   storyshot login <url> [--save videos/<site>-login.json]
                                     open a browser window to log in once; saves the session for
                                     \`storageState:\` (and adds it to .gitignore)
@@ -23,6 +26,11 @@ Usage:
   storyshot compose <storyboard.yaml>     re-compose from the last recording
                                     (after changing captions, durations, zoom, music, voice, end card)
   storyshot record  <storyboard.yaml>     only (re-)record the browser session
+  storyshot cues    <storyboard.yaml>     when each phrase of each scene's narration is spoken
+                                    (the times S.at(k) returns in the scene); synthesizes the voice
+  storyshot scene   <storyboard.yaml> --step N [--at 1.5,4] [--no-check]
+                                    preview one scene: stills as each phrase is spoken (or at --at
+                                    seconds), HyperFrames lint and layout check — without a full render
   storyshot guide                   print the agent playbook + storyboard reference
   storyshot setup <agent>          add the MCP server + playbook to this project for your coding agent:
                                     cursor, claude, codex, gemini, vscode (Copilot), windsurf, cline —
@@ -41,8 +49,10 @@ Options:
 const args = process.argv.slice(2);
 const [cmd, arg] = args;
 const flag = (name) => { const i = args.indexOf(`--${name}`); return i > 0 ? args[i + 1] : undefined; };
-const NEEDS_ARG = ['login', 'init', 'inspect', 'check', 'render', 'compose', 'record', 'setup'];
-if (![...NEEDS_ARG, 'mcp', 'guide', 'doctor'].includes(cmd) || (NEEDS_ARG.includes(cmd) && !arg)) {
+const NEEDS_ARG = ['login', 'init', 'inspect', 'check', 'render', 'compose', 'record', 'setup', 'cues', 'scene'];
+// an explainer has no url to start from: `storyshot init --purpose explainer --topic …`
+const explainerInit = cmd === 'init' && flag('purpose') === 'explainer';
+if (![...NEEDS_ARG, 'mcp', 'guide', 'doctor'].includes(cmd) || (NEEDS_ARG.includes(cmd) && !arg && !explainerInit)) {
   process.stdout.write(USAGE);
   process.exit(['--help', '-h', 'help'].includes(cmd) ? 0 : 1);
 }
@@ -92,6 +102,21 @@ try {
     const r = await login(arg, { file: flag('save') ?? authFileFor(arg), viewport: viewport() });
     console.log(`✔ saved the login session to ${r.file} (${r.how}, ${r.cookies} cookies, ${r.siteCookies} for this site${r.sessionStorage ? `, sessionStorage for ${r.sessionStorage} site(s)` : ''})${r.gitignore ? `\n  added it to ${r.gitignore}` : ''}` +
       `\n  use it: \`storageState: ${r.file.split(/[\\/]/).pop()}\` in the storyboard (path relative to the yaml), or \`--storage ${r.file}\` for inspect/init`);
+  } else if (explainerInit) {
+    const { initExplainer } = await import('../src/init.mjs');
+    const r = initExplainer({ topic: flag('topic'), file: flag('file'), lang: flag('lang'), portrait: args.includes('--portrait') });
+    console.log(`✔ wrote ${r.file}\n${r.scenes.map((f) => `  + ${f}`).join('\n')}\n  next: write the say: lines, then \`storyshot cues ${r.file}\` and the scenes; preview one with \`storyshot scene ${r.file} --step 1\``);
+  } else if (cmd === 'cues') {
+    const { sceneCues } = await import('../src/scene-tools.mjs');
+    const r = await sceneCues(loadConfig(arg, { draft: args.includes('--draft') }));
+    console.log(`${r.text || 'no scene steps in this storyboard'}\n\n✔ ${r.file}`);
+  } else if (cmd === 'scene') {
+    const { previewScene, formatPreview } = await import('../src/scene-tools.mjs');
+    const step = Number(flag('step'));
+    if (!(step >= 1)) throw new Error('which scene? --step N (the step number in the storyboard, from 1)');
+    const at = flag('at') ? flag('at').split(',').map(Number).filter((x) => x >= 0) : null;
+    const r = await previewScene(loadConfig(arg, { draft: args.includes('--draft') }), step, { at, check: !args.includes('--no-check') });
+    console.log(formatPreview(r, step));
   } else if (cmd === 'init') {
     const { initStoryboard } = await import('../src/init.mjs');
     const r = await initStoryboard(arg, { purpose: flag('purpose') ?? 'pitch', topic: flag('topic'), file: flag('file'), storageState: flag('storage'), ignoreHTTPSErrors: args.includes('--insecure'), viewport: viewport() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Turn a short YAML storyboard into a polished product demo video of your web app — smooth cursor, auto zoom, captions, music.",
   "author": "boheling <boheling@gmail.com>",
   "repository": {

package/skills/storyshot/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: storyshot
-description: Make videos of a web app with Storyshot — promo/demo clips, narrated how-to tutorials, teaching walkthroughs, or per-step GIFs for docs (smooth cursor, auto zoom, captions, voiceover, music). Use when the user asks for a demo video, promo or launch clip, product walkthrough, tutorial or onboarding video, course/lesson video, or GIFs of their website or web app.
+description: Make videos of a web app with Storyshot — promo/demo clips, narrated how-to tutorials, teaching walkthroughs, or per-step GIFs for docs (smooth cursor, auto zoom, captions, voiceover, music) — and narrated explainers of a concept told with animated scenes. Use when the user asks for a demo video, promo or launch clip, product walkthrough, tutorial or onboarding video, course/lesson video, GIFs of their website or web app, or an animated explainer video of how something works.
 ---
 
 # Making videos with Storyshot
 
 Storyshot drives a real browser through a site according to a YAML storyboard,
 then retimes, zooms, captions, narrates and scores the recording into an MP4.
+A step can also be a **scene**: an animation you write (a HyperFrames
+composition) that explains an idea, timed to its narration. A storyboard of
+scenes only is an **explainer** (`purpose: explainer`, no url); see
+"Scenes and explainers" below.
 Your job: **look → confirm the brief with the user → write the storyboard →
 check → render → look at the preview → fix → repeat**, then deliver.
 
 A render takes 1–3 minutes and a paid voice costs credits, so a wrong guess
 about what the user wants is the most expensive mistake. Confirm the brief
-once, up front, before writing anything.
+once, up front, before writing anything (unless the user said not to ask:
+then state your choices in the reply).
 
 ## Tools
 
@@ -30,6 +35,9 @@ Use the `storyshot` MCP tools if they are available. Otherwise use the CLI:
 | record + render (1–3 min) | `render_video` → `render_status` if it returns a `job_id` | `storyshot render videos/<name>.yaml` |
 | re-render without re-recording | `render_video` mode `compose` | `storyshot compose videos/<name>.yaml` |
 | free draft voice | `render_video` `draft: true` | `--draft` |
+| starter explainer (scene steps + starter scene files) | `init_storyboard` `purpose: explainer`, `topic` | `storyshot init --purpose explainer --topic "how X works" [--lang zh]` |
+| when each phrase of each scene's narration is spoken | `scene_cues` | `storyshot cues videos/<name>.yaml` |
+| stills + lint + layout check of one scene (20–40 s) | `preview_scene` (`step`) | `storyshot scene videos/<name>.yaml --step 2` |
 
 Always pass **absolute paths** to MCP tools.
 
@@ -42,7 +50,9 @@ everything.
 the browser can't start (an agent sandbox that blocks it, a missing Chromium),
 or the tools keep failing, stop and tell the user what blocked it and how to
 allow it. Never produce a substitute: no mock-ups, redrawn screens, scripted
-frames or stock footage presented as a recording of their app.
+frames or stock footage presented as a recording of their app. A scene explains
+an idea (a mechanism, a diagram, a number); it never redraws the app's screens
+or stands in for a recording of them.
 
 ## 1. Look, then confirm the brief
 
@@ -83,6 +93,13 @@ frames or stock footage presented as a recording of their app.
    | `tutorial` | every step of the workflow, each explained, plus a second example; as long as that takes | yes | soft | step numbers, spotlight, camera follows, part cards, recap, .srt, chapters |
    | `course` | the concepts to teach: each idea, shown in the app, checked with a question | yes | none | spotlight, camera follows, concept and question cards, recap, .srt, chapters |
    | `docs` | one clip per step, each just long enough to see its result | none | none | step numbers, spotlight, cropped GIFs + PNGs, README.md article |
+   | `explainer` | the questions the viewer has about the concept, each answered by one scene; no web app | yes | calm | your scenes in a look chosen for the subject and the audience, .srt or burned-in subtitles, chapters |
+
+   An explainer has no site to look at, so the plan carries one more line: the
+   **look** — who the viewer is, and the style that suits them and the subject
+   ("3rd–5th graders, so a classroom poster: warm paper, dark ink, chunky
+   shapes"). See "The look follows the subject" in step 3. It is much cheaper to
+   agree on it now than to repaint ten finished scenes.
 
    Captions match the site's language. `kokoro` (free, local) speaks English
    and Mandarin Chinese: for Chinese lines use `voice: { provider: kokoro,
@@ -365,6 +382,244 @@ Notes:
 - `.storyshot/` next to the YAML is a cache of recordings, screenshots and
   voice lines. Add it to `.gitignore`.
 
+### Scenes and explainers
+
+A **scene** is a step whose picture you write instead of recording: an
+animation that shows an idea the app can't, such as how a probe lights up, why an
+algorithm scores a match, or what a number means. It is a HyperFrames
+composition, an HTML file with a GSAP timeline, and it plays as long as the
+step's `say:` line needs. Use it two ways:
+
+- **`purpose: explainer`**: the whole video is scenes, with no `url` and nothing
+  recorded. Use it for "explain how X works" when there is no web app to show.
+- **Inside a tutorial or lesson**: a `scene:` step between recorded steps
+  explains the why ("what does this score mean?"), then the video goes back to
+  the app. Keep these to 10–30 s.
+
+```yaml
+- scene: scenes/fret.html          # or { file: …, title: Chapter title, lead: 0.5, tail: 0.8 }
+  say: The quencher sits right next to the dye. Its energy is passed across before it can become light.
+```
+
+`lead` is how long the scene plays before the voice starts (default 0.5 s).
+`tail` is how long it holds after the voice ends (default 0.8 s). A scene
+with no `say:` needs a `duration`. A scene has no `actions`, `caption` or
+`zoom`, because it draws its own picture and text.
+
+**Workflow.** Write the words first, then the pictures:
+1. **Facts.** Every claim, number and sequence on screen comes from a source
+   you checked: a paper, the official docs, a database. Put the source on
+   screen in small type where its number appears, and list the sources in your
+   reply. Mark drawings that are schematic ("示意", "illustrative"). A
+   beautiful wrong diagram is worse than none. (A credit line may be smaller
+   than the 28 px text floor: put `data-layout-ignore` on it.)
+2. **Story.** Start from something the viewer knows: a real case, their own
+   question, one concrete example that runs through the whole video (one
+   gene, one request, one dataset). Then one question per scene, answered by
+   one picture. Follow "Writing the narration" above: short spoken sentences;
+   question → concrete case → name the idea → why → recap.
+3. **Lines.** Write the `say:` lines: one idea per scene, usually 2–5
+   sentences (about 60 English words or 120 Chinese characters at most).
+   Commas are cue points: each phrase can trigger one change on screen.
+4. **Cues.** Run `storyshot cues` (MCP `scene_cues`). It synthesizes the voice
+   and prints each scene's length and when each phrase is spoken. These are
+   the times `S.at(k)` returns inside the scene.
+5. **Look.** Choose the film's style from its subject and its audience, write
+   it down (ground, palette, type, how objects are drawn), and put it in the
+   scene kit before any scene is written. "The look follows the subject" below.
+6. **Scenes.** Write each scene file (contract below). Then preview it with
+   `storyshot scene … --step N` (MCP `preview_scene`), which gives stills a beat
+   into each phrase, HyperFrames lint, and a layout check. Look at every still,
+   fix the scene, and preview again until it is right.
+7. **Render**, look at `preview.jpg` (one frame per scene), and fix. After
+   editing only scenes or lines, `compose` re-renders just the scenes that
+   changed.
+
+**The scene file contract** (`storyshot check` and `preview_scene` enforce it):
+
+```html
+<template>
+  <style>
+    #fret { position: absolute; inset: 0; overflow: hidden; background: #121110; font-family: var(--font); }
+    #fret-dye { position: absolute; left: 600px; top: 420px; width: 120px; height: 120px; border-radius: 50%; background: #f4a62a; }
+  </style>
+  <div id="fret" data-composition-id="fret" data-width="1920" data-height="1080">
+    <div id="fret-dye"></div>
+  </div>
+  <script>
+    (function () {
+      const S = window.__storyshot;               // this scene's timing, size and theme
+      const tl = gsap.timeline({ paused: true });
+      tl.fromTo('#fret-dye', { scale: 0 }, { scale: 1, duration: 0.6, ease: 'expo.out' }, S.at(0));
+      tl.fromTo('#fret-dye', { opacity: 1 }, { opacity: 0.25, duration: 0.4 }, S.at('passed across'));
+      window.__timelines['fret'] = tl;
+    })();
+  </script>
+</template>
+```
+
+- One `<template>` holds the styles, markup and script. The root element's
+  `id` equals its `data-composition-id`, is unique among the scenes, and
+  prefixes every other id in the file. `data-width`/`data-height` match the
+  video (1920×1080, or 1080×1920 for portrait).
+- One paused GSAP timeline, registered as `window.__timelines['<id>']`. Use
+  `fromTo` (not `from`). No `Date`, timers, `requestAnimationFrame`,
+  `repeat: -1`, or unseeded `Math.random`: frames are rendered by seeking the
+  timeline.
+- Media go in `assets/` next to the scene file, referenced as `assets/x.png`.
+- **A look shared by every scene** (a palette, fonts, a helper that draws
+  your recurring objects): put it in files and list them once at the top of
+  the storyboard, `scenes: { css: scenes/kit/kit.css, js: scenes/kit/kit.js }`.
+  They load before each scene's own script, so a scene can call your helpers
+  and use your CSS variables.
+- **`window.__storyshot`** (`S`) gives you:
+  - `S.at(k, offset)`: when phrase `k` starts. `k` counts from 0, `-1` is the
+    last phrase, and a string means the phrase that contains it.
+  - `S.end(k)`: when phrase `k` ends.
+  - `S.cues`: `[{ text, t, end }]` for every phrase.
+  - `S.duration`, `S.width`, `S.height`, `S.lead`.
+  - `S.safeBottom`: the pixels at the bottom that burned-in subtitles take
+    (16% of the height, 22% in portrait, 0 without `subtitles: burn`); keep
+    content above it. The same value is available as the CSS variable
+    `var(--safe-bottom)`. `preview_scene` draws this band on its stills as a
+    striped red strip.
+  - `S.theme`: `{ accent, ink, font }`, also available as `var(--accent)`,
+    `var(--ink)` and `var(--font)`. The font falls back to the machine's CJK
+    font for Chinese.
+
+  Time every reveal from `S.at`, never from hard-coded seconds, so the
+  animation stays on the words when a line changes.
+
+**The look follows the subject and the audience.** There is no house style, and
+the last explainer's look is not a default. A film for eight-year-olds about
+voting and a film for biologists about pooled screens should not look alike:
+choose the style, say so in the plan, and put it in the scene kit
+(`scenes: { css: …, js: … }`) before the first scene is written, so ten scenes
+can't disagree about it.
+
+Two questions decide it. **Who is watching?** Children and general audiences
+need big friendly drawings, few colours and a light ground; specialists read
+dense instrument-like pictures and are at home on a dark panel. **What is the
+subject made of?** A thing that glows, fluoresces, counts or signals wants a
+dark ground to light up on; a thing that is printed, taught, filled in or voted
+on wants paper. Starting points, not a menu to pick blindly:
+
+| subject, and who it is for | the look | made of |
+|---|---|---|
+| a mechanism, molecule, instrument or pipeline, for people who work on it | instrument panel | near-black ground, one or two signal colours that light up, hairlines, mono labels, counters, glows |
+| anything for children; civics, history and everyday subjects for everyone | classroom poster | warm paper, dark ink, chunky rounded shapes, thick strokes, big plain type, drawings with visible hand |
+| money, policy, a market, a result, for a general adult or professional audience | clean report | white ground, one accent, wide margins, one typeface, real numbers, nothing decorative |
+| a machine, a building, a physical process | blueprint | deep blue or sepia ground, a faint grid, dimension and leader lines, small-caps part labels |
+| a person, a place, a historical event | storybook | a tinted ground that is neither black nor white, illustrated figures, soft shapes, one warm accent |
+
+**Then tell Storyshot which ground you chose**: `ground: light` or
+`ground: dark` in the storyboard. Burned-in subtitles and the intro/section/end
+cards follow it — ink letters with a white outline on a light film, white
+letters with an ink outline on a dark one — so the words read without a bar
+drawn under them. Left out, `auto` reads the ground from the scenes — their own
+background, or the kit rule for a class on their root (`<div id="x"
+class="world">`). When it is a variable or an image, nothing can be read:
+`check` warns, and the subtitles stay white until you say which the film is.
+
+**What a ground costs.** The choice is not only a colour; it changes what works:
+- **On a light ground**, a glow is a smudge: make it a flat tinted panel, a ring
+  or nothing. Keep shadows at `rgba(<ink>, .12)` or less, or they look dirty. A
+  cream card that floated on black becomes a *white* sheet, which needs its own
+  shadow and some real structure inside (rules, a divider) or it reads as a
+  blank rectangle. A saturated accent that sang on black usually fails the
+  contrast check as text on paper (amber `#f4a62a` on white is about 2:1):
+  darken it for text, keep the bright one for fills, or give the words a thin
+  ink outline — and settle that in the kit, once.
+- **On a dark ground**, thin dark lines and dark figures vanish: every object
+  needs a light value of its own, and faint white strokes (`rgba(255,255,255,.06)`)
+  that carry structure there have no quiet equivalent on paper.
+- **Either way**, a colour used as a *fill* can be bright, while the same colour
+  as *text* has to pass the contrast check (the layout check measures it, 3:1
+  for large text and 4.5:1 for normal). Watch a colour sitting inside a panel
+  of its own hue (teal dots on a teal wing): it measures against the panel, not
+  against the ground, and that is where contrast is usually lost.
+
+**Repaint before the scenes exist, not after.** Converting a finished ten-scene
+film to the other ground is an hour or more of work with nothing new to show
+for it: the colour swap is mechanical, but every glow, shadow, faint stroke and
+floating card needs a judgement, and the contrast findings all change. It is
+much cheaper to show one previewed scene in the chosen style and ask.
+
+**Pictures that explain** (what the preview stills should show):
+- **The object is the explanation.** Draw the actual thing, such as the
+  molecule, the queue or the circuit, big enough to be the hero: at least 40%
+  of the frame's width or height. Use the real data where it exists: a real
+  sequence, real numbers. Never show a small icon floating in an empty frame:
+  if a still is mostly empty ground, scale the diagram up until it fills the
+  frame.
+- **One diagram that grows.** Start from the simplest true picture and add one
+  part per phrase, each when the voice names it, with its label on it (a
+  leader line, not a legend). Never put the finished diagram on screen at
+  once.
+- **Motion.** One hero move per beat, and something new every 2–4 s.
+  Arrivals ease out (`expo.out`, 0.5–0.7 s) and exits are shorter. Text lands
+  and then stays still while it is read.
+- **Text.** At least 28 px at 1080p, and nothing under `S.safeBottom`. Never
+  repeat the narration word for word on screen (the subtitles do that).
+  Avoid bullet slides and rows of three cards.
+- **Colour.** Rationed: one accent, plus one colour per thing the story
+  tracks (for example, allele G amber and allele A green everywhere: dye,
+  dot, label).
+- **Seams.** Consecutive scenes cut straight into each other. End a scene on
+  a state the next one starts from (the same object in the same place), or
+  on a clean hold. The video's first frame is its thumbnail: show the subject
+  there, never an empty ground.
+- **Look before you move on.** Read `preview_scene`'s stills like a stranger
+  would. Is every object recognisable without explanation, does each part
+  appear when it is named, and does nothing overlap, crop or sit under the
+  subtitles? Fix every ✖ from lint and the layout check.
+
+**Gotchas** (each one cost a real run several previews):
+- **Several tweens on one property.** Several `fromTo`s on the same property
+  of one element (fade a label in, later fade it out) are fine: Storyshot
+  gives every later one `immediateRender: false`, so it does not show its
+  start state from the first frame. With `to()` or `from()`, or a position
+  that is not a number, set `immediateRender: false` yourself.
+- **SVG sizes.** Animate them with `attr: { width: 300 }`. A CSS transform
+  on an SVG `<rect>` (`scaleX` with `transform-origin`) can render nothing.
+- **Lines that draw themselves.** Give the path `pathLength="1"`,
+  `stroke-dasharray: 1`, and tween `strokeDashoffset` from 1 to 0 with
+  `autoRound: false`. Without it, GSAP rounds the offset to whole pixels and
+  the line pops in instead of drawing.
+- **Layout check findings that are intended.**
+  - A glow that spills out of its box: `data-layout-allow-overflow` on the box.
+  - A label sitting on its object: `data-layout-allow-overlap` on the container.
+  - Small credits or texture: `data-layout-ignore`.
+- **"The film's last line needs 2 s".** Only the video's last scene must hold
+  its final words. Elsewhere, reveal text on an earlier phrase or raise
+  `tail:`.
+- **The ground under the cards.** Intro and end cards follow the film's ground,
+  so they come out dark when the scenes do; `ground: light | dark` settles the
+  whole film and `cards: light | dark` overrides the cards alone. Keep
+  end-card bullets short: about 10 Chinese characters or 5 English words each.
+
+Long narration is fine: a scene's `say:` is spoken in chunks of whole
+sentences, and in an explainer no pause inside a line lasts longer than
+`voice.maxPause` (0.55 s by default), so the voice keeps moving.
+
+Explainer defaults:
+- **Music:** `music: { style: calm }`, soft pads with no drums;
+  `music: false` for none.
+- **Subtitles:** `subtitles: true` writes an .srt; `burn` puts them on the
+  video, the better choice for social video and Chinese. Burned-in words take
+  their colour from `ground:` (see "The look follows the subject"), so set it.
+- **Ground:** `ground: light | dark`, chosen for the subject and the audience,
+  not inherited from the last film.
+- **Chapters:** come from the scenes' `title`s.
+- **Cards:** an `intro` and an `end_card` work as in lessons.
+
+Long explainers (more than about 6 scenes) build fastest if each scene is
+written by its own sub-agent, all from the same lines, cues, scene contract and
+scene kit — and from the same written description of the look, or they will
+each invent one. Settle anything they disagree about (a colour that fails
+contrast, an object drawn two ways) in the kit, once, not scene by scene.
+Review every scene's stills yourself afterwards.
+
 ## 4. Render, look, fix
 
 1. `render_video` (use `draft: true` while iterating if the voice is
@@ -407,6 +662,9 @@ Notes:
    - Draft looks right: `compose` with `draft: false` for the final voice.
      Only lines not yet synthesized cost credits. `draft` only matters with
      a paid voice; with `kokoro`, it is the same voice either way.
+   - Changed only scenes (their files, lines or assets): `compose`; only the
+     scenes that changed render again. An explainer has nothing to record,
+     so `render` and `compose` do the same.
 
 ## 5. Deliver
 

package/src/audio.mjs

@@ -42,6 +42,31 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
       '-f', 'f32le', '-ac', '2', '-ar', `${SR}`, 'pipe:1'], { maxBuffer: 1 << 30 });
     const f = new Float32Array(pcm.buffer, pcm.byteOffset, pcm.length / 4);
     for (let i = 0; i < Math.min(N, f.length / 2); i++) { music[0][i] = f[2 * i] * 0.5; music[1][i] = f[2 * i + 1] * 0.5; }
+  } else if (cfg.music?.style === 'calm') {
+    // calm (explainers): slow pad chords vi–IV–I–V in C, two bars each, a soft bass under them and a
+    // sparse bell; no drums, nothing on the beat that would pull at the voice
+    const BEAT = 60 / cfg.music.bpm, LEN = BEAT * 8;
+    const chords = [[57, 60, 64], [53, 57, 60], [48, 52, 55], [55, 59, 62]];
+    for (let b = 0, t0 = 0; t0 < events.total; b++, t0 = b * LEN) {
+      const ch = chords[b % chords.length], len = Math.min(LEN, events.total - t0) + 1.2; // rings into the next chord
+      for (const [k, note] of [...ch, ch[0] + 12].entries()) {
+        for (const det of [-0.06, 0.06]) {
+          const f = hz(note + det), filt = svf();
+          add(music, t0, len, (t) => {
+            const env = Math.min(1, t / 1.4) * Math.min(1, Math.max(0, len - t) / 1.6);
+            return filt(saw(f * t) * 0.6 + Math.sin(2 * Math.PI * f * t) * 0.4, 650 + 250 * Math.sin(t * 0.4 + k)).lp * env;
+          }, 0.024, (k - 1.5) * 0.35 + det * 2);
+        }
+      }
+      const fb = hz(ch[0] - 12);
+      add(music, t0, len, (t) => Math.sin(2 * Math.PI * fb * t) * Math.min(1, t / 0.6) * Math.min(1, Math.max(0, len - t) / 1.2), 0.09);
+      if (b % 2 === 0) for (const [j, note] of [ch[2] + 12, ch[1] + 24].entries()) {
+        const f = hz(note);
+        add(music, t0 + j * BEAT * 2, 2.5, (t) => (Math.sin(2 * Math.PI * f * t) + 0.15 * Math.sin(4 * Math.PI * f * t)) * Math.exp(-t * 1.8) * Math.min(1, t / 0.01), 0.03, j ? 0.3 : -0.3);
+      }
+    }
+    // fade in over 2 s, out over the last 3 s
+    for (const c of music) for (let i = 0; i < N; i++) c[i] *= Math.min(1, i / SR / 2) * Math.min(1, (N - i) / SR / 3);
   } else if (cfg.music) {
     // I–V–vi–IV in C at `bpm`, resolving on the end card (or fading at the end)
     const BEAT = 60 / cfg.music.bpm, BAR = BEAT * 4;
@@ -134,7 +159,7 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   if (cfg.voice && events.voice?.length) {
     let prevEnd = 0;
     for (const line of events.voice) {
-      let { pcm, parts } = await speak(cfg, line.text, { log });
+      let { pcm, parts } = await speak(cfg, line.text, { log, chunk: !!line.chunk });
       let dur = pcm.length / 2 / SR;
       const start = Math.max(line.start, prevEnd + 0.12), room = line.until - start - 0.1;
       let sped = 1;
@@ -198,7 +223,7 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   // so re-encoding by video sites doesn't clip
   execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', silentVideo, '-i', wavFile,
     '-map', '0:v', '-map', '1:a', '-c:v', 'copy', '-af', `loudnorm=I=-14:TP=-1.5:LRA=11,aresample=${SR},alimiter=limit=0.7:level=false:attack=1:release=50`, '-ar', `${SR}`, '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', cfg.out]);
-  log(`soundtrack: ${cfg.music ? (cfg.music.file ? 'music file' : `synth ${cfg.music.bpm} bpm`) : 'no music'}, ${events.clicks.length} clicks, ${cfg.sfx?.transitions ? events.whooshes.length : 0} whooshes` +
+  log(`soundtrack: ${cfg.music ? (cfg.music.file ? 'music file' : `synth${cfg.music.style ? ` ${cfg.music.style}` : ''} ${cfg.music.bpm} bpm`) : 'no music'}, ${events.clicks.length} clicks, ${cfg.sfx?.transitions ? events.whooshes.length : 0} whooshes` +
     (cfg.voice ? `, ${events.voice.length} narration lines (${cfg.voice.provider}/${cfg.voice.voice})` : ''));
   return { out: cfg.out, warnings, narration };
 }

package/src/build.mjs

@@ -1,4 +1,7 @@
 // record → compose → soundtrack, shared by the CLI and the MCP server.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { record } from './record.mjs';
 import { compose } from './compose.mjs';
 import { soundtrack } from './audio.mjs';
@@ -7,7 +10,9 @@ import { writeOutputs, burnSubtitles } from './outputs.mjs';
 
 export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const t0 = Date.now();
-  if (mode !== 'compose') await record(cfg, { log });
+  // a storyboard of scenes only (an explainer) has no web app to record: an empty recording stands in
+  if (!cfg.url) noRecording(cfg);
+  else if (mode !== 'compose') await record(cfg, { log });
   if (mode === 'record') return { warnings: [] };
   const voiceLens = await measureVoice(cfg, { log });
   const { silent, clean, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
@@ -16,3 +21,12 @@ export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const extras = await writeOutputs(cfg, { captions, cards, segs, clean, narration: audio.narration, total: events.total }, { log });
   return { out: audio.out, extras, preview, warnings: [...warnings, ...audio.warnings], duration: events.total, seconds: Math.round((Date.now() - t0) / 1000) };
 }
+
+// The recording of a storyboard with nothing to record: one black frame, every step empty.
+export function noRecording(cfg) {
+  fs.mkdirSync(path.join(cfg.work, 'raw'), { recursive: true });
+  const frame = path.join(cfg.work, 'raw', 'blank.jpg');
+  if (!fs.existsSync(frame)) execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-f', 'lavfi', '-i', `color=c=black:s=${cfg.output.width}x${cfg.output.height}`, '-frames:v', '1', frame]);
+  const steps = cfg.steps.map((s) => ({ start: 0, end: 0, hidden: !!s.hidden, zoomBox: null, zoomTarget: null, waits: [], holds: 0, marks: [] }));
+  fs.writeFileSync(path.join(cfg.work, 'timeline.json'), JSON.stringify({ frames: [{ t: 0, file: 'blank.jpg' }], steps, clicks: [], navs: [], gotos: [], urls: [], app: null, introLogo: null, scale: cfg.scale }, null, 1));
+}