storyshot 0.7.0 → 0.7.3

package/README.md

@@ -15,6 +15,12 @@ second or two on screen.
 The agent plans, writes and fixes the storyboard. Storyshot does the
 recording and editing, and the same storyboard always renders the same video.
 
+https://github.com/user-attachments/assets/05dd9a73-2edc-46af-9b2b-a8e33c7005b4
+
+A 68-second pitch for Storyshot, made with [HyperFrames](https://hyperframes.heygen.com) and a free
+local voice (Kokoro). The request, storyboard, recording, contact sheet and render log in it, and the
+16 videos on the wall, are real Storyshot output.
+
 ## Gallery
 
 **[boheling.github.io/storyshot-gallery](https://boheling.github.io/storyshot-gallery/)**: promos,
@@ -211,7 +217,7 @@ Everything the agent does is also a command:
 | `storyshot init <url> [--purpose tutorial] [--topic export-pdf] [--storage videos/<site>-login.json]` | Write `videos/<site>-<kind>[-<topic>].yaml` with verified targets; the video gets the same name. |
 | `storyshot login <url> [--save videos/<site>-login.json]` | Log in once in a browser window and save the session. |
 | `storyshot inspect <url> [--storage auth.json]` | List verified targets and save screenshots. |
-| `storyshot inspect videos/acme-promo.yaml --after 3` | The same, for the page after steps 1–3. |
+| `storyshot inspect videos/acme-promo.yaml --after 3` | The same, for the page after steps 1–3. What step 3 opened is marked ★ and listed first. |
 | `storyshot check videos/acme-promo.yaml` | Validate without opening a browser. |
 | `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. |
@@ -257,7 +263,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); uses ffmpeg's libass when it has it, else draws the words itself
+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; in a vertical video the lines sit above the bottom fifth, which short-video apps cover, and the cards keep above them); 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
@@ -326,7 +332,7 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | `move` / `hover` | `move: { text: "$0" }` or `move: { x: 0.5, y: 0.4, ms: 1200 }` |
 | `type` | `type: { target: { label: Email }, text: hi@acme.com, delay: 60 }`, or `type: hello` to type into whatever has focus. `clear: true` empties a pre-filled field first |
 | `drag` | `drag: { from: { css: ".slider" }, by: [{ x: -300 }, { x: 450 }] }` (several moves while held), or `to: <target or point>` |
-| `press` | `press: Enter`, `press: "^"`, `press: { key: Meta+K, show: true }`. When highlighting, shortcuts and special keys show an on-screen badge; plain characters don't. `show: false` hides it. |
+| `press` | `press: Enter`, `press: "^"`, `press: { key: Meta+K, show: true }`. When highlighting, shortcuts and special keys show an on-screen badge next to the cursor; plain characters don't. `show: false` hides it. |
 | `pause` | `pause: 700` (ms) |
 | `waitFor` | `waitFor: { role: button, name: Done, timeout: 120000 }` |
 | `waitForUrl` | `waitForUrl: "**/dashboard"` |
@@ -336,9 +342,9 @@ You can add `exact: true`, `last: true` or `nth: 2` to any of them.
 | `scroll` | `scroll: 600` |
 | `dismiss` | `dismiss: { role: button, name: Close }` (clicks only if visible) |
 | `hide` | `hide: '[id*="QSI"], .chat-widget'` hides pop-ups, survey prompts, feedback tabs and chat widgets for the whole video, including ones that appear late (use it in `setup`) |
-| `mark` | `mark: "automatic zoom, captions"` sweeps a highlighter over that phrase, even inside a paragraph (scrolling to it only if it's off screen, and below a sticky header). `mark: { css: "table tr:nth-child(3)" }` marks any target with a box. Options: `ms` (sweep time, default 700), `color` (default: theme accent), `box: true/false`. Marks stay until the step ends. |
+| `mark` | `mark: "automatic zoom, captions"` sweeps a highlighter over that phrase, even inside a paragraph (scrolling to it only if it's off screen, and below a sticky header). `mark: { css: "table tr:nth-child(3)" }` marks any target with a box. Options: `ms` (sweep time, default 700), `color` (default: theme accent), `box: true/false`. Only text the viewer can see counts: a copy that is hidden, transparent, collapsed or covered is skipped. Marks stay until the step ends, and a mark whose text scrolls out of view (out of its panel, under a header) disappears with it. |
 | `unmark` | `unmark: true` clears the marks (and notes) earlier |
-| `note` | `note: { target: { label: Database }, text: Curated proteins only }` puts a short label with an arrow next to the element, on the side with the most room (or `side: left/right/top/bottom`). It stays until the step ends and gets reading time (about 3 words a second, or `ms`). |
+| `note` | `note: { target: { label: Database }, text: Curated proteins only }` puts a short label with an arrow next to the element, on the side with the most room (or `side: left/right/top/bottom`). It stays until the step ends and gets reading time (about 3 words or 5 Chinese/Japanese/Korean characters a second, or `ms`). |
 | `paste` | `paste: { target: { label: JSON }, text: '{"a": 1}' }` pastes text in one go through the real clipboard (with a ⌘V badge), so editors react as to a real paste; `paste: "..."` pastes into whatever has focus |
 | `slide` | `slide: { target: { label: Quality }, to: 0.2 }` drags a slider to a position along its track (0 = start, 1 = end), found from the element, not pixels. `value: 3` drags it to that value instead, when the slider reports its range (an `<input type=range>`, or an ARIA slider such as Desmos's; `inspect` shows the range). The target can be the slider or its knob |
 | `select` | `select: { target: { label: Database }, option: "UniProtKB/Swiss-Prot" }` picks an option in a dropdown (by its visible text, or part of it). `inspect` lists each dropdown's options. |
@@ -386,8 +392,10 @@ rather than cut off.
 ### Voiceover
 
 Add a `voice` block, then give steps a `say:` line (and optionally
-`end_card.say`). Each line starts as its step begins (`sayAt` shifts it) and may
-run until the next line. A line that is up to 20% too long is sped up slightly.
+`end_card.say`). Each line starts as its step begins (`sayAt: 0.5` starts it
+half a second in; `sayAt: after` starts it, and the step's caption, once the
+step's actions are done, for a line about their result) and may run until the
+next line. A line that is up to 20% too long is sped up slightly.
 A line longer than that is queued after the previous line, and you get a
 warning telling you to shorten it. Music ducks under the voice, and the final
 mix is normalized to -14 LUFS.
@@ -398,7 +406,7 @@ mix is normalized to -14 LUFS.
 | `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. For Chinese, use `qwen` (Apple Silicon) or `kokoro` with `zf_001` rather than `Tingting`. |
+| `say` | none | macOS built-in voices, robotic; for drafts only: Apple's license allows them for personal, non-commercial use, and not in anything you publish or share. 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
@@ -426,7 +434,9 @@ first use) and compares what it hears with the line: Chinese by sound, so a homo
 numbers digit by digit. A take that comes out wrong, or far too long or short, is made again with another
 seed (up to 4 tries), and Storyshot warns, quoting what it heard, if a line still doesn't come out right.
 This adds about 0.2 s per line. 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`),
+model babbling. Lines in Latin letters are read in the storyboard's `lang` when Qwen3-TTS knows it
+(`en`, `es`, `fr`, `de`, `it`, `pt`), so a Spanish lesson with `lang: es` gets a Spanish reading, checked
+by ear in Spanish. On other machines the same storyboard renders with `kokoro` (`zf_001`, or `draftVoice`),
 with a note.
 
 Other fields: `speed` (default 1), `volume` (default 1), `pause` (the shortest pause between the
@@ -453,7 +463,7 @@ usually shouldn't.
 
 | field | meaning |
 |---|---|
-| `logo` | A target on the page (captured as an image, e.g. `{ alt: Acme logo }`) or a path to an image file. If the logo image already contains the wordmark, leave out `title`. |
+| `logo` | A target on the page (captured as an image, e.g. `{ alt: Acme logo }`; an inline SVG logo is `{ css: "header a svg" }` or similar) or a path to a PNG, JPG or SVG file. With a `title` too, the title shows under the logo; if the logo already contains the wordmark, leave out `title`. |
 | `title` | Large product name next to the logo. |
 | `kicker` | Small label above the title, e.g. `Part 2`. |
 | `subtitle` | One line; `**bold**` gets an accent highlight. |
@@ -463,7 +473,7 @@ 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. |
+| `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. |
 
 ### HyperFrames cards
 
@@ -500,6 +510,29 @@ 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`).
 
+## Licenses of what Storyshot uses
+
+Storyshot is MIT. What it installs and downloads:
+
+- **npm packages** are MIT, BSD, ISC, Apache-2.0 or BlueOak, with two exceptions, both under the optional
+  `kokoro-js` (the `kokoro` voice):
+  - `phonemizer` says Apache-2.0, but it bundles [eSpeak NG](https://github.com/espeak-ng/espeak-ng),
+    which is GPL-3.0-or-later, compiled to WebAssembly. If you ship Storyshot inside a closed-source
+    product, account for that, or install without it (`npm install --omit=optional`) and narrate with
+    `qwen` or a cloud voice.
+  - `sharp` loads libvips (LGPL-3.0) as a separate library.
+- **Downloaded on first use:** Chromium (through Playwright), HyperFrames (Apache-2.0), the voice and
+  speech models (Kokoro-82M, Qwen3-TTS, Qwen3-ASR: all Apache-2.0) and their Python packages
+  (mlx-audio: MIT, pypinyin: MIT). ffmpeg is your own install; Storyshot runs it as a separate program.
+- **The cards** animate with the browser's own Web Animations API. The Virgil font is under the SIL Open
+  Font License 1.1. The music and sound effects are synthesized by Storyshot.
+- **Your videos:** narration made with `kokoro` or `qwen` comes from Apache-2.0 models, so you can use it
+  in commercial work. The macOS `say` voices are for drafts only: Apple's license allows them for
+  personal, non-commercial use, and not in anything published or shared. ElevenLabs and OpenAI voices
+  follow those services' terms.
+
+This is a summary, not legal advice.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "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": {
@@ -39,7 +39,6 @@
     "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "gsap": "^3.14.2",
     "kokoro-js": "^1.2.1",
     "roughjs": "^4.6.6"
   }

package/skills/storyshot/SKILL.md

@@ -96,8 +96,11 @@ frames or stock footage presented as a recording of their app.
    models on first use. Storyshot listens to each take and makes it again if
    it comes out garbled; a `⚠ qwen: … sounds like "…"` warning means a line
    still came out wrong after 4 tries: rephrase it (spell out a number, say
-   `一格` for `1 格`). Elsewhere a `qwen` storyboard renders with kokoro. For other
-   languages, use ElevenLabs.
+   `一格` for `1 格`). Elsewhere a `qwen` storyboard renders with kokoro.
+   `qwen` also reads Spanish, French, German, Italian and Portuguese: set the
+   storyboard's `lang` (`lang: es`). For other languages, use ElevenLabs.
+   Never publish a video narrated with macOS `say`: Apple's license allows its
+   voices only for personal, non-commercial use, so keep it for drafts.
 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
@@ -127,7 +130,13 @@ frames or stock footage presented as a recording of their app.
 3. For states you can only reach by clicking (an editor after an upload, an
    open menu, a modal), write the steps up to that point, then call
    `inspect_page` with `storyboard` + `after_step: N`. It runs steps 1..N fast
-   (about 10 s) and lists the targets on the page at that moment.
+   (about 10 s) and lists the targets on the page at that moment. What step N
+   opened (a menu, a dialog, a panel) is marked ★ and listed first. If a step
+   fails, the result lists the targets on the page at that moment.
+   - Inspect lists up to 150 targets. When it says "… and N more not listed",
+     open the panel you need with a step and inspect after that step.
+   - `(covered by something on top right now)` means a dialog or banner sits over
+     that element: a click lands on the cover. Close or `hide` it first.
 4. Copy targets exactly as printed: `{ role: "button", name: "Convert", exact: true }`.
    - `name` is the accessible name. It can differ from the label on screen;
      inspect shows `(on screen: "Export Image")` when it does. Never write a
@@ -161,6 +170,12 @@ small controls are readable. Your job is the structure:
   its own `say:` explaining **what** it does and **why this value**. Never
   "fill in the form and submit" in one line. `check` warns when a tutorial
   step does more than two things.
+- **Say it when it happens.** A line starts with its step, so the viewer hears
+  "now the line is flat" before the drag has flattened it. When a line is about
+  what the step's actions produce, give that step `sayAt: after`: its line and
+  caption start once the actions are done (needs `duration: auto`, the default
+  for tutorials and lessons). Lines that say what you're about to do ("click
+  Send") stay as they are.
 - **Show, then explain the result.** After an action that produces output
   (a results table, a number, a plot, a status), add a step that only looks:
   `mark` the value or row you're talking about (`mark: "E value"`,

package/src/check.mjs

@@ -98,6 +98,8 @@ export function check(file, { draft = false } = {}) {
       else target(s.zoom.target, `${where} zoom.target`);
     }
     if (s.hidden && (s.caption || s.say)) warnings.push(`${where}: hidden steps are cut from the video, so caption/say are ignored`);
+    if (s.sayAt != null && s.sayAt !== 'after' && !(typeof s.sayAt === 'number' && s.sayAt >= 0)) errors.push(`${where}: sayAt must be seconds into the step (e.g. 0.5) or "after" (once the step's actions are done)`);
+    if (s.sayAt === 'after' && typeof (s.duration ?? raw.duration) === 'number') warnings.push(`${where}: sayAt: after needs duration: auto (a fixed-length step has no time after its actions)`);
     if (!Array.isArray(s.actions ?? [])) errors.push(`${where}: actions must be a list`);
     for (const [j, a] of (s.actions ?? []).entries()) checkAction(a, `${where} action ${j + 1}`);
     if (s.card) unknown(s.card, END, `${where} card`);
@@ -181,7 +183,7 @@ export function check(file, { draft = false } = {}) {
         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 room = span.reduce((a, d) => a + d, 0) - (typeof s.sayAt === 'number' ? 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)`);
       }

package/src/compose.mjs

@@ -25,7 +25,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   const cardLen = (c, voice, min) => (c.duration === 'auto' || c.duration == null ? Math.max(min, (voice ?? 0) + 0.9, readTime(c)) + (c.think ?? 0) : c.duration);
   // the end card carries the call to action: long enough to read it (and for a command to type itself out)
   const ctaTime = (c) => (c?.cta ? 0.8 + String(c.cta).length * 0.045 + 1.6 : 0);
-  const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(2.5, (voiceLens.endCard ?? 0) + 0.6, readTime(ec0), ctaTime(ec0)) : ec0.duration;
+  const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(2.5, (voiceLens.endCard ?? 0) + 0.6 + cfg.pace.tail * 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(cfg.hyperframes?.template === 'launch' ? 2.8 : 1.8, (voiceLens.intro ?? 0) + 0.8, readTime(in0)) : in0.duration;
@@ -56,21 +56,27 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const M = parts.filter((p) => !p[2]).reduce((x, p) => x + p[1] - p[0], 0);
     const Wt = parts.filter((p) => p[2]).reduce((x, p) => x + p[1] - p[0], 0);
     let D, waitBudget, motionBudget, hold = 0;
+    // when the line starts: `sayAt: after` once the step's actions are done (a line about their result:
+    // "now the line is flat"), else this many seconds into the step
+    let sayAt = typeof s.sayAt === 'number' ? s.sayAt : 0.15;
     if (s.duration === 'auto') {
-      const voiceNeed = voiceLens.steps[i] != null ? voiceLens.steps[i] + (s.sayAt ?? 0.15) + cfg.pace.tail : 0;
       waitBudget = Math.min(Wt, cfg.maxWait);
       motionBudget = M;
+      if (s.sayAt === 'after') sayAt = M + waitBudget + 0.2;
+      const voiceNeed = voiceLens.steps[i] != null ? voiceLens.steps[i] + sayAt + cfg.pace.tail : 0;
       // a silent step holds its result too (docs GIFs: long enough to see it before the loop restarts)
       const quiet = s.say ? 0 : cfg.clips.length ? 1.5 : cfg.pace.tail;
       D = Math.max(M + waitBudget + quiet, voiceNeed, 0.8);
       let extra = D - M - waitBudget;
-      const stretch = Math.min(extra, Wt - waitBudget);
+      // more of the waiting first, then hold the last frame (after the line about the result: only hold)
+      const stretch = s.sayAt === 'after' ? 0 : Math.min(extra, Wt - waitBudget);
       waitBudget += stretch; extra -= stretch;
       hold = extra;
     } else {
       D = s.duration;
       waitBudget = M + Wt <= D ? Wt * D / (M + Wt) : M === 0 ? D : Math.min(Wt, Math.max(D - M, 0.15 * D));
       motionBudget = D - waitBudget;
+      if (s.sayAt === 'after') warn(`step ${i + 1}: sayAt: after needs duration: auto (a fixed-length step has no time after its actions) — the line starts with the step`);
     }
     if (s.card) {
       // a section card plays over the step's first frame, before the step
@@ -83,7 +89,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       cards.push({ i, t0: acc, t1: acc + C, card: s.card, thinkAt: C - (s.card.think ?? 0) - 0.3 });
       acc += C;
     }
-    const g = { i, step: s, o0: acc, o1: acc + D, zoomBox: r.zoomBox, afterHidden, hold,
+    const g = { i, step: s, o0: acc, o1: acc + D, sayAt, zoomBox: r.zoomBox, afterHidden, hold,
       motionSpeed: M && motionBudget ? M / motionBudget : 1, waitSpeed: Wt && waitBudget ? Wt / waitBudget : 1 };
     for (const [a, b, w] of parts) {
       const len = (b - a) / (w ? g.waitSpeed : g.motionSpeed);
@@ -173,7 +179,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const spoken = [
       ...(in0 ? [[0, INTRO]] : []), // cards are their own pictures (the frames under them don't show)
       ...cards.map((c) => [c.t0, c.t1]),
-      ...segs.filter((g) => voiceLens.steps[g.i] != null).map((g) => [g.o0 + (g.step.sayAt ?? 0.15), g.o0 + (g.step.sayAt ?? 0.15) + voiceLens.steps[g.i]]),
+      ...segs.filter((g) => voiceLens.steps[g.i] != null).map((g) => [g.o0 + g.sayAt, g.o0 + g.sayAt + voiceLens.steps[g.i]]),
     ];
     let from = null;
     const report = (to) => {
@@ -360,7 +366,8 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       warn(`step ${g.i + 1}: the ${want} caption would cover ${hit.what}, so it was moved to the ${other}` + (explicit ? ` (despite captionPosition: ${explicit})` : '') + ` — set captionPosition: ${other} to make this explicit`);
     } else if (hit) warn(`step ${g.i + 1}: the caption covers ${hit.what} at both top and bottom — shorten the caption, or change the zoom`);
     if (prev && n === prev.n && prev.pos === pos) prev.t[1] = g.o1;
-    else captions.push({ text: g.step.caption, t: [g.o0, g.o1], pos, n, h });
+    // a line about the step's result (sayAt: after) shows its caption with it, not before the result is there
+    else captions.push({ text: g.step.caption, t: [g.step.sayAt === 'after' ? g.o0 + Math.max(0, g.sayAt - 0.1) : g.o0, g.o1], pos, n, h });
   }
   for (const [i, c] of (cfg.captions ? captions : []).entries()) await shot(bubble(c.text, c.n, c.pos), path.join(cfg.work, `cap${i}.png`), true);
   // Intro and end cards are short animations (logo pops, title rises, the highlight sweeps, a command
@@ -488,10 +495,22 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       return f;
     };
     const sizeOf = (f) => {
+      if (/\.svg$/i.test(f)) {
+        // ffprobe can't read SVG: its shape from width/height or the viewBox, as large as the cards draw a logo
+        const tag = fs.readFileSync(f, 'utf8').match(/<svg\b[^>]*>/i)?.[0] ?? '';
+        const attr = (a) => parseFloat(tag.match(new RegExp(`\\s${a}\\s*=\\s*["']?([\\d.]+)(px)?["'\\s>]`, 'i'))?.[1]);
+        const vb = tag.match(/viewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)/i);
+        const [w, h] = attr('width') > 0 && attr('height') > 0 ? [attr('width'), attr('height')] : vb ? [+vb[1], +vb[2]] : [0, 0];
+        if (!(w > 0 && h > 0)) { warn(`the logo ${path.basename(f)} has no width/height or viewBox, so the cards leave it out — add a viewBox, or use a PNG`); return null; }
+        const k = Math.min((W * 0.42) / w, (H * 0.17) / h) / 3.2;
+        return { w: w * k, h: h * k };
+      }
       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; }
+        if (w && h) return { w, h };
+      } catch {}
+      warn(`could not read the size of the logo ${path.basename(f)}, so the cards leave it out — use a PNG, JPG or SVG`);
+      return null;
     };
     const voice = (text, start, len) => (text && len ? { text, start, len } : null);
     const jobs = [];
@@ -519,7 +538,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   // 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,
+    W, H, FPS, dark: darkCards, accent, ink, font, lang: cfg.lang, labels: cfg.labels, opts: cfg.hyperframes, work: cfg.work, subs: cfg.subtitles === 'burn',
     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 }) : {};
@@ -675,7 +694,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     voice: [
       ...(in0?.say ? [{ text: in0.say, start: 0.15, where: 'intro' }] : []),
       ...cards.filter((c) => c.card.say).map((c) => ({ text: c.card.say, start: c.t0 + 0.15, where: `step ${c.i + 1} card` })),
-      ...segs.filter((g) => g.step.say).map((g) => ({ text: g.step.say, start: g.o0 + (g.step.sayAt ?? 0.15), where: `step ${g.i + 1}` })),
+      ...segs.filter((g) => g.step.say).map((g) => ({ text: g.step.say, start: g.o0 + g.sayAt, where: `step ${g.i + 1}` })),
       ...(ec?.say ? [{ text: ec.say, start: VIDEO + 0.05, where: 'end card' }] : []),
     ],
   };

package/src/config.mjs

@@ -154,7 +154,7 @@ export function loadConfig(file, { draft = false } = {}) {
     // 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, pause: pace0.sentencePause, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...raw.voice, provider };
+    voice = { speed: pace0.voiceSpeed, volume: 1, pause: pace0.sentencePause, ...VOICE_DEFAULTS[provider], ...(byLang ? { voice: byLang } : {}), ...(raw.lang ? { lang: raw.lang } : {}), ...raw.voice, provider };
     if (!(typeof voice.pause === 'number' && voice.pause >= 0 && voice.pause <= 3)) throw new Error('voice.pause is the shortest pause between the sentences of a line, in seconds, 0–3 (0 leaves the voice as it is)');
     if (provider === 'qwen') {
       const v = qwenVoice(voice.voice);