storyshot 0.4.1 → 0.5.0

package/README.md

@@ -152,7 +152,7 @@ Rendering is free and runs locally. Only the voiceover can cost money:
 | voice | cost | notes |
 |---|---|---|
 | none | free | captions only |
-| `kokoro` | free | local, English only; downloads a ~90 MB model on first use |
+| `kokoro` | free | local, English and Mandarin Chinese (`zf_001`); downloads a ~90 MB model on first use (Chinese: ~130 MB, and needs Python 3.10–3.12) |
 | ElevenLabs | your credits | the most natural voice; many languages including Chinese. Put `ELEVENLABS_API_KEY` in `.env`. |
 | OpenAI | your credits | `OPENAI_API_KEY` |
 
@@ -217,7 +217,7 @@ Everything the agent does is also a command:
 | `storyshot record videos/acme-promo.yaml` | Only record. |
 | `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, Chromium and voices; install Chromium if it's missing. |
+| `storyshot doctor` | Check Node, ffmpeg (and the filters and encoders Storyshot uses), Chromium and voices; install Chromium if it's missing. |
 | `storyshot mcp` | Run the MCP server. |
 
 Recordings, previews and voice lines are cached in `.storyshot/` next to the
@@ -247,7 +247,7 @@ viewport: { width: 1600, height: 900 }          # CSS px the site is laid out at
 output: { width: 1920, height: 1080, fps: 30 }  # same aspect ratio; use 1080x1920 with a 900x1600 viewport for vertical
 theme: { accent: "#d9f75b", ink: "#0f172a", font: Inter }
 music: { bpm: 120, volume: 1 }                  # or { file: track.mp3 }, or false
-sfx: true                                       # click / whoosh / riser sounds
+sfx: true                                       # click / whoosh / riser sounds; clicks = no whooshes on cards and page changes (tutorial and course default); false = none
 voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceover, see below
 storageState: auth.json                         # optional Playwright login state
 ignoreHTTPSErrors: true                         # internal site with a self-signed HTTPS certificate (plain http:// needs nothing)
@@ -256,7 +256,7 @@ captions: true                                  # false keeps caption pills off
 purpose: pitch                                  # pitch | tutorial | course | docs (sets the defaults below)
 highlight: false                                # spotlight targets before click/type (per step or per action too)
 stepNumbers: false                              # numbered caption badges
-subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top)
+subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top); uses ffmpeg's libass when it has it, else draws the words itself
 pace: slow                                      # fast (pitch) | normal (docs) | slow (tutorial, course): cursor and typing speed, a beat after each click, hold after narration, voice speed, how much of a wait is shown
 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
@@ -393,10 +393,21 @@ mix is normalized to -14 LUFS.
 
 | provider | key (env or `.env`) | notes |
 |---|---|---|
-| `kokoro` (default) | none | Local and free; English voices only (`af_heart`, `am_michael`, `bf_emma`, …). Needs `npm i kokoro-js`; the first run downloads an ~90 MB model. |
+| `kokoro` (default) | none | Local and free. English voices (`af_heart`, `am_michael`, `bf_emma`, …) and Mandarin Chinese ones (`zf_001`, see below). Needs `npm i kokoro-js`; the first run downloads an ~90 MB model. |
 | `elevenlabs` | `ELEVENLABS_API_KEY` | Most natural, many languages including Chinese. `voice` is a voice ID; `model` defaults to `eleven_multilingual_v2`. The key needs Text to Speech access, plus Voices → Read to list voices. |
 | `openai` | `OPENAI_API_KEY` | `voice: alloy`, `model: gpt-4o-mini-tts`; optional `instructions` for tone. |
-| `say` | none | macOS built-in voices, robotic; fine for drafts. |
+| `say` | none | macOS built-in voices, robotic; fine for drafts. For Chinese, use `kokoro` with `zf_001` rather than `Tingting`. |
+
+**Chinese narration.** `voice: { provider: kokoro, voice: zf_001 }` speaks Mandarin with Kokoro
+v1.1-zh, free and local, and is what `kokoro` uses when the `say:` lines are Chinese and no voice is
+named. It sounds far more natural than macOS `say -v Tingting`. Other voices: `zf_002` (female),
+`zm_010`, `zm_011` (male), and others between `zf_001`…`zf_099` and `zm_009`…`zm_100` (not every
+number exists). Its text-to-phoneme step (misaki) needs Python 3.10–3.12: on first use Storyshot
+creates its own venv in `~/.cache/storyshot/zh-venv` (about 250 MB, under a minute; nothing is installed globally;
+`STORYSHOT_PYTHON` picks the interpreter) and downloads a ~130 MB model. `storyshot doctor` says
+whether it's ready. English words and letters in a line (`GeoGebra`, `y 等于 m x 加 b`) are spoken in
+English, a 2 before a measure word is read 两 (`2 个单位`), and `=`, `+`, `×`, `÷`, `²` are spoken;
+subtitles keep the line as written. Known issue: with every Kokoro voice, 逗号 can sound like 度号.
 
 Other fields: `speed` (default 1), `volume` (default 1), and `pronounce`, a
 map of word → spoken form used only for TTS, e.g.
@@ -430,6 +441,41 @@ usually shouldn't.
 | `cta` | Dark call-to-action pill, e.g. `Start free at acme.com`. |
 | `duration` | Seconds. Default: fits the `say` line, else 1.0 (end card) or 2.2 (intro). |
 | `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. |
+
+### HyperFrames cards (optional)
+
+`hyperframes: true` renders the intro, section and end cards with
+[HyperFrames](https://hyperframes.heygen.com) (HeyGen's open-source HTML-to-video
+renderer, Apache-2.0) for more motion. Two templates, picked by `purpose`:
+
+- **lesson** (tutorials, courses, docs): the title lands word by word over a
+  slowly drifting, blurred view of the page the section leads into; section
+  cards show a progress bar of the parts; the intro's steps and the end card's
+  recap points light up as the narration names them.
+- **launch** (promos): hand-drawn accents (a box round the logo, an underlined
+  highlight, an arrow to the call to action). The intro's paper turns into the
+  browser window and its logo lands on the app's own logo in the first frame;
+  the outro zooms from the last frame into the page and draws the call to
+  action over it.
+
+```yaml
+hyperframes:
+  template: lesson        # or launch (default: launch for pitch, lesson otherwise)
+  band: MVHLTPEEKSAVTALWGKV…  # optional: text drifting behind the titles (a sequence, a formula)
+  bandColors: aminoacid   # aminoacid | nucleotide | accent (default)
+  emblem: [LHCDKLHVDPENFRLL, "||||||||||||+|||", LHCDKLHVDPENFKLL]  # optional, over the titles
+  hand: true              # launch: hand lettering (Virgil) for the subtitle and call to action
+  backdrop: false         # lesson: plain background instead of the blurred page
+```
+
+It needs Node 22 or newer. On first use storyshot installs the pinned
+HyperFrames version into `~/.cache/storyshot/hyperframes/` (a local install
+of the `hyperframes` package wins); its telemetry is switched off. Cards are
+cached, so `compose` only re-renders the ones that changed (about 10–25 s
+each). Any card that can't be rendered falls back to the built-in one with a
+warning. The Virgil font is © Ellinor Rapp, SIL Open Font License 1.1
+(`src/fonts/Virgil-LICENSE.md`).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.4.1",
+  "version": "0.5.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": {
@@ -12,6 +12,9 @@
   "bin": {
     "storyshot": "bin/storyshot.mjs"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "bin",
     "src",
@@ -36,6 +39,8 @@
     "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "kokoro-js": "^1.2.1"
+    "gsap": "^3.14.2",
+    "kokoro-js": "^1.2.1",
+    "roughjs": "^4.6.6"
   }
 }

package/skills/storyshot/SKILL.md

@@ -65,8 +65,8 @@ frames or stock footage presented as a recording of their app.
       narrated how-to; course = narrated lesson; docs = silent step-by-step GIFs)
    2. Length: about 20 s, 6 shots (it follows from the flow below)
    3. Flow: hero → Examples → Try It → AI result → pricing → end card
-   4. Voice: none (other options: free local English voice; ElevenLabs, best
-      quality and Chinese support, key found in .env)
+   4. Voice: none (other options: free local voice, English or Chinese;
+      ElevenLabs, best quality, key found in .env)
    5. Music: upbeat · Captions: English · Subtitle file (.srt): no
    6. Format: 16:9, 1080p (other option: 9:16 vertical)
    7. Login: not needed (or: Examples needs a login, so I'll open a browser
@@ -85,7 +85,11 @@ frames or stock footage presented as a recording of their app.
    | `docs` | one clip per step, each just long enough to see its result | none | none | step numbers, spotlight, cropped GIFs + PNGs, README.md article |
 
    Captions match the site's language. `kokoro` (free, local) speaks English
-   only; for other languages, use ElevenLabs.
+   and Mandarin Chinese: for Chinese lines use `voice: { provider: kokoro,
+   voice: zf_001 }` (the default for Chinese `say:` lines), not macOS `say -v
+   Tingting`, which sounds robotic. It needs Python 3.10–3.12 and sets up its
+   own venv on first use (`doctor` reports it). For other languages, use
+   ElevenLabs.
 3. **Login.** If the flow needs a logged-in page:
    - Tell the user a browser window will open and that they should log in
      there, preferably with a demo account (the video shows whatever is on
@@ -175,6 +179,14 @@ small controls are readable. Your job is the structure:
   `note` the field the reader must not miss. Set the article's heading and
   first paragraph with `article: { title: …, intro: … }`. Downloads show a
   "Downloaded" bubble; `paste` and copy-to-clipboard work.
+- **More motion on the cards** (when the user asks for livelier titles, or for
+  a launch video): `hyperframes: true` renders the intro, section and end
+  cards with HyperFrames (needs Node 22+; installs itself on first use). For a
+  subject with its own material, give the titles a backdrop from it:
+  `hyperframes: { band: <a sequence or formula>, emblem: [<1–3 short lines>] }`.
+  Promos get hand-drawn accents; `hand: true` uses hand lettering. Write the
+  intro's `bullets` and the end card's recap with the same words the `say`
+  line uses: each point lights up when the narration names it.
 - **End with a recap**: `end_card` with `bullets` listing the steps or rules
   to remember, and a `say` that repeats them.
 - **Narrating real results.** You can't know the numbers (scores, counts,

package/src/audio.mjs

@@ -101,7 +101,7 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
         return press + release;
       }, 0.55);
     }
-    for (const c of events.whooshes) {
+    for (const c of cfg.sfx.transitions ? events.whooshes : []) {
       const filt = svf(), len = 0.45;
       add(sfx, c - len * 0.55, len, (t) => {
         const p = t / len;
@@ -137,8 +137,14 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
       let dur = pcm.length / 2 / SR;
       const start = Math.max(line.start, prevEnd + 0.12), room = line.until - start - 0.1;
       let sped = 1;
-      if (dur > room && dur / room <= 1.2) { sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR; }
-      else if (dur > room) warn(`${line.where}: narration is ${dur.toFixed(1)}s but only ${Math.max(0, room).toFixed(1)}s until ${line === events.voice.at(-1) ? 'the video ends' : 'the next line'} — shorten "${line.text}" or give the step more duration`);
+      // a line pushed past its window by the one before has no room left (room <= 0): it plays late, at normal speed
+      if (dur > room && room > 0 && dur / room <= 1.2) { sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR; }
+      else if (dur > room) warn(room > 0
+        ? `${line.where}: narration is ${dur.toFixed(1)}s but only ${room.toFixed(1)}s until ${line === events.voice.at(-1) ? 'the video ends' : 'the next line'} — shorten "${line.text}" or give the step more duration`
+        : `${line.where}: the narration before it runs ${(start - line.start).toFixed(1)}s past where this line should start, so "${line.text}" plays late — shorten the earlier lines or give their steps more duration`);
+      if (start + dur > events.total) warn(start >= events.total
+        ? `${line.where}: "${line.text}" is cut off: the narration before it pushes it past the end of the video (${events.total.toFixed(1)}s) — shorten the lines or give the steps more duration`
+        : `${line.where}: the last ${(start + dur - events.total).toFixed(1)}s of "${line.text}" is cut off at the end of the video — shorten it or give the steps more duration`);
       log(`  voice ${start.toFixed(2)}–${(start + dur).toFixed(2)}s  ${line.where}${sped > 1 ? `  (sped up x${sped.toFixed(2)})` : ''}  "${line.text}"`);
       let pk = 0;
       for (const v of pcm) pk = Math.max(pk, Math.abs(v));
@@ -187,7 +193,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, ${events.whooshes.length} whooshes` +
+  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` +
     (cfg.voice ? `, ${events.voice.length} narration lines (${cfg.voice.provider}/${cfg.voice.voice})` : ''));
   return { out: cfg.out, warnings, narration };
 }

package/src/build.mjs

@@ -12,7 +12,7 @@ export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const voiceLens = await measureVoice(cfg, { log });
   const { silent, clean, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
   const audio = await soundtrack(cfg, events, silent, { log });
-  if (cfg.subtitles === 'burn') burnSubtitles(cfg, audio.narration ?? [], { log });
+  if (cfg.subtitles === 'burn') await burnSubtitles(cfg, audio.narration ?? [], { 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) };
 }

package/src/check.mjs

@@ -3,12 +3,14 @@ import fs from 'node:fs';
 import YAML from 'yaml';
 import { loadConfig } from './config.mjs';
 import { gitIgnored } from './auth.mjs';
+import { isZhVoice, zhVoiceStatus } from './kokoro-zh.mjs';
 
 const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'article', 'cards', 'lang', 'colorScheme',
-  'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
+  'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card', 'hyperframes'];
 const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc'];
 const ZOOM = ['target', 'scale', 'start', 'end', 'ramp', 'offset'];
-const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'bullets', 'image', 'think'];
+const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'bullets', 'image', 'think', 'emblem'];
+const HYPERFRAMES = ['template', 'band', 'bandColors', 'emblem', 'hand', 'backdrop'];
 const TARGET = ['role', 'name', 'text', 'label', 'placeholder', 'alt', 'testId', 'css', 'exact', 'last', 'nth'];
 const OPTS = ['ms', 'offset', 'timeout', 'highlight', 'color', 'box'];
 const ACTIONS = {
@@ -84,6 +86,7 @@ export function check(file, { draft = false } = {}) {
   }
   if (raw.end_card) unknown(raw.end_card, END, 'end_card');
   if (raw.intro) unknown(raw.intro, END, 'intro');
+  if (raw.hyperframes && typeof raw.hyperframes === 'object') unknown(raw.hyperframes, HYPERFRAMES, 'hyperframes');
   if (raw.article) unknown(raw.article, ['title', 'intro'], 'article');
   if (raw.frame && typeof raw.frame === 'object') unknown(raw.frame, ['background', 'style', 'window', 'title', 'icon'], 'frame');
   const todo = (fs.readFileSync(file, 'utf8').split('\n').map((l, i) => [l.replace(/#.*$/, ''), i + 1]).filter(([l]) => /\bTODO\b/.test(l)));
@@ -138,6 +141,28 @@ export function check(file, { draft = false } = {}) {
     const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0) + (cfg.intro?.say ? 1 : 0);
     if (cfg.voice && !says) warnings.push('voice is set but no step has a `say:` line');
     if (!cfg.voice && says) warnings.push('steps have `say:` lines but there is no `voice:` block, so they will not be spoken');
+    // fixed-length steps: a line that clearly can't be spoken before the next one starts (a rough
+    // estimate from its length; the render measures the real voice)
+    if (cfg.voice) {
+      const words = (t) => { const x = String(t).replace(/\*\*/g, ''); const c = (x.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length; return { c, w: x.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter(Boolean).length }; };
+      const secs = (t) => { const { c, w } = words(t); return (c / 4.5 + w / 2.8) / (cfg.voice.speed ?? 1); };
+      const vis = visible.map((s) => ({ s, i: cfg.steps.indexOf(s) }));
+      for (const [k, { s, i }] of vis.entries()) {
+        if (!s.say) continue;
+        const nextK = vis.findIndex((v, j) => j > k && v.s.say);
+        const span = vis.slice(k, nextK < 0 ? undefined : nextK).map((v) => v.s.duration);
+        if (!span.every((d) => typeof d === 'number')) continue;
+        const room = span.reduce((a, d) => a + d, 0) - (s.sayAt ?? 0.15) + (nextK < 0 && cfg.endCard ? 2.5 : 0);
+        const need = secs(s.say);
+        if (need > room * 1.4 && need - room > 1) warnings.push(`step ${i + 1}: the say: line takes about ${need.toFixed(1)}s to speak but has ${room.toFixed(1)}s before ${nextK < 0 ? 'the video ends' : 'the next line'} — shorten it or raise duration (the lines after it would play late)`);
+      }
+    }
+    // the Chinese Kokoro voice needs a Python for its G2P: say so now, not after the recording
+    const v = draft && cfg.voice ? loadConfig(file, { draft }).voice : cfg.voice;
+    if (v?.provider === 'kokoro' && isZhVoice(v.voice)) {
+      const zh = zhVoiceStatus();
+      if (zh.problem) errors.push(zh.problem);
+    }
     if (!draft && cfg.voice && ['elevenlabs', 'openai'].includes(cfg.voice.provider)) {
       const env = cfg.voice.provider === 'elevenlabs' ? 'ELEVENLABS_API_KEY' : 'OPENAI_API_KEY';
       if (!process.env[env]) errors.push(`voice provider ${cfg.voice.provider} needs ${env} (environment or a .env file next to the storyboard) — or render with draft mode to use the free local voice`);

package/src/compose.mjs

@@ -4,6 +4,7 @@ import { chromium } from 'playwright';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { renderHyperframesCards } from './hyperframes.mjs';
 
 const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 const md = (s, accent) => esc(s).replace(/\*\*(.+?)\*\*/g, `<b style="color:${accent};font-weight:700">$1</b>`);
@@ -27,7 +28,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(2.5, (voiceLens.endCard ?? 0) + 0.6, readTime(ec0), ctaTime(ec0)) : ec0.duration;
   if (ec0 && END < 2.5) warn(`the end card shows for only ${END.toFixed(1)}s: too short to read its call to action — use duration: auto, or at least 2.5`);
   const in0 = cfg.intro;
-  const INTRO = !in0 ? 0 : in0.duration === 'auto' ? Math.max(1.8, (voiceLens.intro ?? 0) + 0.8, readTime(in0)) : in0.duration;
+  const INTRO = !in0 ? 0 : in0.duration === 'auto' ? Math.max(cfg.hyperframes?.template === 'launch' ? 2.8 : 1.8, (voiceLens.intro ?? 0) + 0.8, readTime(in0)) : in0.duration;
   if (INTRO > 8) warn(`the intro card plays ${INTRO.toFixed(1)}s before anything happens: viewers leave during long intros — shorten its say or bullets (aim for 6–8s)`);
   const cards = []; // section cards: { i, t0, t1, card }
 
@@ -74,7 +75,11 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     if (s.card) {
       // a section card plays over the step's first frame, before the step
       const C = cardLen(s.card, voiceLens.cards?.[i], 2.4);
-      pieces.push({ raw: [r.start, r.start], o0: acc, o1: acc + C });
+      // while the card fades in, the page under it is still the last one shown (else the new step's
+      // page flashes through the fade); it changes once the card covers the screen
+      const prev = pieces.at(-1)?.raw[1];
+      if (prev != null) pieces.push({ raw: [prev, prev], o0: acc, o1: acc + 0.25 });
+      pieces.push({ raw: [r.start, r.start], o0: acc + (prev != null ? 0.25 : 0), o1: acc + C });
       cards.push({ i, t0: acc, t1: acc + C, card: s.card, thinkAt: C - (s.card.think ?? 0) - 0.3 });
       acc += C;
     }
@@ -419,9 +424,6 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     }
   };
   const ec = cfg.endCard;
-  if (ec) await animate(card(ec, ec.logoFile ?? path.join(cfg.work, 'logo.png')), END + 0.5, path.join(cfg.work, 'endcard'));
-  for (const [k, c] of cards.entries()) await animate(card(c.card, c.card.logoFile ?? '', { thinkAt: c.thinkAt }), c.t1 - c.t0, path.join(cfg.work, `card${k}`));
-  if (in0) await animate(card(in0, in0.logoFile ?? path.join(cfg.work, 'intro-logo.png')), INTRO, path.join(cfg.work, 'intro'));
   if (cfg.frame) {
     // three layers: the backdrop (a picture, or the page itself blurred), the window chrome (shadow and
     // title bar), and the page with rounded bottom corners
@@ -467,6 +469,74 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     await pg.screenshot({ path: path.join(cfg.work, 'frame-mask.png') });
     await pg.setViewportSize({ width: W, height: H });
   }
+
+  // what each HyperFrames card is about: its text, when its narration plays (card seconds), and
+  // pictures from the recording (the page it leads into, blurred, as a backdrop; for a launch intro, the
+  // first page sharp, and where the app shows the intro's logo, so the logo can land there)
+  function hfJobs() {
+    const launch = cfg.hyperframes.template === 'launch';
+    const seqAt = (t) => path.join(SEQ, `${String(Math.min(nFrames - 1, Math.max(0, Math.round(t * FPS)))).padStart(5, '0')}.jpg`);
+    const blurred = (t, name) => {
+      if (cfg.hyperframes.backdrop === false || !nFrames) return null;
+      const f = path.join(cfg.work, `${name}-backdrop.jpg`);
+      execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', seqAt(t), '-vf', `scale=${even(W / 4)}:-2,gblur=sigma=6`, '-q:v', '4', f]);
+      return f;
+    };
+    const sizeOf = (f) => {
+      try {
+        const [w, h] = execFileSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'csv=p=0', f]).toString().trim().split(',').map(Number);
+        return w && h ? { w, h } : null;
+      } catch { return null; }
+    };
+    const voice = (text, start, len) => (text && len ? { text, start, len } : null);
+    const jobs = [];
+    if (in0) {
+      const logo = [in0.logoFile, path.join(cfg.work, 'intro-logo.png')].find((f) => f && fs.existsSync(f)) ?? null;
+      const target = launch && logo && tl.introLogo ? onScreen(tl.introLogo, INTRO) : null;
+      jobs.push({ name: 'intro', kind: 'intro', seconds: INTRO, card: in0, voice: voice(in0.say, 0.15, voiceLens.intro), image: in0.imageFile,
+        logo, logoSize: target ? { w: target.w, h: target.h } : logo && sizeOf(logo), logoTarget: target,
+        page: launch && nFrames ? seqAt(INTRO) : null, backdrop: launch ? null : blurred(INTRO + 0.05, 'intro') });
+    }
+    for (const [k, c] of cards.entries()) {
+      jobs.push({ name: `card${k}`, kind: 'section', seconds: c.t1 - c.t0, card: c.card, voice: voice(c.card.say, 0.15, voiceLens.cards?.[c.i]),
+        index: k, of: cards.length, thinkAt: c.thinkAt, image: c.card.imageFile, backdrop: blurred(c.t1 + 0.05, `card${k}`) });
+    }
+    if (ec) {
+      const logo = [ec.logoFile, path.join(cfg.work, 'logo.png')].find((f) => f && fs.existsSync(f)) ?? null;
+      // the end card starts as the video ends (launch: over it, at VIDEO; lesson: a beat before)
+      jobs.push({ name: 'endcard', kind: 'end', seconds: launch ? END + 0.05 : END + 0.5, card: ec, voice: voice(ec.say, launch ? 0.05 : 0.3, voiceLens.endCard),
+        image: ec.imageFile, logo, logoSize: logo && sizeOf(logo), backdrop: launch ? null : blurred(VIDEO - 0.3, 'endcard') });
+    }
+    return jobs;
+  }
+
+  // the cards: HyperFrames compositions when asked for (`hyperframes:`), else (or for any card that
+  // doesn't render) the built-in ones. A launch outro is drawn with transparency over the last frame,
+  // which the ffmpeg pass below zooms into the page.
+  const hf = cfg.hyperframes ? await renderHyperframesCards(hfJobs(), {
+    W, H, FPS, dark: darkCards, accent, ink, font, lang: cfg.lang, labels: cfg.labels, opts: cfg.hyperframes, work: cfg.work,
+    frame: { FX, FY, FW, FH, ...Object.fromEntries([['frameBg', 'frame-bg.png'], ['chrome', 'frame-chrome.png'], ['url', 'frame-url0.png']]
+      .map(([k, f]) => [k, cfg.frame && fs.existsSync(path.join(cfg.work, f)) ? path.join(cfg.work, f) : null])) },
+  }, { log, warn }) : {};
+  const place = (name, seconds) => {
+    const dir = path.join(cfg.work, name), src = fs.readdirSync(hf[name].dir).filter((f) => f.endsWith(`.${hf[name].ext}`)).sort();
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    for (let k = 0, n = Math.ceil(seconds * FPS) + 1; k < n; k++) fs.copyFileSync(path.join(hf[name].dir, src[Math.min(k, src.length - 1)]), path.join(dir, `${String(k).padStart(4, '0')}.${hf[name].ext}`));
+  };
+  const ecAlpha = !!hf.endcard?.alpha;
+  if (ec) {
+    if (hf.endcard) place('endcard', ecAlpha ? END + 0.05 : END + 0.5);
+    else await animate(card(ec, ec.logoFile ?? path.join(cfg.work, 'logo.png')), END + 0.5, path.join(cfg.work, 'endcard'));
+  }
+  for (const [k, c] of cards.entries()) {
+    if (hf[`card${k}`]) place(`card${k}`, c.t1 - c.t0);
+    else await animate(card(c.card, c.card.logoFile ?? '', { thinkAt: c.thinkAt }), c.t1 - c.t0, path.join(cfg.work, `card${k}`));
+  }
+  if (in0) {
+    if (hf.intro) place('intro', INTRO);
+    else await animate(card(in0, in0.logoFile ?? path.join(cfg.work, 'intro-logo.png')), INTRO, path.join(cfg.work, 'intro'));
+  }
   await browser.close();
 
   // --- 5. ffmpeg --------------------------------------------------------------------------------
@@ -508,12 +578,28 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     last = `v${idx++}`;
   }
   for (const [k, c] of cards.entries()) {
+    // a card right after the intro is already in place (its first frame held) while the intro fades
+    // out, so the intro dissolves into it instead of showing the page for a moment in between
+    const lead = in0 && Math.abs(c.t0 - INTRO) < 0.02 ? Math.min(0.2, INTRO) : 0, s0 = c.t0 - lead;
     inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, `card${k}`, '%04d.jpg'));
-    graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${c.t0.toFixed(3)}/TB,fade=in:st=${c.t0.toFixed(3)}:d=0.15:alpha=1,fade=out:st=${Math.max(c.t0, c.t1 - 0.15).toFixed(3)}:d=0.15:alpha=1[sc${k}];\n` +
-      `[${last}][sc${k}]overlay=0:0:eof_action=pass:enable='between(t,${c.t0.toFixed(3)},${c.t1.toFixed(3)})'[v${++idx}];\n`;
+    graph += `[${idx}:v]format=rgba,${lead ? `tpad=start_duration=${lead.toFixed(3)}:start_mode=clone,` : ''}setpts=PTS-STARTPTS+${s0.toFixed(3)}/TB,` +
+      `${lead ? '' : `fade=in:st=${c.t0.toFixed(3)}:d=0.15:alpha=1,`}fade=out:st=${Math.max(c.t0, c.t1 - 0.15).toFixed(3)}:d=0.15:alpha=1[sc${k}];\n` +
+      `[${last}][sc${k}]overlay=0:0:eof_action=pass:enable='between(t,${s0.toFixed(3)},${c.t1.toFixed(3)})'[v${++idx}];\n`;
     last = `v${idx}`;
   }
-  if (ec) {
+  if (ec && ecAlpha) {
+    // launch outro: the last frame zooms into the page (an upscaled copy, so the slow zoom doesn't
+    // jitter), then the card draws itself over it
+    const q = `clip((on/${FPS}-0.05)/0.6,0,1)`, E = `(${q})*(${q})*(3-2*(${q}))`, Z = 2;
+    const zoom = cfg.frame
+      ? `z='${W}/(${W}-${E}*${W - FW})':x='${E}*${FX * Z}':y='${E}*${FY * Z}'`
+      : `z='1+0.06*${E}':x='(iw-iw/zoom)/2':y='(ih-ih/zoom)/2'`;
+    inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, 'endcard', '%04d.png'));
+    graph += `[${last}]split[pre][post];[pre]trim=end=${VIDEO.toFixed(3)},setpts=PTS-STARTPTS,format=yuv420p,setsar=1[pre1];\n` +
+      `[post]trim=start=${VIDEO.toFixed(3)},setpts=PTS-STARTPTS,scale=${W * Z}:${H * Z}:flags=lanczos,zoompan=${zoom}:d=1:fps=${FPS}:s=${W}x${H}[post1];\n` +
+      `[${idx}:v]format=rgba,setpts=PTS-STARTPTS[ec];[post1][ec]overlay=0:0:eof_action=repeat,format=yuv420p,setsar=1[post2];[pre1][post2]concat=n=2:v=1:a=0[v${++idx}];\n`;
+    last = `v${idx}`;
+  } else if (ec) {
     const st = VIDEO - 0.25;
     inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, 'endcard', '%04d.jpg'));
     graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${st.toFixed(3)}/TB,fade=in:st=${st.toFixed(3)}:d=0.3:alpha=1[ec];\n` +

package/src/config.mjs

@@ -2,17 +2,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
-import { VOICE_DEFAULTS } from './voice.mjs';
+import { VOICE_DEFAULTS, kokoroVoiceFor } from './voice.mjs';
 
 // Built-in labels drawn into the video, by `lang` (e.g. es, es-MX); other languages get English
 export const LABELS = {
-  en: { think: 'Pause and think', intro: 'Introduction', downloaded: 'Downloaded' },
-  zh: { think: '先想一想', intro: '开场', downloaded: '已下载' },
-  es: { think: 'Piénsalo un momento', intro: 'Introducción', downloaded: 'Descargado' },
-  pt: { think: 'Pense um pouco', intro: 'Introdução', downloaded: 'Baixado' },
-  fr: { think: 'Réfléchissez', intro: 'Introduction', downloaded: 'Téléchargé' },
-  de: { think: 'Kurz nachdenken', intro: 'Einführung', downloaded: 'Heruntergeladen' },
-  ja: { think: '考えてみよう', intro: 'はじめに', downloaded: 'ダウンロード済み' },
+  en: { think: 'Pause and think', intro: 'Introduction', downloaded: 'Downloaded', tryIt: 'try it' },
+  zh: { think: '先想一想', intro: '开场', downloaded: '已下载', tryIt: '试试看' },
+  es: { think: 'Piénsalo un momento', intro: 'Introducción', downloaded: 'Descargado', tryIt: 'pruébalo' },
+  pt: { think: 'Pense um pouco', intro: 'Introdução', downloaded: 'Baixado', tryIt: 'experimente' },
+  fr: { think: 'Réfléchissez', intro: 'Introduction', downloaded: 'Téléchargé', tryIt: 'essayez' },
+  de: { think: 'Kurz nachdenken', intro: 'Einführung', downloaded: 'Heruntergeladen', tryIt: 'ausprobieren' },
+  ja: { think: '考えてみよう', intro: 'はじめに', downloaded: 'ダウンロード済み', tryIt: '試してみて' },
 };
 
 // Load API keys (ELEVENLABS_API_KEY, OPENAI_API_KEY) from .env next to the storyboard
@@ -31,8 +31,8 @@ export function loadEnv(dir) {
 // What the video is for sets sensible defaults; anything in the YAML overrides them.
 export const PURPOSES = {
   pitch:    { duration: null,   music: { bpm: 120, volume: 1 },    sfx: true,  highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: 'aurora', pace: 'fast', follow: false },
-  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: true,  highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
-  course:   { duration: 'auto', music: false,                     sfx: true,  highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
+  tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 },  sfx: 'clicks', highlight: true,  stepNumbers: true,  subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
+  course:   { duration: 'auto', music: false,                     sfx: 'clicks', highlight: true,  stepNumbers: false, subtitles: true,  chapters: true,  clips: null, frame: 'studio', pace: 'slow', follow: true },
   docs:     { duration: 'auto', music: false,                     sfx: false, highlight: true,  stepNumbers: true,  subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false },
 };
 
@@ -114,7 +114,9 @@ export function loadConfig(file, { draft = false } = {}) {
   if (endCard) endCard = { duration: 'auto', ...endCard };
   // An intro title card (promos; optional for tutorials and lessons). Same fields as the end card.
   let intro = raw.intro === false ? null : raw.intro ?? null;
-  if (intro) intro = { duration: intro.say ? 'auto' : 2.2, ...intro };
+  // (a HyperFrames launch intro also turns into the app window at the end: it needs a little longer)
+  const launchCards = raw.hyperframes && (raw.hyperframes.template ?? (purpose === 'pitch' ? 'launch' : 'lesson')) === 'launch';
+  if (intro) intro = { duration: intro.say ? 'auto' : launchCards ? 3.0 : 2.2, ...intro };
   for (const card of [endCard, intro]) {
     if (card?.image) card.imageFile = path.resolve(dir, card.image);
     if (card?.logo && typeof card.logo === 'string' && /\.(png|jpe?g|svg|webp)$/i.test(card.logo)) card.logoFile = path.resolve(dir, card.logo);
@@ -134,14 +136,23 @@ export function loadConfig(file, { draft = false } = {}) {
   if (frame && !['browser', 'app'].includes(frame.window)) throw new Error('frame.window must be browser or app');
   if (frame?.icon) frame.iconFile = path.resolve(dir, frame.icon);
 
+  // hyperframes: true | { template: lesson | launch, band, bandColors, emblem, hand, backdrop } — cards
+  // rendered by HyperFrames (see hyperframes.mjs); promos get the launch template, the rest the lesson one
+  const hf0 = raw.hyperframes;
+  const hyperframes = hf0 ? { template: purpose === 'pitch' ? 'launch' : 'lesson', backdrop: true, ...(typeof hf0 === 'object' ? hf0 : {}) } : null;
+  if (hyperframes && !['lesson', 'launch'].includes(hyperframes.template)) throw new Error('hyperframes.template must be lesson or launch');
+  if (hyperframes?.bandColors && !['aminoacid', 'nucleotide', 'accent'].includes(hyperframes.bandColors)) throw new Error('hyperframes.bandColors must be aminoacid, nucleotide or accent');
+
   let voice = null;
   if (raw.voice) {
     const provider = raw.voice.provider ?? 'kokoro';
     if (!VOICE_DEFAULTS[provider]) throw new Error(`voice.provider must be one of ${Object.keys(VOICE_DEFAULTS).join(', ')}`);
     const pace0 = PACES[pick('pace')] ?? PACES.normal;
-    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...raw.voice, provider };
+    // kokoro's default voice follows the narration's language (zf_001 for Chinese, af_heart otherwise)
+    const kokoroVoice = kokoroVoiceFor(raw);
+    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...(provider === 'kokoro' ? { voice: kokoroVoice } : {}), ...raw.voice, provider };
     if (draft && provider !== 'kokoro') {
-      voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? VOICE_DEFAULTS.kokoro.voice, model: undefined };
+      voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? kokoroVoice, model: undefined };
     }
   }
 
@@ -186,10 +197,13 @@ export function loadConfig(file, { draft = false } = {}) {
     lang: raw.lang ?? (/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(JSON.stringify(raw.steps ?? [])) ? 'zh' : 'en'),
     labels: LABELS[String(raw.lang ?? '').toLowerCase().split(/[-_]/)[0]] ?? (/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(JSON.stringify(raw.steps ?? [])) ? LABELS.zh : LABELS.en),
     frame,
+    hyperframes,
     follow,
     music,
     voice,
-    sfx: pick('sfx') !== false,
+    // sfx: true (clicks and transition whooshes), 'clicks' (no whooshes: tutorials and lessons, where a
+    // sound at every card soon grates), or false
+    sfx: pick('sfx') === false ? false : { clicks: true, transitions: pick('sfx') !== 'clicks' },
     draft,
     out: path.resolve(dir, raw.out ?? `${name}.mp4`).replace(/(\.[^./]+)?$/, (ext) => (draft ? `.draft${ext || '.mp4'}` : ext)),
     work: path.resolve(dir, '.storyshot', name),

package/src/doctor.mjs

@@ -5,6 +5,9 @@ import { chromium } from 'playwright';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { hasFilter, hasEncoder, NEEDED, OPTIONAL } from './ffmpeg.mjs';
+import { zhVoiceStatus } from './kokoro-zh.mjs';
+import { hyperframesCli, HF_VERSION } from './hyperframes.mjs';
 
 const has = (cmd, args = ['--version']) => { try { execFileSync(cmd, args, { stdio: 'ignore' }); return true; } catch { return false; } };
 
@@ -47,7 +50,15 @@ export async function doctor({ log = console.log } = {}) {
 
   try {
     const v = execFileSync('ffmpeg', ['-version']).toString().match(/ffmpeg version (\S+)/)?.[1];
-    lines.push(`✔ ffmpeg ${v ?? ''}`.trim());
+    // a build can lack pieces Storyshot uses: say which, and what that affects
+    const missing = [...NEEDED.filters.filter((f) => !hasFilter(f)), ...NEEDED.encoders.filter((e) => !hasEncoder(e))];
+    if (missing.length) {
+      lines.push(`✖ ffmpeg ${v ?? ''} is missing ${missing.join(', ')}`);
+      todo.push(`install an ffmpeg build with ${missing.join(', ')} (${process.platform === 'darwin' ? 'e.g. brew install ffmpeg-full, then put "$(brew --prefix ffmpeg-full)/bin" first on your PATH, as it is keg-only; or a static build from https://ffmpeg.org/download.html' : 'e.g. a static build from https://ffmpeg.org/download.html'})`);
+    } else lines.push(`✔ ffmpeg ${v ?? ''}`.trim());
+    for (const o of OPTIONAL) {
+      if (o.filter ? !hasFilter(o.filter) : !hasEncoder(o.encoder)) lines.push(`· ffmpeg has no ${o.filter ? `${o.filter} filter` : `${o.encoder} encoder`} — ${o.for}`);
+    }
   } catch {
     lines.push('✖ ffmpeg not found');
     todo.push(ffmpegInstallCommand());
@@ -62,6 +73,15 @@ export async function doctor({ log = console.log } = {}) {
   }
 
   try { await import('kokoro-js'); lines.push('✔ free local voice (kokoro)'); } catch { lines.push('· free local voice (kokoro) not installed — optional: npm i kokoro-js'); }
+  // Mandarin (kokoro zf_001…): its G2P runs in a Python 3.10–3.12 venv that storyshot creates on first use
+  const zh = zhVoiceStatus();
+  lines.push(zh.ready ? `✔ Chinese voice (kokoro zf_001): Python ${zh.python?.version ?? '?'} venv in ${zh.venv}`
+    : zh.python ? `· Chinese voice (kokoro zf_001): Python ${zh.python.version} found; storyshot sets up its venv in ${zh.venv} on first use`
+      : '· Chinese voice (kokoro zf_001) needs Python 3.10–3.12 — optional: brew install python@3.12, or uv python install 3.12 (or set STORYSHOT_PYTHON)');
+  const hf = hyperframesCli();
+  lines.push(hf.error ? `· HyperFrames cards (hyperframes: true) unavailable — optional: ${hf.error}`
+    : hf.missing ? `· HyperFrames cards (hyperframes: true): ${HF_VERSION} installs itself on first use`
+      : `✔ HyperFrames cards (${hf.how})`);
   lines.push(process.env.ELEVENLABS_API_KEY ? '✔ ELEVENLABS_API_KEY set' : '· ELEVENLABS_API_KEY not set — optional, for the best voice (put it in .env)');
   return { ok: !todo.length, report: lines.join('\n'), todo };
 }

package/src/ffmpeg.mjs

@@ -0,0 +1,27 @@
+// What the installed ffmpeg can do: builds differ (Homebrew's default ffmpeg has no libass, so no
+// `ass` filter for burned-in subtitles).
+import { execFileSync } from 'node:child_process';
+
+const cache = {};
+const list = (kind) => {
+  if (!cache[kind]) {
+    try {
+      const out = execFileSync('ffmpeg', ['-hide_banner', `-${kind}`], { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+      // " .. zoompan  V->V  ..." (filters) or " V....D libx264  ..." (encoders): the name is the second column
+      cache[kind] = new Set(out.split('\n').map((l) => l.trim().split(/\s+/)[1]).filter(Boolean));
+    } catch { cache[kind] = new Set(); }
+  }
+  return cache[kind];
+};
+export const hasFilter = (name) => list('filters').has(name);
+export const hasEncoder = (name) => list('encoders').has(name);
+
+// what Storyshot needs from ffmpeg, and what each optional piece is for
+export const NEEDED = {
+  filters: ['zoompan', 'overlay', 'alphamerge', 'gblur', 'fade', 'tpad', 'loudnorm', 'alimiter', 'aresample', 'atempo', 'silenceremove', 'areverse', 'palettegen', 'paletteuse'],
+  encoders: ['libx264', 'aac'],
+};
+export const OPTIONAL = [
+  { filter: 'ass', for: '`subtitles: burn` uses its own renderer instead (the word highlight steps word by word rather than sweeping)' },
+  { encoder: 'libvpx-vp9', for: 'webm clips (clips: webm)' },
+];