storyshot 0.6.0 → 0.7.2

package/README.md

@@ -153,7 +153,7 @@ Rendering is free and runs locally. Only the voiceover can cost money:
 |---|---|---|
 | none | free | captions only |
 | `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 |
+| `qwen` | free | local, Apple Silicon Macs only; the most natural free Chinese voice (`dylan`, `serena`); every take is checked by a speech recognizer and made again if it comes out wrong; downloads ~3.3 GB of models 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` |
 
@@ -191,7 +191,7 @@ from `storyshot guide`.
 | `inspect_page` | Verified click targets and a screenshot, for a URL or for the state after step N of a storyboard. Reports login walls. |
 | `login` | Opens a browser window where the **user** logs in, and saves the session. |
 | `init_storyboard` | Writes a starter storyboard with verified targets. |
-| `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file. |
+| `check_storyboard` | Validates in about a second: typos with "did you mean", action and target shapes, `TODO`s, keys, the session file, and narration that sounds machine-written ("not just X, but Y", "seamless", 赋能…) or runs on without a breath. |
 | `render_video` / `render_status` | Renders in the background and returns the MP4 path, warnings, a per-step speed log and the preview image. If the render isn't done within 45 s, it returns a `job_id`, so client tool timeouts never kill a render. |
 
 Any other MCP client: run `npx -y storyshot mcp` (stdio), and point the agent at the playbook (`storyshot guide`). When run from a git
@@ -211,7 +211,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. |
@@ -248,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; clicks = no whooshes on cards and page changes (tutorial and course default); false = none
+sfx: true                                       # click / whoosh / riser sounds; clicks = no whooshes on cards and page changes, and no rising sound under a riser step, only its chime (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)
@@ -287,7 +287,7 @@ steps:
       - click: { role: button, name: Try it }
   - caption: AI does the work
     duration: 1.3
-    sfx: riser                                        # rising sound + chime (or `chime`)
+    sfx: riser                                        # rising sound + chime (or `chime`); a tutorial or lesson plays only the chime
     actions:
       - waitFor: { text: Done, timeout: 120000 }      # waiting is compressed automatically
   - card: { kicker: Part 2, title: Read the results }  # a section card before this step (tutorials); becomes a chapter
@@ -326,21 +326,21 @@ 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"` |
 | `networkIdle` | `networkIdle: true` |
 | `goto` | `goto: /pricing` |
-| `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` |
+| `scrollTo` | `scrollTo: { css: "#pricing", ms: 1200 }` scrolls the target to the top of the window, below a sticky header |
 | `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 if needed). `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 |
+| `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. |
 
 `ms` sets how long the cursor takes to travel to the target (`dragMs` for each
@@ -375,7 +375,7 @@ In-page anchor links (`href="#..."`) scroll smoothly instead of jumping.
 |---|---|
 | `target` | What to center on: a target, or a point `{ x: 0.5, y: 0.3 }`. If a step action used the same target, its position at that moment is used (so you can zoom on a button that disappears after the click). Otherwise it is measured at the start of the step when the zoom begins in the first half, or at the end of the step otherwise. |
 | `scale` | Zoom factor (default 1.3). 1.2–1.5 works well. |
-| `start`, `end` | Seconds from the start of the step. The camera eases in from 1× at `start` and is back at 1× at `end` (default: the step's end). `end` may run past the step, e.g. to hold the zoom through a click. |
+| `start`, `end` | Seconds from the start of the step. The camera eases in from 1× at `start` and is back at 1× at `end` (default: the step's end). A zoom belongs to its step: an `end` past the step's end stops there, with a warning. |
 | `ramp` | Ease-in / ease-out seconds: `0.5` or `[in, out]`. |
 | `offset` | Moves the camera center from the target's center, in viewport CSS px. `{ y: -120 }` centers 120 px above the target. |
 
@@ -386,8 +386,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 +400,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
@@ -419,14 +421,22 @@ for Chinese tutorials, lessons and docs), `serena` (female, warm; the default fo
 `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`),
+and peaks at about 8 GB of memory. The model samples its speech, so a take now and then garbles a few
+words, drops one, runs on into invented words or stops short. Storyshot listens to every take with
+[Qwen3-ASR 0.6B](https://huggingface.co/Qwen/Qwen3-ASR-0.6B) (Apache-2.0, a ~1 GB model downloaded on
+first use) and compares what it hears with the line: Chinese by sound, so a homophone isn't a mistake, and
+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. 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), and `pronounce`, a
-map of word → spoken form used only for TTS, e.g.
+Other fields: `speed` (default 1), `volume` (default 1), `pause` (the shortest pause between the
+sentences of a line, in seconds: 0.3 for promos, 0.6 for tutorials and lessons; a voice's own longer pause
+stays, and `0` leaves the voice as it is),
+and `pronounce`, a map of word → spoken form used only for TTS, e.g.
 `pronounce: { pxGenius: P X Genius, PPTX: P P T X }`. Subtitles keep the real
 spelling. Synthesized lines
 are cached in `.storyshot/tts-cache/`, so `compose` only pays for lines you
@@ -447,7 +457,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. |
@@ -457,13 +467,14 @@ 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 (optional)
+### HyperFrames cards
 
-`hyperframes: true` renders the intro, section and end cards with
+Tutorials and lessons render their 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`:
+renderer, Apache-2.0) for more motion; `hyperframes: false` keeps the built-in
+cards, and `hyperframes: true` turns them on for a promo. 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
@@ -485,7 +496,7 @@ hyperframes:
   backdrop: false         # lesson: plain background instead of the blurred page
 ```
 
-It needs Node 22 or newer. On first use storyshot installs the pinned
+It needs Node 22 or newer; on older Node, tutorials and lessons use the built-in cards. 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
@@ -493,6 +504,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.6.0",
+  "version": "0.7.2",
   "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

@@ -92,9 +92,15 @@ frames or stock footage presented as a recording of their app.
    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.
+   zf_001 with English words and letters, about 2x real time, ~3.3 GB of
+   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.
+   `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
@@ -124,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
@@ -158,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"`,
@@ -184,14 +202,18 @@ 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:
+- **Animated cards that help explain.** Tutorials and lessons render their
+  cards with HyperFrames by default (Node 22+; it installs itself on first
+  use): titles land word by word, and each bullet lights up when the `say`
+  line names it, so write the bullets in the narration's own words. Use them:
+  a concept card for every idea that isn't on screen (the idea as the title,
+  its 2–4 steps as bullets, a formula or a line of code as `emblem`), a
+  question card for each check, and a recap end card. For a subject with its
+  own material, give every title 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.
+  For a promo, `hyperframes: true` gives the launch template with hand-drawn
+  accents (`hand: true` for hand lettering). `hyperframes: false` keeps the
+  built-in cards.
 - **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,
@@ -206,6 +228,59 @@ small controls are readable. Your job is the structure:
   don't pad: if a part is long, split it into more parts rather than
   speeding it up.
 
+### Writing the narration
+
+Viewers notice three things first: lines that run together, phrasing nobody
+says out loud, and an explanation that jumps around. Write the `say:` lines as
+a script before the steps around them, then read them in order on their own.
+They should sound like one person talking a friend through it.
+
+**Say it like a person.**
+- Short sentences, one idea each: about 15 words at most in English, 25
+  characters in Chinese. If you would run out of breath, split it.
+- Spoken words: contractions ("you'll", "it's"), "you", present tense, active
+  voice. In Chinese, 口语 rather than 书面语: "点一下这里", not "进行点击操作".
+- Use the exact labels on screen, and the same term every time (no synonyms
+  for variety).
+- Each sentence gets a breath after it: Storyshot widens the pause between
+  sentences to at least `voice.pause` (0.3 s for `pitch`, 0.6 s for tutorials
+  and lessons). Commas get no extra pause, so split long lines into sentences
+  rather than chaining clauses with commas.
+- For fixed durations, budget about 2.5 words a second in English and 4
+  characters a second in Chinese, and leave silence while the screen is busy.
+
+**Cut the phrases that mark text as machine-written** (`check` flags the
+common ones):
+- Contrasts that only add weight: "not just X, but Y", "it's not X, it's Y".
+- Inflated words: seamless, effortless, powerful, robust, unlock, elevate,
+  supercharge, revolutionize, leverage, cutting-edge, game-changer, delve;
+  "in today's fast-paced world". In Chinese: 赋能, 助力, 一站式, 全方位, 极致,
+  无缝, 轻松搞定, 不仅……更……, 让我们一起.
+- Openers and closers that say nothing: "Let's dive in", "Ever wondered…?",
+  "And that's it!", "Simple as that."
+- Three adjectives in a row, line after line ("fast, simple and powerful").
+- Filler that talks down to a stuck viewer: basically, simply, just, easily.
+- Dashes (—) in `say:` lines. Voices read them as a run-on; use a period.
+
+**Explain in an order the viewer can follow** (tutorials and lessons):
+1. The question or the goal ("How does b move the line?").
+2. A concrete case on screen first: change the value, show the result.
+3. Then name the idea, in plain words, the first time it appears.
+4. Why it works, in one or two sentences, with a concept card if it isn't on
+   screen (its bullets light up as you name them; a formula goes in `emblem`).
+5. A check: a question card, then the step that reveals the answer.
+6. The recap, in the same words as before.
+
+Every step answers the question the step before it raised. Link them out loud:
+"Now that b has moved the line up, let's see what m does." When the camera
+has to go somewhere else on the page, say why first ("The results are further
+down, in the table."). If a line only makes sense with the video, or the
+script reads as a list of disconnected facts, reorder the steps before you
+render.
+
+(These rules borrow from [humanizer](https://github.com/blader/humanizer) and
+[stop-slop](https://github.com/hardikpandya/stop-slop), both MIT.)
+
 Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
@@ -225,11 +300,15 @@ Rules of thumb from real renders (promos and tutorials):
   `voice.pronounce` (e.g. `pxGenius: P X Genius`, `AI: A I`) so subtitles stay
   correct. For fixed durations, budget about 2.5 words per second.
 - **Isolate long waits** (AI processing, uploads) in their own step: a
-  `waitFor` the finished state, `sfx: riser`, and in `pitch` mode
-  `duration: 1.0–1.5`. Waiting is compressed automatically.
+  `waitFor` the finished state. In `pitch` mode add `sfx: riser` and
+  `duration: 1.0–1.5`. In tutorials and lessons, say what is happening
+  instead; at most `sfx: chime` when the result arrives (a riser there plays
+  only its chime). Waiting is compressed automatically.
 - **Zoom sparingly**, on 2–4 payoff moments (headline, clicked button, result,
   price), with `scale: 1.2–1.5`.
-- **Show the signature interaction.** Use `drag` for sliders and before/after
+- **Show the signature interaction.** Use `slide` for sliders:
+  `slide: { target: <the slider inspect lists>, value: 3 }` lands on that value
+  (`to: 0..1` for sliders that don't report a range). Use `drag` for before/after
   views (`drag: { from: { x: 0.57, y: 0.5 }, by: [{ x: -300 }, { x: 400 }] }`;
   `from` can be a target or a point). Use `type` for inputs: `type: y=x^2`
   types into whatever has focus (for editors and canvases with hidden inputs),

package/src/audio.mjs

@@ -108,7 +108,8 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
         return filt(rand(), 400 + 5000 * Math.sin(Math.PI * p), 1.6).bp * Math.pow(Math.sin(Math.PI * p), 2);
       }, 0.5);
     }
-    for (const [a, b] of events.risers) {
+    // the rising sound under a wait is for promos; tutorials and lessons (sfx: clicks) keep only its chime
+    for (const [a, b] of cfg.sfx.transitions ? events.risers : []) {
       const len = b - a, filt = svf();
       let ph = 0;
       add(sfx, a, len, (t) => {
@@ -133,12 +134,15 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   if (cfg.voice && events.voice?.length) {
     let prevEnd = 0;
     for (const line of events.voice) {
-      let pcm = await speak(cfg, line.text, { log });
+      let { pcm, parts } = await speak(cfg, line.text, { 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;
       // 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; }
+      if (dur > room && room > 0 && dur / room <= 1.2) {
+        sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR;
+        parts = parts.map((p) => ({ ...p, start: p.start / sped, end: p.end / sped }));
+      }
       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`);
@@ -154,7 +158,8 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
         voiceOn[s0 + i] = 1;
       }
       prevEnd = start + dur;
-      narration.push({ start, end: start + dur, text: line.text });
+      // subtitles per sentence, so the pauses between them don't throw off the word timing
+      for (const p of parts) narration.push({ start: start + p.start, end: Math.min(start + p.end, start + dur), text: p.text });
     }
   }
 

package/src/check.mjs

@@ -5,6 +5,34 @@ import { loadConfig } from './config.mjs';
 import { gitIgnored } from './auth.mjs';
 import { isZhVoice, zhVoiceStatus } from './kokoro-zh.mjs';
 import { qwenStatus } from './qwen-tts.mjs';
+import { sentences } from './voice.mjs';
+
+// Phrases that mark narration as machine-written, and sentences too long to say in one breath.
+const TELLS = [
+  /\bnot (?:just|only|merely) [^.,;!?]{1,40}?,? but(?: also)?\b/i, // "not just X, but Y"
+  /\bit'?s not (?:about )?[^.,;!?]{1,30}[,;—–-]+ it'?s\b/i, // "it's not X, it's Y"
+  /\b(?:seamless(?:ly)?|effortless(?:ly)?|supercharg\w*|revolutioni[sz]\w*|game[- ]chang\w*|cutting[- ]edge|elevat(?:e|es|ed|ing)|leverag(?:e|es|ed|ing)|delv(?:e|es|ing))\b/i,
+  /\bin today'?s (?:fast-paced|digital|modern)\b/i,
+  /\blet'?s dive in\b|\bever wondered\b|\bsimple as that\b|\band that'?s it\b/i,
+  /\b(?:basically|simply)\b/i, // ("easily" is too often literal: "binds more easily")
+  /[—–]/,
+  /赋能|助力|一站式|全方位|极致|无缝|轻松搞定|让我们一起|不仅[^。！？]{1,20}更/,
+];
+export function narrationLint(text) {
+  const t = String(text).replace(/\*\*/g, ''), tells = [];
+  for (const re of TELLS) {
+    const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+    for (const m of t.matchAll(g)) if (!tells.includes(m[0].trim())) tells.push(m[0].trim());
+  }
+  let long = null;
+  for (const s of sentences(t)) {
+    const cjk = (s.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length;
+    const words = s.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter((w) => /\w/.test(w)).length;
+    if (cjk > 40 && !long) long = `${cjk}-character`;
+    else if (!cjk && words > 25 && !long) long = `${words}-word`;
+  }
+  return { tells, long };
+}
 
 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', 'hyperframes'];
@@ -70,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`);
@@ -107,7 +137,7 @@ export function check(file, { draft = false } = {}) {
     if (type === 'target') target(v, `${where} (${kind})`);
     if (type === 'mark' && typeof v !== 'string') target(v, `${where} (mark)`); // a string is a phrase to highlight
     if (type === 'slide') {
-      if (!v?.target || typeof v?.to !== 'number' || v.to < 0 || v.to > 1) errors.push(`${where}: slide needs { target: <slider>, to: 0..1 } (0 = start of the track, 1 = end)`);
+      if (!v?.target || (typeof v?.value !== 'number' && (typeof v?.to !== 'number' || v.to < 0 || v.to > 1))) errors.push(`${where}: slide needs { target: <slider>, to: 0..1 } (0 = start of the track, 1 = end) or { target: <slider>, value: <number> }`);
       else target(v.target, `${where} (slide.target)`);
     }
     if (type === 'select') {
@@ -146,18 +176,28 @@ export function check(file, { draft = false } = {}) {
     // 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 secs = (t) => { const { c, w } = words(t); return (c / 4.5 + w / 2.8) / (cfg.voice.speed ?? 1) + (sentences(t).length - 1) * (cfg.voice.pause ?? 0); };
       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 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)`);
       }
     }
+    // spoken lines that read as machine-written, or run on without a breath (the skill's "Writing the narration")
+    if (cfg.voice) {
+      const lines = [...visible.flatMap((s) => [[s.say, `step ${cfg.steps.indexOf(s) + 1}`], [s.card?.say, `step ${cfg.steps.indexOf(s) + 1} card`]]),
+        [cfg.intro?.say, 'intro'], [cfg.endCard?.say, 'end card']].filter(([t]) => t);
+      for (const [text, where] of lines) {
+        const { tells, long } = narrationLint(text);
+        if (tells.length) warnings.push(`${where}: the narration sounds machine-written (${tells.map((x) => `"${x}"`).join(', ')}) — say it plainly, as you would out loud`);
+        if (long) warnings.push(`${where}: a ${long} sentence — split it, so the voice gets a breath between the parts`);
+      }
+    }
     // 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)) {

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) => {
@@ -235,6 +241,11 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       g.zoomBox = null;
     } else if (z && !g.zoomBox) warn(`step ${g.i + 1}: zoom target not found on the page, zoom skipped`);
     if (!z || !g.zoomBox) continue;
+    {
+      // measured off screen (e.g. before the step scrolled to it): the camera can only frame what's in the window
+      const b = g.zoomBox, cx = b.x + b.width / 2, cy = b.y + b.height / 2, { width: VW, height: VH } = cfg.viewport;
+      if (cx < 0 || cx > VW || cy < 0 || cy > VH) warn(`step ${g.i + 1}: the zoom target was off screen when it was measured (${cy > VH ? `${Math.round(cy - VH)}px below` : cy < 0 ? `${Math.round(-cy)}px above` : 'beside'} the window), so the zoom frames the edge of the page instead — zoom on something an action in this step moves to, or use a point target`);
+    }
     g.zoomPeak = g.o0 + (z.start ?? 0) + (Array.isArray(z.ramp) ? z.ramp[0] : z.ramp ?? 0.5) + 0.1;
     const b = g.zoomBox, off = z.offset ?? {};
     const c = [(b.x + b.width / 2 + (off.x ?? 0)) * K, (b.y + b.height / 2 + (off.y ?? 0)) * K];
@@ -355,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
@@ -483,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 = [];
@@ -670,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' }] : []),
     ],
   };