@argo-video/cli 0.1.0 → 0.2.0

package/dist/overlays/types.js

@@ -0,0 +1,25 @@
+export const ZONES = [
+    'bottom-center',
+    'top-left',
+    'top-right',
+    'bottom-left',
+    'bottom-right',
+    'center',
+];
+export const TEMPLATE_TYPES = [
+    'lower-third',
+    'headline-card',
+    'callout',
+    'image-card',
+];
+export const MOTIONS = ['none', 'fade-in', 'slide-in'];
+export function isValidZone(value) {
+    return ZONES.includes(value);
+}
+export function isValidTemplateType(value) {
+    return TEMPLATE_TYPES.includes(value);
+}
+export function isValidMotion(value) {
+    return MOTIONS.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/overlays/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/overlays/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,eAAe;IACf,UAAU;IACV,WAAW;IACX,aAAa;IACb,cAAc;IACd,QAAQ;CACA,CAAC;AAIX,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa;IACb,eAAe;IACf,SAAS;IACT,YAAY;CACJ,CAAC;AAIX,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AA8ChE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAQ,KAA2B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAQ,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAQ,OAA6B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC"}

package/dist/overlays/zones.d.ts

@@ -0,0 +1,23 @@
+import type { Page } from '@playwright/test';
+import type { Zone } from './types.js';
+export declare const ZONE_ID_PREFIX = "argo-overlay-";
+/**
+ * Inject content into a zone. Replaces any existing overlay in that zone.
+ * Security: contentHtml is generated by template renderers which escape all
+ * text fields via escapeHtml(). Content originates from author-controlled
+ * manifest files, not end-user input.
+ */
+export declare function injectIntoZone(page: Page, zone: Zone, contentHtml: string, containerStyles: Record<string, string>, animationCSS?: string): Promise<void>;
+export type BackgroundTheme = 'dark' | 'light';
+/**
+ * Detect whether the background at a zone's position is dark or light.
+ * Samples the element at the zone coordinates, skipping fixed-position elements
+ * (navbars, toolbars) to read the actual page content background.
+ * Returns the *overlay* theme for contrast: dark bg → 'light' overlay, light bg → 'dark' overlay.
+ */
+export declare function detectBackgroundTheme(page: Page, zone: Zone): Promise<BackgroundTheme>;
+/**
+ * Remove the overlay in the specified zone, if any.
+ */
+export declare function removeZone(page: Page, zone: Zone): Promise<void>;
+//# sourceMappingURL=zones.d.ts.map

package/dist/overlays/zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.d.ts","sourceRoot":"","sources":["../../src/overlays/zones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAuB9C;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAwC5F;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtE"}

package/dist/overlays/zones.js

@@ -0,0 +1,117 @@
+export const ZONE_ID_PREFIX = 'argo-overlay-';
+const ZONE_POSITIONS = {
+    'bottom-center': {
+        position: 'fixed', bottom: '60px', left: '50%', transform: 'translateX(-50%)',
+    },
+    'top-left': {
+        position: 'fixed', top: '40px', left: '40px',
+    },
+    'top-right': {
+        position: 'fixed', top: '40px', right: '40px',
+    },
+    'bottom-left': {
+        position: 'fixed', bottom: '60px', left: '40px',
+    },
+    'bottom-right': {
+        position: 'fixed', bottom: '60px', right: '40px',
+    },
+    'center': {
+        position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)',
+    },
+};
+/**
+ * Inject content into a zone. Replaces any existing overlay in that zone.
+ * Security: contentHtml is generated by template renderers which escape all
+ * text fields via escapeHtml(). Content originates from author-controlled
+ * manifest files, not end-user input.
+ */
+export async function injectIntoZone(page, zone, contentHtml, containerStyles, animationCSS) {
+    const zoneId = ZONE_ID_PREFIX + zone;
+    const positionStyles = ZONE_POSITIONS[zone];
+    const baseStyles = {
+        ...positionStyles,
+        zIndex: '999999',
+        pointerEvents: 'none',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        ...containerStyles,
+    };
+    await page.evaluate(([id, html, styles, css]) => {
+        const existing = document.getElementById(id);
+        if (existing)
+            existing.remove();
+        if (css) {
+            const styleId = id + '-style';
+            let styleEl = document.getElementById(styleId);
+            if (!styleEl) {
+                styleEl = document.createElement('style');
+                styleEl.id = styleId;
+                document.head.appendChild(styleEl);
+            }
+            styleEl.textContent = css;
+        }
+        const container = document.createElement('div');
+        container.id = id;
+        container.innerHTML = html;
+        Object.assign(container.style, styles);
+        document.body.appendChild(container);
+    }, [zoneId, contentHtml, baseStyles, animationCSS ?? '']);
+}
+/**
+ * Detect whether the background at a zone's position is dark or light.
+ * Samples the element at the zone coordinates, skipping fixed-position elements
+ * (navbars, toolbars) to read the actual page content background.
+ * Returns the *overlay* theme for contrast: dark bg → 'light' overlay, light bg → 'dark' overlay.
+ */
+export async function detectBackgroundTheme(page, zone) {
+    const pos = ZONE_POSITIONS[zone];
+    return page.evaluate((zonePos) => {
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        let x = vw / 2;
+        let y = vh / 2;
+        if (zonePos.left === '40px')
+            x = 80;
+        else if (zonePos.right === '40px')
+            x = vw - 80;
+        else if (zonePos.left === '50%')
+            x = vw / 2;
+        if (zonePos.top === '40px')
+            y = 80;
+        else if (zonePos.bottom === '60px')
+            y = vh - 80;
+        else if (zonePos.top === '50%')
+            y = vh / 2;
+        // Get all elements at this point, skip fixed-position ones (navs, toolbars)
+        const elements = document.elementsFromPoint(x, y);
+        for (const el of elements) {
+            const style = getComputedStyle(el);
+            // Skip fixed elements (navbars, overlays) — they don't represent page content
+            if (style.position === 'fixed' || style.position === 'sticky')
+                continue;
+            const bg = style.backgroundColor;
+            const match = bg.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+            if (match) {
+                const [, r, g, b, a] = match;
+                const alpha = a !== undefined ? parseFloat(a) : 1;
+                if (alpha > 0.1) {
+                    const luminance = 0.299 * Number(r) + 0.587 * Number(g) + 0.114 * Number(b);
+                    return luminance < 128 ? 'light' : 'dark';
+                }
+            }
+        }
+        // Fall back to system theme
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        return prefersDark ? 'light' : 'dark';
+    }, pos);
+}
+/**
+ * Remove the overlay in the specified zone, if any.
+ */
+export async function removeZone(page, zone) {
+    const zoneId = ZONE_ID_PREFIX + zone;
+    await page.evaluate((id) => {
+        document.getElementById(id)?.remove();
+        document.getElementById(id + '-style')?.remove();
+    }, zoneId);
+}
+//# sourceMappingURL=zones.js.map

package/dist/overlays/zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.js","sourceRoot":"","sources":["../../src/overlays/zones.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;AAE9C,MAAM,cAAc,GAAyC;IAC3D,eAAe,EAAE;QACf,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,kBAAkB;KAC9E;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;KAC7C;IACD,WAAW,EAAE;QACX,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;KAC9C;IACD,aAAa,EAAE;QACb,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;KAChD;IACD,cAAc,EAAE;QACd,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;KACjD;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,uBAAuB;KAC/E;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAU,EACV,IAAU,EACV,WAAmB,EACnB,eAAuC,EACvC,YAAqB;IAErB,MAAM,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACrC,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,UAAU,GAA2B;QACzC,GAAG,cAAc;QACjB,MAAM,EAAE,QAAQ;QAChB,aAAa,EAAE,MAAM;QACrB,UAAU,EAAE,sCAAsC;QAClD,GAAG,eAAe;KACnB,CAAC;IAEF,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE;QAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QAEhC,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,OAAO,GAAG,EAAE,GAAG,QAAQ,CAAC;YAC9B,IAAI,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,OAAO,CAA4B,CAAC;YAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;gBAC1C,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC;YACD,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC;QAC5B,CAAC;QAED,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAChD,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC;QAClB,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,IAAI,EAAE,CAAU,CAAC,CAAC;AACrE,CAAC;AAID;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAU,EAAE,IAAU;IAChE,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;QAC9B,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEf,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;YAAE,CAAC,GAAG,EAAE,CAAC;aAC/B,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM;YAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;aAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK;YAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAE5C,IAAI,OAAO,CAAC,GAAG,KAAK,MAAM;YAAE,CAAC,GAAG,EAAE,CAAC;aAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;YAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;aAC3C,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK;YAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAE3C,4EAA4E;QAC5E,MAAM,QAAQ,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAElD,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;YACnC,8EAA8E;YAC9E,IAAI,KAAK,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ;gBAAE,SAAS;YAExE,MAAM,EAAE,GAAG,KAAK,CAAC,eAAe,CAAC;YACjC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;YAC5E,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;gBAC7B,MAAM,KAAK,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClD,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;oBAChB,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;oBAC5E,OAAO,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,OAAgB,CAAC,CAAC,CAAC,MAAe,CAAC;gBAC9D,CAAC;YACH,CAAC;QACH,CAAC;QAED,4BAA4B;QAC5B,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC;QAC9E,OAAO,WAAW,CAAC,CAAC,CAAC,OAAgB,CAAC,CAAC,CAAC,MAAe,CAAC;IAC1D,CAAC,EAAE,GAAG,CAAC,CAAC;AACV,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAU,EAAE,IAAU;IACrD,MAAM,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACrC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE;QACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;QACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACnD,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC"}

package/dist/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { ArgoConfig } from './config.js';
+export declare function runPipeline(demoName: string, config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'outputDir' | 'tts' | 'video' | 'export' | 'overlays'>): Promise<string>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA0B9C,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC,GACvG,OAAO,CAAC,MAAM,CAAC,CAqGjB"}

package/dist/pipeline.js

@@ -0,0 +1,109 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { generateClips } from './tts/generate.js';
+import { record } from './record.js';
+import { alignClips } from './tts/align.js';
+import { parseWavHeader, createWavBuffer } from './tts/engine.js';
+import { exportVideo, checkFfmpeg } from './export.js';
+function getVideoDurationMs(videoPath) {
+    let raw;
+    try {
+        raw = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', videoPath], { encoding: 'utf-8' }).trim();
+    }
+    catch (err) {
+        throw new Error(`Failed to get video duration from ${videoPath}. ` +
+            `Ensure ffprobe is installed (it usually comes with ffmpeg). ` +
+            `Original error: ${err.message}`);
+    }
+    const durationMs = Math.round(parseFloat(raw) * 1000);
+    if (isNaN(durationMs) || durationMs <= 0) {
+        throw new Error(`ffprobe returned invalid duration "${raw}" for ${videoPath}. The video file may be corrupt.`);
+    }
+    return durationMs;
+}
+export async function runPipeline(demoName, config) {
+    if (!config.baseURL) {
+        throw new Error('baseURL is required but not set. Set it in argo.config.js or pass --config.');
+    }
+    if (!config.tts.engine) {
+        throw new Error('TTS engine is not configured. Ensure config.tts.engine is set.');
+    }
+    checkFfmpeg();
+    const argoDir = join('.argo', demoName);
+    // Step 1: Generate TTS clips
+    console.log('Step 1/4: Generating TTS clips...');
+    const clipResults = await generateClips({
+        manifestPath: `${config.demosDir}/${demoName}.voiceover.json`,
+        demoName,
+        engine: config.tts.engine,
+        projectRoot: '.',
+        defaults: { voice: config.tts.defaultVoice, speed: config.tts.defaultSpeed },
+    });
+    if (clipResults.length === 0) {
+        throw new Error(`No TTS clips were generated from ${config.demosDir}/${demoName}.voiceover.json. ` +
+            `Ensure the manifest contains at least one entry.`);
+    }
+    // Write scene durations so demo scripts can use narration.durationFor()
+    const sceneDurations = {};
+    for (const cr of clipResults) {
+        sceneDurations[cr.scene] = cr.durationMs;
+    }
+    const sceneDurationsPath = join(argoDir, '.scene-durations.json');
+    writeFileSync(sceneDurationsPath, JSON.stringify(sceneDurations, null, 2), 'utf-8');
+    // Step 2: Record browser demo
+    console.log('Step 2/4: Recording browser demo...');
+    const { timingPath } = await record(demoName, {
+        demosDir: config.demosDir,
+        baseURL: config.baseURL,
+        video: { width: config.video.width, height: config.video.height },
+        autoBackground: config.overlays.autoBackground,
+    });
+    // Step 3: Align clips with timing
+    console.log('Step 3/4: Aligning narration with video...');
+    const timing = JSON.parse(readFileSync(timingPath, 'utf-8'));
+    // Load WAV clips into memory
+    const clips = clipResults.map((cr) => {
+        const wavBuf = readFileSync(cr.clipPath);
+        const header = parseWavHeader(wavBuf);
+        // Extract Float32 samples from the data chunk
+        const sampleCount = header.dataSize / 4; // 32-bit float = 4 bytes
+        const samples = new Float32Array(sampleCount);
+        for (let i = 0; i < sampleCount && header.dataOffset + i * 4 + 3 < wavBuf.length; i++) {
+            samples[i] = wavBuf.readFloatLE(header.dataOffset + i * 4);
+        }
+        return {
+            scene: cr.scene,
+            durationMs: header.durationMs,
+            samples,
+        };
+    });
+    // Use actual video duration for alignment
+    const videoPath = join(argoDir, 'video.webm');
+    const totalDurationMs = getVideoDurationMs(videoPath);
+    const aligned = alignClips(timing, clips, totalDurationMs);
+    const alignedWav = createWavBuffer(aligned.samples, 24_000);
+    const alignedPath = join(argoDir, 'narration-aligned.wav');
+    writeFileSync(alignedPath, alignedWav);
+    const tailPadMs = aligned.overflowMs > 0 ? aligned.overflowMs + 100 : undefined;
+    if (tailPadMs !== undefined) {
+        console.warn(`Aligned narration runs ${aligned.overflowMs}ms past the recording. ` +
+            `Padding the final video frame to preserve the full audio.`);
+    }
+    // Step 4: Export final video
+    console.log('Step 4/4: Exporting final video...');
+    const exportOptions = {
+        demoName,
+        argoDir: '.argo',
+        outputDir: config.outputDir,
+        preset: config.export.preset,
+        crf: config.export.crf,
+        fps: config.video.fps,
+    };
+    if (tailPadMs !== undefined)
+        exportOptions.tailPadMs = tailPadMs;
+    const outputPath = await exportVideo(exportOptions);
+    console.log(`Done! Video saved to: ${outputPath}`);
+    return outputPath;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/record.d.ts

@@ -0,0 +1,15 @@
+export interface RecordOptions {
+    demosDir: string;
+    baseURL: string;
+    video: {
+        width: number;
+        height: number;
+    };
+    autoBackground?: boolean;
+}
+export interface RecordResult {
+    videoPath: string;
+    timingPath: string;
+}
+export declare function record(demoName: string, options: RecordOptions): Promise<RecordResult>;
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAyCD,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA2E5F"}

package/dist/record.js

@@ -0,0 +1,110 @@
+import { execFile } from 'node:child_process';
+import { mkdirSync, readdirSync, copyFileSync, existsSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { startAssetServer } from './asset-server.js';
+import { loadOverlayManifest, hasImageAssets } from './overlays/manifest.js';
+function findVideoInResults(testResultsDir) {
+    if (!existsSync(testResultsDir))
+        return undefined;
+    for (const entry of readdirSync(testResultsDir, { recursive: true })) {
+        const name = typeof entry === 'string' ? entry : entry.toString();
+        if (name.endsWith('.webm')) {
+            return path.join(testResultsDir, name);
+        }
+    }
+    return undefined;
+}
+function createPlaywrightConfig(options, outputDir) {
+    const demosDir = path.resolve(options.demosDir);
+    const { width, height } = options.video;
+    return `import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  preserveOutput: 'always',
+  outputDir: ${JSON.stringify(outputDir)},
+  projects: [
+    {
+      name: 'demos',
+      testDir: ${JSON.stringify(demosDir)},
+      testMatch: '**/*.demo.ts',
+      use: {
+        baseURL: ${JSON.stringify(options.baseURL)},
+        viewport: { width: ${width}, height: ${height} },
+        video: {
+          mode: 'on',
+          size: { width: ${width}, height: ${height} },
+        },
+      },
+    },
+  ],
+});
+`;
+}
+export async function record(demoName, options) {
+    const argoDir = path.join('.argo', demoName);
+    mkdirSync(argoDir, { recursive: true });
+    const videoPath = path.join(argoDir, 'video.webm');
+    const timingPath = path.join(argoDir, '.timing.json');
+    const testResultsDir = path.resolve('test-results');
+    const recordConfigPath = path.join(argoDir, 'playwright.record.config.mjs');
+    writeFileSync(recordConfigPath, createPlaywrightConfig(options, testResultsDir), 'utf-8');
+    // Clean test-results to avoid picking up stale videos
+    rmSync(testResultsDir, { recursive: true, force: true });
+    // Start asset server if overlay manifest has image assets
+    let assetServer;
+    const overlayManifestPath = path.join(options.demosDir, `${demoName}.overlays.json`);
+    try {
+        const overlayEntries = await loadOverlayManifest(overlayManifestPath);
+        if (overlayEntries && hasImageAssets(overlayEntries)) {
+            const assetDir = path.join(options.demosDir, 'assets');
+            assetServer = await startAssetServer(assetDir);
+        }
+    }
+    catch (err) {
+        // A malformed overlay manifest should not block recording —
+        // overlays are rendered by explicit showOverlay()/withOverlay() calls in the demo script,
+        // not from the manifest. Only warn.
+        console.warn(`Warning: could not parse overlay manifest: ${err.message}`);
+    }
+    try {
+        return await new Promise((resolve, reject) => {
+            execFile('npx', ['playwright', 'test', '--config', recordConfigPath, '--grep', demoName, '--project', 'demos'], {
+                env: {
+                    ...process.env,
+                    ARGO_DEMO_NAME: demoName,
+                    ARGO_OUTPUT_DIR: argoDir,
+                    BASE_URL: options.baseURL,
+                    ARGO_ASSET_URL: assetServer?.url ?? '',
+                    ARGO_AUTO_BACKGROUND: options.autoBackground ? '1' : '',
+                    ARGO_SCENE_DURATIONS_PATH: path.resolve(path.join('.argo', demoName, '.scene-durations.json')),
+                },
+            }, (error, stdout, stderr) => {
+                if (error) {
+                    const output = [stdout, stderr].filter(Boolean).join('\n');
+                    reject(new Error(`Playwright recording failed:\n${output}`));
+                    return;
+                }
+                // Copy the video from test-results/ to .argo/<demo>/video.webm
+                const found = findVideoInResults(testResultsDir);
+                if (!found) {
+                    reject(new Error(`No video recording found in test-results/. ` +
+                        `Ensure playwright.config.ts has video: 'on' or video: { mode: 'on' }.`));
+                    return;
+                }
+                copyFileSync(found, videoPath);
+                // Verify timing file was written by the narration fixture
+                if (!existsSync(timingPath)) {
+                    reject(new Error(`No timing file found at ${timingPath}. ` +
+                        `Ensure the demo uses the argo test fixture with narration.mark() calls.`));
+                    return;
+                }
+                resolve({ videoPath, timingPath });
+            });
+        });
+    }
+    finally {
+        if (assetServer)
+            await assetServer.close();
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"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"}

package/dist/tts/align.d.ts

@@ -0,0 +1,26 @@
+export type SceneTiming = Record<string, number>;
+export interface ClipInfo {
+    scene: string;
+    durationMs: number;
+    samples: Float32Array;
+}
+export interface Placement {
+    scene: string;
+    startMs: number;
+    endMs: number;
+}
+export interface AlignResult {
+    placements: Placement[];
+    samples: Float32Array;
+    requiredDurationMs: number;
+    overflowMs: number;
+}
+export interface ScheduledSceneInput {
+    scene: string;
+    startMs: number;
+    durationMs: number;
+}
+export declare const OVERLAP_GAP_MS = 100;
+export declare function schedulePlacements(scenes: ScheduledSceneInput[]): Placement[];
+export declare function alignClips(timing: SceneTiming, clips: ClipInfo[], totalDurationMs: number, sampleRate?: number): AlignResult;
+//# sourceMappingURL=align.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../src/tts/align.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,SAAS,EAAE,CAkB7E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,EAAE,EACjB,eAAe,EAAE,MAAM,EACvB,UAAU,SAAS,GAClB,WAAW,CA6Cb"}

package/dist/tts/align.js

@@ -0,0 +1,53 @@
+export const OVERLAP_GAP_MS = 100;
+export function schedulePlacements(scenes) {
+    const sorted = [...scenes].sort((a, b) => a.startMs - b.startMs);
+    const placements = [];
+    let previousEndMs = 0;
+    for (const scene of sorted) {
+        let startMs = scene.startMs;
+        if (placements.length > 0 && startMs < previousEndMs) {
+            startMs = previousEndMs + OVERLAP_GAP_MS;
+        }
+        const endMs = startMs + scene.durationMs;
+        placements.push({ scene: scene.scene, startMs, endMs });
+        previousEndMs = endMs;
+    }
+    return placements;
+}
+export function alignClips(timing, clips, totalDurationMs, sampleRate = 24_000) {
+    // 1. Filter to clips with matching scenes
+    const matched = clips.filter((c) => c.scene in timing);
+    const unmatched = clips.filter((c) => !(c.scene in timing));
+    if (unmatched.length > 0) {
+        const names = unmatched.map((c) => c.scene).join(', ');
+        console.warn(`Warning: ${unmatched.length} clip(s) have no matching scene in timing and will be skipped: ${names}. ` +
+            `Check that voiceover manifest scene names match narration.mark() calls.`);
+    }
+    // 2. Sort by scene timestamp ascending
+    matched.sort((a, b) => timing[a.scene] - timing[b.scene]);
+    // 3. Place each clip, preventing overlap
+    const placements = schedulePlacements(matched.map((clip) => ({
+        scene: clip.scene,
+        startMs: timing[clip.scene],
+        durationMs: clip.durationMs,
+    })));
+    const requiredDurationMs = placements.length > 0
+        ? placements[placements.length - 1].endMs
+        : 0;
+    const overflowMs = Math.max(0, requiredDurationMs - totalDurationMs);
+    // 4. Create silence buffer
+    const outputDurationMs = Math.max(totalDurationMs, requiredDurationMs);
+    const totalSamples = Math.round((outputDurationMs / 1000) * sampleRate);
+    const output = new Float32Array(totalSamples);
+    // 5. Mix each clip's samples into output
+    for (let i = 0; i < placements.length; i++) {
+        const placement = placements[i];
+        const clip = matched[i];
+        const startSample = Math.round((placement.startMs / 1000) * sampleRate);
+        for (let j = 0; j < clip.samples.length && startSample + j < totalSamples; j++) {
+            output[startSample + j] += clip.samples[j];
+        }
+    }
+    return { placements, samples: output, requiredDurationMs, overflowMs };
+}
+//# sourceMappingURL=align.js.map

package/dist/tts/align.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.js","sourceRoot":"","sources":["../../src/tts/align.ts"],"names":[],"mappings":"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"}

package/dist/tts/cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Content-addressed clip cache for Argo TTS output.
+ */
+export interface ManifestEntry {
+    scene: string;
+    text: string;
+    voice?: string;
+    speed?: number;
+}
+export declare class ClipCache {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Returns the full file path for a cached clip.
+     */
+    getClipPath(demoName: string, entry: ManifestEntry): string;
+    /**
+     * Checks whether a clip is already cached on disk.
+     */
+    isCached(demoName: string, entry: ManifestEntry): boolean;
+    /**
+     * Returns the cached WAV buffer, or null if not cached.
+     */
+    getCachedClip(demoName: string, entry: ManifestEntry): Buffer | null;
+    /**
+     * Writes a WAV buffer to the cache, creating directories as needed.
+     */
+    cacheClip(demoName: string, entry: ManifestEntry, wavBuffer: Buffer): void;
+    private computeHash;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/tts/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,EAAE,MAAM;IAI/B;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM;IAK3D;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO;IAIzD;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;IAQpE;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAM1E,OAAO,CAAC,WAAW;CAOpB"}

package/dist/tts/cache.js

@@ -0,0 +1,51 @@
+/**
+ * Content-addressed clip cache for Argo TTS output.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+export class ClipCache {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Returns the full file path for a cached clip.
+     */
+    getClipPath(demoName, entry) {
+        const hash = this.computeHash(entry);
+        return path.join(this.projectRoot, '.argo', demoName, 'clips', `${hash}.wav`);
+    }
+    /**
+     * Checks whether a clip is already cached on disk.
+     */
+    isCached(demoName, entry) {
+        return fs.existsSync(this.getClipPath(demoName, entry));
+    }
+    /**
+     * Returns the cached WAV buffer, or null if not cached.
+     */
+    getCachedClip(demoName, entry) {
+        const clipPath = this.getClipPath(demoName, entry);
+        if (!fs.existsSync(clipPath)) {
+            return null;
+        }
+        return fs.readFileSync(clipPath);
+    }
+    /**
+     * Writes a WAV buffer to the cache, creating directories as needed.
+     */
+    cacheClip(demoName, entry, wavBuffer) {
+        const clipPath = this.getClipPath(demoName, entry);
+        fs.mkdirSync(path.dirname(clipPath), { recursive: true });
+        fs.writeFileSync(clipPath, wavBuffer);
+    }
+    computeHash(entry) {
+        const { scene, text, voice, speed } = entry;
+        return crypto
+            .createHash('sha256')
+            .update(JSON.stringify({ scene, text, voice, speed }))
+            .digest('hex');
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/tts/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/tts/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAS7B,MAAM,OAAO,SAAS;IACH,WAAW,CAAS;IAErC,YAAY,WAAmB;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAgB,EAAE,KAAoB;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;IAChF,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,QAAgB,EAAE,KAAoB;QAC7C,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,QAAgB,EAAE,KAAoB;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAAgB,EAAE,KAAoB,EAAE,SAAiB;QACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACxC,CAAC;IAEO,WAAW,CAAC,KAAoB;QACtC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QAC5C,OAAO,MAAM;aACV,UAAU,CAAC,QAAQ,CAAC;aACpB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;aACrD,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;CACF"}