storyshot 0.4.0 → 0.4.2

package/README.md

@@ -217,7 +217,7 @@ Everything the agent does is also a command:
 | `storyshot record videos/acme-promo.yaml` | Only record. |
 | `storyshot guide` | Print the playbook and the reference. |
 | `storyshot setup <agent>` (`cursor`, `claude`, `codex`, `gemini`, `vscode`, `windsurf`, `cline`) | Set up the MCP server and the skill in this project, and install or check what Storyshot needs. |
-| `storyshot doctor` | Check Node, ffmpeg, Chromium and voices; install Chromium if it's missing. |
+| `storyshot doctor` | Check Node, ffmpeg (and the filters and encoders Storyshot uses), Chromium and voices; install Chromium if it's missing. |
 | `storyshot mcp` | Run the MCP server. |
 
 Recordings, previews and voice lines are cached in `.storyshot/` next to the
@@ -252,15 +252,18 @@ voice: { provider: elevenlabs, voice: hpp4J3VqNfWAUOO0d1Us }   # optional voiceo
 storageState: auth.json                         # optional Playwright login state
 ignoreHTTPSErrors: true                         # internal site with a self-signed HTTPS certificate (plain http:// needs nothing)
 captionPosition: bottom                         # or top; can also be set per step. A caption that would cover a step's click target or zoom subject moves to the other side automatically
+captions: true                                  # false keeps caption pills off the video (chapters and SRT still use them), e.g. with subtitles: burn
 purpose: pitch                                  # pitch | tutorial | course | docs (sets the defaults below)
 highlight: false                                # spotlight targets before click/type (per step or per action too)
 stepNumbers: false                              # numbered caption badges
-subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top)
+subtitles: false                                # write <out>.srt (narration, else captions); `burn` also burns the narration into the video, each word lighting up as it is spoken (captions move to the top); uses ffmpeg's libass when it has it, else draws the words itself
 pace: slow                                      # fast (pitch) | normal (docs) | slow (tutorial, course): cursor and typing speed, a beat after each click, hold after narration, voice speed, how much of a wait is shown
 follow: true                                    # tutorial/course default: the camera zooms in on what each step touches and pans between steps (a step's own zoom wins; follow: false on a step skips it); or { scale: 1.8 }
 article: { title: Export a drawing, intro: … }  # docs: heading and first paragraph of <out>-steps/README.md
+lang: es                                        # language of built-in labels ("Pause and think", chapter "Introduction", "Downloaded"): en, zh, es, pt, fr, de, ja; default: zh if the steps contain Chinese, else en
 cards: auto                                     # intro/section/end cards: auto follows the frame (dark frames get dark cards), or light | dark
-frame: aurora                                   # the recording sits in a browser window on a backdrop: aurora (dark, grain; pitch default), studio (light, grain; tutorial and course default), dark, pastel, blur (the page itself, blurred); false = full frame; or { style, background: <css> }
+frame: aurora                                   # the recording sits in a browser window on a backdrop: aurora (dark, grain; pitch default), studio (light, grain; tutorial and course default), dark, pastel, blur (the page itself, blurred); false = full frame; or { style, background: <css>, window, title, icon }
+                                                # window: app draws an installed app's window (its icon and name in the title bar, no address bar) for a PWA or desktop web app; title and icon come from the page's web app manifest unless given
 chapters: false                                 # write <out>.chapters.txt for YouTube
 clips: null                                     # gif | webm | mp4 | png, or a list (docs default: [gif, png]): one file per step in <out>-steps/, cropped to what the step touches, plus README.md, a ready-to-paste article (step captions, `doc:` text, images)
 maxWait: 1.0                                    # with duration: auto, the longest a wait is shown
@@ -299,8 +302,7 @@ end_card:
   logo: { alt: Company logo }                         # captured from the page, or a path to an image
   title: Acme
   subtitle: Ship **faster**
-  cta: Start free at acme.com
-  duration: 1.0
+  cta: Start free at acme.com                         # duration: auto (default) fits the say line, bullets and cta, at least 2.5 s
 ```
 
 Steps that share a caption keep it on screen across both steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyshot",
-  "version": "0.4.0",
+  "version": "0.4.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": {

package/skills/storyshot/SKILL.md

@@ -193,10 +193,12 @@ Rules of thumb from real renders (promos and tutorials):
 
 - **One idea per step.**
   - `pitch`: 1.5–3 s per step (`duration:`), so the viewer gets one beat per
-    shot; the number of shots comes from the story, plus a 1–1.5 s `end_card`. Typical shape: `intro` → hero → 2–4
+    shot; the number of shots comes from the story, plus an `end_card` held long enough to read its call to action (at least 2.5 s; leave its `duration` out). Typical shape: `intro` → hero → 2–4
     steps of the core flow ending on a visible result → pricing or CTA → end
     card. Promos sit in a browser window on a backdrop (`frame: false` turns
-    that off).
+    that off). For an app people install (a PWA, or a desktop app built on
+    web tech), use `frame: { window: app }`: the title bar shows the app's
+    icon and name, not an address bar.
   - Other purposes: leave out `duration`. `auto` times each step to its
     narration and plays motion in real time.
 - **Captions ≤ 7 words.** `**bold**` the payoff ("Every text box is
@@ -257,8 +259,13 @@ the page. Test new targets with `inspect_page` + `after_step`, which is much
 faster than a failed render.
 
 Notes:
-- The end card's duration fits its `say:` line automatically; leave out
-  `duration` there.
+- The end card's duration fits its `say:` line, bullets and `cta`
+  automatically (never under 2.5 s); leave out `duration` there.
+- Compose warns about **dead air**: 3 s or more where nothing moves and
+  nothing is said. Shorten the wait or pause, hide the load in a `hidden`
+  step, or narrate it. Keep `intro` cards to 6–8 s.
+- With `subtitles: burn`, the top caption pills can repeat the subtitles;
+  `captions: false` keeps them off the video (chapters and SRT still use them).
 - `.storyshot/` next to the YAML is a cache of recordings, screenshots and
   voice lines. Add it to `.gitignore`.
 

package/src/audio.mjs

@@ -137,8 +137,14 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
       let dur = pcm.length / 2 / SR;
       const start = Math.max(line.start, prevEnd + 0.12), room = line.until - start - 0.1;
       let sped = 1;
-      if (dur > room && dur / room <= 1.2) { sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR; }
-      else if (dur > room) warn(`${line.where}: narration is ${dur.toFixed(1)}s but only ${Math.max(0, room).toFixed(1)}s until ${line === events.voice.at(-1) ? 'the video ends' : 'the next line'} — shorten "${line.text}" or give the step more duration`);
+      // a line pushed past its window by the one before has no room left (room <= 0): it plays late, at normal speed
+      if (dur > room && room > 0 && dur / room <= 1.2) { sped = dur / room; pcm = tempo(pcm, sped); dur = pcm.length / 2 / SR; }
+      else if (dur > room) warn(room > 0
+        ? `${line.where}: narration is ${dur.toFixed(1)}s but only ${room.toFixed(1)}s until ${line === events.voice.at(-1) ? 'the video ends' : 'the next line'} — shorten "${line.text}" or give the step more duration`
+        : `${line.where}: the narration before it runs ${(start - line.start).toFixed(1)}s past where this line should start, so "${line.text}" plays late — shorten the earlier lines or give their steps more duration`);
+      if (start + dur > events.total) warn(start >= events.total
+        ? `${line.where}: "${line.text}" is cut off: the narration before it pushes it past the end of the video (${events.total.toFixed(1)}s) — shorten the lines or give the steps more duration`
+        : `${line.where}: the last ${(start + dur - events.total).toFixed(1)}s of "${line.text}" is cut off at the end of the video — shorten it or give the steps more duration`);
       log(`  voice ${start.toFixed(2)}–${(start + dur).toFixed(2)}s  ${line.where}${sped > 1 ? `  (sped up x${sped.toFixed(2)})` : ''}  "${line.text}"`);
       let pk = 0;
       for (const v of pcm) pk = Math.max(pk, Math.abs(v));
@@ -183,8 +189,10 @@ export async function soundtrack(cfg, events, silentVideo, { log = console.log }
   const wavFile = path.join(cfg.work, 'soundtrack.wav');
   fs.writeFileSync(wavFile, wav);
 
+  // loudnorm alone lets peaks through after AAC encoding; the limiter keeps true peaks near −2 dB,
+  // 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', '-ar', `${SR}`, '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', cfg.out]);
+    '-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` +
     (cfg.voice ? `, ${events.voice.length} narration lines (${cfg.voice.provider}/${cfg.voice.voice})` : ''));
   return { out: cfg.out, warnings, narration };

package/src/build.mjs

@@ -12,7 +12,7 @@ export async function build(cfg, mode = 'render', { log = console.log } = {}) {
   const voiceLens = await measureVoice(cfg, { log });
   const { silent, clean, events, preview, warnings, captions, cards, segs } = await compose(cfg, { log, voiceLens });
   const audio = await soundtrack(cfg, events, silent, { log });
-  if (cfg.subtitles === 'burn') burnSubtitles(cfg, audio.narration ?? [], { log });
+  if (cfg.subtitles === 'burn') await burnSubtitles(cfg, audio.narration ?? [], { log });
   const extras = await writeOutputs(cfg, { captions, cards, segs, clean, narration: audio.narration, total: events.total }, { log });
   return { out: audio.out, extras, preview, warnings: [...warnings, ...audio.warnings], duration: events.total, seconds: Math.round((Date.now() - t0) / 1000) };
 }

package/src/check.mjs

@@ -5,7 +5,7 @@ import { loadConfig } from './config.mjs';
 import { gitIgnored } from './auth.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', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
+  'scrollOffset', 'captionPosition', 'captions', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
 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'];
@@ -85,7 +85,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.article) unknown(raw.article, ['title', 'intro'], 'article');
-  if (raw.frame && typeof raw.frame === 'object') unknown(raw.frame, ['background', 'style'], 'frame');
+  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)));
   for (const [, n] of todo) errors.push(`line ${n}: replace the TODO placeholder`);
 
@@ -138,6 +138,22 @@ export function check(file, { draft = false } = {}) {
     const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0) + (cfg.intro?.say ? 1 : 0);
     if (cfg.voice && !says) warnings.push('voice is set but no step has a `say:` line');
     if (!cfg.voice && says) warnings.push('steps have `say:` lines but there is no `voice:` block, so they will not be spoken');
+    // fixed-length steps: a line that clearly can't be spoken before the next one starts (a rough
+    // estimate from its length; the render measures the real voice)
+    if (cfg.voice) {
+      const words = (t) => { const x = String(t).replace(/\*\*/g, ''); const c = (x.match(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g) ?? []).length; return { c, w: x.replace(/[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/g, ' ').split(/\s+/).filter(Boolean).length }; };
+      const secs = (t) => { const { c, w } = words(t); return (c / 4.5 + w / 2.8) / (cfg.voice.speed ?? 1); };
+      const vis = visible.map((s) => ({ s, i: cfg.steps.indexOf(s) }));
+      for (const [k, { s, i }] of vis.entries()) {
+        if (!s.say) continue;
+        const nextK = vis.findIndex((v, j) => j > k && v.s.say);
+        const span = vis.slice(k, nextK < 0 ? undefined : nextK).map((v) => v.s.duration);
+        if (!span.every((d) => typeof d === 'number')) continue;
+        const room = span.reduce((a, d) => a + d, 0) - (s.sayAt ?? 0.15) + (nextK < 0 && cfg.endCard ? 2.5 : 0);
+        const need = secs(s.say);
+        if (need > room * 1.4 && need - room > 1) warnings.push(`step ${i + 1}: the say: line takes about ${need.toFixed(1)}s to speak but has ${room.toFixed(1)}s before ${nextK < 0 ? 'the video ends' : 'the next line'} — shorten it or raise duration (the lines after it would play late)`);
+      }
+    }
     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

@@ -22,9 +22,13 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   const readTime = (c) => (c?.bullets?.length ? 1.6 + 0.4 * c.bullets.length + 0.6 * c.bullets.length : 0);
   // `think: N` (question cards): after the question is read out, N seconds with a countdown bar
   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);
-  const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(1.0, (voiceLens.endCard ?? 0) + 0.6, readTime(ec0)) : ec0.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;
+  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;
+  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 }
 
   // --- 1. segments (one per visible step), split into motion / waiting pieces ------------
@@ -150,6 +154,39 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     }
   }
 
+  // --- 2c. dead air: stretches where nothing moves and nobody speaks --------------------------------
+  {
+    const tw = 160, th = 90, rate = 10;
+    const buf = execFileSync('ffmpeg', ['-loglevel', 'error', '-framerate', `${FPS}`, '-i', path.join(SEQ, '%05d.jpg'),
+      '-vf', `fps=${rate},scale=${tw}:${th},format=gray`, '-f', 'rawvideo', 'pipe:1'], { maxBuffer: 1 << 28 });
+    const n = Math.floor(buf.length / (tw * th)), still = [false];
+    for (let f = 1; f < n; f++) {
+      let changed = 0; // pixels that changed visibly: even the cursor moving changes a few
+      for (let k = 0, a = f * tw * th, b = a - tw * th; k < tw * th; k++) if (Math.abs(buf[a + k] - buf[b + k]) > 10) changed++;
+      still.push(changed < 4);
+    }
+    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]]),
+    ];
+    let from = null;
+    const report = (to) => {
+      if (from != null && to - from >= 3) {
+        const ns = segs.filter((x) => x.o1 > from + 1e-6 && x.o0 < to - 1e-6).map((x) => x.i + 1);
+        warn(`${ns.length > 1 ? `steps ${ns[0]}–${ns.at(-1)}` : `step ${ns[0] ?? segs.at(-1).i + 1}`}: ${(to - from).toFixed(1)}s of dead air at ${from.toFixed(1)}–${to.toFixed(1)}s (nothing moves and nothing is said) — shorten the wait or pause, hide the load, or narrate what is happening`);
+      }
+      from = null;
+    };
+    for (let f = 0; f < n; f++) {
+      const t = f / rate;
+      const dead = still[f] && !spoken.some(([a, b]) => t >= a && t <= b);
+      if (dead && from == null) from = t;
+      else if (!dead) report(t);
+    }
+    report(n / rate);
+  }
+
   // --- 3. zoom keyframes: [time, zoom, [cx, cy]] in output px -------------------------------
   const C0 = [W / 2, H / 2];
   const kf = [[0, 1, C0]];
@@ -197,7 +234,9 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     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];
     const [rin, rout] = Array.isArray(z.ramp) ? z.ramp : [z.ramp ?? 0.5, z.ramp ?? 0.5];
-    const s = g.o0 + (z.start ?? 0), e = Math.min(TOTAL, g.o0 + (z.end ?? g.o1 - g.o0)), scale = z.scale ?? 1.3;
+    // a zoom belongs to its step: an `end` past the step (e.g. after the narration grew it) stops there
+    if (z.end != null && g.o0 + z.end > g.o1 + 0.05) warn(`step ${g.i + 1}: zoom end ${z.end}s is past the step's end (${(g.o1 - g.o0).toFixed(1)}s), so it stops there — leave out end to zoom to the step's end`);
+    const s = g.o0 + (z.start ?? 0), e = Math.min(TOTAL, g.o1, g.o0 + (z.end ?? g.o1 - g.o0)), scale = z.scale ?? 1.3;
     const last = kf.at(-1)[0];
     if (s < last) { warn(`zoom in step ${g.i + 1} overlaps the previous zoom, skipped`); continue; }
     kf.push([s, 1, C0], [Math.min(s + rin, e), scale, c], [Math.max(s + rin, e - rout), scale, c], [e, 1, C0]);
@@ -235,6 +274,20 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     return { x: FX + (b.x * K - v.x0) * v.z * F, y: FY + (b.y * K - v.y0) * v.z * F, w: b.width * K * v.z * F, h: b.height * K * v.z * F };
   };
 
+  // what the address bar shows over time: the page's URL when each visible moment was recorded
+  const addressOf = (u) => { try { const x = new URL(u); return x.host.replace(/^www\./, '') + x.pathname.replace(/\/$/, ''); } catch { return String(u); } };
+  const urlAt = (r) => (tl.urls ?? []).filter((x) => x.t <= r).at(-1)?.url ?? cfg.url;
+  const addresses = [];
+  for (const g of cfg.frame?.window === 'browser' ? segs : []) {
+    const r = tl.steps[g.i], changes = (tl.urls ?? []).filter((x) => x.t > r.start && x.t <= r.end);
+    for (const [t, u] of [[g.o0, urlAt(r.start)], ...changes.map((x) => [toOut(x.t) ?? g.o0, x.url])]) {
+      const text = addressOf(u), last = addresses.at(-1);
+      if (last?.text === text) continue;
+      if (last) last.t1 = t;
+      addresses.push({ text, t0: last ? t : 0, t1: TOTAL });
+    }
+  }
+
   // --- 4. captions + end card rendered as PNGs ----------------------------------------------
   const { accent, ink, font } = cfg.theme;
   const fontCss = `font-family:'${font}',-apple-system,'Segoe UI','Helvetica Neue',sans-serif;`;
@@ -247,8 +300,10 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     await pg.screenshot({ path: file, omitBackground: transparent });
   };
   const fs1 = Math.round(H * 0.043), MARGIN = Math.round(H * 0.06);
+  // in a browser-window frame a top caption sits just inside the page, below the address bar
+  const TOP = cfg.frame ? FY + Math.round(H * 0.022) : MARGIN;
   const bubble = (text, n, pos) => `<body style="margin:0;background:transparent">
-      <div style="position:absolute;left:0;right:0;${pos === 'top' ? 'top' : 'bottom'}:${MARGIN}px;display:flex;justify-content:center;padding:0 5%">
+      <div style="position:absolute;left:0;right:0;${pos === 'top' ? `top:${TOP}` : `bottom:${MARGIN}`}px;display:flex;justify-content:center;padding:0 5%">
         <div id="cap" style="${fontCss}font-size:${fs1}px;font-weight:500;letter-spacing:-.01em;color:#fff;background:${ink}e0;text-align:center;
           padding:${Math.round(fs1 * 0.43)}px ${Math.round(fs1 * 0.87)}px;border-radius:${fs1}px;box-shadow:0 12px 40px rgba(0,0,0,.28);border:1px solid rgba(255,255,255,.12)">
           ${cfg.stepNumbers ? `<span style="display:inline-flex;align-items:center;justify-content:center;width:1.45em;height:1.45em;margin:-.2em .55em -.2em -.35em;border-radius:50%;background:${accent};color:${ink};font-weight:700;font-size:.85em;vertical-align:middle">${n}</span>` : ''}${md(text, accent)}</div></div></body>`;
@@ -273,7 +328,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const n = prev && prev.text === g.step.caption && Math.abs(prev.t[1] - g.o0) < 1e-6 ? prev.n : captions.length + 1;
     const explicit = g.step.captionPosition, want = explicit ?? cfg.captionPosition;
     const { w, h } = await sizeOf(g.step.caption, n);
-    const rectOf = (pos) => ({ x: (W - w) / 2, y: pos === 'top' ? MARGIN : H - MARGIN - h, w, h });
+    const rectOf = (pos) => ({ x: (W - w) / 2, y: pos === 'top' ? TOP : H - MARGIN - h, w, h });
     const subjects = [];
     for (const m of tl.steps[g.i].marks ?? []) {
       const t = toOut(m.t);
@@ -297,7 +352,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     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 });
   }
-  for (const [i, c] of captions.entries()) await shot(bubble(c.text, c.n, c.pos), path.join(cfg.work, `cap${i}.png`), true);
+  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
   // CTA types itself out), rendered frame by frame by seeking the page's CSS animations.
   const u = H / 1080;
@@ -313,7 +368,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     const image = c.imageFile && fs.existsSync(c.imageFile)
       ? `<img class="a rise" src="data:image/${path.extname(c.imageFile).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(c.imageFile).toString('base64')}" style="animation-delay:.4s;max-width:${W * 0.6}px;max-height:${H * 0.42}px;border-radius:${12 * H / 1080}px;box-shadow:0 ${12 * H / 1080}px ${36 * H / 1080}px rgba(15,23,42,.18)">` : '';
     const think = c.think ? `<div class="a rise" style="animation-delay:${thinkAt.toFixed(2)}s;position:absolute;left:50%;bottom:${H * 0.1}px;transform:translateX(-50%);width:${W * 0.3}px;text-align:center;font-size:${26 * H / 1080}px;color:${CK.muted}">
-        <div style="margin-bottom:${12 * H / 1080}px">${cfg.lang === 'zh' ? '先想一想' : 'Pause and think'}</div>
+        <div style="margin-bottom:${12 * H / 1080}px">${cfg.labels.think}</div>
         <div style="height:${8 * H / 1080}px;border-radius:99px;background:${CK.track};overflow:hidden"><div style="height:100%;background:${accent};transform-origin:left;animation:drain ${c.think}s linear ${thinkAt.toFixed(2)}s both"></div></div></div>
         <style>@keyframes drain{from{transform:scaleX(1)}to{transform:scaleX(0)}}</style>` : '';
     const logo = fs.existsSync(logoPath)
@@ -379,7 +434,16 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       blur: { dark: true, bg: null },
     };
     const st = STYLES[cfg.frame.style], bg = cfg.frame.background ?? st.bg;
-    const R = Math.round(14 * u), host = new URL(cfg.url).host.replace(/^www\./, '') + new URL(cfg.url).pathname.replace(/\/$/, '');
+    // an app window: the app's icon and name in the title bar instead of an address bar
+    let app = null;
+    if (cfg.frame.window === 'app') {
+      const MIME = { svg: 'image/svg+xml', ico: 'image/x-icon', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', png: 'image/png' };
+      const [file, type] = cfg.frame.iconFile ? [cfg.frame.iconFile, MIME[path.extname(cfg.frame.iconFile).slice(1).toLowerCase()] ?? 'image/png']
+        : tl.app?.icon ? [path.join(cfg.work, tl.app.icon.file), tl.app.icon.type] : [];
+      const icon = file && fs.existsSync(file) ? `data:${type};base64,${fs.readFileSync(file).toString('base64')}` : null;
+      app = { icon, title: cfg.frame.title ?? tl.app?.title ?? (() => { try { return new URL(cfg.url).host.replace(/^www\./, ''); } catch { return ''; } })() };
+    }
+    const R = Math.round(14 * u);
     const dot = (col) => `<span style="width:${13 * u}px;height:${13 * u}px;border-radius:50%;background:${col};display:inline-block"></span>`;
     const [barBg, barFg, pill, line] = st.dark ? ['#1f2430', '#9aa4b2', '#2b3140', '#11151d'] : ['#e8ebef', '#4b5563', '#fff', '#d5d9df'];
     if (bg) await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:${bg}"></body>`, path.join(cfg.work, 'frame-bg.png'), false);
@@ -387,8 +451,16 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${FH + BAR}px;border-radius:${R}px;background:#fff;box-shadow:0 ${30 * u}px ${80 * u}px rgba(0,0,0,${st.dark ? '.5' : '.25'}),0 0 0 1px rgba(255,255,255,.08)"></div>
       <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${BAR}px;border-radius:${R}px ${R}px 0 0;background:${barBg};display:flex;align-items:center;border-bottom:1px solid ${line}">
         <div style="display:flex;gap:${8 * u}px;margin-left:${16 * u}px">${dot('#ff5f57')}${dot('#febc2e')}${dot('#28c840')}</div>
-        <div style="position:absolute;left:50%;transform:translateX(-50%);font-size:${15 * u}px;color:${barFg};background:${pill};border-radius:${8 * u}px;padding:${4 * u}px ${60 * u}px">${esc(host)}</div>
+        ${app ? `<div style="position:absolute;left:0;right:0;top:0;bottom:0;display:flex;align-items:center;justify-content:center;gap:${8 * u}px;font-size:${15 * u}px;font-weight:600;color:${barFg}">
+          ${app.icon ? `<img src="${app.icon}" style="width:${18 * u}px;height:${18 * u}px;object-fit:contain;border-radius:${4 * u}px">` : ''}<span style="max-width:${FW * 0.5}px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis">${esc(app.title)}</span></div>` : ''}
       </div></body>`, path.join(cfg.work, 'frame-chrome.png'), true);
+    // the address bar follows the page: one pill per address it shows
+    for (const [k, a] of addresses.entries()) {
+      await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:transparent;${fontCss}">
+        <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${BAR}px;display:flex;align-items:center;justify-content:center">
+        <div style="font-size:${15 * u}px;color:${barFg};background:${pill};border-radius:${8 * u}px;padding:${4 * u}px ${60 * u}px;max-width:${FW * 0.5}px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis">${esc(a.text)}</div>
+      </div></body>`, path.join(cfg.work, `frame-url${k}.png`), true);
+    }
     // alpha mask for the page: rounded bottom corners (the title bar covers the top ones)
     await pg.setViewportSize({ width: FW, height: FH });
     await pg.setContent(`<body style="margin:0;width:${FW}px;height:${FH}px;background:#000"><div style="width:100%;height:100%;background:#fff;border-radius:0 0 ${R}px ${R}px"></div></body>`);
@@ -416,12 +488,17 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
     graph += `[${blur ? 'v0a' : 'v0'}]scale=${FW}:${FH}:flags=lanczos,format=rgba[pg0];[${mask}:v]format=gray,scale=${FW}:${FH}[pm];[pg0][pm]alphamerge[pg];\n` +
       `[${base}][${chrome}:v]overlay=0:0[fc];[fc][pg]overlay=${FX}:${FY},format=yuv420p[vf];\n`;
     last = 'vf';
+    for (const [k, a] of addresses.entries()) {
+      inputs.push('-loop', '1', '-t', `${(a.t1 - a.t0 + 0.1).toFixed(3)}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, `frame-url${k}.png`));
+      graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${a.t0.toFixed(3)}/TB[u${k}];[${last}][u${k}]overlay=0:0:eof_action=pass:enable='between(t,${a.t0.toFixed(3)},${a.t1.toFixed(3)})'[vu${k}];\n`;
+      last = `vu${k}`; idx++;
+    }
   }
   // docs: a second, caption-free copy for the per-step clips and stills (the article carries the
   // text), so crops never have to dodge a caption
   const clean = cfg.clips.length ? path.join(cfg.work, 'video-clean.mp4') : null;
   if (clean) { graph += `[${last}]split[vmain][vclean0];\n`; last = 'vmain'; }
-  for (const [i, c] of captions.entries()) {
+  for (const [i, c] of (cfg.captions ? captions : []).entries()) {
     const a = c.t[0] + 0.1, b = c.t[1] - 0.1;
     // each caption is an input only as long as it is on screen (decoding a looped PNG for the whole
     // video, once per caption, made long tutorials take minutes to compose)
@@ -432,7 +509,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   }
   for (const [k, c] of cards.entries()) {
     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.25:alpha=1,fade=out:st=${Math.max(c.t0, c.t1 - 0.3).toFixed(3)}:d=0.3:alpha=1[sc${k}];\n` +
+    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`;
     last = `v${idx}`;
   }
@@ -445,7 +522,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
   }
   if (in0) {
     inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, 'intro', '%04d.jpg'));
-    graph += `[${idx}:v]format=rgba,fade=out:st=${Math.max(0, INTRO - 0.35).toFixed(3)}:d=0.35:alpha=1[in];\n` +
+    graph += `[${idx}:v]format=rgba,fade=out:st=${Math.max(0, INTRO - 0.2).toFixed(3)}:d=0.2:alpha=1[in];\n` +
       `[${last}][in]overlay=0:0:eof_action=pass[v${++idx}];\n`;
     last = `v${idx}`;
   }
@@ -497,8 +574,8 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
       ...(tl.gotos ?? tl.navs.filter((n) => !tl.clicks.some((c) => n - c >= 0 && n - c < 2) && !tl.steps.some((s) => (s.waits ?? []).some(([a, b]) => n >= a - 0.5 && n <= b + 0.5))))
         .map(toOut).filter((t) => t != null && t > 0.2),
       ...segs.filter((g) => g.afterHidden).map((g) => g.o0),
-      ...(in0 ? [INTRO - 0.3] : []),
-      ...cards.flatMap((c) => [c.t0, c.t1 - 0.3]),
+      ...(in0 ? [INTRO - 0.2] : []),
+      ...cards.flatMap((c) => [c.t0, c.t1 - 0.15]),
       ...(ec ? [VIDEO - 0.25] : []),
     ]),
     risers: segs.filter((g) => g.step.sfx === 'riser').map((g) => [g.o0, g.o1]),

package/src/config.mjs

@@ -4,6 +4,17 @@ import path from 'node:path';
 import YAML from 'yaml';
 import { VOICE_DEFAULTS } from './voice.mjs';
 
+// Built-in labels drawn into the video, by `lang` (e.g. es, es-MX); other languages get English
+export const LABELS = {
+  en: { think: 'Pause and think', intro: 'Introduction', downloaded: 'Downloaded' },
+  zh: { think: '先想一想', intro: '开场', downloaded: '已下载' },
+  es: { think: 'Piénsalo un momento', intro: 'Introducción', downloaded: 'Descargado' },
+  pt: { think: 'Pense um pouco', intro: 'Introdução', downloaded: 'Baixado' },
+  fr: { think: 'Réfléchissez', intro: 'Introduction', downloaded: 'Téléchargé' },
+  de: { think: 'Kurz nachdenken', intro: 'Einführung', downloaded: 'Heruntergeladen' },
+  ja: { think: '考えてみよう', intro: 'はじめに', downloaded: 'ダウンロード済み' },
+};
+
 // Load API keys (ELEVENLABS_API_KEY, OPENAI_API_KEY) from .env next to the storyboard
 // and in the working directory; variables already set in the environment win.
 export function loadEnv(dir) {
@@ -99,7 +110,8 @@ export function loadConfig(file, { draft = false } = {}) {
   });
 
   let endCard = raw.end_card === false ? null : raw.end_card ?? null;
-  if (endCard) endCard = { duration: endCard.say ? 'auto' : 1.0, ...endCard };
+  // auto: as long as its narration, bullets and call to action need, and never under 2.5s
+  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 };
@@ -112,11 +124,15 @@ export function loadConfig(file, { draft = false } = {}) {
   // follow: the camera zooms in on what each step touches and pans from step to step (tutorials)
   const follow0 = pick('follow');
   const follow = follow0 ? { scale: 1.8, ...(typeof follow0 === 'object' ? follow0 : {}) } : null;
-  // frame: false | true | a style name | { style, background: <css> }. Styles: aurora (dark, grain),
-  // studio (light, grain), dark, pastel, blur (the page itself, blurred, behind the window)
+  // frame: false | true | a style name | { style, background: <css>, window, title, icon }. Styles: aurora
+  // (dark, grain), studio (light, grain), dark, pastel, blur (the page itself, blurred, behind the window).
+  // window: browser (an address bar) or app (an installed web app / desktop app: its icon and name in the
+  // title bar, no address bar; both are read from the page's web app manifest unless given)
   const styleOf = (f) => (typeof f === 'string' ? f : f?.style) ?? (typeof P.frame === 'string' ? P.frame : 'aurora');
-  const frame = frame0 ? { background: null, ...(typeof frame0 === 'object' ? frame0 : {}), style: styleOf(frame0) } : null;
+  const frame = frame0 ? { background: null, window: 'browser', ...(typeof frame0 === 'object' ? frame0 : {}), style: styleOf(frame0) } : null;
   if (frame && !FRAME_STYLES.includes(frame.style)) throw new Error(`frame style must be one of ${FRAME_STYLES.join(', ')}`);
+  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);
 
   let voice = null;
   if (raw.voice) {
@@ -162,9 +178,13 @@ export function loadConfig(file, { draft = false } = {}) {
     endCard,
     intro,
     article: raw.article ?? null,
+    // captions: false keeps the caption pills off the video (chapters and SRT still use them),
+    // e.g. when burned-in subtitles already carry the words
+    captions: raw.captions !== false,
     cards: raw.cards ?? 'auto',
     // language of the built-in labels ("Pause and think", "Introduction"): `lang`, else guessed from the captions
     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,
     follow,
     music,

package/src/doctor.mjs

@@ -5,6 +5,7 @@ import { chromium } from 'playwright';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { hasFilter, hasEncoder, NEEDED, OPTIONAL } from './ffmpeg.mjs';
 
 const has = (cmd, args = ['--version']) => { try { execFileSync(cmd, args, { stdio: 'ignore' }); return true; } catch { return false; } };
 
@@ -47,7 +48,15 @@ export async function doctor({ log = console.log } = {}) {
 
   try {
     const v = execFileSync('ffmpeg', ['-version']).toString().match(/ffmpeg version (\S+)/)?.[1];
-    lines.push(`✔ ffmpeg ${v ?? ''}`.trim());
+    // a build can lack pieces Storyshot uses: say which, and what that affects
+    const missing = [...NEEDED.filters.filter((f) => !hasFilter(f)), ...NEEDED.encoders.filter((e) => !hasEncoder(e))];
+    if (missing.length) {
+      lines.push(`✖ ffmpeg ${v ?? ''} is missing ${missing.join(', ')}`);
+      todo.push(`install an ffmpeg build with ${missing.join(', ')} (${process.platform === 'darwin' ? 'e.g. brew install ffmpeg-full, then put "$(brew --prefix ffmpeg-full)/bin" first on your PATH, as it is keg-only; or a static build from https://ffmpeg.org/download.html' : 'e.g. a static build from https://ffmpeg.org/download.html'})`);
+    } else lines.push(`✔ ffmpeg ${v ?? ''}`.trim());
+    for (const o of OPTIONAL) {
+      if (o.filter ? !hasFilter(o.filter) : !hasEncoder(o.encoder)) lines.push(`· ffmpeg has no ${o.filter ? `${o.filter} filter` : `${o.encoder} encoder`} — ${o.for}`);
+    }
   } catch {
     lines.push('✖ ffmpeg not found');
     todo.push(ffmpegInstallCommand());

package/src/ffmpeg.mjs

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

package/src/inspect.mjs

@@ -67,10 +67,12 @@ function collect() {
     clean(el.closest('label')?.innerText) || '';
   // a label's own text, without the links/buttons inside it (e.g. a "Clear" link)
   const labelText = (lab) => { if (!lab) return null; const c = lab.cloneNode(true); c.querySelectorAll('a,button,select,input,textarea').forEach((x) => x.remove()); return clean(c.innerText) || null; };
+  // styled checkboxes and radios hide the real input and draw their label instead: list them where the label is
+  const shownBy = (el) => (el.tagName === 'INPUT' && ['checkbox', 'radio'].includes(el.type) && !vis(el) ? [...(el.labels ?? [])].find(vis) : null);
   const interactive = [...document.querySelectorAll(NATIVE)]
-    .filter((el) => vis(el) && el.tagName !== 'LABEL' && !isAd(el) && !(el.isContentEditable && el.parentElement?.isContentEditable))
+    .filter((el) => (vis(el) || shownBy(el)) && el.tagName !== 'LABEL' && !isAd(el) && !(el.isContentEditable && el.parentElement?.isContentEditable))
     .map((el) => ({ kind: 'role', role: roleOf(el), name: (el.isContentEditable || el.tagName === 'TEXTAREA' ? editorName(el) : nameOf(el)).slice(0, 80), shows: clean(el.innerText).slice(0, 60), alt: clean(el.querySelector('img[alt]')?.alt) || null, href: el.getAttribute('href'), label: labelText(el.labels?.[0]),
-      options: el.tagName === 'SELECT' ? [...el.options].map((o) => ({ text: clean(o.text), on: o.selected })).filter((o) => o.text).slice(0, 12) : null, ...pos(el) }));
+      options: el.tagName === 'SELECT' ? [...el.options].map((o) => ({ text: clean(o.text), on: o.selected })).filter((o) => o.text).slice(0, 12) : null, ...pos(shownBy(el) ?? el) }));
   // custom clickables: outermost cursor:pointer elements that aren't native controls
   const pointer = [];
   for (const el of document.querySelectorAll('body *')) {

package/src/outputs.mjs

@@ -2,6 +2,8 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { chromium } from 'playwright';
+import { hasFilter } from './ffmpeg.mjs';
 
 const plain = (s) => String(s).replace(/\*\*/g, '');
 const srtTime = (t) => {
@@ -27,7 +29,7 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, clean, nar
   if (cfg.chapters && (captions.length || cards.length)) {
     // section cards make the chapters when there are any; otherwise one chapter per caption
     const lines = cards.length
-      ? [...(cards[0].t > 1 ? [`0:00 ${cfg.lang === 'zh' ? '开场' : 'Introduction'}`] : []), ...cards.map((c, k) => `${clock(k === 0 && cards[0].t <= 1 ? 0 : c.t)} ${plain(c.title)}`)]
+      ? [...(cards[0].t > 1 ? [`0:00 ${cfg.labels.intro}`] : []), ...cards.map((c, k) => `${clock(k === 0 && cards[0].t <= 1 ? 0 : c.t)} ${plain(c.title)}`)]
       : captions.map((c, k) => `${clock(k === 0 ? 0 : c.t[0])} ${cfg.stepNumbers ? `${c.n}. ` : ''}${plain(c.text)}`);
     fs.writeFileSync(`${base}.chapters.txt`, `${lines.join('\n')}\n`);
     files.push(`${base}.chapters.txt`);
@@ -80,15 +82,22 @@ export async function writeOutputs(cfg, { captions, cards = [], segs, clean, nar
 
 // `subtitles: burn`: the narration burned into the video, a few words at a time, each word lighting
 // up as it is spoken (karaoke). Word timing is estimated from word length within each spoken line.
-export function burnSubtitles(cfg, narration, { log = console.log } = {}) {
+export async function burnSubtitles(cfg, narration, { log = console.log, renderer = hasFilter('ass') ? 'ass' : 'png' } = {}) {
   if (!narration.length) return log('note: subtitles: burn needs narration (say: lines and a voice); nothing burned in');
   const { width: W, height: H } = cfg.output;
   const bgr = (hex, a = '00') => { const h = hex.replace('#', ''); return `&H${a}${h.slice(4, 6)}${h.slice(2, 4)}${h.slice(0, 2)}`.toUpperCase(); };
   const t = (s) => { const cs = Math.round(s * 100); return `${Math.floor(cs / 360000)}:${String(Math.floor(cs / 6000) % 60).padStart(2, '0')}:${String(Math.floor(cs / 100) % 60).padStart(2, '0')}.${String(cs % 100).padStart(2, '0')}`; };
-  const size = Math.round(H * 0.048), edge = Math.max(2, Math.round(size * 0.09));
-  const events = [];
+  // Chinese, Japanese, Korean: no spaces between words, so lines are cut by characters (one line of
+  // at most ~18), in a lighter weight and a font that has the glyphs
+  const cjk = cfg.lang === 'zh' || narration.some((l) => /[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af]/.test(l.text));
+  const size = Math.round(H * (cjk ? 0.042 : 0.048)), edge = Math.max(2, Math.round(size * (cjk ? 0.07 : 0.09)));
+  const fontName = cjk && cfg.theme.font === 'Inter' ? (process.platform === 'darwin' ? 'PingFang SC' : 'Noto Sans CJK SC') : cfg.theme.font;
+  const cues = []; // { words: [{ w, start, d }] }: one on-screen line each
   for (const line of narration) {
-    const words = plain(line.text).split(/\s+/).filter(Boolean);
+    // CJK: one token per character (Latin words inside stay whole), punctuation stays with the one before
+    const words = cjk
+      ? (plain(line.text).match(/[A-Za-z0-9.%+-]+[，。！？；：、,.!?;:）)」』]*|\S[，。！？；：、,.!?;:）)」』]*/g) ?? [])
+      : plain(line.text).split(/\s+/).filter(Boolean);
     const weight = (w) => w.replace(/[^\p{L}\p{N}]/gu, '').length + 2;
     const total = words.reduce((a, w) => a + weight(w), 0), span = line.end - line.start;
     let at = line.start;
@@ -97,13 +106,76 @@ export function burnSubtitles(cfg, narration, { log = console.log } = {}) {
     let chunk = [];
     const flush = () => {
       if (!chunk.length) return;
-      const s0 = chunk[0].start, e0 = chunk.at(-1).start + chunk.at(-1).d;
-      events.push(`Dialogue: 0,${t(s0)},${t(e0 + 0.05)},Sub,,0,0,0,,${chunk.map((x) => `{\\kf${Math.round(x.d * 100)}}${x.w.replace(/[{}]/g, '')}`).join(' ')}`);
+      cues.push({ words: chunk });
       chunk = [];
     };
-    for (const x of timed) { chunk.push(x); if (chunk.length >= 7 || /[.!?;:]$/.test(x.w)) flush(); }
+    const len = () => chunk.reduce((a, x) => a + x.w.length, 0);
+    for (const x of timed) {
+      // a CJK line ends at a sentence break, or at a comma once it is half full, or at 18 characters
+      if (cjk && chunk.length && len() + x.w.length > 18) flush();
+      chunk.push(x);
+      if (cjk ? /[。！？；!?;]$/.test(x.w) || (/[，、：,:]$/.test(x.w) && len() >= 9) : chunk.length >= 7 || /[.!?;:]$/.test(x.w)) flush();
+    }
     flush();
   }
+  const tmp = cfg.out.replace(/(\.[^.]+)$/, '.burn$1');
+  const encode = ['-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-pix_fmt', 'yuv420p', '-c:a', 'copy', '-movflags', '+faststart', tmp];
+  const edgeCol = cfg.theme.ink, sweep = cfg.theme.accent;
+  if (renderer === 'png') {
+    // no libass in this ffmpeg: draw each state of each line (the words spoken so far in the accent
+    // colour) in Chromium, string them into one transparent track and overlay it
+    const dir = path.join(cfg.work, 'subs');
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    const esc = (x) => x.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const font = `'${fontName}',${cjk ? "'PingFang SC','Hiragino Sans GB','Noto Sans CJK SC','Microsoft YaHei'," : ''}-apple-system,'Segoe UI','Helvetica Neue',sans-serif`;
+    const head = cjk ? '' : `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=${encodeURIComponent(fontName)}:wght@400;700&display=block">`;
+    const browser = await chromium.launch();
+    const pg = await browser.newPage({ viewport: { width: W, height: H } });
+    const shot = async (html, file) => {
+      await pg.setContent(`<html><head>${head}</head><body style="margin:0;background:transparent">${html}</body></html>`, { waitUntil: 'networkidle' }).catch(() => {});
+      await pg.evaluate(() => document.fonts.ready);
+      await pg.screenshot({ path: file, omitBackground: true });
+    };
+    const list = ['ffconcat version 1.0'];
+    let at = 0, n = 0;
+    const push = (file, until) => { if (until - at > 0.001) { list.push(`file '${file}'`, `duration ${(until - at).toFixed(3)}`); at = until; } };
+    await shot('', path.join(dir, 'blank.png'));
+    // libass sizes a font by its line height (ascent + descent), CSS by its em: match libass
+    await pg.setContent(`<html><head>${head}</head><body></body></html>`, { waitUntil: 'networkidle' }).catch(() => {});
+    const em = await pg.evaluate(async (font) => {
+      await document.fonts.load(`100px ${font}`);
+      const m = document.createElement('canvas').getContext('2d');
+      m.font = `100px ${font}`;
+      const r = m.measureText('Hg中');
+      return 100 / ((r.fontBoundingBoxAscent + r.fontBoundingBoxDescent) || 100);
+    }, font);
+    const px = Math.round(size * em);
+    for (const cue of cues) {
+      const end = cue.words.at(-1).start + cue.words.at(-1).d + 0.05;
+      if (cue.words[0].start > at) push('blank.png', cue.words[0].start);
+      for (const [j, x] of cue.words.entries()) {
+        const file = `s${String(n++).padStart(5, '0')}.png`;
+        const text = cue.words.map((y, k) => `<span style="color:${k <= j ? sweep : '#fff'}">${esc(y.w)}</span>`).join(cjk ? '' : ' ');
+        await shot(`<div style="position:absolute;left:${Math.round(W * 0.08)}px;right:${Math.round(W * 0.08)}px;bottom:${Math.round(H * 0.06)}px;text-align:center;
+          font-family:${font};font-size:${px}px;font-weight:${cjk ? 400 : 700};line-height:1.2;
+          -webkit-text-stroke:${edge * 2}px ${edgeCol};paint-order:stroke fill;text-shadow:${Math.round(edge * 0.8)}px ${Math.round(edge * 0.8)}px 0 rgba(0,0,0,.5)">${text}</div>`, path.join(dir, file));
+        push(file, j + 1 < cue.words.length ? cue.words[j + 1].start : end);
+      }
+    }
+    await browser.close();
+    push('blank.png', at + 1);
+    list.push("file 'blank.png'"); // the last entry's duration only counts when a file follows it
+    fs.writeFileSync(path.join(dir, 'list.txt'), list.join('\n') + '\n');
+    execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', cfg.out, '-f', 'concat', '-safe', '0', '-i', path.join(dir, 'list.txt'),
+      '-filter_complex', '[1:v]format=rgba[s];[0:v][s]overlay=0:0:eof_action=pass,format=yuv420p[v]', '-map', '[v]', '-map', '0:a?', ...encode]);
+    fs.renameSync(tmp, cfg.out);
+    return log(`subtitles: burned in ${cues.length} lines with word-by-word highlight (drawn by Storyshot: this ffmpeg has no libass)`);
+  }
+  const events = cues.map(({ words }) => {
+    const s0 = words[0].start, e0 = words.at(-1).start + words.at(-1).d;
+    return `Dialogue: 0,${t(s0)},${t(e0 + 0.05)},Sub,,0,0,0,,${words.map((x) => `{\\kf${Math.round(x.d * 100)}}${x.w.replace(/[{}]/g, '')}`).join(cjk ? '' : ' ')}`;
+  });
   const ass = `[Script Info]
 ScriptType: v4.00+
 PlayResX: ${W}
@@ -112,17 +184,17 @@ WrapStyle: 0
 
 [V4+ Styles]
 Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Sub,${cfg.theme.font},${size},${bgr(cfg.theme.accent)},&H00FFFFFF,${bgr(cfg.theme.ink)},&H80000000,1,0,0,0,100,100,0,0,1,${edge},${Math.round(edge * 0.8)},2,${Math.round(W * 0.08)},${Math.round(W * 0.08)},${Math.round(H * 0.06)},1
+Style: Sub,${fontName},${size},${bgr(sweep)},&H00FFFFFF,${bgr(edgeCol)},&H80000000,${cjk ? 0 : 1},0,0,0,100,100,0,0,1,${edge},${Math.round(edge * 0.8)},2,${Math.round(W * 0.08)},${Math.round(W * 0.08)},${Math.round(H * 0.06)},1
 
 [Events]
 Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
 ${events.join('\n')}
 `;
-  const file = path.join(cfg.work, 'subtitles.ass'), tmp = cfg.out.replace(/(\.[^.]+)$/, '.burn$1');
+  const file = path.join(cfg.work, 'subtitles.ass');
   fs.writeFileSync(file, ass);
   // the filter argument is parsed by ffmpeg: escape the characters it treats specially in paths
   const arg = file.replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, "\\'");
-  execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', cfg.out, '-vf', `ass='${arg}'`, '-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-pix_fmt', 'yuv420p', '-c:a', 'copy', '-movflags', '+faststart', tmp]);
+  execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', cfg.out, '-vf', `ass='${arg}'`, ...encode]);
   fs.renameSync(tmp, cfg.out);
   log(`subtitles: burned in ${events.length} lines with word-by-word highlight`);
 }

package/src/record.mjs

@@ -260,13 +260,13 @@ function pageScript({ scrollOffset }) {
   window.__demoMenuHover = (i) => { const m = document.getElementById('__demo_menu'); if (m) [...m.children].forEach((o, k) => { o.style.background = k === i ? '#e0ecff' : ''; }); };
   window.__demoMenuClose = () => document.getElementById('__demo_menu')?.remove();
   // downloads leave no trace in a recording: show a browser-style "downloaded" bubble instead
-  window.__demoDownload = (name) => {
+  window.__demoDownload = (name, label = 'Downloaded') => {
     const el = document.createElement('div');
-    el.innerHTML = `<span style="display:inline-grid;place-items:center;width:30px;height:30px;border-radius:50%;background:#22c55e;color:#fff;font-weight:700">✓</span><span><b style="display:block;font-weight:600">${name.replace(/[<&]/g, '')}</b><span style="color:#64748b;font-size:14px">Downloaded</span></span>`;
+    el.innerHTML = `<span style="display:inline-grid;place-items:center;width:30px;height:30px;border-radius:50%;background:#22c55e;color:#fff;font-weight:700">✓</span><span><b style="display:block;font-weight:600">${name.replace(/[<&]/g, '')}</b><span style="color:#64748b;font-size:14px">${label}</span></span>`;
     Object.assign(el.style, { position: 'fixed', right: '24px', top: '20px', zIndex: '2147483646', pointerEvents: 'none', display: 'flex', alignItems: 'center', gap: '12px',
       background: '#fff', color: '#0f172a', font: '16px -apple-system, "Segoe UI", sans-serif', padding: '12px 18px 12px 14px', borderRadius: '12px', boxShadow: '0 12px 32px rgba(15,23,42,.25)', border: '1px solid #e2e8f0' });
     document.documentElement.appendChild(el);
-    el.animate([{ opacity: 0, transform: 'translateY(-8px)' }, { opacity: 1, transform: 'none', offset: 0.1 }, { opacity: 1, offset: 0.85 }, { opacity: 0 }], { duration: 2800, easing: 'ease-out' }).onfinish = () => el.remove();
+    el.animate([{ opacity: 0, transform: 'translateY(-8px)' }, { opacity: 1, transform: 'none', offset: 0.1 }, { opacity: 1, offset: 0.9 }, { opacity: 0 }], { duration: 4500, easing: 'ease-out' }).onfinish = () => el.remove();
   };
   window.__demoUnnote = (instant) => {
     // detach it first, so a note or mark added during the fade gets a fresh layer instead of vanishing with this one
@@ -343,7 +343,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   await context.addInitScript(pageScript, { scrollOffset: cfg.scrollOffset });
   const page = await context.newPage();
   page.on('download', (d) => {
-    page.evaluate((n) => window.__demoDownload?.(n), d.suggestedFilename()).catch(() => {});
+    page.evaluate(([n, l]) => window.__demoDownload?.(n, l), [d.suggestedFilename(), cfg.labels.downloaded]).catch(() => {});
     marks.push({ t: Date.now() / 1000, box: { x: cfg.viewport.width - 360, y: 10, width: 340, height: 80 } }); // so docs crops include the bubble
   });
   const sleep = (ms) => page.waitForTimeout(ms);
@@ -551,13 +551,18 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
           await press();
         }
         const text = String(v.text);
-        const before = await page.evaluate(() => (document.activeElement?.value ?? document.activeElement?.textContent ?? '').length).catch(() => 0);
-        const copied = await page.evaluate((t) => navigator.clipboard.writeText(t).then(() => true, () => false), text).catch(() => false);
+        // the paste worked if the page received a paste event carrying the text (code editors keep their
+        // text outside the focused element, so comparing its value would miss it and paste twice)
+        const copied = await page.evaluate((t) => navigator.clipboard.writeText(t).then(() => {
+          window.__demoPasted = false;
+          document.addEventListener('paste', (e) => { window.__demoPasted = !!e.clipboardData?.getData('text'); }, { capture: true, once: true });
+          return true;
+        }, () => false), text).catch(() => false);
         if (!fast) await page.evaluate((l) => window.__demoKeys(l), process.platform === 'darwin' ? '⌘ V' : 'Ctrl V').catch(() => {});
         if (copied) await page.keyboard.press('ControlOrMeta+V');
         await sleep(200);
-        const after = await page.evaluate(() => (document.activeElement?.value ?? document.activeElement?.textContent ?? '').length).catch(() => 0);
-        if (!copied || after === before) await page.keyboard.insertText(text); // no clipboard access: insert it in one go
+        const pasted = copied && await page.evaluate(() => window.__demoPasted === true).catch(() => false);
+        if (!pasted) await page.keyboard.insertText(text); // no clipboard access: insert it in one go
         if (lit) await spotOff();
         await settle();
         await beat();
@@ -572,8 +577,16 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
         const from = await locate(page, value.target).evaluate((el) => {
           const r = el.type === 'range' ? el : el.querySelector?.('input[type=range]');
           if (r) return (Number(r.value) - Number(r.min || 0)) / ((Number(r.max || 100) - Number(r.min || 0)) || 1);
-          const now = Number(el.getAttribute('aria-valuenow')), lo = Number(el.getAttribute('aria-valuemin') ?? 0), hi = Number(el.getAttribute('aria-valuemax') ?? 100);
-          return Number.isFinite(now) ? (now - lo) / ((hi - lo) || 1) : 0.5;
+          const aria = el.hasAttribute('aria-valuenow') ? el : el.querySelector?.('[aria-valuenow]');
+          if (aria) {
+            const now = Number(aria.getAttribute('aria-valuenow')), lo = Number(aria.getAttribute('aria-valuemin') ?? 0), hi = Number(aria.getAttribute('aria-valuemax') ?? 100);
+            if (Number.isFinite(now)) return (now - lo) / ((hi - lo) || 1);
+          }
+          // custom sliders (e.g. Desmos): start where the knob is drawn, so the value doesn't jump first
+          const t = el.getBoundingClientRect();
+          const knob = [...el.querySelectorAll('[role=slider], [class*=thumb], [class*=handle], [class*=knob]')]
+            .map((k) => k.getBoundingClientRect()).find((k) => k.width > 0 && k.width < t.width * 0.5);
+          return knob ? (knob.x + knob.width / 2 - t.x) / (t.width || 1) : 0.5;
         }).catch(() => 0.5);
         const x0 = b.x + b.width * from, x1 = b.x + b.width * Math.max(0, Math.min(1, value.to)), y = b.y + b.height / 2;
         await moveTo(x0, y, value.ms ?? cfg.pace.cursor);
@@ -706,6 +719,36 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     await locate(page, card.logo).screenshot({ path: path.join(cfg.work, file), omitBackground: true, timeout: 5000 })
       .catch((e) => log(`warning: could not capture logo (${e.message.split('\n')[0]})`));
   }
+  // an app window shows the app's icon and name: from the web app manifest, else the page's own
+  let app = null;
+  if (cfg.frame?.window === 'app' && !fast) {
+    const found = await page.evaluate(async () => {
+      const abs = (u, base) => { try { return new URL(u, base).href; } catch { return null; } };
+      const size = (s) => Math.max(0, ...String(s ?? '').split(/\s+/).map((x) => (x === 'any' ? 1e4 : parseInt(x, 10) || 0)));
+      let name = null, icon = null;
+      const link = document.querySelector('link[rel="manifest"]');
+      if (link) {
+        try {
+          const m = await (await fetch(link.href)).json();
+          name = m.short_name ?? m.name ?? null;
+          const best = (m.icons ?? []).filter((i) => !/monochrome/.test(i.purpose ?? '')).sort((a, b) => size(b.sizes) - size(a.sizes))[0];
+          if (best) icon = abs(best.src, link.href);
+        } catch {}
+      }
+      const links = [...document.querySelectorAll('link[rel~="icon"], link[rel="apple-touch-icon"]')].sort((a, b) => size(b.sizes) - size(a.sizes));
+      icon ??= links[0]?.href ?? abs('/favicon.ico', location.href);
+      return { name: name ?? (document.querySelector('meta[name="application-name"]')?.content || document.title || null), icon };
+    }).catch(() => ({}));
+    app = { title: found.name ?? null, icon: null };
+    if (!cfg.frame.iconFile && found.icon) {
+      const r = await page.request.get(found.icon).catch(() => null);
+      if (r?.ok()) {
+        const type = (r.headers()['content-type'] ?? 'image/png').split(';')[0];
+        fs.writeFileSync(path.join(cfg.work, 'app-icon'), await r.body());
+        app.icon = { file: 'app-icon', type };
+      } else log(`warning: could not fetch the app icon (${found.icon})`);
+    }
+  }
   await nudge();
   await sleep(600);
 
@@ -734,8 +777,12 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
     frames.push({ file, t: metadata.timestamp });
     cdp.send('Page.screencastFrameAck', { sessionId }).catch(() => {});
   });
-  const navs = [];
-  page.on('framenavigated', (f) => { if (f === page.mainFrame()) navs.push(now()); });
+  const navs = [], urls = [{ t: now(), url: page.url() }]; // urls: what the frame's address bar shows
+  page.on('framenavigated', (f) => {
+    if (f !== page.mainFrame()) return;
+    navs.push(now());
+    if (f.url() !== urls.at(-1).url) urls.push({ t: now(), url: f.url() });
+  });
   await cdp.send('Page.startScreencast', {
     format: 'jpeg', quality: 92, maxWidth: cfg.output.width, maxHeight: cfg.output.height, everyNthFrame: 1,
   });
@@ -777,7 +824,7 @@ export async function record(cfg, { log = console.log, inspectAfter = null } = {
   await cdp.send('Page.stopScreencast');
   await browser.close();
 
-  const timeline = { frames, steps, clicks, navs, gotos, scale: cfg.scale };
+  const timeline = { frames, steps, clicks, navs, gotos, urls, app, scale: cfg.scale };
   fs.writeFileSync(path.join(cfg.work, 'timeline.json'), JSON.stringify(timeline, null, 1));
   log(`recorded ${frames.length} frames`);
   return timeline;

package/src/voice.mjs

@@ -94,6 +94,7 @@ export async function speak(cfg, line, { log = console.log } = {}) {
 
 // Speed a clip up (factor > 1) with ffmpeg's pitch-preserving atempo.
 export function tempo(pcm, factor) {
+  if (!(factor >= 0.5 && factor <= 100)) throw new Error(`internal: speed factor ${factor} is outside what ffmpeg's atempo accepts (0.5–100)`);
   const out = execFileSync('ffmpeg', ['-loglevel', 'error', '-f', 'f32le', '-ac', '2', '-ar', `${SR}`, '-i', 'pipe:0',
     '-af', `atempo=${factor.toFixed(4)}`, '-f', 'f32le', '-ac', '2', '-ar', `${SR}`, 'pipe:1'], { input: Buffer.from(pcm.buffer, pcm.byteOffset, pcm.byteLength), maxBuffer: 1 << 28 });
   return new Float32Array(out.buffer, out.byteOffset, out.length / 4);