@tandryukha/aidemo 0.17.0 → 0.18.0

package/README.md

@@ -154,7 +154,7 @@ A bundled fixture store (search → results → cart → checkout) that renders
 finished demo with zero external dependencies:
 
 ```bash
-npm install                                # Node 20+, system Chrome, ffmpeg on PATH
+npm install                                # Node 22+, system Chrome, ffmpeg on PATH
 node examples/local-demo/serve.mjs         # terminal 1: fixture on :8787
 node bin/aidemo.mjs render examples/local-demo --headless   # terminal 2
 open examples/local-demo/output/final-demo.mp4   # xdg-open on Linux, start on Windows
@@ -164,7 +164,10 @@ Voice/captions need `OPENAI_API_KEY` in `.env` — **or** `AIDEMO_TTS_PROVIDER=l
 (no key, offline), **or** `OPENAI_BASE_URL` at a local server. See
 [docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md). No Playwright browser download is
 needed — the engine uses your system Chrome (`channel: "chrome"`; see
-[Setup](#setup) to use a different browser).
+[Setup](#setup) to use a different browser). The one Playwright download is
+its ~2 MB ffmpeg helper, which encodes the take: the first take installs it
+automatically (`AIDEMO_NO_AUTO_INSTALL=1` to manage it yourself with
+`npx playwright install ffmpeg`).
 
 [![Quickstart output — the bundled fixture rendered end-to-end](docs/quickstart.gif)](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/quickstart-demo.mp4)
 
@@ -251,7 +254,9 @@ Codex).
 
 ## Setup
 
-Prereqs: **Node 20+**, **Google Chrome**, **ffmpeg + ffprobe** on `PATH`.
+Prereqs: **Node 22+**, **Google Chrome**, **ffmpeg + ffprobe** on `PATH`. The
+first take also fetches Playwright's ~2 MB ffmpeg helper, which encodes the
+recording (once per Playwright version; `AIDEMO_NO_AUTO_INSTALL=1` opts out).
 Developed and tested on macOS; Linux works for the default (Playwright) capture
 and `--capture obs`. Run `aidemo doctor` to check your setup.
 
@@ -294,9 +299,11 @@ demos/<name>/          ← your working area (untracked; scaffold with `aidemo i
   `postinstall`/`preinstall`).
 - **Network is user-initiated only:** `api.openai.com` (only `voice`/`captions`,
   your key — or a local server via `OPENAI_BASE_URL`), `api.elevenlabs.io` (opt-in),
-  `huggingface.co` (download-only, once, for `AIDEMO_TTS_PROVIDER=local`), and
+  `huggingface.co` (download-only, once, for `AIDEMO_TTS_PROVIDER=local`),
+  `cdn.playwright.dev` (download-only, once per Playwright version: the ~2 MB
+  ffmpeg helper that encodes the take; off with `AIDEMO_NO_AUTO_INSTALL=1`), and
   `github.com` (your own `gh`, for `aidemo feedback`). Recording/composing are
-  fully local. The MCP server is **stdio-only** — no listener.
+  otherwise fully local. The MCP server is **stdio-only** — no listener.
 - **Small, auditable surface:** ~20 source files, 7 runtime deps, MIT. Pin an
   immutable ref if you're wary of the moving `#stable` tag:
   `npx -y github:tandryukha/aidemo#v0.14.0` (any released tag).

package/bin/aidemo.mjs

@@ -6,6 +6,20 @@ import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
+// Fail fast on an unsupported Node with the fix, instead of an arbitrary crash
+// deep inside a dependency (openai 7 needs Node 22). Node 20 reached
+// end-of-life on 2026-04-30. Keep in sync with package.json "engines".
+const MIN_NODE_MAJOR = 22;
+const nodeMajor = Number(process.versions.node.split(".")[0]);
+if (nodeMajor < MIN_NODE_MAJOR) {
+  console.error(
+    `aidemo: Node.js ${MIN_NODE_MAJOR}+ is required (found ${process.version}). ` +
+      `Install Node ${MIN_NODE_MAJOR} LTS or newer (nvm install ${MIN_NODE_MAJOR}; in CI, ` +
+      `actions/setup-node with node-version: ${MIN_NODE_MAJOR}) and re-run.`
+  );
+  process.exit(1);
+}
+
 const here = dirname(fileURLToPath(import.meta.url));
 const cli = resolve(here, "..", "src", "cli.ts");
 const require = createRequire(import.meta.url);

package/docs/AUTHORING.md

@@ -1256,9 +1256,14 @@ CLI. If nothing came up, skip this.
   …) is set; the executable wins. Use `chromium` when a managed Chrome closes
   the automated session after a few seconds ("Target page, context or browser
   has been closed").
-- `doctor` checks Node, ffmpeg, the browser in use, the TTS/STT endpoint
-  (and flags LLM-only servers like Ollama, which have no audio endpoints — point
-  `OPENAI_BASE_URL` at a speech server such as speaches instead).
+- `doctor` checks Node (22+), ffmpeg, the browser in use, Playwright's ffmpeg
+  helper, the TTS/STT endpoint (and flags LLM-only servers like Ollama, which
+  have no audio endpoints — point `OPENAI_BASE_URL` at a speech server such as
+  speaches instead).
+- The first take installs Playwright's ~2 MB ffmpeg helper (it encodes the
+  recording; once per Playwright version) and logs `installing Playwright's
+  ffmpeg helper`. If that download is blocked, the error names the manual
+  command; `AIDEMO_NO_AUTO_INSTALL=1` turns the download off.
 
 ## Import from Playwright (trace or test file)
 

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@tandryukha/aidemo",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "license": "MIT",
   "description": "AI Demo Engine — turn a storyboard into a narrated, captioned product demo video",
   "type": "module",
   "bin": {
     "aidemo": "bin/aidemo.mjs"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -37,7 +40,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
     "commander": "^12.1.0",
-    "openai": "^6.49.0",
+    "openai": "^7.47.0",
     "playwright": "^1.55.1",
     "re2js": "2.9.1",
     "tsx": "^4.23.1",

package/src/browser.ts

@@ -8,10 +8,147 @@
  * the options are exactly the engine's historical `{ channel: "chrome", ... }`.
  */
 import { chromium, type Browser, type BrowserContext, type LaunchOptions } from "playwright";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { BrowserSetupError, chromeLaunchOptions, type ChromeLaunchTarget } from "./config.js";
+import { log, ok } from "./util.js";
 
 type PersistentOptions = NonNullable<Parameters<typeof chromium.launchPersistentContext>[1]>;
 
+/** Executable name of Playwright's ffmpeg helper, per platform. */
+const FFMPEG_HELPER_EXE: Partial<Record<NodeJS.Platform, string>> = {
+  linux: "ffmpeg-linux",
+  darwin: "ffmpeg-mac",
+  win32: "ffmpeg-win64.exe",
+};
+
+/**
+ * Playwright's own ffmpeg helper: the encoder recordVideo writes every take
+ * with. It is neither the system ffmpeg (compose) nor a browser — a ~2 MB
+ * download per Playwright ffmpeg *revision*, and no npm install fetches it
+ * (playwright has no install script). So a fresh npx install, or a Playwright
+ * minor that bumps the revision (1.64: 1011 → 1013, with VP9 encoding), leaves
+ * it missing and the take fails at launch. Mirrors playwright-core's
+ * documented lookup (PLAYWRIGHT_BROWSERS_PATH, else the per-OS
+ * ms-playwright cache dir). `install` is the exact command for THIS engine's
+ * Playwright. null when the location can't be determined.
+ */
+export function recorderFfmpeg(): {
+  path: string;
+  revision: string;
+  /** This engine's playwright/cli.js — runs Playwright's own installer. */
+  cli: string;
+  install: string;
+} | null {
+  try {
+    const exe = FFMPEG_HELPER_EXE[process.platform];
+    if (!exe) return null;
+    const req = createRequire(import.meta.url);
+    const playwrightPkg = req.resolve("playwright/package.json");
+    // playwright-core is playwright's dependency: resolve it from there.
+    const corePkg = createRequire(playwrightPkg).resolve("playwright-core/package.json");
+    const coreDir = dirname(corePkg);
+    const browsers = JSON.parse(readFileSync(join(coreDir, "browsers.json"), "utf8")) as {
+      browsers: Array<{ name: string; revision: string }>;
+    };
+    const revision = browsers.browsers.find((b) => b.name === "ffmpeg")?.revision;
+    if (!revision) return null;
+    const env = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    let registry =
+      env === "0"
+        ? join(coreDir, ".local-browsers")
+        : env || join(defaultPlaywrightCacheDir(), "ms-playwright");
+    if (!isAbsolute(registry)) registry = resolve(process.env.INIT_CWD || process.cwd(), registry);
+    const cli = join(dirname(playwrightPkg), "cli.js");
+    return {
+      path: join(registry, `ffmpeg-${revision}`, exe),
+      revision,
+      cli,
+      install: `node "${cli}" install ffmpeg`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function defaultPlaywrightCacheDir(): string {
+  if (process.platform === "darwin") return join(homedir(), "Library", "Caches");
+  if (process.platform === "win32") return process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local");
+  return process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+}
+
+/** AIDEMO_NO_AUTO_INSTALL=1: never download the helper (air-gapped / managed caches). */
+export const recorderAutoInstall = (): boolean =>
+  !/^(1|true|yes)$/i.test(process.env.AIDEMO_NO_AUTO_INSTALL?.trim() ?? "");
+
+/**
+ * Before a built-in capture launches, make sure Playwright's ffmpeg helper is
+ * there, installing it with Playwright's own installer when it is not, so a
+ * fresh install records out of the box (the GitHub Action runs the same step).
+ * ~2 MB from Playwright's CDN, once per helper revision.
+ * PLAYWRIGHT_SKIP_BROWSER_GC=1 keeps the installer from pruning browsers other
+ * Playwright projects on the machine installed. With AIDEMO_NO_AUTO_INSTALL=1,
+ * an unknown layout or an already-installed helper this is a no-op (a missing
+ * helper then fails the launch with explainLaunchError's install command).
+ */
+export async function ensureRecorderFfmpeg(): Promise<void> {
+  const helper = recorderFfmpeg();
+  if (!helper || existsSync(helper.path) || !recorderAutoInstall()) return;
+  log(
+    `installing Playwright's ffmpeg helper (revision ${helper.revision}, ~2 MB, once per ` +
+      `Playwright version; it encodes the take — AIDEMO_NO_AUTO_INSTALL=1 skips this)`
+  );
+  let output = "";
+  const keep = (d: Buffer | string): void => {
+    output = (output + d.toString()).slice(-4000);
+  };
+  const code = await new Promise<number | null>((done) => {
+    const child = spawn(process.execPath, [helper.cli, "install", "ffmpeg"], {
+      env: { ...process.env, PLAYWRIGHT_SKIP_BROWSER_GC: "1" },
+      // Off stdout: under `aidemo mcp`, stdout is the JSON-RPC channel.
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const timer = setTimeout(() => child.kill(), 5 * 60_000);
+    child.on("error", (err) => {
+      keep(String(err));
+      clearTimeout(timer);
+      done(null);
+    });
+    child.on("close", (c) => {
+      clearTimeout(timer);
+      done(c);
+    });
+  });
+  if (code !== 0 || !existsSync(helper.path)) {
+    // The installer prints the cause as "Error: …" between stack frames and an
+    // error-object dump; surface that line, not the frames.
+    const lines = output
+      .replace(/\u001b\[[0-9;]*m/g, "")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("at ") && !/^[{}]$/.test(l));
+    // Root cause first ("connect ECONNREFUSED …", "server returned code 403"),
+    // then the installer's own summary line.
+    const errors = [...new Set(lines.filter((l) => /error/i.test(l)))];
+    const why = (errors.length ? errors.slice(0, 2) : lines.slice(-1))
+      .map((l) => l.slice(0, 200))
+      .join(" — ");
+    throw new BrowserSetupError(
+      `could not install Playwright's ffmpeg helper (revision ${helper.revision}), which the ` +
+        `take is recorded with${why ? `: ${why}` : ""}. Install it yourself: ${helper.install}`
+    );
+  }
+  ok(`Playwright ffmpeg helper installed (revision ${helper.revision})`);
+}
+
+/** A launch that failed on Playwright's missing ffmpeg helper, not on the browser. */
+const FFMPEG_HELPER_RE = /playwright install ffmpeg|[\\/]ffmpeg-\d+[\\/]ffmpeg/i;
+
 /** Human-readable description of the configured browser, for logs/doctor. */
 export function describeChromeTarget(target: ChromeLaunchTarget = chromeLaunchOptions()): string {
   if ("executablePath" in target) return `executable ${target.executablePath} (AIDEMO_CHROME_EXECUTABLE)`;
@@ -31,6 +168,20 @@ const MISSING_RE =
 export function explainLaunchError(err: unknown, target: ChromeLaunchTarget): Error {
   const e = err instanceof Error ? err : new Error(String(err));
   if (!MISSING_RE.test(e.message)) return e;
+  if (FFMPEG_HELPER_RE.test(e.message)) {
+    // The browser is fine — Playwright's recording helper is what's missing.
+    // Blaming Chrome here sent users to reinstall a browser that works.
+    const helper = recorderFfmpeg();
+    const out = new BrowserSetupError(
+      `Playwright's ffmpeg helper${helper ? ` (revision ${helper.revision})` : ""} is missing — ` +
+        `the ~2 MB encoder Playwright records the take with (not the system ffmpeg, not a ` +
+        `browser; no npm install fetches it). Install it once per Playwright version: ` +
+        `${helper?.install ?? "npx playwright install ffmpeg"}` +
+        `\nOriginal error: ${e.message}`
+    );
+    (out as Error & { cause?: unknown }).cause = e;
+    return out;
+  }
   let hint: string;
   if ("executablePath" in target) {
     hint =

package/src/distribute.ts

@@ -25,7 +25,12 @@ import {
   chromeLaunchOptions,
   type ChromeLaunchTarget,
 } from "./config.js";
-import { describeChromeTarget, probeConfiguredBrowser } from "./browser.js";
+import {
+  describeChromeTarget,
+  probeConfiguredBrowser,
+  recorderAutoInstall,
+  recorderFfmpeg,
+} from "./browser.js";
 import { localTtsStatus } from "./voice-local.js";
 import { Project } from "./project.js";
 import { STARTER_BRIEF, STARTER_STORYBOARD, briefFromInspect, storyboardFromInspect } from "./starter.js";
@@ -659,6 +664,19 @@ export interface DoctorReport {
     };
   };
   playwright: boolean;
+  /**
+   * Playwright's ffmpeg helper for THIS engine's Playwright — the encoder the
+   * built-in capture records every take with (see recorderFfmpeg). Missing is
+   * only fatal with `autoInstall` off: the first take installs it otherwise.
+   * null when its location can't be determined.
+   */
+  recorderFfmpeg: {
+    found: boolean;
+    path: string;
+    revision: string;
+    install: string;
+    autoInstall: boolean;
+  } | null;
   skill: {
     target: string;
     installed: { version: string; stableAvailable: string | null } | null;
@@ -667,6 +685,11 @@ export interface DoctorReport {
   ok: boolean;
 }
 
+/** Oldest supported Node major (bin/aidemo.mjs fails fast below it; package.json "engines"). */
+const MIN_NODE_MAJOR = 22;
+const nodeSupported = (version: string): boolean =>
+  Number(version.replace(/^v/, "").split(".")[0]) >= MIN_NODE_MAJOR;
+
 /** Build the structured preflight report (used by CLI doctor + MCP doctor). */
 export async function doctorReport(dir: string | undefined): Promise<DoctorReport> {
   const base = openAiBaseUrl();
@@ -694,6 +717,7 @@ export async function doctorReport(dir: string | undefined): Promise<DoctorRepor
   const localTts = ttsProvider() === "local" ? await localTtsStatus() : null;
   const chrome = await probeChrome();
   const browser = await probeBrowserTarget(chrome);
+  const helper = recorderFfmpeg();
   const report: DoctorReport = {
     engineVersion: latest,
     node: process.version,
@@ -725,6 +749,15 @@ export async function doctorReport(dir: string | undefined): Promise<DoctorRepor
         : {}),
     },
     playwright: playwrightOk,
+    recorderFfmpeg: helper
+      ? {
+          found: await exists(helper.path),
+          path: helper.path,
+          revision: helper.revision,
+          install: helper.install,
+          autoInstall: recorderAutoInstall(),
+        }
+      : null,
     skill: {
       target,
       installed: manifest
@@ -738,9 +771,11 @@ export async function doctorReport(dir: string | undefined): Promise<DoctorRepor
     ok: false,
   };
   report.ok = Boolean(
-    report.ffmpeg &&
+    nodeSupported(report.node) &&
+      report.ffmpeg &&
       report.browser.found &&
       report.playwright &&
+      (report.recorderFfmpeg ? report.recorderFfmpeg.found || report.recorderFfmpeg.autoInstall : true) &&
       // Local TTS needs no key: voice is in-process, captions auto-fall-back
       // to the offline derivation in `render`.
       (report.apiKey !== "missing" || report.tts.provider === "local") &&
@@ -758,7 +793,8 @@ export async function doctor(dir: string | undefined): Promise<void> {
   const line = (label: string, val: string | null) =>
     val ? ok(`${label}: ${val}`) : fail(`${label}: NOT FOUND`);
 
-  line("node", r.node);
+  if (nodeSupported(r.node)) ok(`node: ${r.node}`);
+  else fail(`node: ${r.node} — aidemo needs Node ${MIN_NODE_MAJOR}+ (Node 20 is end-of-life)`);
   line("ffmpeg", r.ffmpeg);
   if (r.browser.source === "default") {
     line("chrome", r.chrome);
@@ -806,6 +842,20 @@ export async function doctor(dir: string | undefined): Promise<void> {
   );
   if (r.playwright) ok(`playwright: resolvable`);
   else fail(`playwright: not installed`);
+  const helper = r.recorderFfmpeg;
+  if (helper?.found) {
+    ok(`playwright ffmpeg helper: revision ${helper.revision} (records the take)`);
+  } else if (helper?.autoInstall) {
+    log(
+      `playwright ffmpeg helper: revision ${helper.revision} not installed yet — the first ` +
+        `take installs it (~2 MB from Playwright's CDN); or now: ${helper.install}`
+    );
+  } else if (helper) {
+    fail(
+      `playwright ffmpeg helper: revision ${helper.revision} NOT FOUND at ${helper.path} and ` +
+        `AIDEMO_NO_AUTO_INSTALL is set — every take fails without it: ${helper.install}`
+    );
+  }
 
   if (r.skill.installed) {
     ok(

package/src/mcp/server.ts

@@ -556,7 +556,9 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
       description:
         "Check prereqs: node, ffmpeg, Chrome (or the AIDEMO_CHROME_CHANNEL / " +
         "AIDEMO_CHROME_EXECUTABLE browser in use), TTS/STT endpoint (flags " +
-        "LLM-only servers like Ollama), API key, playwright, installed skill.",
+        "LLM-only servers like Ollama), API key, playwright + its ffmpeg " +
+        "helper (records the take; installed on the first take unless " +
+        "AIDEMO_NO_AUTO_INSTALL=1), installed skill.",
       inputSchema: {
         dir: z.string().optional().describe("repo to check for an installed skill"),
       },
@@ -586,6 +588,18 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           elevenLabsKey: z.enum(["set", "missing"]).optional(),
         }),
         playwright: z.boolean(),
+        recorderFfmpeg: z
+          .object({
+            found: z.boolean(),
+            path: z.string(),
+            revision: z.string(),
+            install: z.string().describe("exact command to install it"),
+            autoInstall: z
+              .boolean()
+              .describe("the first take installs it (off with AIDEMO_NO_AUTO_INSTALL=1)"),
+          })
+          .nullable()
+          .describe("Playwright's ffmpeg helper the built-in capture records with"),
         skill: z.object({
           target: z.string(),
           installed: z

package/src/recorder.ts

@@ -1,4 +1,4 @@
-import { describeChromeTarget, launchChromePersistent } from "./browser.js";
+import { describeChromeTarget, ensureRecorderFfmpeg, launchChromePersistent } from "./browser.js";
 import { promises as fs } from "node:fs";
 import {
   TimelineSchema,
@@ -316,6 +316,10 @@ export async function record(
   const screenCapPath = join(videoDir, "capture.mkv");
   await fs.rm(screenCapPath, { force: true });
 
+  // The built-in capture encodes the take with Playwright's ffmpeg helper,
+  // which a fresh install (or a Playwright upgrade) may not have yet.
+  if (!external) await ensureRecorderFfmpeg();
+
   let context;
   try {
     context = await launchChromePersistent(profileDir, {