@argo-video/cli 0.1.0 → 0.1.1

package/dist/tts/generate.js

@@ -0,0 +1,58 @@
+/**
+ * TTS clip generation with manifest parsing and cache integration.
+ */
+import fs from 'node:fs';
+import { ClipCache } from './cache.js';
+export async function generateClips(options) {
+    const { manifestPath, demoName, engine, projectRoot, defaults } = options;
+    // 1. Check manifest exists
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Manifest file not found: ${manifestPath}`);
+    }
+    // 2. Read and parse JSON
+    let rawEntries;
+    try {
+        const content = fs.readFileSync(manifestPath, 'utf-8');
+        rawEntries = JSON.parse(content);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`Failed to parse manifest ${manifestPath}: ${err.message}`);
+        }
+        throw err;
+    }
+    if (!Array.isArray(rawEntries)) {
+        throw new Error(`Manifest ${manifestPath} must contain a JSON array`);
+    }
+    // 3. Validate entries
+    for (const entry of rawEntries) {
+        const e = entry;
+        if (typeof e.scene !== 'string' || typeof e.text !== 'string') {
+            throw new Error('Manifest entry missing required field: scene and text are required');
+        }
+    }
+    const cache = new ClipCache(projectRoot);
+    const results = [];
+    for (const raw of rawEntries) {
+        const r = raw;
+        // 4. Build ManifestEntry with defaults
+        const manifestEntry = {
+            scene: r.scene,
+            text: r.text,
+            voice: r.voice ?? defaults?.voice,
+            speed: r.speed ?? defaults?.speed,
+        };
+        const clipPath = cache.getClipPath(demoName, manifestEntry);
+        // 5/6. Check cache or generate
+        if (!cache.isCached(demoName, manifestEntry)) {
+            const wavBuffer = await engine.generate(manifestEntry.text, {
+                voice: manifestEntry.voice,
+                speed: manifestEntry.speed,
+            });
+            cache.cacheClip(demoName, manifestEntry, wavBuffer);
+        }
+        results.push({ scene: manifestEntry.scene, clipPath });
+    }
+    return results;
+}
+//# sourceMappingURL=generate.js.map

package/dist/tts/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/tts/generate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAe3D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE1E,2BAA2B;IAC3B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,4BAA4B,YAAY,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,yBAAyB;IACzB,IAAI,UAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,4BAA4B,YAAY,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,YAAY,YAAY,4BAA4B,CAAC,CAAC;IACxE,CAAC;IAED,sBAAsB;IACtB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,WAAW,CAAC,CAAC;IACzC,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,GAA8B,CAAC;QAEzC,uCAAuC;QACvC,MAAM,aAAa,GAAkB;YACnC,KAAK,EAAE,CAAC,CAAC,KAAe;YACxB,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,KAAK,EAAG,CAAC,CAAC,KAA4B,IAAI,QAAQ,EAAE,KAAK;YACzD,KAAK,EAAG,CAAC,CAAC,KAA4B,IAAI,QAAQ,EAAE,KAAK;SAC1D,CAAC;QAEF,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QAE5D,+BAA+B;QAC/B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,CAAC;YAC7C,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE;gBAC1D,KAAK,EAAE,aAAa,CAAC,KAAK;gBAC1B,KAAK,EAAE,aAAa,CAAC,KAAK;aAC3B,CAAC,CAAC;YACH,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/tts/kokoro.d.ts

@@ -0,0 +1,13 @@
+import type { TTSEngine, TTSEngineOptions } from './engine.js';
+export declare class KokoroEngine implements TTSEngine {
+    private tts;
+    private modelId;
+    private dtype;
+    constructor(options?: {
+        modelId?: string;
+        dtype?: string;
+    });
+    private getTTS;
+    generate(text: string, options: TTSEngineOptions): Promise<Buffer>;
+}
+//# sourceMappingURL=kokoro.d.ts.map

package/dist/tts/kokoro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kokoro.d.ts","sourceRoot":"","sources":["../../src/tts/kokoro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;YAK5C,MAAM;IAiBd,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAqBzE"}

package/dist/tts/kokoro.js

@@ -0,0 +1,46 @@
+export class KokoroEngine {
+    tts = null;
+    modelId;
+    dtype;
+    constructor(options) {
+        this.modelId = options?.modelId ?? 'onnx-community/Kokoro-82M-ONNX';
+        this.dtype = options?.dtype ?? 'fp32';
+    }
+    async getTTS() {
+        if (this.tts)
+            return this.tts;
+        try {
+            const { KokoroTTS } = await import('kokoro-js');
+            this.tts = await KokoroTTS.from_pretrained(this.modelId, {
+                dtype: this.dtype,
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to initialize Kokoro TTS (model: ${this.modelId}, dtype: ${this.dtype}). ` +
+                `This may require an internet connection for first-time model download. ` +
+                `Original error: ${err.message}`);
+        }
+        return this.tts;
+    }
+    async generate(text, options) {
+        if (!text?.trim())
+            throw new Error('TTS text must not be empty');
+        const tts = await this.getTTS();
+        const audio = await tts.generate(text, {
+            voice: options.voice ?? 'af_heart',
+            speed: options.speed ?? 1.0,
+        });
+        const samples = audio.data ?? audio.audio;
+        if (!samples || !(samples instanceof Float32Array)) {
+            throw new Error('kokoro-js returned unexpected audio format: neither .data nor .audio contains Float32Array samples. ' +
+                'Check that your kokoro-js version is compatible.');
+        }
+        const sampleRate = audio.sampling_rate;
+        if (typeof sampleRate !== 'number' || sampleRate <= 0) {
+            throw new Error(`kokoro-js returned invalid sample rate: ${sampleRate}.`);
+        }
+        const { createWavBuffer } = await import('./engine.js');
+        return createWavBuffer(samples, sampleRate);
+    }
+}
+//# sourceMappingURL=kokoro.js.map

package/dist/tts/kokoro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kokoro.js","sourceRoot":"","sources":["../../src/tts/kokoro.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,YAAY;IACf,GAAG,GAAQ,IAAI,CAAC;IAChB,OAAO,CAAS;IAChB,KAAK,CAAS;IAEtB,YAAY,OAA8C;QACxD,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,gCAAgC,CAAC;QACpE,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,MAAM,CAAC;IACxC,CAAC;IAEO,KAAK,CAAC,MAAM;QAClB,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;YAChD,IAAI,CAAC,GAAG,GAAG,MAAM,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE;gBACvD,KAAK,EAAE,IAAI,CAAC,KAAgD;aAC7D,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,OAAO,YAAY,IAAI,CAAC,KAAK,KAAK;gBAClF,yEAAyE;gBACzE,mBAAoB,GAAa,CAAC,OAAO,EAAE,CAC5C,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAyB;QACpD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;YACrC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,UAAU;YAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG;SAC5B,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC;QAC1C,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,YAAY,YAAY,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,sGAAsG;gBACtG,kDAAkD,CACnD,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC;QACvC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,2CAA2C,UAAU,GAAG,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxD,OAAO,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC9C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@argo-video/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn Playwright demo scripts into polished product demo videos with AI voiceover",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,6 +28,18 @@
     "commander": "^12.0.0",
     "kokoro-js": "^1.2.1"
   },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shreyaskarnik/argo.git"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "bin"
+  ],
   "devDependencies": {
     "@playwright/test": "^1.50.0",
     "@types/node": "^25.5.0",

package/.claude/settings.local.json

@@ -1,34 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(gh repo:*)",
-      "Bash(gh api:*)",
-      "Bash(/Users/shreyas/work/rnd/argo/bin/argo.js:*)",
-      "Bash(chmod +x /Users/shreyas/work/rnd/argo/bin/argo.js)",
-      "Bash(npm install:*)",
-      "Bash(npx tsc:*)",
-      "Bash(ls /Users/shreyas/work/rnd/argo/src/ /Users/shreyas/work/rnd/argo/tests/ 2>/dev/null; ls /Users/shreyas/work/rnd/argo/vitest.config.* 2>/dev/null)",
-      "Bash(npx vitest:*)",
-      "Bash(CI=true npx vitest run tests/tts/kokoro.test.ts 2>&1)",
-      "mcp__plugin_context7_context7__resolve-library-id",
-      "mcp__plugin_context7_context7__query-docs",
-      "Bash(node -e \"\nimport\\('@huggingface/transformers'\\).then\\(async \\(m\\) => {\n  // Check what task maps to what\n  console.log\\('SUPPORTED_TASKS keys that include audio or speech:'\\);\n  const keys = Object.keys\\(m\\).filter\\(k => k.toLowerCase\\(\\).includes\\('task'\\) || k.toLowerCase\\(\\).includes\\('mapping'\\)\\);\n  console.log\\(keys.slice\\(0, 20\\)\\);\n}\\).catch\\(e => console.error\\(e.message\\)\\);\n\" 2>&1)",
-      "Bash(node -e \"\nimport\\('@huggingface/transformers'\\).then\\(async \\(m\\) => {\n  try {\n    const p = await m.pipeline\\('text-to-audio', 'onnx-community/Kokoro-82M-v1.0-ONNX', { dtype: 'fp32' }\\);\n    console.log\\('SUCCESS with text-to-audio'\\);\n  } catch\\(e\\) {\n    console.log\\('text-to-audio error:', e.message\\);\n  }\n}\\).catch\\(e => console.error\\(e.message\\)\\);\n\" 2>&1)",
-      "Bash(npm ls:*)",
-      "Bash(npm run:*)",
-      "Bash(node bin/argo.js init 2>&1)",
-      "Bash(node bin/argo.js --help 2>&1)",
-      "Bash(rm -rf demos argo.config.ts && node bin/argo.js init 2>&1)",
-      "Bash(git rm:*)",
-      "Bash(rm -f argo.config.ts argo.config.js && rm -rf demos/ && npm run build 2>&1 && node bin/argo.js init 2>&1)",
-      "Bash(node -e \"import\\('./dist/config.js'\\).then\\(m => m.loadConfig\\(process.cwd\\(\\)\\)\\).then\\(c => console.log\\(JSON.stringify\\(c, null, 2\\)\\)\\)\" 2>&1)",
-      "Bash(rm -rf demos argo.config.* playwright.config.ts && npm run build 2>&1 && node bin/argo.js init 2>&1)",
-      "Bash(node bin/argo.js record example 2>&1)",
-      "Bash(npx playwright:*)",
-      "Bash(npm link:*)",
-      "Bash(node bin/argo.js pipeline example 2>&1)"
-    ]
-  }
-}

package/DESIGN.md

@@ -1,261 +0,0 @@
-# Argo — Playwright Demo Recording with Voiceover
-
-**Date:** 2026-03-12
-**Status:** Draft
-
-## Overview
-
-Argo is a standalone, open-source tool that turns Playwright scripts into polished product demo videos with AI-generated voiceover. Developers author demo scripts using Playwright fixtures; anyone can regenerate the final video with a single CLI command.
-
-The pipeline: **TTS** (Kokoro generates voiceover clips via Transformers.js, cached) → **record** (Playwright captures video + scene timestamps) → **align** (clips placed at recorded timestamps) → **export** (ffmpeg merges video + audio into MP4).
-
-## Target Users
-
-- **Developers** author demo scripts using Playwright's familiar test API
-- **Non-developers** (marketing, DevRel) regenerate videos via CLI without touching code
-
-## Architecture
-
-### Library + CLI
-
-Argo ships as a single package with two interfaces:
-
-**Library** — Playwright fixtures and helpers for authoring demos:
-- `test`, `expect` — re-exported Playwright fixtures with `narration` auto-injected
-- `NarrationTimeline` — low-level control for manual usage
-- `showCaption`, `hideCaption`, `withCaption` — DOM caption helpers
-- `defineConfig` — creates a full Argo config with sensible defaults
-- `demosProject` — creates a Playwright project entry for integration into existing configs
-
-**CLI** — pipeline commands anyone can run:
-- `argo record <demo>` — run Playwright for a specific demo
-- `argo tts generate <manifest>` — generate TTS clips from `.voiceover.json`
-- `argo tts align <demo>` — align clips to recording timestamps
-- `argo export <demo>` — merge video + audio via ffmpeg
-- `argo pipeline <demo>` — all steps end-to-end
-- `argo init` — scaffold demo files + config into a project
-
-### Project Layout
-
-```
-argo/
-├── src/
-│   ├── index.ts          # Library exports
-│   ├── cli.ts            # CLI entry point
-│   ├── fixtures.ts       # Playwright test fixture (injects narration)
-│   ├── narration.ts      # NarrationTimeline class
-│   ├── captions.ts       # DOM caption overlay helpers
-│   ├── tts/
-│   │   ├── engine.ts     # TTSEngine interface
-│   │   ├── kokoro.ts     # Default Kokoro via @huggingface/transformers
-│   │   └── align.ts      # Timestamp alignment logic
-│   ├── export.ts         # ffmpeg video+audio merge
-│   ├── pipeline.ts       # Orchestrates record→tts→align→export
-│   └── config.ts         # defineConfig helper + defaults
-├── bin/
-│   └── argo.js           # CLI bin entry
-├── package.json
-└── tsconfig.json
-```
-
-### Dependencies
-
-- `playwright` — recording engine (peer dependency)
-- `@huggingface/transformers@next` — Kokoro TTS via ONNX in Node.js
-- `ffmpeg` — system dependency for video export (not bundled)
-
-No Python required. The entire pipeline runs in Node.js.
-
-**ffmpeg detection:** All CLI commands that need ffmpeg (`export`, `pipeline`) check for it on startup and exit with a clear error message + install instructions if missing.
-
-## Authoring API
-
-A demo consists of two files:
-
-### Demo Script (`demos/onboarding.demo.ts`)
-
-```ts
-import { test, demoType } from 'argo';
-
-test('onboarding', async ({ page, narration }) => {
-  // narration.start() is called automatically by the fixture before the test runs
-  await page.goto('/');
-
-  // Show caption + record scene timestamp
-  await narration.showCaption(page, 'welcome', 'Welcome to our app', 3000);
-
-  // Caption around an action
-  await narration.withCaption(page, 'signup', 'Sign up in seconds', async () => {
-    await page.fill('[name=email]', 'demo@example.com');
-    await demoType(page, '[name=password]', 'supersecure');
-  });
-
-  // Timestamp-only scene (no visible caption, used for voiceover alignment)
-  narration.mark('dashboard-loaded');
-});
-```
-
-**Constraints:** Each demo file must contain exactly one `test()` block (one video per demo). Use separate demo files for separate videos.
-
-**Key API:**
-- `narration.showCaption(page, scene, text, durationMs)` — show overlay + record timestamp
-- `narration.withCaption(page, scene, text, action)` — wrap action with caption
-- `narration.mark(scene)` — record timestamp without visual
-- `demoType(page, selector, text)` — standalone helper, slow-types for demo effect (60ms/char)
-- `narration.start()` — sets timestamp zero; called automatically by fixture before each test
-- `narration.flush()` — writes `.timing.json`; called automatically by fixture after each test
-
-### Voiceover Manifest (`demos/onboarding.voiceover.json`)
-
-```json
-[
-  {
-    "scene": "welcome",
-    "text": "Welcome to Acme — get started in under a minute."
-  },
-  {
-    "scene": "signup",
-    "text": "Just enter your email and choose a password.",
-    "speed": 0.9
-  },
-  {
-    "scene": "dashboard-loaded",
-    "text": "And you're in.",
-    "voice": "af_heart"
-  }
-]
-```
-
-Scene names link the manifest to the demo script. `voice` and `speed` are optional (defaults from config).
-
-### Config (`argo.config.ts`, optional)
-
-The CLI looks for `argo.config.ts` (or `.js`, `.mjs`) in the current working directory. Override with `--config <path>` on any CLI command.
-
-```ts
-import { defineConfig } from 'argo';
-
-export default defineConfig({
-  baseURL: 'http://localhost:3000',
-  demosDir: 'demos/',
-  outputDir: 'videos/',
-  tts: {
-    defaultVoice: 'af_heart',
-    defaultSpeed: 1.0,
-    // engine: myCustomTTSEngine
-  },
-  video: {
-    width: 2560,
-    height: 1440,
-    fps: 30,
-  },
-  export: {
-    preset: 'slow',
-    crf: 16,
-  },
-});
-```
-
-## TTS System
-
-### Default Engine: Kokoro via Transformers.js
-
-- Uses `@huggingface/transformers@next` with ONNX Kokoro model
-- Runs in Node.js — no Python, no GPU
-- Model downloaded on first run (~80MB ONNX), cached locally
-- Generates one WAV clip per scene
-
-### Alignment
-
-1. Recording produces `.timing.json` (scene name → millisecond timestamp)
-2. Aligner reads `.timing.json` + clip durations
-3. Places each clip at its scene's recorded timestamp
-4. Prevents overlap — clips pushed forward with 100ms minimum gap
-5. Outputs single `narration-aligned.wav` matching video duration
-
-### Plugin Interface
-
-```ts
-interface TTSEngine {
-  generate(text: string, options: {
-    voice?: string;
-    speed?: number;
-    lang?: string;
-  }): Promise<Buffer>;
-  // Must return a complete WAV file (with headers).
-  // Required format: mono, 24kHz, 32-bit float.
-  // Argo will resample if needed, but matching this format avoids overhead.
-}
-```
-
-Custom engines (ElevenLabs, OpenAI TTS, Piper, etc.) implement this single method. Argo validates the returned WAV headers and resamples to 24kHz mono if the format doesn't match.
-
-### Clip Caching
-
-Clips stored in `.argo/<demoName>/clips/`. Each clip is keyed by a hash of its manifest entry (`scene` + `text` + `voice` + `speed`). When a clip's entry hasn't changed, the cached WAV is reused. When an entry changes (different text, voice, or speed), only that clip is regenerated. This is per-entry, not per-file — reordering entries or changing one scene doesn't invalidate others.
-
-## Recording
-
-- `argo record` runs Playwright with the demos project config
-- Uses Playwright's default VP8 encoder (no patching)
-- Higher quality achieved during export via ffmpeg re-encoding
-- Output: `video.webm` + `.timing.json` in `.argo/<demoName>/`
-
-## Export
-
-- ffmpeg merges video + aligned audio
-- Re-encodes to `libx264` (compensates for VP8's lower quality)
-- Default: preset slow, crf 16, AAC audio @ 192k
-- Configurable via `argo.config.ts` or CLI flags (`--crf`, `--preset`, `--fps`, `--width`, `--height`)
-- Uses `-shortest` so audio trims to video length
-- Output: `<outputDir>/<demoName>.mp4`
-
-## Pipeline
-
-`argo pipeline <demo>` chains all steps:
-
-```
-1. Generate TTS clips (skip if cached & manifest unchanged)
-2. Record demo via Playwright → .webm + .timing.json
-3. Align clips to timestamps → narration-aligned.wav
-4. Export → final .mp4
-```
-
-Each step is independently runnable.
-
-## `argo init`
-
-Scaffolds into an existing project:
-- Creates `demos/` directory
-- Generates sample `example.demo.ts` and `example.voiceover.json`
-- Creates starter `argo.config.ts`
-- Adds `demos` project to `playwright.config.ts` (or creates one) using `defineConfig`
-- Prints next steps
-
-## Playwright Integration
-
-Two modes:
-
-**Standalone** — Argo provides its own Playwright config via `defineConfig`. Users just install and point at their app URL. `argo init` sets this up.
-
-**Integrated** — Power users add a `demos` project to their existing `playwright.config.ts` using the exported config helper:
-
-```ts
-import { demosProject } from 'argo';
-
-export default defineConfig({
-  projects: [
-    // ... existing projects
-    demosProject({ baseURL: 'http://localhost:3000' }),
-  ],
-});
-```
-
-## Out of Scope (v1)
-
-- Post-render subtitle burn-in via ffmpeg (future enhancement)
-- npm registry publishing
-- Non-Playwright backends (Puppeteer, Cypress)
-- Video editing (cuts, transitions, zooms)
-- Background music / audio mixing
-- GUI / visual editor