node-av 5.1.0 → 5.1.1

package/benchmarks/runner.ts

@@ -1,247 +0,0 @@
-/**
- * Benchmark Runner
- *
- * Core class for running benchmarks and collecting results.
- * Supports both FFmpeg CLI and node-av implementations.
- */
-
-import { existsSync, unlinkSync } from 'node:fs';
-import { mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-import { measureFFmpegCLI } from './utils/ffmpeg-cli.js';
-import { aggregateResults, measure } from './utils/measure.js';
-
-import type { FFmpegRunOptions } from './utils/ffmpeg-cli.js';
-import type { AggregatedResult, MeasureResult } from './utils/measure.js';
-
-/**
- * Configuration for a benchmark test case
- */
-export interface BenchmarkConfig {
-  /** Name of the benchmark */
-  name: string;
-  /** Description of what this benchmark tests */
-  description: string;
-  /** Category: transcode, memory, or latency */
-  category: 'transcode' | 'memory' | 'latency';
-  /** Number of iterations to run */
-  iterations: number;
-  /** Number of warmup iterations (not counted in results) */
-  warmupIterations: number;
-  /** Input file path */
-  inputFile: string;
-  /** Output file path (will be deleted after each run) */
-  outputFile: string;
-}
-
-/**
- * Result of a benchmark comparison between FFmpeg CLI and node-av
- */
-export interface BenchmarkComparison {
-  config: BenchmarkConfig;
-  ffmpegCLI: AggregatedResult;
-  nodeAV: AggregatedResult;
-  /** Difference metrics */
-  comparison: {
-    /** Duration difference (positive means node-av is slower) */
-    durationDiffPercent: number;
-    /** Memory difference (positive means node-av uses more memory) */
-    memoryDiffPercent: number;
-    /** FPS difference (positive means node-av is faster) */
-    fpsDiffPercent?: number;
-  };
-}
-
-/**
- * Callback type for node-av benchmark function
- */
-export type NodeAVBenchmarkFn = () => Promise<{ framesProcessed?: number }>;
-
-/**
- * Runner for executing and comparing benchmarks
- */
-export class BenchmarkRunner {
-  private results: BenchmarkComparison[] = [];
-
-  /**
-   * Run a single iteration and measure results
-   */
-  private async runSingleIteration(
-    config: BenchmarkConfig,
-    ffmpegOptions: FFmpegRunOptions,
-    nodeAVFn: NodeAVBenchmarkFn,
-  ): Promise<{ ffmpeg: MeasureResult; nodeAV: MeasureResult }> {
-    // Ensure output directory exists
-    const outputDir = dirname(config.outputFile);
-    if (!existsSync(outputDir)) {
-      await mkdir(outputDir, { recursive: true });
-    }
-
-    // Run FFmpeg CLI
-    const ffmpegResult = await measureFFmpegCLI(ffmpegOptions);
-
-    // Clean up output file
-    if (existsSync(config.outputFile)) {
-      unlinkSync(config.outputFile);
-    }
-
-    // Run node-av
-    const nodeAVResult = await measure(nodeAVFn);
-
-    // Clean up output file
-    if (existsSync(config.outputFile)) {
-      unlinkSync(config.outputFile);
-    }
-
-    return { ffmpeg: ffmpegResult, nodeAV: nodeAVResult };
-  }
-
-  /**
-   * Run a complete benchmark with warmup and multiple iterations
-   */
-  async runBenchmark(config: BenchmarkConfig, ffmpegOptions: FFmpegRunOptions, nodeAVFn: NodeAVBenchmarkFn): Promise<BenchmarkComparison> {
-    console.log(`\n📊 Running benchmark: ${config.name}`);
-    console.log(`   ${config.description}`);
-    console.log(`   Iterations: ${config.iterations} (+ ${config.warmupIterations} warmup)\n`);
-
-    const ffmpegResults: MeasureResult[] = [];
-    const nodeAVResults: MeasureResult[] = [];
-
-    // Warmup iterations
-    for (let i = 0; i < config.warmupIterations; i++) {
-      process.stdout.write(`   Warmup ${i + 1}/${config.warmupIterations}...\r`);
-      await this.runSingleIteration(config, ffmpegOptions, nodeAVFn);
-      // GC between iterations to prevent memory accumulation
-      if (global.gc) {
-        global.gc();
-        await new Promise((resolve) => setTimeout(resolve, 100));
-      }
-    }
-
-    // Actual benchmark iterations
-    for (let i = 0; i < config.iterations; i++) {
-      process.stdout.write(`   Iteration ${i + 1}/${config.iterations}...\r`);
-      const { ffmpeg, nodeAV } = await this.runSingleIteration(config, ffmpegOptions, nodeAVFn);
-      ffmpegResults.push(ffmpeg);
-      nodeAVResults.push(nodeAV);
-      // GC between iterations to prevent memory accumulation
-      if (global.gc) {
-        global.gc();
-        await new Promise((resolve) => setTimeout(resolve, 100));
-      }
-    }
-
-    console.log(''); // New line after progress
-
-    // Aggregate results
-    const ffmpegAggregated = aggregateResults(ffmpegResults);
-    const nodeAVAggregated = aggregateResults(nodeAVResults);
-
-    // Calculate comparison metrics
-    const durationDiffPercent = this.percentDiff(ffmpegAggregated.durationMs.mean, nodeAVAggregated.durationMs.mean);
-
-    const memoryDiffPercent =
-      ffmpegAggregated.peakMemoryBytes.mean > 0 ? this.percentDiff(ffmpegAggregated.peakMemoryBytes.mean, nodeAVAggregated.peakMemoryBytes.mean) : 0;
-
-    const fpsDiffPercent = ffmpegAggregated.fps && nodeAVAggregated.fps ? this.percentDiff(ffmpegAggregated.fps.mean, nodeAVAggregated.fps.mean) : undefined;
-
-    const result: BenchmarkComparison = {
-      config,
-      ffmpegCLI: ffmpegAggregated,
-      nodeAV: nodeAVAggregated,
-      comparison: {
-        durationDiffPercent,
-        memoryDiffPercent,
-        fpsDiffPercent,
-      },
-    };
-
-    this.results.push(result);
-
-    // Print summary
-    this.printBenchmarkSummary(result);
-
-    return result;
-  }
-
-  /**
-   * Calculate percentage difference
-   */
-  private percentDiff(baseline: number, comparison: number): number {
-    if (baseline === 0) return 0;
-    return ((comparison - baseline) / baseline) * 100;
-  }
-
-  /**
-   * Print summary of a single benchmark result
-   */
-  private printBenchmarkSummary(result: BenchmarkComparison): void {
-    const { ffmpegCLI, nodeAV, comparison } = result;
-
-    console.log('   Results:');
-    console.log('   ┌──────────────────┬──────────────────┬──────────────────┐');
-    console.log('   │ Metric           │ FFmpeg CLI       │ node-av          │');
-    console.log('   ├──────────────────┼──────────────────┼──────────────────┤');
-
-    const durationStr = `${ffmpegCLI.durationMs.mean.toFixed(0)}ms`;
-    const nodeAVDurationStr = `${nodeAV.durationMs.mean.toFixed(0)}ms`;
-    console.log(`   │ Duration         │ ${durationStr.padEnd(16)} │ ${nodeAVDurationStr.padEnd(16)} │`);
-
-    if (ffmpegCLI.fps && nodeAV.fps) {
-      const fpsStr = `${ffmpegCLI.fps.mean.toFixed(1)} fps`;
-      const nodeAVFpsStr = `${nodeAV.fps.mean.toFixed(1)} fps`;
-      console.log(`   │ FPS              │ ${fpsStr.padEnd(16)} │ ${nodeAVFpsStr.padEnd(16)} │`);
-    }
-
-    const memStr = this.formatBytes(ffmpegCLI.peakMemoryBytes.mean);
-    const nodeAVMemStr = this.formatBytes(nodeAV.peakMemoryBytes.mean);
-    console.log(`   │ Peak Memory      │ ${memStr.padEnd(16)} │ ${nodeAVMemStr.padEnd(16)} │`);
-
-    console.log('   └──────────────────┴──────────────────┴──────────────────┘');
-
-    const diffSign = comparison.durationDiffPercent > 0 ? '+' : '';
-    console.log(`   Difference: ${diffSign}${comparison.durationDiffPercent.toFixed(1)}% duration`);
-
-    if (comparison.fpsDiffPercent !== undefined) {
-      const fpsSign = comparison.fpsDiffPercent > 0 ? '+' : '';
-      console.log(`              ${fpsSign}${comparison.fpsDiffPercent.toFixed(1)}% FPS`);
-    }
-  }
-
-  /**
-   * Format bytes to human readable
-   */
-  private formatBytes(bytes: number): string {
-    if (bytes === 0) return 'N/A';
-    const units = ['B', 'KB', 'MB', 'GB'];
-    let value = bytes;
-    let unitIndex = 0;
-
-    while (value >= 1024 && unitIndex < units.length - 1) {
-      value /= 1024;
-      unitIndex++;
-    }
-
-    return `${value.toFixed(1)} ${units[unitIndex]}`;
-  }
-
-  /**
-   * Get all collected results
-   */
-  getResults(): BenchmarkComparison[] {
-    return this.results;
-  }
-
-  /**
-   * Clear all results
-   */
-  clearResults(): void {
-    this.results = [];
-  }
-}
-
-/**
- * Global benchmark runner instance
- */
-export const runner = new BenchmarkRunner();

package/benchmarks/utils/ffmpeg-cli.ts

@@ -1,363 +0,0 @@
-/**
- * FFmpeg CLI Wrapper
- *
- * Provides utilities for running FFmpeg CLI commands and measuring
- * their performance for comparison with node-av.
- */
-
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { platform } from 'node:os';
-
-import { ffmpegPath, isFfmpegAvailable } from '../../src/ffmpeg/index.js';
-
-import type { MeasureResult } from './measure.js';
-
-export interface FFmpegRunOptions {
-  /** Input file path */
-  input: string;
-  /** Output file path */
-  output: string;
-  /** Additional FFmpeg arguments */
-  args?: string[];
-  /** Timeout in milliseconds */
-  timeout?: number;
-}
-
-export interface FFmpegRunResult {
-  /** Exit code */
-  exitCode: number;
-  /** Standard output */
-  stdout: string;
-  /** Standard error (contains progress) */
-  stderr: string;
-  /** Duration in milliseconds */
-  durationMs: number;
-  /** Parsed frame count if available */
-  framesProcessed?: number;
-  /** Parsed FPS if available */
-  fps?: number;
-  /** Peak memory (estimated from /usr/bin/time if available) */
-  peakMemoryBytes?: number;
-}
-
-/**
- * Get the FFmpeg binary path, checking if it exists
- */
-export function getFFmpegPath(): string {
-  if (isFfmpegAvailable()) {
-    return ffmpegPath();
-  }
-
-  // Try system ffmpeg
-  const systemPaths = ['/usr/bin/ffmpeg', '/usr/local/bin/ffmpeg', '/opt/homebrew/bin/ffmpeg'];
-
-  for (const path of systemPaths) {
-    if (existsSync(path)) {
-      return path;
-    }
-  }
-
-  throw new Error('FFmpeg binary not found. Please install FFmpeg or run npm install to download the bundled binary.');
-}
-
-/**
- * Run FFmpeg CLI with the given arguments
- */
-export async function runFFmpegCLI(options: FFmpegRunOptions): Promise<FFmpegRunResult> {
-  const { input, output, args = [], timeout = 300000 } = options;
-
-  const ffmpeg = getFFmpegPath();
-
-  const ffmpegArgs = ['-hide_banner', '-y', '-i', input, ...args, output];
-
-  // Use /usr/bin/time to measure memory usage
-  // macOS: /usr/bin/time -l outputs "maximum resident set size" in bytes
-  // Linux: /usr/bin/time -v outputs "Maximum resident set size (kbytes)"
-  const os = platform();
-  const useTime = os === 'darwin' || os === 'linux';
-  const timePath = '/usr/bin/time';
-  const timeExists = useTime && existsSync(timePath);
-
-  let command: string;
-  let fullArgs: string[];
-
-  if (timeExists) {
-    command = timePath;
-    if (os === 'darwin') {
-      // macOS: -l for resource usage
-      fullArgs = ['-l', ffmpeg, ...ffmpegArgs];
-    } else {
-      // Linux: -v for verbose (includes memory)
-      fullArgs = ['-v', ffmpeg, ...ffmpegArgs];
-    }
-  } else {
-    command = ffmpeg;
-    fullArgs = ffmpegArgs;
-  }
-
-  return new Promise((resolve, reject) => {
-    const startTime = process.hrtime.bigint();
-
-    const proc = spawn(command, fullArgs, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    proc.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    const timeoutId = setTimeout(() => {
-      proc.kill('SIGKILL');
-      reject(new Error(`FFmpeg timed out after ${timeout}ms`));
-    }, timeout);
-
-    proc.on('close', (code) => {
-      clearTimeout(timeoutId);
-      const endTime = process.hrtime.bigint();
-      const durationMs = Number(endTime - startTime) / 1_000_000;
-
-      // Parse frame count from stderr (look for the last occurrence)
-      const frameMatches = [...stderr.matchAll(/frame=\s*(\d+)/g)];
-      const frameCount = frameMatches.length > 0 ? parseInt(frameMatches[frameMatches.length - 1][1], 10) : undefined;
-
-      // Parse FPS - try multiple methods:
-      // 1. Direct fps= value (if > 0)
-      // 2. Calculate from speed= multiplier and video duration
-      // 3. Calculate from frame count and our measured duration
-      let fps: number | undefined;
-
-      const fpsMatch = /fps=\s*([\d.]+)/.exec(stderr);
-      if (fpsMatch && parseFloat(fpsMatch[1]) > 0) {
-        fps = parseFloat(fpsMatch[1]);
-      } else if (frameCount && durationMs > 0) {
-        // Calculate FPS from frames processed and actual duration
-        fps = (frameCount / durationMs) * 1000;
-      }
-
-      // Parse peak memory from /usr/bin/time output
-      let peakMemoryBytes: number | undefined;
-      if (timeExists) {
-        if (os === 'darwin') {
-          // macOS: "maximum resident set size" is in bytes
-          // Format: "    123456789  maximum resident set size"
-          const memMatch = /(\d+)\s+maximum resident set size/.exec(stderr);
-          if (memMatch) {
-            peakMemoryBytes = parseInt(memMatch[1], 10);
-          }
-        } else {
-          // Linux: "Maximum resident set size (kbytes): 123456"
-          const memMatch = /Maximum resident set size.*?:\s*(\d+)/.exec(stderr);
-          if (memMatch) {
-            peakMemoryBytes = parseInt(memMatch[1], 10) * 1024; // Convert KB to bytes
-          }
-        }
-      }
-
-      resolve({
-        exitCode: code ?? 0,
-        stdout,
-        stderr,
-        durationMs,
-        framesProcessed: frameCount,
-        fps,
-        peakMemoryBytes,
-      });
-    });
-
-    proc.on('error', (err) => {
-      clearTimeout(timeoutId);
-      reject(err);
-    });
-  });
-}
-
-/**
- * Run FFmpeg CLI and return a MeasureResult for comparison
- */
-export async function measureFFmpegCLI(options: FFmpegRunOptions): Promise<MeasureResult> {
-  const result = await runFFmpegCLI(options);
-
-  if (result.exitCode !== 0) {
-    throw new Error(`FFmpeg failed with exit code ${result.exitCode}: ${result.stderr}`);
-  }
-
-  // Calculate FPS from frames and duration if not available from output
-  const fps = result.fps ?? (result.framesProcessed ? (result.framesProcessed / result.durationMs) * 1000 : undefined);
-
-  return {
-    durationMs: result.durationMs,
-    peakMemoryBytes: result.peakMemoryBytes ?? 0,
-    memorySamples: [],
-    framesProcessed: result.framesProcessed,
-    fps,
-  };
-}
-
-/**
- * Get FFmpeg version string
- */
-export async function getFFmpegVersion(): Promise<string> {
-  const ffmpeg = getFFmpegPath();
-
-  return new Promise((resolve, reject) => {
-    const proc = spawn(ffmpeg, ['-version'], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-
-    proc.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    proc.on('close', (code) => {
-      if (code !== 0) {
-        reject(new Error('Failed to get FFmpeg version'));
-        return;
-      }
-
-      // Parse version from first line
-      const match = /ffmpeg version (\S+)/.exec(stdout);
-      resolve(match ? match[1] : 'unknown');
-    });
-
-    proc.on('error', reject);
-  });
-}
-
-/**
- * Probe a media file using ffprobe
- */
-export async function probeMediaFile(
-  filePath: string,
-): Promise<{ duration: number; videoCodec?: string; audioCodec?: string; width?: number; height?: number; fps?: number }> {
-  const ffmpeg = getFFmpegPath();
-  const ffprobe = ffmpeg.replace('ffmpeg', 'ffprobe');
-
-  // Check if ffprobe exists, otherwise use ffmpeg -i
-  const probeExists = existsSync(ffprobe);
-
-  return new Promise((resolve, reject) => {
-    if (probeExists) {
-      const proc = spawn(ffprobe, ['-v', 'quiet', '-print_format', 'json', '-show_format', '-show_streams', filePath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-
-      let stdout = '';
-
-      proc.stdout.on('data', (data) => {
-        stdout += data.toString();
-      });
-
-      proc.on('close', (code) => {
-        if (code !== 0) {
-          reject(new Error('Failed to probe media file'));
-          return;
-        }
-
-        try {
-          const info = JSON.parse(stdout);
-          const videoStream = info.streams?.find((s: { codec_type: string }) => s.codec_type === 'video');
-          const audioStream = info.streams?.find((s: { codec_type: string }) => s.codec_type === 'audio');
-
-          let fps: number | undefined;
-          if (videoStream?.r_frame_rate) {
-            const [num, den] = videoStream.r_frame_rate.split('/').map(Number);
-            fps = num / den;
-          }
-
-          resolve({
-            duration: parseFloat(info.format?.duration ?? '0'),
-            videoCodec: videoStream?.codec_name,
-            audioCodec: audioStream?.codec_name,
-            width: videoStream?.width,
-            height: videoStream?.height,
-            fps,
-          });
-        } catch (e) {
-          reject(e);
-        }
-      });
-
-      proc.on('error', reject);
-    } else {
-      // Fallback: use ffmpeg -i and parse stderr
-      const proc = spawn(ffmpeg, ['-i', filePath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-
-      let stderr = '';
-
-      proc.stderr.on('data', (data) => {
-        stderr += data.toString();
-      });
-
-      proc.on('close', () => {
-        // Parse duration
-        const durationMatch = /Duration: (\d+):(\d+):(\d+\.\d+)/.exec(stderr);
-        let duration = 0;
-        if (durationMatch) {
-          duration = parseInt(durationMatch[1]) * 3600 + parseInt(durationMatch[2]) * 60 + parseFloat(durationMatch[3]);
-        }
-
-        // Parse video stream info
-        const videoMatch = /Stream #\d+:\d+.*Video: (\w+).*, (\d+)x(\d+).*, ([\d.]+) fps/.exec(stderr);
-
-        // Parse audio stream info
-        const audioMatch = /Stream #\d+:\d+.*Audio: (\w+)/.exec(stderr);
-
-        resolve({
-          duration,
-          videoCodec: videoMatch?.[1],
-          width: videoMatch ? parseInt(videoMatch[2]) : undefined,
-          height: videoMatch ? parseInt(videoMatch[3]) : undefined,
-          fps: videoMatch ? parseFloat(videoMatch[4]) : undefined,
-          audioCodec: audioMatch?.[1],
-        });
-      });
-
-      proc.on('error', reject);
-    }
-  });
-}
-
-/**
- * Build common FFmpeg arguments for different test cases
- * Note: -threads 0 enables auto-detection (same as node-av default)
- */
-export const FFmpegArgs = {
-  /** Software H.264 encoding */
-  swH264: (crf = 23): string[] => ['-threads', '0', '-c:v', 'libx264', '-preset', 'medium', '-crf', crf.toString(), '-c:a', 'copy'],
-
-  /** Software H.265/HEVC encoding */
-  swH265: (crf = 28): string[] => ['-threads', '0', '-c:v', 'libx265', '-preset', 'medium', '-crf', crf.toString(), '-c:a', 'copy'],
-
-  /** Hardware H.264 encoding (VideoToolbox) */
-  hwH264VideoToolbox: (): string[] => ['-threads', '0', '-c:v', 'h264_videotoolbox', '-b:v', '2M', '-c:a', 'copy'],
-
-  /** Hardware H.264 encoding (NVENC) */
-  hwH264Nvenc: (): string[] => ['-threads', '0', '-c:v', 'h264_nvenc', '-preset', 'p4', '-b:v', '2M', '-c:a', 'copy'],
-
-  /** Hardware H.264 encoding (VAAPI) */
-  hwH264Vaapi: (): string[] => ['-threads', '0', '-vaapi_device', '/dev/dri/renderD128', '-c:v', 'h264_vaapi', '-b:v', '2M', '-c:a', 'copy'],
-
-  /** Hardware H.264 encoding (QSV) */
-  hwH264Qsv: (): string[] => ['-threads', '0', '-c:v', 'h264_qsv', '-preset', 'medium', '-b:v', '2M', '-c:a', 'copy'],
-
-  /** Stream copy (no re-encoding) */
-  streamCopy: (): string[] => ['-c', 'copy'],
-
-  /** Video only (no audio) */
-  videoOnly: (videoArgs: string[]): string[] => [...videoArgs, '-an'],
-
-  /** First N seconds only */
-  duration: (seconds: number, args: string[]): string[] => ['-t', seconds.toString(), ...args],
-};