@argo-video/cli 0.1.0 → 0.1.1

package/src/pipeline.ts

@@ -1,120 +0,0 @@
-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, type ClipInfo, type SceneTiming } from './tts/align.js';
-import { parseWavHeader, createWavBuffer } from './tts/engine.js';
-import { exportVideo, checkFfmpeg } from './export.js';
-import type { ArgoConfig } from './config.js';
-
-function getVideoDurationMs(videoPath: string): number {
-  let raw: string;
-  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 as Error).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: string,
-  config: Pick<ArgoConfig, 'baseURL' | 'demosDir' | 'outputDir' | 'tts' | 'video' | 'export'>
-): Promise<string> {
-  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.`
-    );
-  }
-
-  // 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 },
-  });
-
-  // Step 3: Align clips with timing
-  console.log('Step 3/4: Aligning narration with video...');
-  const timing: SceneTiming = JSON.parse(readFileSync(timingPath, 'utf-8'));
-
-  // Load WAV clips into memory
-  const clips: ClipInfo[] = 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);
-
-  // Step 4: Export final video
-  console.log('Step 4/4: Exporting final video...');
-  const outputPath = await exportVideo({
-    demoName,
-    argoDir: '.argo',
-    outputDir: config.outputDir,
-    preset: config.export.preset,
-    crf: config.export.crf,
-    fps: config.video.fps,
-  });
-
-  console.log(`Done! Video saved to: ${outputPath}`);
-  return outputPath;
-}

package/src/record.ts

@@ -1,123 +0,0 @@
-import { execFile } from 'node:child_process';
-import { mkdirSync, readdirSync, copyFileSync, existsSync, rmSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { startAssetServer, type AssetServer } from './asset-server.js';
-import { loadOverlayManifest, hasImageAssets } from './overlays/manifest.js';
-
-export interface RecordOptions {
-  demosDir: string;
-  baseURL: string;
-  video: { width: number; height: number };
-}
-
-export interface RecordResult {
-  videoPath: string;
-  timingPath: string;
-}
-
-function findVideoInResults(testResultsDir: string): string | undefined {
-  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: RecordOptions, outputDir: string): string {
-  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: string, options: RecordOptions): Promise<RecordResult> {
-  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: AssetServer | undefined;
-  const overlayManifestPath = path.join(options.demosDir, `${demoName}.overlays.json`);
-  const overlayEntries = await loadOverlayManifest(overlayManifestPath);
-  if (overlayEntries && hasImageAssets(overlayEntries)) {
-    const assetDir = path.join(options.demosDir, 'assets');
-    assetServer = await startAssetServer(assetDir);
-  }
-
-  try {
-    return await new Promise<RecordResult>((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 ?? '',
-        },
-      }, (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();
-  }
-}

package/src/tts/align.ts

@@ -1,75 +0,0 @@
-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;
-}
-
-const OVERLAP_GAP_MS = 100;
-
-export function alignClips(
-  timing: SceneTiming,
-  clips: ClipInfo[],
-  totalDurationMs: number,
-  sampleRate = 24_000,
-): AlignResult {
-  // 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: Placement[] = [];
-  let previousEndMs = 0;
-
-  for (const clip of matched) {
-    let startMs = timing[clip.scene];
-
-    // If this would overlap the previous clip, push forward
-    if (placements.length > 0 && startMs < previousEndMs) {
-      startMs = previousEndMs + OVERLAP_GAP_MS;
-    }
-
-    const endMs = startMs + clip.durationMs;
-    placements.push({ scene: clip.scene, startMs, endMs });
-    previousEndMs = endMs;
-  }
-
-  // 4. Create silence buffer
-  const totalSamples = Math.round((totalDurationMs / 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 };
-}

package/src/tts/cache.ts

@@ -1,65 +0,0 @@
-/**
- * Content-addressed clip cache for Argo TTS output.
- */
-
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-
-export interface ManifestEntry {
-  scene: string;
-  text: string;
-  voice?: string;
-  speed?: number;
-}
-
-export class ClipCache {
-  private readonly projectRoot: string;
-
-  constructor(projectRoot: string) {
-    this.projectRoot = projectRoot;
-  }
-
-  /**
-   * Returns the full file path for a cached clip.
-   */
-  getClipPath(demoName: string, entry: ManifestEntry): string {
-    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: string, entry: ManifestEntry): boolean {
-    return fs.existsSync(this.getClipPath(demoName, entry));
-  }
-
-  /**
-   * Returns the cached WAV buffer, or null if not cached.
-   */
-  getCachedClip(demoName: string, entry: ManifestEntry): Buffer | null {
-    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: string, entry: ManifestEntry, wavBuffer: Buffer): void {
-    const clipPath = this.getClipPath(demoName, entry);
-    fs.mkdirSync(path.dirname(clipPath), { recursive: true });
-    fs.writeFileSync(clipPath, wavBuffer);
-  }
-
-  private computeHash(entry: ManifestEntry): string {
-    const { scene, text, voice, speed } = entry;
-    return crypto
-      .createHash('sha256')
-      .update(JSON.stringify({ scene, text, voice, speed }))
-      .digest('hex');
-  }
-}

package/src/tts/engine.ts

@@ -1,147 +0,0 @@
-/**
- * TTS Engine interface and WAV utilities for Argo.
- */
-
-export interface TTSEngineOptions {
-  voice?: string;
-  speed?: number;
-  lang?: string;
-}
-
-export interface TTSEngine {
-  generate(text: string, options: TTSEngineOptions): Promise<Buffer>;
-}
-
-/**
- * Creates a valid WAV file buffer from Float32Array samples.
- * Format: mono, 32-bit IEEE float, given sample rate.
- */
-export function createWavBuffer(samples: Float32Array, sampleRate = 24000): Buffer {
-  const numChannels = 1;
-  const bitsPerSample = 32;
-  const bytesPerSample = bitsPerSample / 8;
-  const blockAlign = numChannels * bytesPerSample;
-  const byteRate = sampleRate * blockAlign;
-  const dataSize = samples.length * bytesPerSample;
-  const headerSize = 44;
-
-  const buf = Buffer.alloc(headerSize + dataSize);
-
-  // RIFF header
-  buf.write('RIFF', 0, 'ascii');
-  buf.writeUInt32LE(headerSize + dataSize - 8, 4);
-  buf.write('WAVE', 8, 'ascii');
-
-  // fmt chunk
-  buf.write('fmt ', 12, 'ascii');
-  buf.writeUInt32LE(16, 16);          // fmt chunk size
-  buf.writeUInt16LE(3, 20);           // audioFormat = 3 (IEEE float)
-  buf.writeUInt16LE(numChannels, 22);
-  buf.writeUInt32LE(sampleRate, 24);
-  buf.writeUInt32LE(byteRate, 28);
-  buf.writeUInt16LE(blockAlign, 32);
-  buf.writeUInt16LE(bitsPerSample, 34);
-
-  // data chunk
-  buf.write('data', 36, 'ascii');
-  buf.writeUInt32LE(dataSize, 40);
-
-  // sample data
-  for (let i = 0; i < samples.length; i++) {
-    buf.writeFloatLE(samples[i], headerSize + i * bytesPerSample);
-  }
-
-  return buf;
-}
-
-export interface WavHeader {
-  sampleRate: number;
-  numChannels: number;
-  bitsPerSample: number;
-  audioFormat: number;
-  dataSize: number;
-  dataOffset: number;
-  durationMs: number;
-}
-
-/**
- * Parses a WAV file header. Searches for the 'data' chunk rather than
- * assuming a fixed offset.
- */
-export function parseWavHeader(wav: Buffer): WavHeader {
-  if (wav.length < 44) {
-    throw new Error('Buffer too small to be a valid WAV file');
-  }
-  if (wav.toString('ascii', 0, 4) !== 'RIFF') {
-    throw new Error('Not a valid WAV file: missing RIFF header');
-  }
-  if (wav.toString('ascii', 8, 12) !== 'WAVE') {
-    throw new Error('Not a valid WAV file: missing WAVE marker');
-  }
-
-  // Validate and parse fmt chunk (expected at byte 12)
-  if (wav.toString('ascii', 12, 16) !== 'fmt ') {
-    throw new Error('Not a valid WAV file: fmt chunk not found at expected offset');
-  }
-  const audioFormat = wav.readUInt16LE(20);
-  const numChannels = wav.readUInt16LE(22);
-  const sampleRate = wav.readUInt32LE(24);
-  const bitsPerSample = wav.readUInt16LE(34);
-
-  // Search for 'data' chunk
-  let offset = 12; // after 'WAVE'
-  let dataSize = 0;
-  let dataOffset = 0;
-
-  while (offset < wav.length - 8) {
-    const chunkId = wav.toString('ascii', offset, offset + 4);
-    const chunkSize = wav.readUInt32LE(offset + 4);
-
-    if (chunkId === 'data') {
-      dataSize = chunkSize;
-      dataOffset = offset + 8;
-      break;
-    }
-
-    offset += 8 + chunkSize;
-  }
-
-  if (dataOffset === 0) {
-    throw new Error('No data chunk found in WAV file');
-  }
-
-  const bytesPerSample = bitsPerSample / 8;
-  const totalSamples = dataSize / (bytesPerSample * numChannels);
-  const durationMs = (totalSamples / sampleRate) * 1000;
-
-  return {
-    sampleRate,
-    numChannels,
-    bitsPerSample,
-    audioFormat,
-    dataSize,
-    dataOffset,
-    durationMs,
-  };
-}
-
-/**
- * Creates a mock TTS engine that produces silent WAV buffers of the given
- * duration and records all calls for test assertions.
- */
-export function createMockTTSEngine(
-  durationMs = 500,
-): TTSEngine & { calls: Array<{ text: string; options: TTSEngineOptions }> } {
-  const calls: Array<{ text: string; options: TTSEngineOptions }> = [];
-
-  return {
-    calls,
-    async generate(text: string, options: TTSEngineOptions): Promise<Buffer> {
-      calls.push({ text, options });
-      const sampleRate = 24000;
-      const numSamples = Math.round((durationMs / 1000) * sampleRate);
-      const samples = new Float32Array(numSamples); // zeros = silence
-      return createWavBuffer(samples, sampleRate);
-    },
-  };
-}

package/src/tts/generate.ts

@@ -1,83 +0,0 @@
-/**
- * TTS clip generation with manifest parsing and cache integration.
- */
-
-import fs from 'node:fs';
-import type { TTSEngine } from './engine.js';
-import { ClipCache, type ManifestEntry } from './cache.js';
-
-export interface GenerateClipsOptions {
-  manifestPath: string;
-  demoName: string;
-  engine: TTSEngine;
-  projectRoot: string;
-  defaults?: { voice?: string; speed?: number };
-}
-
-export interface ClipResult {
-  scene: string;
-  clipPath: string;
-}
-
-export async function generateClips(options: GenerateClipsOptions): Promise<ClipResult[]> {
-  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: unknown[];
-  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 as Record<string, unknown>;
-    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: ClipResult[] = [];
-
-  for (const raw of rawEntries) {
-    const r = raw as Record<string, unknown>;
-
-    // 4. Build ManifestEntry with defaults
-    const manifestEntry: ManifestEntry = {
-      scene: r.scene as string,
-      text: r.text as string,
-      voice: (r.voice as string | undefined) ?? defaults?.voice,
-      speed: (r.speed as number | undefined) ?? 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;
-}

package/src/tts/kokoro.ts

@@ -1,51 +0,0 @@
-import type { TTSEngine, TTSEngineOptions } from './engine.js';
-
-export class KokoroEngine implements TTSEngine {
-  private tts: any = null;
-  private modelId: string;
-  private dtype: string;
-
-  constructor(options?: { modelId?: string; dtype?: string }) {
-    this.modelId = options?.modelId ?? 'onnx-community/Kokoro-82M-ONNX';
-    this.dtype = options?.dtype ?? 'fp32';
-  }
-
-  private async getTTS(): Promise<any> {
-    if (this.tts) return this.tts;
-    try {
-      const { KokoroTTS } = await import('kokoro-js');
-      this.tts = await KokoroTTS.from_pretrained(this.modelId, {
-        dtype: this.dtype as 'fp32' | 'fp16' | 'q8' | 'q4' | 'q4f16',
-      });
-    } 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 as Error).message}`
-      );
-    }
-    return this.tts;
-  }
-
-  async generate(text: string, options: TTSEngineOptions): Promise<Buffer> {
-    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);
-  }
-}