voila-recorder 0.5.0 → 0.7.0

package/AGENTS.md

@@ -24,6 +24,9 @@ npx -y voila-recorder record <url> --steps steps.yaml [--device mobile]
 npx -y voila-recorder review demo.mp4
 npx -y voila-recorder voices
 npx -y voila-recorder login <url>
+npx -y voila-recorder doctor
+npx -y voila-recorder fork demo.mp4 [--url other] [--print]
+npx -y voila-recorder rerender <dir> --voice bf_emma
 ```
 
 ## The loop — always follow it
@@ -55,8 +58,12 @@ npx -y voila-recorder login <url>
 - Narration style: short sentences, product language, 8-15 words per beat.
 - Prefer `zoom` with a `selector` over a raw `level`: voila measures the element
   and picks the level and camera centre so nothing gets cropped.
-- Voices: 28 English (US/UK). af_heart (A) is the default, af_bella (A-) and
-  bf_emma (British) are the other good ones. `speed` 0.5-1.6 sets pace.
+- Voices: Kokoro is English only (af_heart A, af_bella A-, bf_emma British).
+  `speed` 0.5-1.6 sets pace.
+- Other languages: set `voice:` per narration step, so one demo can mix them.
+  `say:Monica` uses a macOS system voice (~50 languages, `voila voices --all`);
+  `--tts-cmd 'engine -o {out} "{text}"'` plugs in any engine on any platform;
+  `audio: clip.mp3` on a step uses a file you already have.
 - Sign-in walls: recording refuses to film a login page. Run `voila login <url>`
   (or the voila_login tool), let the HUMAN sign in in the window that opens, and
   the session persists in a local profile for every later recording.

package/README.md

@@ -28,9 +28,18 @@ voila record <url> --device mobile            # iPhone-class viewport (portrait)
 voila outline <url>                           # page structure for planning
 voila review demo.mp4 --frames 12             # frames + recipe for self-review
 voila serve                                   # web UI
+voila doctor                                  # check + pre-download chromium and the voice model
+voila fork demo.mp4 --url https://other.app   # rebuild any voila demo from the recipe inside it
+voila rerender <dir> --voice bf_emma          # new voice, no re-recording (needs --keep-frames)
+voila login https://app.example.com           # you sign in; session saved locally
+voila voices                                  # 28 narration voices, graded
 voila mcp                                     # stdio MCP server
 ```
 
+First run downloads Chromium (~150MB) and the voice model (~90MB) into
+`~/.cache/voila`, so upgrades do not re-download. Consent banners are dismissed
+before recording, preferring "reject" over "accept".
+
 Devices: `desktop` (1280×800), `mobile` (390×844, touch + mobile UA),
 `tablet` (834×1112). Cross-platform: verified on macOS and Linux (arm64
 container); recording is headless-safe for CI.
@@ -64,6 +73,28 @@ on-device, no cloud, no API keys ([audio.js](audio.js)). Falls back to macOS
 `say` if Kokoro can't load. Voices: `af_heart` (default), `af_bella`,
 `am_adam`, … (`voice` param). Disable with `narrate: false` / `--no-narrate`.
 
+**Other languages, and mixing them.** Kokoro's JS port speaks English only, so
+non-English narration comes from one of two other engines, chosen per step:
+
+```yaml
+- action: hover
+  selector: h1
+  narration: "This part is English."          # Kokoro
+- action: scroll_to
+  selector: "#pricing"
+  voice: "say:Mónica"                          # macOS system voice
+  narration: "Esta parte está en español."
+- action: wait
+  ms: 500
+  audio: ./clips/intro-ja.mp3                  # a clip you already have
+```
+
+`voila voices --all` lists the ~180 system voices across ~50 languages on
+macOS. On Linux and Windows use any engine you like:
+`--tts-cmd 'piper -m es.onnx -f {out} -- "{text}"'` ({out}, {text}, {voice}).
+Every step is still paced to its own spoken clip, so mixed-language demos stay
+in sync.
+
 ## Recipes — demos as code
 
 Every video ships with its source: `recipe.json` (URL + steps + narration +

package/RECIPE.md

@@ -51,6 +51,10 @@ Each step: `{ action, ...params, caption?, narration?, optional?, pause? }`
 | `zoom`      | `level` (1-3) or `selector`, `ms`   | camera zoom; with a selector it frames that element |
 | `wait`      | `ms`                                | hold (cursor keeps breathing on long holds) |
 
+Any step may also carry `voice:` (Kokoro id, `say:Name`, or an id for your
+`--tts-cmd` engine) and `audio:` (a ready-made clip, skipping TTS entirely).
+Because voice is per step, a recipe can mix languages.
+
 `caption` renders as a lower-third; `narration` is spoken by on-device TTS and
 **paces the segment** — the recording holds until the clip finishes, so a
 recreated demo re-times itself to whatever voice regenerates it.

package/audio.js

@@ -22,6 +22,7 @@ async function getKokoro() {
     // Must load the CJS build (exports map: require → dist/kokoro.cjs): it
     // resolves bundled voice files via __dirname, while the ESM build loses
     // __dirname and breaks when cwd isn't the package root.
+    require('./modelcache').useStableCache();
     const { KokoroTTS } = require('kokoro-js');
     kokoroInstance = await KokoroTTS.from_pretrained(
       'onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'q8' }
@@ -30,7 +31,7 @@ async function getKokoro() {
   return kokoroInstance;
 }
 
-async function synthKokoro(texts, dir, voice, onStatus, speed = 1) {
+async function _unusedSynthKokoro(texts, dir, voice, onStatus, speed = 1) {
   // Fail loudly on a bad voice name rather than silently using the default.
   if (voice && /^[a-z]{2}_/.test(voice) && !voices.isValid(voice)) {
     throw new Error(`unknown voice "${voice}". Try: ${voices.suggest(voice).join(', ')} (run \`voila voices\` for all ${voices.ranked().length})`);
@@ -76,7 +77,7 @@ async function pickSayVoice(preferred) {
   return 'Samantha';
 }
 
-async function synthSay(texts, dir, voice, onStatus) {
+async function _unusedSynthSay(texts, dir, voice, onStatus) {
   const v = await pickSayVoice(voice);
   onStatus(`narrating with say (${v})`);
   const clips = [];
@@ -89,25 +90,113 @@ async function synthSay(texts, dir, voice, onStatus) {
 }
 
 // --- pipeline entry ----------------------------------------------------------
+// Each narration item is {text, voice?, audio?}. Voice decides the engine:
+//   af_heart          -> Kokoro (English, best quality, cross platform)
+//   say:Monica        -> a system voice (macOS; ~50 languages)
+//   (--tts-cmd set)   -> any external engine, any language
+// A step can also point at a ready-made file with `audio:`, which bypasses TTS.
+// Because the voice is per item, one demo can mix languages.
+
+function engineFor(voice, ttsCmd) {
+  // Supplying --tts-cmd means "use my engine", unless a step names a specific
+  // Kokoro or system voice, which then wins for that step.
+  if (!voice) {
+    if (ttsCmd) return 'cmd';
+    return process.env.VOILA_TTS === 'say' ? 'say' : 'kokoro';
+  }
+  if (String(voice).startsWith('cmd:') || (ttsCmd && String(voice).startsWith('cmd'))) return 'cmd';
+  if (String(voice).startsWith('say:')) return 'say';
+  if (voices.isValid(voice)) return 'kokoro';
+  if (voices.isSystemVoice(voice)) return 'say';
+  if (ttsCmd) return 'cmd';
+  throw new Error(
+    `unknown voice "${voice}". Kokoro (English): ${voices.suggest(voice).join(', ')}. ` +
+    `For other languages use a system voice like "say:Monica" (see \`voila voices --all\`) ` +
+    `or supply --tts-cmd for your own engine.`
+  );
+}
+
+async function sayOne(text, file, voiceName, speed) {
+  const rate = Math.round(185 * (speed || 1));
+  await run('say', ['-v', voiceName, '-r', String(rate), '-o', file, text]);
+}
+
+async function cmdOne(text, file, voiceName, ttsCmd) {
+  const cmd = ttsCmd
+    .replaceAll('{text}', text.replace(/"/g, '\\"'))
+    .replaceAll('{out}', file)
+    .replaceAll('{voice}', voiceName || '');
+  await new Promise((res, rej) => {
+    require('child_process').exec(cmd, { maxBuffer: 1e7 }, (err, _o, se) =>
+      err ? rej(new Error(`tts-cmd failed: ${String(se || err.message).slice(0, 200)}`)) : res());
+  });
+  if (!fs.existsSync(file)) throw new Error(`tts-cmd produced no file at ${file}`);
+}
 
-// Synthesize narration clips up front so the recorder can pace segments to the
-// spoken durations. Returns {clips: [{file, durMs}], voice, backend}.
-async function prepareNarration(texts, dir, voice, onStatus = () => {}, speed = 1) {
+// Synthesize every narration clip up front so the recorder can pace segments
+// to real spoken durations. Returns {clips:[{file,durMs}], voice, backend}.
+async function prepareNarration(items, dir, defaultVoice, onStatus = () => {}, speed = 1, ttsCmd = null) {
   fs.mkdirSync(dir, { recursive: true });
-  const backend = process.env.VOILA_TTS || 'kokoro';
-  if (backend === 'kokoro') {
-    try {
-      return await synthKokoro(texts, dir, voice, onStatus, speed);
-    } catch (e) {
-      if (/unknown voice/.test(e.message)) throw e;   // user error, not a fallback case
-      onStatus(`kokoro unavailable (${e.message.slice(0, 80)})`);
+  const norm = items.map(it => (typeof it === 'string' ? { text: it } : it));
+  const clips = [];
+  const used = new Set();
+  let kokoro = null;
+
+  for (let i = 0; i < norm.length; i++) {
+    const it = norm[i];
+    const voice = it.voice || defaultVoice || null;
+
+    // A pre-made audio file wins over any engine.
+    if (it.audio) {
+      if (!fs.existsSync(it.audio)) throw new Error(`audio file not found: ${it.audio}`);
+      clips.push({ file: it.audio, durMs: await ffDurationMs(it.audio) });
+      used.add('file');
+      continue;
+    }
+
+    const engine = engineFor(voice, ttsCmd);
+    const ext = engine === 'kokoro' ? 'wav' : engine === 'say' ? 'aiff' : 'wav';
+    const file = path.join(dir, `seg${i}.${ext}`);
+
+    if (engine === 'kokoro') {
+      if (!kokoro) {
+        onStatus('loading Kokoro TTS');
+        require('./modelcache').useStableCache();
+        const { KokoroTTS } = require('kokoro-js');
+        kokoro = await KokoroTTS.from_pretrained('onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'q8' });
+      }
+      const v = voice && voices.isValid(voice) ? voice : 'af_heart';
+      onStatus(`narrating ${i + 1}/${norm.length} with Kokoro (${v})`);
+      const audio = await kokoro.generate(it.text, { voice: v, speed });
+      await audio.save(file);
+      clips.push({
+        file,
+        durMs: audio.audio && audio.sampling_rate
+          ? Math.round((audio.audio.length / audio.sampling_rate) * 1000)
+          : await ffDurationMs(file),
+      });
+      used.add(`kokoro:${v}`);
+    } else if (engine === 'say') {
+      if (process.platform !== 'darwin') {
+        throw new Error(`system voices need macOS. Use a Kokoro voice for English, or --tts-cmd on this platform.`);
+      }
+      const name = String(voice).replace(/^say:/, '');
+      onStatus(`narrating ${i + 1}/${norm.length} with system voice (${name})`);
+      await sayOne(it.text, file, name, speed);
+      clips.push({ file, durMs: await ffDurationMs(file) });
+      used.add(`say:${name}`);
+    } else {
+      onStatus(`narrating ${i + 1}/${norm.length} with tts-cmd`);
+      await cmdOne(it.text, file, String(voice || '').replace(/^cmd:/, ''), ttsCmd);
+      clips.push({ file, durMs: await ffDurationMs(file) });
+      used.add('cmd');
     }
   }
-  if (process.platform === 'darwin') return synthSay(texts, dir, voice, onStatus);
-  throw new Error('no TTS backend available');
+
+  return { clips, voice: [...used].join(', ') || 'none', backend: [...used].join(', ') };
 }
 
-async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1, prepared = null, onStatus = () => {} } = {}) {
+async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1, ttsCmd = null, prepared = null, onStatus = () => {} } = {}) {
   const segs = (meta.segments || []).filter(s => s.narration);
   if (!segs.length) {
     fs.copyFileSync(videoIn, videoOut);
@@ -119,7 +208,9 @@ async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1,
   let synth = prepared && prepared.clips.length === segs.length ? prepared : null;
   if (!synth) {
     try {
-      synth = await prepareNarration(segs.map(s => s.narration), dir, voice, onStatus, speed);
+      synth = await prepareNarration(
+        segs.map(s => ({ text: s.narration, voice: s.voice, audio: s.audio })),
+        dir, voice, onStatus, speed, ttsCmd);
     } catch (e) {
       onStatus(`narration skipped: ${e.message}`);
       fs.copyFileSync(videoIn, videoOut);
@@ -153,7 +244,7 @@ async function addNarration(meta, videoIn, videoOut, { voice = null, speed = 1,
     ff.on('error', rej);
   });
 
-  fs.rmSync(dir, { recursive: true, force: true });
+  fs.rmSync(dir, { recursive: true, force: true });   // only generated clips live here
   return { narrated: true, voice: synth.voice, backend: synth.backend, segments: clips.length };
 }
 

package/cli.js

@@ -18,11 +18,14 @@ function arg(name, fallback = null) {
 }
 
 const USAGE = `usage:
+  voila doctor                          (check + download everything voila needs)
   voila outline <url> [--device desktop|mobile|tablet]
-  voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--no-narrate] [--headful] [--out dir] [--profile dir]
+  voila record <url> [--steps f.yaml] [--device mobile] [--voice name] [--speed 1] [--tts-cmd tmpl] [--no-narrate] [--headful] [--keep-frames] [--no-dismiss] [--dismiss sel] [--out dir] [--profile dir]
   voila review <video.mp4> [--frames 12] [--out dir]
   voila login <url> [--profile dir]     (sign in yourself; session is saved locally)
-  voila voices                          (list every narration voice, best first)
+  voila voices [--all]                  (Kokoro voices; --all adds system voices for other languages)
+  voila fork <video.mp4> [--url u] [--voice v] [--print] [--out dir]
+  voila rerender <dir> [--voice v] [--speed n]   (needs --keep-frames on the original)
   voila skill   (install the voila skill into ~/.claude/skills)
   voila serve   (web UI, PORT env or --port)
   voila mcp     (stdio MCP server)`;
@@ -39,8 +42,16 @@ const USAGE = `usage:
     require('./mcp');
     return;
   }
+  if (cmd === 'doctor' || cmd === '--version' || cmd === '-v') {
+    if (cmd !== 'doctor') { console.log(require('./package.json').version); return; }
+    console.error(`voila ${require('./package.json').version}\n`);
+    const r = await require('./doctor').doctor({ fix: !process.argv.includes('--check') });
+    process.exit(r.ready ? 0 : 1);
+  }
   if (cmd === 'voices') {
-    console.log(require('./voices').format());
+    const v = require('./voices');
+    console.log(process.argv.includes('--all') ? v.formatAll() : v.format());
+    if (!process.argv.includes('--all')) console.log('\nNon-English? run: voila voices --all');
     return;
   }
   if (cmd === 'skill') {
@@ -68,6 +79,61 @@ const USAGE = `usage:
     return;
   }
 
+  if (cmd === 'fork') {
+    // The recipe inside a voila MP4 is its source. Turn it back into a script
+    // and, unless --print, record it again (optionally against another URL).
+    const video = process.argv[3];
+    if (!video) { console.error(USAGE); process.exit(1); }
+    const { reviewDemo } = require('./review');
+    const info = await reviewDemo(video, { count: 3 });
+    if (!info.recipe || !info.recipe.steps) {
+      console.error('FAILED: no voila recipe found in that file (was it made by voila?)');
+      process.exit(1);
+    }
+    const stepsYaml = yaml.dump(info.recipe.steps);
+    if (process.argv.includes('--print')) { console.log(stepsYaml); return; }
+
+    const target = arg('--url', info.recipe.url);
+    const workDir = arg('--out', path.join(__dirname, 'recordings', `fork-${Date.now()}`));
+    fs.mkdirSync(workDir, { recursive: true });
+    fs.writeFileSync(path.join(workDir, 'steps.yaml'), stepsYaml);
+    console.error(`[voila] forking ${info.recipe.steps.length} steps onto ${target}`);
+
+    const { VoilaSession } = require('./recorder');
+    const { produceDemo } = require('./pipeline');
+    const s2 = new VoilaSession({
+      headless: !process.argv.includes('--headful'),
+      device: arg('--device', 'desktop'),
+      profileDir: arg('--profile', path.join(__dirname, 'profile')),
+    });
+    try {
+      const r = await produceDemo(s2, {
+        url: target, steps: yaml.load(stepsYaml), workDir,
+        narrate: !process.argv.includes('--no-narrate'),
+        voice: arg('--voice'), speed: Number(arg('--speed', '1')) || 1,
+        keepFrames: process.argv.includes('--keep-frames'),
+        onStatus: m => console.error('[voila]', m),
+      });
+      console.log(r.video);
+    } finally { await s2.close(); }
+    return;
+  }
+
+  if (cmd === 'rerender') {
+    const dir = process.argv[3];
+    if (!dir) { console.error(USAGE); process.exit(1); }
+    const { rerender } = require('./pipeline');
+    const r = await rerender(dir, {
+      voice: arg('--voice'),
+      speed: Number(arg('--speed', '1')) || 1,
+      ttsCmd: arg('--tts-cmd'),
+      narrate: !process.argv.includes('--no-narrate'),
+      onStatus: m => console.error('[voila]', m),
+    });
+    console.log(r.video);
+    return;
+  }
+
   const url = process.argv[3];
   if (!cmd || !url || !['outline', 'record', 'login'].includes(cmd)) {
     console.error(USAGE);
@@ -80,6 +146,8 @@ const USAGE = `usage:
     headless: !process.argv.includes('--headful'),
     device: arg('--device', 'desktop'),
     profileDir: arg('--profile', path.join(__dirname, 'profile')),
+    dismiss: !process.argv.includes('--no-dismiss'),
+    dismissSelector: arg('--dismiss'),
   });
 
   try {
@@ -101,6 +169,8 @@ const USAGE = `usage:
         narrate: !process.argv.includes('--no-narrate'),
         voice: arg('--voice'),
         speed: Number(arg('--speed', '1')) || 1,
+        ttsCmd: arg('--tts-cmd'),
+        keepFrames: process.argv.includes('--keep-frames'),
         onStatus: s => console.error('[voila]', s),
       });
       console.log(result.video);

package/consent.js

@@ -0,0 +1,97 @@
+// Cookie and consent banners ruin a demo: they sit in frame for the whole
+// recording. Dismiss them before the camera rolls.
+//
+// Privacy first: we look for "reject" / "necessary only" before "accept", so
+// the recorded session declines non-essential cookies wherever that choice
+// exists. Accepting is only a last resort to clear the overlay.
+
+const REJECT = [
+  /^(reject|decline|refuse)( all)?$/i,
+  /necessary (cookies )?only/i,
+  /^only (essential|necessary|required)/i,
+  /^(essential|required) (cookies )?only/i,
+  /continue without accepting/i,
+  /^reject non-essential/i,
+];
+
+const ACCEPT = [
+  /^(accept|allow|agree)( all| cookies)?$/i,
+  /^(ok|got it|i understand|understood)$/i,
+  /^(dismiss|close)$/i,
+];
+
+// Runs in the page. Returns the label it clicked, or null.
+const dismissInPage = ([rejectSrc, acceptSrc]) => {
+  const toRe = arr => arr.map(([s, f]) => new RegExp(s, f));
+  const reject = toRe(rejectSrc), accept = toRe(acceptSrc);
+
+  const visible = el => {
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return r.width > 20 && r.height > 12 && cs.visibility !== 'hidden' && cs.opacity !== '0';
+  };
+
+  // Only consider controls that live inside something banner-shaped, so we
+  // never click an "Accept" button that is part of the product itself.
+  const looksLikeBanner = el => {
+    const box = el.closest('[class*="cookie" i],[id*="cookie" i],[class*="consent" i],[id*="consent" i],[class*="gdpr" i],[id*="gdpr" i],[aria-label*="cookie" i],[role="dialog"],[class*="banner" i]');
+    if (box) return true;
+    // Or a fixed-position bar pinned to an edge of the viewport.
+    let n = el;
+    for (let i = 0; i < 6 && n; i++, n = n.parentElement) {
+      const cs = getComputedStyle(n);
+      if (cs.position === 'fixed' || cs.position === 'sticky') {
+        const r = n.getBoundingClientRect();
+        if (r.width > innerWidth * 0.5 && (r.bottom > innerHeight * 0.6 || r.top < innerHeight * 0.4)) return true;
+      }
+    }
+    return false;
+  };
+
+  const controls = [...document.querySelectorAll('button,a[role="button"],[role="button"],input[type="button"],input[type="submit"]')]
+    .filter(visible).filter(looksLikeBanner);
+
+  for (const patterns of [reject, accept]) {
+    for (const el of controls) {
+      const label = (el.innerText || el.value || el.getAttribute('aria-label') || '').trim();
+      if (!label || label.length > 40) continue;
+      if (patterns.some(re => re.test(label))) { el.click(); return label; }
+    }
+  }
+  return null;
+};
+
+async function dismissConsent(page, { selector = null, timeout = 2500 } = {}) {
+  const results = [];
+  if (selector) {
+    const el = page.locator(selector).first();
+    try {
+      await el.waitFor({ state: 'visible', timeout });
+      await el.click({ timeout: 2000 });
+      results.push(`custom: ${selector}`);
+    } catch { /* nothing matched the override */ }
+  }
+
+  const src = [
+    REJECT.map(r => [r.source, r.flags]),
+    ACCEPT.map(r => [r.source, r.flags]),
+  ];
+
+  // Banners often mount late, and some sites stack two of them.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    let clicked = null;
+    try {
+      clicked = await page.evaluate(dismissInPage, src);
+      for (const frame of page.frames()) {
+        if (clicked || frame === page.mainFrame()) continue;
+        clicked = await frame.evaluate(dismissInPage, src).catch(() => null);
+      }
+    } catch { /* page navigated mid-check */ }
+    if (clicked) results.push(clicked);
+    await page.waitForTimeout(attempt === 0 ? 700 : 500);
+    if (!clicked && attempt > 0) break;
+  }
+  return results;
+}
+
+module.exports = { dismissConsent };

package/doctor.js

@@ -0,0 +1,118 @@
+// Pre-flight: tell people what voila needs, what is already on disk, and
+// download the rest with visible progress. The first run used to be several
+// silent minutes, which reads as a hang.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile, execFileSync } = require('child_process');
+
+const MB = n => `${(n / 1e6).toFixed(0)}MB`;
+
+function chromiumPath() {
+  try {
+    const { chromium } = require('playwright');
+    return chromium.executablePath();
+  } catch { return null; }
+}
+
+function chromiumReady() {
+  const p = chromiumPath();
+  return !!(p && fs.existsSync(p));
+}
+
+// transformers.js caches models under ~/.cache/huggingface by default.
+function kokoroCacheDir() {
+  return require('./modelcache').CACHE_DIR;
+}
+
+function kokoroReady() {
+  const dir = kokoroCacheDir();
+  if (!fs.existsSync(dir)) return false;
+  const hit = [];
+  const walk = (d, depth = 0) => {
+    if (depth > 4 || hit.length) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (hit.length) return;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (/\.onnx(_data)?$/.test(e.name) && fs.statSync(full).size > 5e6) hit.push(full);
+    }
+  };
+  try { walk(dir); } catch { /* unreadable cache */ }
+  return hit.length > 0;
+}
+
+function ffmpegReady() {
+  try { return fs.existsSync(require('ffmpeg-static')); } catch { return false; }
+}
+
+// Install Chromium with its progress bar visible instead of swallowed.
+function installChromium({ quiet = false } = {}) {
+  let cliPath;
+  try { cliPath = require.resolve('playwright/cli'); }
+  catch { cliPath = path.join(path.dirname(require.resolve('playwright')), 'cli.js'); }
+  execFileSync(process.execPath, [cliPath, 'install', 'chromium'], {
+    stdio: quiet ? 'pipe' : ['ignore', 'inherit', 'inherit'],
+    timeout: 900000,
+  });
+}
+
+async function warmKokoro(onStatus = () => {}) {
+  require('./modelcache').useStableCache();
+  const { KokoroTTS } = require('kokoro-js');
+  let lastPct = -5;
+  const tts = await KokoroTTS.from_pretrained('onnx-community/Kokoro-82M-v1.0-ONNX', {
+    dtype: 'q8',
+    progress_callback: p => {
+      if (p.status === 'download') return onStatus(`fetching ${p.file}`);
+      if (p.status !== 'progress') return;
+      // Hugging Face omits content-length on some files, so fall back to bytes.
+      if (typeof p.total === 'number' && p.total > 0) {
+        const pct = Math.floor((p.progress || 0) / 5) * 5;
+        if (pct > lastPct) { lastPct = pct; onStatus(`${p.file || 'model'} ${pct}% of ${MB(p.total)}`); }
+      } else if (typeof p.loaded === 'number') {
+        const step = Math.floor(p.loaded / 1e7);
+        if (step > lastPct) { lastPct = step; onStatus(`${p.file || 'model'} ${MB(p.loaded)} downloaded`); }
+      }
+    },
+  });
+  // Force one tiny synthesis so the voice files are fetched too.
+  await tts.generate('Ready.', { voice: 'af_heart' });
+  return true;
+}
+
+async function doctor({ fix = true, log = console.error } = {}) {
+  const nodeOk = Number(process.versions.node.split('.')[0]) >= 20;
+  log(`node        ${process.versions.node} ${nodeOk ? 'ok' : 'TOO OLD, voila needs >= 20'}`);
+  log(`ffmpeg      ${ffmpegReady() ? 'bundled, ok' : 'MISSING (reinstall voila-recorder)'}`);
+
+  let chrome = chromiumReady();
+  log(`chromium    ${chrome ? 'installed' : 'not installed (~150MB download)'}`);
+  if (!chrome && fix) {
+    log('\ndownloading chromium...');
+    installChromium();
+    chrome = chromiumReady();
+    log(`chromium    ${chrome ? 'installed' : 'FAILED'}`);
+  }
+
+  let voice = kokoroReady();
+  log(`voice model ${voice ? `cached in ${kokoroCacheDir()}` : 'not cached (~90MB download, first narration only)'}`);
+  if (!voice && fix) {
+    log('\nfetching the voice model...');
+    try {
+      await warmKokoro(m => log(`  ${m}`));
+      voice = true;
+      log('voice model cached');
+    } catch (e) {
+      log(`voice model FAILED: ${e.message.slice(0, 120)}`);
+      log('(recording still works with --no-narrate)');
+    }
+  }
+
+  const ready = nodeOk && ffmpegReady() && chrome;
+  log(`\n${ready ? 'voila is ready. Try: voila record https://example.com' : 'voila is not ready yet, see above.'}`);
+  return { nodeOk, ffmpeg: ffmpegReady(), chromium: chrome, voice, ready };
+}
+
+module.exports = { doctor, chromiumReady, kokoroReady, installChromium, warmKokoro };

package/mcp.js

@@ -37,7 +37,7 @@ function getSession(device) {
   return sessions.get(key);
 }
 
-const server = new McpServer({ name: 'voila', version: '0.5.0' });
+const server = new McpServer({ name: 'voila', version: '0.7.0' });
 const deviceParam = z.enum(['desktop', 'mobile', 'tablet']).optional().default('desktop');
 
 server.tool(
@@ -61,6 +61,7 @@ server.tool(
   'caption is burned into the video as a lower-third; narration is spoken via on-device TTS (Kokoro) at that step, ' +
   'and segment pacing automatically stretches to fit each narration clip — no need to pad waits. ' +
   'Steps marked optional:true are skipped on failure instead of aborting. ' +
+  'A step may set its own voice: (mixing languages within one demo) or audio: (a ready-made clip). ' +
   'device selects the recorded viewport (mobile emulates an iPhone-class device). ' +
   'On failure the error names the failing step and includes the live page outline — patch the steps and retry. ' +
   'Returns the MP4 path, the recipe path, and any warnings.',
@@ -68,16 +69,17 @@ server.tool(
     url: z.string().url(),
     steps_yaml: z.string().optional(),
     narrate: z.boolean().optional().default(true),
-    voice: z.string().optional().describe('narration voice id, e.g. af_heart (A), af_bella (A-), bf_emma (B-, British). Call voila_voices for the full list.'),
+    voice: z.string().optional().describe('default narration voice. Kokoro is ENGLISH ONLY (af_heart, af_bella, bf_emma). For other languages use a macOS system voice ("say:Monica") or set tts_cmd. Per-step `voice:` overrides this, so one demo can mix languages.'),
     speed: z.number().min(0.5).max(1.6).optional().default(1).describe('narration speed; 0.9 reads calmer'),
+    tts_cmd: z.string().optional().describe('external TTS engine template for any language/platform, e.g. \'piper -m es.onnx -f {out} -- "{text}"\'. Placeholders: {out} {text} {voice}.'),
     device: deviceParam,
   },
-  async ({ url, steps_yaml, narrate, voice, speed, device }) => enqueue(async () => {
+  async ({ url, steps_yaml, narrate, voice, speed, tts_cmd, device }) => enqueue(async () => {
     const steps = steps_yaml ? yaml.load(steps_yaml) : null;
     const workDir = path.join(__dirname, 'recordings', `mcp-${Date.now()}`);
     fs.mkdirSync(workDir, { recursive: true });
     const result = await produceDemo(getSession(device), {
-      url, steps, workDir, narrate, voice: voice || null, speed,
+      url, steps, workDir, narrate, voice: voice || null, speed, ttsCmd: tts_cmd || null,
       onStatus: () => {},
     });
     return {
@@ -116,11 +118,19 @@ server.tool(
 
 server.tool(
   'voila_voices',
-  'List every narration voice with its quality grade, best first. Use before voila_record when the ' +
-  'user asks for a different voice, an accent, or a male or female narrator.',
-  {},
-  async () => ({
-    content: [{ type: 'text', text: JSON.stringify(voiceCatalogue.ranked(), null, 2) }],
+  'List narration voices. Kokoro voices are English only, with quality grades. Pass system:true to ' +
+  'also get the machine\'s system voices, which is how you narrate other languages (macOS only; on ' +
+  'Linux or Windows use tts_cmd instead). Use before voila_record when the user asks for a different ' +
+  'voice, an accent, a male or female narrator, or a non-English language.',
+  { system: z.boolean().optional().default(false) },
+  async ({ system }) => ({
+    content: [{ type: 'text', text: JSON.stringify({
+      kokoro: voiceCatalogue.ranked(),
+      englishOnly: true,
+      system: system ? voiceCatalogue.systemVoices() : undefined,
+      systemLanguages: system ? Object.keys(voiceCatalogue.systemLanguages()) : undefined,
+      note: 'Non-English: use a system voice (say:Name) on macOS, or tts_cmd on any platform.',
+    }, null, 2) }],
   })
 );
 

package/modelcache.js

@@ -0,0 +1,22 @@
+// transformers.js caches models inside its own node_modules folder by default,
+// so every voila upgrade (and every fresh npx hash) would re-download ~90MB.
+// Pin the cache to a stable per-user directory instead.
+
+const os = require('os');
+const path = require('path');
+
+const CACHE_DIR = process.env.VOILA_MODEL_DIR
+  || path.join(os.homedir(), '.cache', 'voila', 'models');
+
+let applied = false;
+function useStableCache() {
+  if (applied) return CACHE_DIR;
+  try {
+    const { env } = require('@huggingface/transformers');
+    env.cacheDir = CACHE_DIR;
+    applied = true;
+  } catch { /* transformers not resolvable; kokoro will use its default */ }
+  return CACHE_DIR;
+}
+
+module.exports = { useStableCache, CACHE_DIR };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voila-recorder",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out — with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
   "license": "MIT",
   "main": "pipeline.js",
@@ -18,13 +18,17 @@
     "render.js",
     "audio.js",
     "review.js",
+    "modelcache.js",
+    "consent.js",
+    "doctor.js",
     "voices.js",
     "auth.js",
     "public/",
     "skills/",
     "AGENTS.md",
     "README.md",
-    "RECIPE.md"
+    "RECIPE.md",
+    "scripts/"
   ],
   "repository": {
     "type": "git",

package/pipeline.js

@@ -44,15 +44,16 @@ function embedRecipe(videoIn, videoOut, recipe) {
   });
 }
 
-async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, speed = 1, narrate = true, onStatus = () => {} }) {
+async function produceDemo(session, { url, mode = 'auto', steps = null, workDir, voice = null, speed = 1, ttsCmd = null, narrate = true, keepFrames = false, onStatus = () => {} }) {
   // Steps mode: synthesize narration BEFORE recording so segment pacing and
   // caption lifetimes match the spoken clip durations exactly.
   let prepared = null;
   if (steps && narrate) {
-    const texts = steps.filter(s => s.narration).map(s => s.narration);
-    if (texts.length) {
+    const items = steps.filter(s => s.narration)
+      .map(s => ({ text: s.narration, voice: s.voice, audio: s.audio }));
+    if (items.length) {
       try {
-        prepared = await prepareNarration(texts, path.join(workDir, 'tts'), voice, onStatus, speed);
+        prepared = await prepareNarration(items, path.join(workDir, 'tts'), voice, onStatus, speed, ttsCmd);
         let i = 0;
         for (const s of steps) if (s.narration) s._narrDurMs = prepared.clips[i++].durMs;
       } catch (e) {
@@ -69,7 +70,7 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
   await render(meta, raw, { onStatus });
 
   let narration = { narrated: false };
-  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, prepared, onStatus });
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, ttsCmd, prepared, onStatus });
   else fs.copyFileSync(raw, narrated);
 
   const recipe = buildRecipe({ url, mode, steps, meta });
@@ -77,10 +78,40 @@ async function produceDemo(session, { url, mode = 'auto', steps = null, workDir,
   onStatus('embedding recipe');
   await embedRecipe(narrated, out, recipe);
 
-  fs.rmSync(meta.framesDir, { recursive: true, force: true });
+  // Frames are the expensive part to recreate: keeping them lets `voila
+  // rerender` change the voice, speed or captions in seconds instead of
+  // re-driving the browser. They are large, so it is opt-in.
+  if (!keepFrames) fs.rmSync(meta.framesDir, { recursive: true, force: true });
   fs.rmSync(raw, { force: true });
   fs.rmSync(narrated, { force: true });
-  return { video: out, recipe: path.join(workDir, 'recipe.json'), meta, narration };
+  return { video: out, recipe: path.join(workDir, 'recipe.json'), meta, narration, framesKept: keepFrames };
+}
+
+// Re-produce the video from frames already on disk: no browser, no re-driving
+// the page. Used to swap the narration voice or speed after the fact.
+async function rerender(workDir, { voice = null, speed = 1, ttsCmd = null, narrate = true, onStatus = () => {} } = {}) {
+  const metaPath = path.join(workDir, 'meta.json');
+  if (!fs.existsSync(metaPath)) throw new Error(`no meta.json in ${workDir}`);
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  if (!fs.existsSync(meta.framesDir) || !fs.readdirSync(meta.framesDir).length) {
+    throw new Error(`frames were not kept for this recording. Re-record with --keep-frames to enable rerender.`);
+  }
+
+  const raw = path.join(workDir, 'raw.mp4');
+  const narrated = path.join(workDir, 'narrated.mp4');
+  const out = path.join(workDir, 'demo.mp4');
+  await render(meta, raw, { onStatus });
+
+  let narration = { narrated: false };
+  if (narrate) narration = await addNarration(meta, raw, narrated, { voice, speed, ttsCmd, onStatus });
+  else fs.copyFileSync(raw, narrated);
+
+  const recipe = JSON.parse(fs.readFileSync(path.join(workDir, 'recipe.json'), 'utf8'));
+  onStatus('embedding recipe');
+  await embedRecipe(narrated, out, recipe);
+  fs.rmSync(raw, { force: true });
+  fs.rmSync(narrated, { force: true });
+  return { video: out, meta, narration };
 }
 
 async function outline(session, url) {
@@ -88,4 +119,4 @@ async function outline(session, url) {
   return extractOutline(page);
 }
 
-module.exports = { produceDemo, outline };
+module.exports = { produceDemo, rerender, outline };

package/recorder.js

@@ -40,8 +40,11 @@ class Timeline {
     this.zoom = 1;
     this.center = null;
   }
-  recordSegment(caption, narration, dur = null) {
-    this.segments.push({ t: Date.now(), caption: caption || null, narration: narration || null, dur });
+  recordSegment(caption, narration, dur = null, voice = null, audio = null) {
+    this.segments.push({
+      t: Date.now(), caption: caption || null, narration: narration || null, dur,
+      ...(voice ? { voice } : {}), ...(audio ? { audio } : {}),
+    });
   }
   recordMove(to, dur) {
     this.moves.push({ t: Date.now(), from: { ...this.pos }, to: { ...to }, dur });
@@ -59,7 +62,9 @@ class Timeline {
 }
 
 class VoilaSession {
-  constructor({ profileDir, headless = false, device = 'desktop' } = {}) {
+  constructor({ profileDir, headless = false, device = 'desktop', dismiss = true, dismissSelector = null } = {}) {
+    this.dismiss = dismiss;
+    this.dismissSelector = dismissSelector;
     this.profileDir = profileDir || path.join(__dirname, 'profile');
     this.headless = headless;
     this.device = DEVICES[device] ? device : 'desktop';
@@ -85,11 +90,9 @@ class VoilaSession {
         // Zero-install path: fetch Chromium on first use instead of making the
         // user run `npx playwright install` themselves.
         if (!/Executable doesn't exist|missing dependencies|browser.*not found/i.test(String(e.message))) throw e;
-        const { execFileSync } = require('child_process');
-        let cliPath;
-        try { cliPath = require.resolve('playwright/cli'); }
-        catch { cliPath = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'); }
-        execFileSync(process.execPath, [cliPath, 'install', 'chromium'], { stdio: 'pipe', timeout: 600000 });
+        // Visible progress: a silent 150MB download reads as a hang.
+        process.stderr.write('[voila] first run: downloading Chromium (~150MB, one time)\n');
+        require('./doctor').installChromium();
         this.context = await launch();
       }
       await this.context.addInitScript(OVERLAY_SOURCE);
@@ -99,6 +102,10 @@ class VoilaSession {
     this.page.on('close', () => { this.page = null; });
     await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 45000 });
     await this.page.waitForLoadState('networkidle', { timeout: 8000 }).catch(() => {});
+    if (this.dismiss) {
+      const { dismissConsent } = require('./consent');
+      this.dismissed = await dismissConsent(this.page, { selector: this.dismissSelector });
+    }
     return this.page;
   }
 
@@ -173,6 +180,7 @@ class VoilaSession {
       frames: frames.sort((a, b) => a.t - b.t),
       moves: tl.moves, zooms: tl.zooms, segments: tl.segments,
       warnings: tl.warnings || [],
+      dismissed: this.dismissed || [],
       framesDir,
     };
     fs.writeFileSync(path.join(workDir, 'meta.json'), JSON.stringify(meta));

package/scripts/check-audio.js

@@ -0,0 +1,14 @@
+// CI helper: assert the rendered demo actually carries a narration track.
+const { execFileSync } = require('child_process');
+const ffmpeg = require('ffmpeg-static');
+
+const file = process.argv[2];
+let out = '';
+try { execFileSync(ffmpeg, ['-i', file], { stdio: 'pipe' }); }
+catch (e) { out = String(e.stderr || ''); }
+
+if (!/Audio: aac/.test(out)) {
+  console.error(out || '(no ffmpeg output)');
+  throw new Error(`no narration track in ${file}`);
+}
+console.log(`narration track OK in ${file}`);

package/scripts/tts-cmd-fixture.js

@@ -0,0 +1,10 @@
+// CI fixture: a stand-in "external TTS engine". Writes a short tone to {out}
+// so the --tts-cmd plumbing can be exercised on every platform, including
+// ones with no system voices installed.
+const { execFileSync } = require('child_process');
+const ffmpeg = require('ffmpeg-static');
+const out = process.argv[2];
+const text = process.argv.slice(3).join(' ');
+const seconds = Math.max(1, Math.min(8, text.split(/\s+/).length / 3)).toFixed(2);
+execFileSync(ffmpeg, ['-y', '-f', 'lavfi', '-i', `sine=frequency=340:duration=${seconds}`, '-ac', '1', out], { stdio: 'pipe' });
+console.log(`fixture wrote ${seconds}s to ${out}`);

package/skills/voila/SKILL.md

@@ -14,9 +14,12 @@ Prefer the MCP tools if registered (`voila_outline`, `voila_record`,
 `voila_review`); otherwise use the CLI via npx:
 
 ```bash
+npx -y voila-recorder doctor            # first run: pre-downloads chromium + voice model
 npx -y voila-recorder outline <url>
 npx -y voila-recorder record <url> --steps steps.yaml [--device mobile]
 npx -y voila-recorder review demo.mp4
+npx -y voila-recorder fork demo.mp4 --url https://other.example
+npx -y voila-recorder rerender <dir> --voice bf_emma
 ```
 
 Register the MCP server once with: `claude mcp add voila -- npx -y voila-recorder mcp`
@@ -61,9 +64,23 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
   for them in chat.
 - Prefer `zoom` with a `selector` over a bare `level`: voila measures the
   element and picks the level and camera centre, so nothing is cropped.
-- Voices: `voila voices` lists 28 English voices with quality grades. af_heart
+- Languages: narration voice is per step, so demos can mix languages. Kokoro
+  is ENGLISH ONLY (af_heart A, af_bella A-, bf_emma British). For other
+  languages use a macOS system voice (`voice: "say:Monica"`, `voila voices
+  --all` lists ~180 across ~50 languages), or `--tts-cmd` with any engine on
+  any platform (placeholders {out} {text} {voice}), or point a step at a
+  ready-made clip with `audio: file.mp3`. On Linux/Windows non-English needs
+  --tts-cmd: tell the user rather than silently narrating in English.
+- Voices: `voila voices` lists the English voices with quality grades. af_heart
   (A) default, af_bella (A-), af_nicole (B-), bf_emma (B-, British). `--speed`
   or the speed param (0.5-1.6) changes pace; 0.9 reads calmer.
 - A failing step is retried once automatically; warnings appear in the result.
+- Iterating on narration? Record once with `--keep-frames`, then `rerender <dir>
+  --voice x --speed n`. It skips the browser entirely and finishes in seconds.
+- Consent banners are auto-dismissed (reject preferred over accept). Use
+  `--dismiss <selector>` for an unusual one, `--no-dismiss` to leave it alone.
+- First run on a new machine downloads ~240MB. Run `voila doctor` first and tell
+  the user it is downloading, so it does not look frozen.
+- `fork <video.mp4>` rebuilds any voila demo from the recipe inside the file.
 - Narration style: short sentences, product language, no "as you can see".
   8–15 words per beat reads best at Kokoro's pace.

package/tour.js

@@ -242,7 +242,7 @@ async function runSteps(page, tl, steps, opts) {
     const step = steps[si];
     if (step.caption || step.narration) {
       await finishSegment();
-      tl.recordSegment(step.caption, step.narration, step._narrDurMs || null);
+      tl.recordSegment(step.caption, step.narration, step._narrDurMs || null, step.voice || null, step.audio || null);
       segStart = Date.now();
       segMinMs = (step._narrDurMs || 0) + 600;
     }

package/voices.js

@@ -55,4 +55,52 @@ function format() {
   return lines.join('\n');
 }
 
-module.exports = { allVoices, ranked, isValid, suggest, format };
+// --- system voices (macOS `say`) ---------------------------------------------
+// Kokoro is English-only in JS (its other voice files ship without a
+// grapheme-to-phoneme stage for those languages). Every Mac already carries
+// ~180 voices across ~50 languages, so those cover non-English narration.
+
+let sysCache = null;
+function systemVoices() {
+  if (sysCache) return sysCache;
+  sysCache = [];
+  if (process.platform !== 'darwin') return sysCache;
+  try {
+    const { execFileSync } = require('child_process');
+    const out = String(execFileSync('say', ['-v', '?'], { maxBuffer: 4e6 }));
+    for (const line of out.split('\n')) {
+      const m = /^(.+?)\s{2,}([a-z]{2}_[A-Z]{2})\s/.exec(line);
+      if (m) sysCache.push({ id: `say:${m[1].trim()}`, name: m[1].trim(), language: m[2].replace('_', '-'), gender: '', grade: 'system' });
+    }
+  } catch { /* no say binary */ }
+  return sysCache;
+}
+
+function systemLanguages() {
+  const langs = {};
+  for (const v of systemVoices()) (langs[v.language] = langs[v.language] || []).push(v.name);
+  return langs;
+}
+
+function isSystemVoice(id) {
+  if (!id) return false;
+  const name = String(id).replace(/^say:/, '').toLowerCase();
+  return systemVoices().some(v => v.name.toLowerCase() === name);
+}
+
+function formatAll() {
+  const lines = [format()];
+  const langs = systemLanguages();
+  const codes = Object.keys(langs).sort();
+  if (!codes.length) {
+    lines.push('\nSystem voices: none found (macOS only). For other languages use --tts-cmd.');
+    return lines.join('\n');
+  }
+  lines.push(`\nSystem voices (macOS, ${systemVoices().length} across ${codes.length} languages)`);
+  for (const c of codes) lines.push(`  ${c.padEnd(7)} ${langs[c].slice(0, 6).join(', ')}${langs[c].length > 6 ? ` +${langs[c].length - 6}` : ''}`);
+  lines.push('\nUse a system voice for non-English narration:  --voice "say:Monica"');
+  lines.push('Any other engine:  --tts-cmd \'piper --model es.onnx -f {out} -- "{text}"\'');
+  return lines.join('\n');
+}
+
+module.exports = { allVoices, ranked, isValid, suggest, format, formatAll, systemVoices, systemLanguages, isSystemVoice };