@argo-video/cli 0.1.0

package/src/export.ts

@@ -0,0 +1,93 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface ExportOptions {
+  demoName: string;
+  argoDir: string;
+  outputDir: string;
+  preset?: string;
+  crf?: number;
+  fps?: number;
+}
+
+/**
+ * Check whether ffmpeg is available on the system PATH.
+ * Returns true if found, throws with install instructions otherwise.
+ */
+export function checkFfmpeg(): boolean {
+  try {
+    execFileSync('ffmpeg', ['-version'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    throw new Error(
+      'ffmpeg is not installed. Install it with:\n' +
+        '  macOS:   brew install ffmpeg\n' +
+        '  Linux:   apt install ffmpeg\n' +
+        '  Windows: choco install ffmpeg',
+    );
+  }
+}
+
+/**
+ * Export a demo to MP4 by combining the screen recording with aligned narration audio.
+ */
+export async function exportVideo(options: ExportOptions): Promise<string> {
+  const {
+    demoName,
+    argoDir,
+    outputDir,
+    preset = 'slow',
+    crf = 16,
+    fps,
+  } = options;
+
+  checkFfmpeg();
+
+  const demoDir = join(argoDir, demoName);
+  const videoPath = join(demoDir, 'video.webm');
+  const audioPath = join(demoDir, 'narration-aligned.wav');
+
+  if (!existsSync(videoPath)) {
+    throw new Error(`Missing video.webm at ${videoPath}`);
+  }
+  if (!existsSync(audioPath)) {
+    throw new Error(`Missing narration-aligned.wav at ${audioPath}`);
+  }
+
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const outputPath = join(outputDir, `${demoName}.mp4`);
+
+  const args: string[] = [
+    '-i', videoPath,
+    '-i', audioPath,
+    '-c:v', 'libx264',
+    '-preset', preset,
+    '-crf', String(crf),
+    '-c:a', 'aac',
+    '-b:a', '192k',
+  ];
+
+  if (fps !== undefined) {
+    args.push('-r', String(fps));
+  }
+
+  args.push('-shortest', '-y', outputPath);
+
+  const result = spawnSync('ffmpeg', args, { stdio: 'inherit' });
+
+  if (result.error) {
+    throw new Error(`Failed to launch ffmpeg: ${result.error.message}`);
+  }
+  if (result.signal) {
+    throw new Error(`ffmpeg was killed by signal ${result.signal}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`ffmpeg failed with exit code ${result.status}`);
+  }
+
+  return outputPath;
+}

package/src/fixtures.ts

@@ -0,0 +1,50 @@
+import { test as base, expect } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import { NarrationTimeline } from './narration.js';
+
+type TimelineFactory = (title: string) => NarrationTimeline;
+
+const defaultFactory: TimelineFactory = () => new NarrationTimeline();
+
+export function createNarrationFixture(factory: TimelineFactory = defaultFactory) {
+  return async (
+    _context: Record<string, unknown>,
+    use: (timeline: NarrationTimeline) => Promise<void>,
+    testInfo: { title: string },
+  ) => {
+    const timeline = factory(testInfo.title);
+    timeline.start();
+    try {
+      await use(timeline);
+    } finally {
+      await timeline.flush(`narration-${testInfo.title}.json`);
+    }
+  };
+}
+
+export async function demoType(
+  page: Page,
+  selector: string,
+  text: string,
+  delay = 60,
+): Promise<void> {
+  await page.locator(selector).pressSequentially(text, { delay });
+}
+
+export const test = base.extend<{ narration: NarrationTimeline }>({
+  narration: async ({}, use, testInfo) => {
+    const timeline = new NarrationTimeline();
+    timeline.start();
+    try {
+      await use(timeline);
+    } finally {
+      const argoDir = process.env.ARGO_OUTPUT_DIR;
+      const outputPath = argoDir
+        ? `${argoDir}/.timing.json`
+        : `narration-${testInfo.title}.json`;
+      await timeline.flush(outputPath);
+    }
+  },
+});
+
+export { expect };

package/src/index.ts

@@ -0,0 +1,41 @@
+// Argo — Playwright demo recording with AI voiceover
+
+// Config
+export {
+  defineConfig,
+  loadConfig,
+  demosProject,
+  type ArgoConfig,
+  type UserConfig,
+  type TTSConfig,
+  type TTSEngine,
+  type VideoConfig,
+  type ExportConfig,
+} from './config.js';
+
+// Fixtures
+export { test, expect, demoType } from './fixtures.js';
+
+// Narration
+export { NarrationTimeline } from './narration.js';
+
+// Captions
+export { showCaption, hideCaption, withCaption } from './captions.js';
+
+// Overlays
+export {
+  showOverlay,
+  hideOverlay,
+  withOverlay,
+  type OverlayCue,
+  type OverlayManifestEntry,
+  type Zone,
+  type TemplateType,
+  type MotionPreset,
+} from './overlays/index.js';
+
+// TTS
+export { type TTSEngineOptions } from './tts/engine.js';
+
+// Init
+export { init } from './init.js';

package/src/init.ts

@@ -0,0 +1,114 @@
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function writeIfMissing(filePath: string, content: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    console.log(`  skip ${filePath} (already exists)`);
+    return false;
+  } catch (err: any) {
+    if (err?.code !== 'ENOENT') {
+      throw new Error(`Cannot access ${filePath}: ${err.message}`);
+    }
+    await writeFile(filePath, content, 'utf-8');
+    console.log(`  create ${filePath}`);
+    return true;
+  }
+}
+
+const EXAMPLE_DEMO = `import { test } from '@argo-video/cli';
+import { showCaption, withCaption } from '@argo-video/cli';
+
+test('example', async ({ page, narration }) => {
+  await page.goto('/');
+
+  narration.mark('welcome');
+  await showCaption(page, 'welcome', 'Welcome to our app', 3000);
+
+  narration.mark('action');
+  await withCaption(page, 'action', 'Watch how easy it is', async () => {
+    await page.click('button');
+  });
+
+  narration.mark('done');
+  await showCaption(page, 'done', 'All done!', 2000);
+});
+`;
+
+const EXAMPLE_VOICEOVER = JSON.stringify(
+  [
+    { scene: 'welcome', text: 'Welcome to our app — let me show you around.' },
+    { scene: 'action', text: 'It only takes one click to get started.' },
+    { scene: 'done', text: "And that's it. You're all set.", voice: 'af_heart' },
+  ],
+  null,
+  2,
+) + '\n';
+
+const EXAMPLE_OVERLAYS = JSON.stringify(
+  [
+    {
+      scene: 'welcome',
+      type: 'lower-third',
+      text: 'Welcome to our app',
+    },
+    {
+      scene: 'action',
+      type: 'headline-card',
+      placement: 'top-left',
+      title: 'One-click setup',
+      body: 'Just press the button to get started.',
+      motion: 'slide-in',
+    },
+  ],
+  null,
+  2,
+) + '\n';
+
+const ARGO_CONFIG = `export default {
+  baseURL: 'http://localhost:3000',
+  demosDir: 'demos/',
+  outputDir: 'videos/',
+  tts: { defaultVoice: 'af_heart', defaultSpeed: 1.0 },
+  video: { width: 1920, height: 1080, fps: 30 },
+  export: { preset: 'slow', crf: 16 },
+};
+`;
+
+const PLAYWRIGHT_CONFIG = `import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  preserveOutput: 'always',
+  projects: [
+    {
+      name: 'demos',
+      testDir: 'demos',
+      testMatch: '**/*.demo.ts',
+      use: {
+        baseURL: process.env.BASE_URL || 'http://localhost:3000',
+        viewport: { width: 1920, height: 1080 },
+        video: {
+          mode: 'on',
+          size: { width: 1920, height: 1080 },
+        },
+      },
+    },
+  ],
+});
+`;
+
+export async function init(cwd: string = process.cwd()): Promise<void> {
+  const demosDir = join(cwd, 'demos');
+  await mkdir(demosDir, { recursive: true });
+
+  await writeIfMissing(join(demosDir, 'example.demo.ts'), EXAMPLE_DEMO);
+  await writeIfMissing(join(demosDir, 'example.voiceover.json'), EXAMPLE_VOICEOVER);
+  await writeIfMissing(join(demosDir, 'example.overlays.json'), EXAMPLE_OVERLAYS);
+  await writeIfMissing(join(cwd, 'argo.config.js'), ARGO_CONFIG);
+  await writeIfMissing(join(cwd, 'playwright.config.ts'), PLAYWRIGHT_CONFIG);
+
+  console.log('\nArgo initialized! Next steps:');
+  console.log('  1. Edit demos/example.demo.ts');
+  console.log('  2. Run: npx argo record example');
+  console.log('  3. Run: npx argo pipeline example');
+}

package/src/narration.ts

@@ -0,0 +1,31 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export class NarrationTimeline {
+  private timings: Map<string, number> = new Map();
+  private startTime: number | null = null;
+
+  start(): void {
+    this.startTime = Date.now();
+    this.timings = new Map();
+  }
+
+  mark(scene: string): void {
+    if (this.startTime === null) {
+      throw new Error('Cannot mark before start() has been called');
+    }
+    if (this.timings.has(scene)) {
+      throw new Error(`Duplicate scene name: "${scene}"`);
+    }
+    this.timings.set(scene, Date.now() - this.startTime);
+  }
+
+  getTimings(): Record<string, number> {
+    return Object.fromEntries(this.timings);
+  }
+
+  async flush(outputPath: string): Promise<void> {
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, JSON.stringify(this.getTimings(), null, 2), 'utf-8');
+  }
+}

package/src/overlays/index.ts

@@ -0,0 +1,54 @@
+import type { Page } from '@playwright/test';
+import type { OverlayCue, Zone } from './types.js';
+import { injectIntoZone, removeZone, ZONE_ID_PREFIX } from './zones.js';
+import { renderTemplate } from './templates.js';
+import { getMotionCSS, getMotionStyles } from './motion.js';
+
+export type { OverlayCue, OverlayManifestEntry, Zone, TemplateType, MotionPreset } from './types.js';
+export { renderTemplate } from './templates.js';
+
+export async function showOverlay(
+  page: Page,
+  _scene: string,
+  cue: OverlayCue,
+  durationMs: number,
+): Promise<void> {
+  const zone: Zone = cue.placement ?? 'bottom-center';
+  const motion = cue.motion ?? 'none';
+  const { contentHtml, styles } = renderTemplate(cue);
+  const zoneId = ZONE_ID_PREFIX + zone;
+  const motionCSS = getMotionCSS(motion, zoneId);
+  const motionStyles = getMotionStyles(motion, zoneId);
+
+  await injectIntoZone(page, zone, contentHtml, { ...styles, ...motionStyles }, motionCSS);
+  await page.waitForTimeout(durationMs);
+  await removeZone(page, zone);
+}
+
+export async function hideOverlay(
+  page: Page,
+  zone: Zone = 'bottom-center',
+): Promise<void> {
+  await removeZone(page, zone);
+}
+
+export async function withOverlay(
+  page: Page,
+  _scene: string,
+  cue: OverlayCue,
+  action: () => Promise<void>,
+): Promise<void> {
+  const zone: Zone = cue.placement ?? 'bottom-center';
+  const motion = cue.motion ?? 'none';
+  const { contentHtml, styles } = renderTemplate(cue);
+  const zoneId = ZONE_ID_PREFIX + zone;
+  const motionCSS = getMotionCSS(motion, zoneId);
+  const motionStyles = getMotionStyles(motion, zoneId);
+
+  await injectIntoZone(page, zone, contentHtml, { ...styles, ...motionStyles }, motionCSS);
+  try {
+    await action();
+  } finally {
+    await removeZone(page, zone);
+  }
+}

package/src/overlays/manifest.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import type { OverlayManifestEntry } from './types.js';
+import { isValidTemplateType, isValidZone, isValidMotion } from './types.js';
+
+export async function loadOverlayManifest(
+  manifestPath: string,
+): Promise<OverlayManifestEntry[] | null> {
+  if (!existsSync(manifestPath)) return null;
+
+  const raw = await readFile(manifestPath, 'utf-8');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse overlay manifest ${manifestPath}: ${(err as Error).message}`,
+    );
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error(`Overlay manifest ${manifestPath} must contain a JSON array`);
+  }
+
+  const entries: OverlayManifestEntry[] = [];
+
+  for (let i = 0; i < parsed.length; i++) {
+    const entry = parsed[i];
+    const prefix = `Overlay manifest entry ${i}`;
+
+    if (!entry.scene || typeof entry.scene !== 'string') {
+      throw new Error(`${prefix}: missing required field "scene"`);
+    }
+    if (!entry.type || typeof entry.type !== 'string') {
+      throw new Error(`${prefix}: missing required field "type"`);
+    }
+    if (!isValidTemplateType(entry.type)) {
+      throw new Error(`${prefix}: unknown overlay type "${entry.type}"`);
+    }
+    if (entry.placement && !isValidZone(entry.placement)) {
+      throw new Error(`${prefix}: unknown placement "${entry.placement}"`);
+    }
+    if (entry.motion && !isValidMotion(entry.motion)) {
+      throw new Error(`${prefix}: unknown motion "${entry.motion}"`);
+    }
+
+    entries.push(entry as OverlayManifestEntry);
+  }
+
+  return entries;
+}
+
+export function hasImageAssets(entries: OverlayManifestEntry[]): boolean {
+  return entries.some((e) => e.type === 'image-card');
+}
+
+export function resolveAssetURLs(
+  entries: OverlayManifestEntry[],
+  assetBaseURL: string,
+): OverlayManifestEntry[] {
+  return entries.map((e) => {
+    if (e.type === 'image-card' && e.src && !e.src.startsWith('http')) {
+      return { ...e, src: `${assetBaseURL}/${e.src.replace(/^assets\//, '')}` };
+    }
+    return e;
+  });
+}

package/src/overlays/motion.ts

@@ -0,0 +1,27 @@
+import type { MotionPreset } from './types.js';
+
+export function getMotionCSS(motion: MotionPreset, elementId: string): string {
+  const animName = `argo-${motion}-${elementId}`;
+  switch (motion) {
+    case 'fade-in':
+      return `@keyframes ${animName} { from { opacity: 0; } to { opacity: 1; } }`;
+    case 'slide-in':
+      return `@keyframes ${animName} { from { opacity: 0; transform: translateX(-20px); } to { opacity: 1; transform: translateX(0); } }`;
+    case 'none':
+    default:
+      return '';
+  }
+}
+
+export function getMotionStyles(motion: MotionPreset, elementId: string): Record<string, string> {
+  const animName = `argo-${motion}-${elementId}`;
+  switch (motion) {
+    case 'fade-in':
+      return { animation: `${animName} 300ms ease-out forwards` };
+    case 'slide-in':
+      return { animation: `${animName} 400ms ease-out forwards` };
+    case 'none':
+    default:
+      return {};
+  }
+}

package/src/overlays/templates.ts

@@ -0,0 +1,121 @@
+import type { OverlayCue } from './types.js';
+
+export interface TemplateResult {
+  contentHtml: string;
+  styles: Record<string, string>;
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function lowerThird(text: string): TemplateResult {
+  return {
+    contentHtml: `<span>${escapeHtml(text)}</span>`,
+    styles: {
+      background: 'rgba(0, 0, 0, 0.85)',
+      color: '#fff',
+      padding: '16px 32px',
+      borderRadius: '12px',
+      fontSize: '28px',
+      fontWeight: '500',
+      textAlign: 'center',
+      maxWidth: '80vw',
+      letterSpacing: '0.01em',
+      lineHeight: '1.4',
+      boxShadow: '0 4px 24px rgba(0, 0, 0, 0.3)',
+    },
+  };
+}
+
+function headlineCard(title: string, kicker?: string, body?: string): TemplateResult {
+  const parts: string[] = [];
+  if (kicker) {
+    parts.push(
+      `<div style="font-size:12px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;color:rgba(255,255,255,0.7);margin-bottom:8px">${escapeHtml(kicker)}</div>`,
+    );
+  }
+  parts.push(
+    `<div style="font-size:26px;font-weight:700;line-height:1.25;color:#fff">${escapeHtml(title)}</div>`,
+  );
+  if (body) {
+    parts.push(
+      `<div style="font-size:16px;line-height:1.5;color:rgba(255,255,255,0.85);margin-top:8px">${escapeHtml(body)}</div>`,
+    );
+  }
+  return {
+    contentHtml: parts.join(''),
+    styles: {
+      background: 'rgba(0, 0, 0, 0.7)',
+      backdropFilter: 'blur(16px)',
+      WebkitBackdropFilter: 'blur(16px)',
+      padding: '24px 28px',
+      borderRadius: '16px',
+      maxWidth: '420px',
+      boxShadow: '0 8px 32px rgba(0, 0, 0, 0.4)',
+    },
+  };
+}
+
+function callout(text: string): TemplateResult {
+  return {
+    contentHtml: `<span>${escapeHtml(text)}</span>`,
+    styles: {
+      background: 'rgba(0, 0, 0, 0.8)',
+      color: '#fff',
+      padding: '10px 18px',
+      borderRadius: '20px',
+      fontSize: '16px',
+      fontWeight: '500',
+      lineHeight: '1.3',
+      maxWidth: '300px',
+      boxShadow: '0 2px 12px rgba(0, 0, 0, 0.3)',
+    },
+  };
+}
+
+function imageCard(src: string, title?: string, body?: string): TemplateResult {
+  const parts: string[] = [];
+  parts.push(
+    `<img src="${escapeHtml(src)}" style="max-width:100%;border-radius:8px;display:block" />`,
+  );
+  if (title) {
+    parts.push(
+      `<div style="font-size:18px;font-weight:600;color:#fff;margin-top:12px">${escapeHtml(title)}</div>`,
+    );
+  }
+  if (body) {
+    parts.push(
+      `<div style="font-size:14px;color:rgba(255,255,255,0.8);margin-top:4px;line-height:1.4">${escapeHtml(body)}</div>`,
+    );
+  }
+  return {
+    contentHtml: parts.join(''),
+    styles: {
+      background: 'rgba(0, 0, 0, 0.75)',
+      backdropFilter: 'blur(12px)',
+      WebkitBackdropFilter: 'blur(12px)',
+      padding: '16px',
+      borderRadius: '14px',
+      maxWidth: '360px',
+      boxShadow: '0 6px 24px rgba(0, 0, 0, 0.4)',
+    },
+  };
+}
+
+export function renderTemplate(cue: OverlayCue): TemplateResult {
+  switch (cue.type) {
+    case 'lower-third':
+      return lowerThird(cue.text);
+    case 'headline-card':
+      return headlineCard(cue.title, cue.kicker, cue.body);
+    case 'callout':
+      return callout(cue.text);
+    case 'image-card':
+      return imageCard(cue.src, cue.title, cue.body);
+  }
+}

package/src/overlays/types.ts

@@ -0,0 +1,73 @@
+export const ZONES = [
+  'bottom-center',
+  'top-left',
+  'top-right',
+  'bottom-left',
+  'bottom-right',
+  'center',
+] as const;
+
+export type Zone = (typeof ZONES)[number];
+
+export const TEMPLATE_TYPES = [
+  'lower-third',
+  'headline-card',
+  'callout',
+  'image-card',
+] as const;
+
+export type TemplateType = (typeof TEMPLATE_TYPES)[number];
+
+export const MOTIONS = ['none', 'fade-in', 'slide-in'] as const;
+
+export type MotionPreset = (typeof MOTIONS)[number];
+
+export interface LowerThirdCue {
+  type: 'lower-third';
+  text: string;
+  placement?: Zone;
+  motion?: MotionPreset;
+}
+
+export interface HeadlineCardCue {
+  type: 'headline-card';
+  title: string;
+  kicker?: string;
+  body?: string;
+  placement?: Zone;
+  motion?: MotionPreset;
+}
+
+export interface CalloutCue {
+  type: 'callout';
+  text: string;
+  placement?: Zone;
+  motion?: MotionPreset;
+}
+
+export interface ImageCardCue {
+  type: 'image-card';
+  src: string;
+  title?: string;
+  body?: string;
+  placement?: Zone;
+  motion?: MotionPreset;
+}
+
+export type OverlayCue = LowerThirdCue | HeadlineCardCue | CalloutCue | ImageCardCue;
+
+export type OverlayManifestEntry = OverlayCue & {
+  scene: string;
+};
+
+export function isValidZone(value: string): value is Zone {
+  return (ZONES as readonly string[]).includes(value);
+}
+
+export function isValidTemplateType(value: string): value is TemplateType {
+  return (TEMPLATE_TYPES as readonly string[]).includes(value);
+}
+
+export function isValidMotion(value: string): value is MotionPreset {
+  return (MOTIONS as readonly string[]).includes(value);
+}