storyshot 0.4.2 → 0.6.0

package/README.md

@@ -152,7 +152,8 @@ 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) |
+| `qwen` | free | local, Apple Silicon Macs only; the most natural free Chinese voice (`dylan`, `serena`); downloads a ~2.3 GB model 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` |
 
@@ -247,7 +248,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)
@@ -393,10 +394,36 @@ 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. |
+| `qwen` | none | Local and free, Apple Silicon Macs only: Qwen3-TTS, the most natural free Chinese voice here (`dylan`, `serena`, see below). |
 | `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 `qwen` (Apple Silicon) or `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 度号.
+
+**Chinese on an Apple Silicon Mac: Qwen3-TTS.** `voice: { provider: qwen }` speaks with
+[Qwen3-TTS 0.6B CustomVoice](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice) (Apache-2.0)
+through [mlx-audio](https://github.com/Blaizzy/mlx-audio). It reads English words, letters and numbers
+in a Chinese line more reliably than `zf_001`. Voices: `dylan` (male, Beijing accent; the default
+for Chinese tutorials, lessons and docs), `serena` (female, warm; the default for Chinese promos),
+`vivian` (female, bright), `uncle_fu` (male, mellow), `eric` (male, Sichuan accent), and `ryan`, `aiden` (English), `ono_anna` (Japanese), `sohee` (Korean). On
+first use Storyshot creates a venv in `~/.cache/storyshot/qwen-venv` (Python 3.10–3.12, about 400 MB)
+and downloads the ~2.3 GB model into the Hugging Face cache. It speaks at about 2x real time on an M4 Pro
+and peaks at about 8 GB of memory. The model samples its speech, so a line now and then runs on into
+invented words or stops short. Storyshot regenerates such a take (it judges by length) and warns if
+one still looks off. A scientific number like `2e-105` is spelled out in Chinese, because it sets the
+model babbling. On other machines the same storyboard renders with `kokoro` (`zf_001`, or `draftVoice`),
+with a note.
 
 Other fields: `speed` (default 1), `volume` (default 1), and `pronounce`, a
 map of word → spoken form used only for TTS, e.g.
@@ -430,6 +457,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.2",
+  "version": "0.6.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,16 @@ 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). On an Apple Silicon Mac, the
+   best free Chinese voice is `voice: { provider: qwen }` (Qwen3-TTS: `dylan`,
+   a male teacher's voice, for tutorials and lessons; `serena`, female, for
+   promos; those are the defaults): clearer than
+   zf_001 with English words and letters, about 2x real time, a ~2.3 GB model
+   on first use. Elsewhere a `qwen` storyboard renders with kokoro. 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 +184,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;
@@ -193,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/check.mjs

@@ -3,12 +3,15 @@ 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';
+import { qwenStatus } from './qwen-tts.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 +87,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)));
@@ -154,6 +158,17 @@ export function check(file, { draft = false } = {}) {
         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 (v?.provider === 'qwen') {
+      const q = qwenStatus();
+      if (q.problem) errors.push(q.problem);
+    }
+    if (v?.fallback) warnings.push(v.fallback);
     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,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
-import { VOICE_DEFAULTS } from './voice.mjs';
+import { VOICE_DEFAULTS, kokoroVoiceFor, qwenVoiceFor } from './voice.mjs';
+import { QWEN_VOICES, qwenSupported, qwenVoice } from './qwen-tts.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 +32,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 +115,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 +137,35 @@ 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 };
-    if (draft && provider !== 'kokoro') {
-      voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? VOICE_DEFAULTS.kokoro.voice, model: undefined };
+    // kokoro's and qwen's default voices follow the narration's language (zf_001 / serena for Chinese)
+    const kokoroVoice = kokoroVoiceFor(raw);
+    const byLang = { kokoro: kokoroVoice, qwen: qwenVoiceFor(raw) }[provider];
+    voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...raw.voice, provider };
+    if (provider === 'qwen') {
+      const v = qwenVoice(voice.voice);
+      if (!v) throw new Error(`voice: qwen has no voice "${voice.voice}" (one of ${QWEN_VOICES.join(', ')})`);
+      voice.voice = v;
+      // MLX needs Apple Silicon: anywhere else the same storyboard renders with kokoro
+      if (!qwenSupported()) {
+        const k = raw.voice.draftVoice ?? kokoroVoice;
+        voice = { ...voice, provider: 'kokoro', voice: k, fallback: `the qwen voice needs an Apple Silicon Mac; using kokoro ${k} instead` };
+      }
+    }
+    // free local voices stay; a paid one is swapped for kokoro
+    if (draft && !['kokoro', 'qwen'].includes(voice.provider)) {
+      voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? kokoroVoice, model: undefined };
     }
   }
 
@@ -186,10 +210,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

@@ -6,6 +6,9 @@ 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 { qwenStatus } from './qwen-tts.mjs';
+import { hyperframesCli, HF_VERSION } from './hyperframes.mjs';
 
 const has = (cmd, args = ['--version']) => { try { execFileSync(cmd, args, { stdio: 'ignore' }); return true; } catch { return false; } };
 
@@ -71,6 +74,20 @@ 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 q = qwenStatus();
+  lines.push(!q.supported ? '· Qwen3-TTS voice (provider: qwen) needs an Apple Silicon Mac; storyboards that use it fall back to kokoro here'
+    : q.ready ? `✔ Qwen3-TTS voice (provider: qwen): venv in ${q.venv}${q.model ? ', model downloaded' : '; the model (~2.3 GB) downloads on first use'}`
+      : q.python ? `· Qwen3-TTS voice (provider: qwen): Python ${q.python.version} found; storyshot sets up its venv in ${q.venv} and downloads the model (~2.3 GB) on first use`
+        : '· Qwen3-TTS voice (provider: qwen) 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/fonts/Virgil-LICENSE.md

@@ -0,0 +1,45 @@
+Copyright (c) 2021 - Present, Ellinor Rapp, with Reserved Font Name Virgil.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1. This license is copied below, and is also available with a FAQ at: [scripts.sil.org/OFL](https://scripts.sil.org/OFL).
+
+# SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+
+## PREAMBLE
+
+The goals of the Open Font License (OFL) are to stimulate worldwide development of collaborative font projects, to support the font creation efforts of academic and linguistic communities, and to provide a free and open framework in which fonts may be shared and improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. The fonts, including any derivative works, can be bundled, embedded, redistributed and/or sold with any software provided that any reserved names are not used by derivative works. The fonts and derivatives, however, cannot be released under any other type of license. The requirement for fonts to remain under this license does not apply to any document created using the fonts or their derivatives.
+
+## DEFINITIONS
+
+"Font Software" refers to the set of files released by the Copyright Holder(s) under this license and clearly marked as such. This may include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting, or substituting -- in part or in whole -- any of the components of the Original Version, by changing formats or by porting the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or other person who contributed to the Font Software.
+
+## PERMISSION & CONDITIONS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software, to use, study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of the Font Software, subject to the following conditions:
+
+1. Neither the Font Software nor any of its individual components, in Original or Modified Versions, may be sold by itself.
+
+2. Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold with any software, provided that each copy contains the above copyright notice and this license. These can be included either as stand-alone text files, human-readable headers or in the appropriate machine-readable metadata fields within text or binary files as long as those fields can be easily viewed by the user.
+
+3. No Modified Version of the Font Software may use the Reserved Font Name(s) unless explicit written permission is granted by the corresponding Copyright Holder. This restriction only applies to the primary font name as presented to the users.
+
+4. The name(s) of the Copyright Holder(s) or the Author(s) of the Font Software shall not be used to promote, endorse or advertise any Modified Version, except to acknowledge the contribution(s) of the Copyright Holder(s) and the Author(s) or with their explicit written permission.
+
+5. The Font Software, modified or unmodified, in part or in whole, must be distributed entirely under this license, and must not be distributed under any other license. The requirement for fonts to remain under this license does not apply to any document created using the Font Software.
+
+## TERMINATION
+
+This license becomes null and void if any of the above conditions are not met.
+
+## DISCLAIMER
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.