@argo-video/cli 0.1.0 → 0.2.0

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

package/docs/enhancement-proposal.md

@@ -1,262 +0,0 @@
-# Enhancement Proposal: Editorial Overlay System
-
-## Summary
-
-Argo's current caption system renders a single bottom-centered text pill. That's enough for narration subtitles but not for editorial demo videos where text feels composed into the frame — headline cards with kicker/title/body hierarchy, callout annotations, image-backed panels at different screen positions.
-
-This proposal evolves `src/captions.ts` from a single-style caption helper into a zone-based overlay system with pluggable templates.
-
-## Goals
-
-- Make captions feel designed, not appended.
-- Support editorial overlays: headline cards, callouts, image-backed panels.
-- Keep narration timing and overlay visuals separate so demos stay easy to author.
-- Preserve the simple default path — `showCaption` and `withCaption` continue to work unchanged.
-
-## Current System
-
-```
-captions.ts
-├── OVERLAY_ID = 'argo-caption-overlay'     ← single element, replaced on each call
-├── CAPTION_STYLES = { ... }                ← one hardcoded style object
-├── injectOverlay(page, text)               ← creates div, sets textContent + styles
-├── showCaption(page, scene, text, dur)     ← inject → wait → remove
-├── withCaption(page, scene, text, action)  ← inject → action → remove (try/finally)
-└── hideCaption(page)                       ← remove by ID
-```
-
-Limitations:
-- One overlay type, one placement, one visual treatment.
-- Single DOM element — showing a new caption removes the previous one globally.
-- No support for images, rich cards, or animation.
-- No way to have two overlays visible simultaneously (e.g., subtitle + headline card).
-
-## Design Decisions
-
-### Zone-based coexistence
-
-Overlays are placed into **zones**. Each zone is a screen region that holds at most one overlay at a time. Showing an overlay in a zone automatically replaces any existing overlay in that zone, but overlays in different zones coexist independently.
-
-Zones:
-- `bottom-center` (default — current caption position)
-- `top-left`
-- `top-right`
-- `bottom-left`
-- `bottom-right`
-- `center`
-
-DOM IDs become `argo-overlay-{zone}` instead of the current single `argo-caption-overlay`.
-
-This gives editorial power (subtitle + headline card visible simultaneously) without requiring manual dismissal of every overlay.
-
-### Asset injection via local server
-
-Image overlays (`image-card`) reference local files like `assets/diagram.png`. These need to be accessible inside the Playwright browser context.
-
-**Approach: local asset server.** A tiny HTTP server (same pattern as the E2E fake server) serves files from the project's asset directory during recording. It starts automatically before `record` and stops after.
-
-Why not base64 data URIs: a 2MB screenshot becomes ~2.7MB of serialized DOM, slowing `page.evaluate`. Asset server keeps the DOM clean and scales to many images.
-
-### Templates, not a theme system
-
-v1 ships with hardcoded visual presets per template — no theme tokens. Each template has one opinionated look that works well on dark and light backgrounds. Theme customization (typography, colors, spacing tokens) is a future enhancement once real usage patterns emerge.
-
-### Motion: two presets only
-
-CSS animations during Playwright recording are frame-rate dependent. v1 supports two safe presets:
-- `fade-in` — opacity 0→1 over 300ms
-- `slide-in` — translateX + opacity over 400ms
-
-Staggered multi-element reveals (kicker, then title, then body) are deferred to v2 — they require careful timing coordination that's hard to get right at variable recording FPS.
-
-## Overlay Templates
-
-### `lower-third` (default)
-
-The current caption style, refined. Bottom-center translucent pill with text.
-
-```
-┌─────────────────────────────────────────┐
-│                                         │
-│                                         │
-│                                         │
-│    ┌─────────────────────────────┐      │
-│    │  Caption text here          │      │
-│    └─────────────────────────────┘      │
-└─────────────────────────────────────────┘
-```
-
-Fields: `text`
-
-### `headline-card`
-
-A card with optional kicker (small caps label), title (large), and body (smaller). Backdrop blur + translucent background.
-
-```
-┌─────────────────────────────────────────┐
-│  ┌──────────────────────┐               │
-│  │  KICKER LABEL        │               │
-│  │  Title text here     │               │
-│  │  Body text here      │               │
-│  └──────────────────────┘               │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-Fields: `kicker?`, `title`, `body?`
-
-### `callout`
-
-A compact annotation bubble for pointing out UI elements. Meant for short text.
-
-Fields: `text`
-
-### `image-card`
-
-An image with optional title and body caption below it. Image loaded from the asset server.
-
-```
-┌─────────────────────────────────────────┐
-│               ┌─────────────────┐       │
-│               │  ┌───────────┐  │       │
-│               │  │   image   │  │       │
-│               │  └───────────┘  │       │
-│               │  Title          │       │
-│               │  Body text      │       │
-│               └─────────────────┘       │
-└─────────────────────────────────────────┘
-```
-
-Fields: `src`, `title?`, `body?`
-
-## Authoring Model
-
-### Overlay manifest (`demos/example.overlays.json`)
-
-A new file, separate from the voiceover manifest. Maps scenes to overlay cues.
-
-```json
-[
-  {
-    "scene": "intro",
-    "type": "lower-third",
-    "text": "Hacker News — the front page of the internet"
-  },
-  {
-    "scene": "browse",
-    "type": "headline-card",
-    "placement": "top-left",
-    "kicker": "LOCAL EXECUTION",
-    "title": "WebGPU + Transformers.js",
-    "body": "Models cache after first load.",
-    "motion": "slide-in"
-  },
-  {
-    "scene": "rerank",
-    "type": "image-card",
-    "placement": "top-right",
-    "src": "assets/rerank-diagram.png",
-    "title": "Cross-encoder reranking"
-  }
-]
-```
-
-Rules:
-- `scene` links to `narration.mark()` calls in the demo script.
-- `type` selects the template. Default: `lower-third`.
-- `placement` selects the zone. Default: `bottom-center`.
-- `motion` selects the entrance animation. Default: none (instant appear).
-- Template-specific fields (`kicker`, `title`, `body`, `src`, `text`) vary by type.
-
-### Programmatic API
-
-The existing `showCaption`/`withCaption` API stays unchanged as sugar for `lower-third` overlays. New overlays are shown via a new function:
-
-```ts
-import { showOverlay, hideOverlay, withOverlay } from 'argo';
-
-// Show a headline card in the top-left zone
-await showOverlay(page, 'browse', {
-  type: 'headline-card',
-  placement: 'top-left',
-  kicker: 'LOCAL EXECUTION',
-  title: 'WebGPU + Transformers.js',
-  motion: 'slide-in',
-}, 4000);
-
-// Hide a specific zone
-await hideOverlay(page, 'top-left');
-
-// Overlay around an action
-await withOverlay(page, 'rerank', {
-  type: 'image-card',
-  placement: 'top-right',
-  src: 'assets/diagram.png',
-  title: 'Reranking pipeline',
-}, async () => {
-  await page.click('.rerank-button');
-});
-```
-
-Backward compatibility: `showCaption(page, scene, text, dur)` becomes equivalent to `showOverlay(page, scene, { type: 'lower-third', text }, dur)`.
-
-### Auto-overlay from manifest
-
-When a `<demo>.overlays.json` file exists alongside the voiceover manifest, the recording fixture automatically injects overlays at their matching `narration.mark()` timestamps. This means users can define overlays purely in JSON without touching the demo script — the programmatic API is for advanced use only.
-
-## Implementation Plan
-
-### Phase 1: Zone-based overlay renderer
-
-1. Refactor `src/captions.ts` → `src/overlays.ts`
-   - Replace single `OVERLAY_ID` with `argo-overlay-{zone}` scheme
-   - Extract template rendering into a `renderTemplate(type, fields)` → HTML+styles function
-   - Implement `lower-third` template (current caption style, now zone-aware)
-   - Implement `showOverlay`, `hideOverlay`, `withOverlay`
-   - Re-export `showCaption`, `withCaption`, `hideCaption` as thin wrappers
-
-2. Add CSS animation injection for `fade-in` and `slide-in` presets
-
-3. Update `src/index.ts` exports
-
-### Phase 2: Editorial templates
-
-4. Implement `headline-card` template (kicker + title + body, backdrop blur)
-5. Implement `callout` template
-6. Implement `image-card` template
-
-### Phase 3: Asset server + image support
-
-7. Extract `tests/e2e/fake-server.ts` pattern into `src/asset-server.ts`
-   - Serves files from a configurable asset directory
-   - Auto-starts before recording, auto-stops after
-   - Only starts if an overlay manifest references image assets
-
-8. Wire asset server URL into `image-card` template `src` resolution
-
-### Phase 4: Manifest-driven overlays
-
-9. Define overlay manifest schema and loader in `src/overlays/manifest.ts`
-10. Wire manifest loading into the recording fixture
-    - If `<demo>.overlays.json` exists, auto-inject overlays at matching scene marks
-
-### Phase 5: Polish
-
-11. Update `argo init` templates with overlay examples
-12. Update README with overlay documentation
-13. Add tests for each template, zone management, and manifest loading
-
-## Migration
-
-- `showCaption`, `withCaption`, `hideCaption` remain exported and unchanged.
-- Existing demos work without modification.
-- The overlay manifest is optional — demos without one behave exactly as before.
-- `src/captions.ts` is replaced by `src/overlays.ts` but all original exports are preserved.
-
-## Out of Scope (v1)
-
-- Theme tokens / custom styling
-- Staggered multi-element animation
-- Overlay transitions (exit animations)
-- Overlay positioning relative to DOM elements (e.g., "anchor to this button")
-- Video-time overlays via ffmpeg (all overlays render in-browser during recording)