voila-recorder 0.5.0 → 0.6.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

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.

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' }

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] [--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 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,6 +42,12 @@ 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());
     return;
@@ -68,6 +77,60 @@ 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,
+      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 +143,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 +166,7 @@ const USAGE = `usage:
         narrate: !process.argv.includes('--no-narrate'),
         voice: arg('--voice'),
         speed: Number(arg('--speed', '1')) || 1,
+        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.6.0' });
 const deviceParam = z.enum(['desktop', 'mobile', 'tablet']).optional().default('desktop');
 
 server.tool(

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,7 +1,7 @@
 {
   "name": "voila-recorder",
-  "version": "0.5.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.",
+  "version": "0.6.0",
+  "description": "Permission-free product demo recorder: URL in, narrated auto-zoomed MP4 out \u2014 with the recipe embedded in the video. Agent-native (MCP), fully on-device.",
   "license": "MIT",
   "main": "pipeline.js",
   "bin": {
@@ -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",
@@ -58,4 +62,4 @@
     "playwright": "^1.48.0",
     "sharp": "^0.33.5"
   }
-}
+}

package/pipeline.js

@@ -44,7 +44,7 @@ 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, 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;
@@ -77,10 +77,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, 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, 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 +118,4 @@ async function outline(session, url) {
   return extractOutline(page);
 }
 
-module.exports = { produceDemo, outline };
+module.exports = { produceDemo, rerender, outline };

package/recorder.js

@@ -59,7 +59,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 +87,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 +99,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 +177,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/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`
@@ -65,5 +68,12 @@ Reference: https://voila.anzalabidi.dev/llms.txt · https://github.com/anzal1/vo
   (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.