node-av 5.1.0 → 5.2.0-beta.2

package/benchmarks/index.ts

@@ -1,264 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * node-av Benchmark CLI
- *
- * Comprehensive benchmark suite comparing node-av with FFmpeg CLI.
- *
- * Usage:
- *   npm run benchmark              # Run all benchmarks
- *   npm run benchmark -- --help    # Show help
- *   npm run benchmark -- transcode # Run only transcode benchmarks
- *   npm run benchmark -- memory    # Run only memory benchmarks
- *   npm run benchmark -- latency   # Run only latency benchmarks
- *   npm run benchmark -- -i file1.mp4 -i file2.mp4  # Multiple inputs
- */
-
-import { existsSync, readdirSync } from 'node:fs';
-import { mkdir } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { measureAllLatencies } from './cases/latency.js';
-import { runAllMemoryBenchmarks } from './cases/memory.js';
-import { runAllTranscodeBenchmarks } from './cases/transcode.js';
-import { runner } from './runner.js';
-import { createInputFileInfo, getSystemInfo, saveResultsJSON, writeReport } from './utils/report.js';
-
-import type { BenchmarkReport, InputFileInfo } from './utils/report.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Default paths
-const testDataDir = resolve(__dirname, '../testdata');
-const resultsDir = resolve(__dirname, 'results');
-const defaultInputFile = join(testDataDir, 'video.mp4');
-
-/**
- * Parse command line arguments
- */
-function parseArgs(): { category?: string; inputFiles: string[]; help: boolean; noReport: boolean; iterations?: number; pattern?: string } {
-  const args = process.argv.slice(2);
-  let category: string | undefined;
-  const inputFiles: string[] = [];
-  let help = false;
-  let noReport = false;
-  let iterations: number | undefined;
-  let pattern: string | undefined;
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-
-    if (arg === '--help' || arg === '-h') {
-      help = true;
-    } else if (arg === '--no-report') {
-      noReport = true;
-    } else if (arg === '--input' || arg === '-i') {
-      inputFiles.push(args[++i]);
-    } else if (arg === '--pattern' || arg === '-p') {
-      pattern = args[++i];
-    } else if (arg === '--iterations' || arg === '-n') {
-      iterations = parseInt(args[++i], 10);
-    } else if (!arg.startsWith('-')) {
-      category = arg;
-    }
-  }
-
-  return { category, inputFiles, help, noReport, iterations, pattern };
-}
-
-/**
- * Expand glob pattern to file list
- */
-function expandPattern(pattern: string): string[] {
-  const dir = dirname(pattern);
-  const filePattern = basename(pattern).replace('*', '.*');
-  const regex = new RegExp(`^${filePattern}$`);
-
-  if (!existsSync(dir)) return [];
-
-  return readdirSync(dir)
-    .filter((file) => regex.test(file))
-    .map((file) => join(dir, file))
-    .sort();
-}
-
-/**
- * Print help message
- */
-function printHelp(): void {
-  console.log(`
-node-av Benchmark Suite
-========================
-
-Usage:
-  npm run benchmark [options] [category]
-
-Categories:
-  transcode    Run transcode speed benchmarks
-  memory       Run memory usage benchmarks
-  latency      Run latency benchmarks
-  all          Run all benchmarks (default)
-
-Options:
-  -h, --help          Show this help message
-  -i, --input FILE    Use custom input file (can be repeated for multiple files)
-  -p, --pattern PAT   Use glob pattern to match input files
-  -n, --iterations N  Number of iterations per benchmark (default: 5)
-  --no-report         Skip generating BENCHMARK.md report
-
-Examples:
-  npm run benchmark                              # Run all benchmarks with default input
-  npm run benchmark transcode                    # Run only transcode benchmarks
-  npm run benchmark -- -i input.mp4              # Use custom input file
-  npm run benchmark -- -i h264.mp4 -i hevc.mp4   # Multiple input files
-  npm run benchmark -- -p "testdata/bbb-4k-*"    # Match pattern
-  npm run benchmark -- -n 10                     # Run 10 iterations
-  npm run benchmark -- --no-report               # Skip report generation
-`);
-}
-
-/**
- * Main benchmark runner
- */
-async function main(): Promise<void> {
-  const { category, inputFiles, help, noReport, pattern } = parseArgs();
-
-  if (help) {
-    printHelp();
-    process.exit(0);
-  }
-
-  // Resolve input files
-  let inputs: string[] = [];
-
-  if (pattern) {
-    inputs = expandPattern(pattern);
-    if (inputs.length === 0) {
-      console.error(`Error: No files matched pattern: ${pattern}`);
-      process.exit(1);
-    }
-  } else if (inputFiles.length > 0) {
-    inputs = inputFiles;
-  } else {
-    inputs = [defaultInputFile];
-  }
-
-  // Validate all input files exist
-  for (const input of inputs) {
-    if (!existsSync(input)) {
-      console.error(`Error: Input file not found: ${input}`);
-      console.error('Please provide a valid input file with --input or ensure testdata/video.mp4 exists.');
-      process.exit(1);
-    }
-  }
-
-  // Ensure results directory exists
-  if (!existsSync(resultsDir)) {
-    await mkdir(resultsDir, { recursive: true });
-  }
-
-  console.log(`
-╔═══════════════════════════════════════════════════════════════╗
-║              node-av Benchmark Suite                          ║
-╚═══════════════════════════════════════════════════════════════╝
-`);
-
-  // Print system info
-  console.log('Gathering system information...\n');
-  const systemInfo = await getSystemInfo();
-
-  console.log(`System: ${systemInfo.os} ${systemInfo.osVersion} (${systemInfo.arch})`);
-  console.log(`CPU: ${systemInfo.cpu} (${systemInfo.cpuCores} cores)`);
-  console.log(`RAM: ${systemInfo.ram}`);
-  if (systemInfo.gpu) {
-    console.log(`GPU: ${systemInfo.gpu}`);
-  }
-  console.log(`Node.js: ${systemInfo.nodeVersion}`);
-  console.log(`FFmpeg: ${systemInfo.ffmpegVersion}`);
-  console.log(`node-av: ${systemInfo.nodeAVVersion}`);
-  console.log(`Input files: ${inputs.length}`);
-  for (const input of inputs) {
-    console.log(`  - ${basename(input)}`);
-  }
-
-  // Get input file info for all files
-  const inputFileInfos: InputFileInfo[] = [];
-  for (const input of inputs) {
-    const info = await createInputFileInfo(input);
-    inputFileInfos.push(info);
-    console.log(`\n${basename(input)}:`);
-    if (info.duration > 0) {
-      console.log(`  Duration: ${info.duration.toFixed(1)}s`);
-      if (info.resolution) {
-        console.log(`  Resolution: ${info.resolution}`);
-      }
-      if (info.codec) {
-        console.log(`  Codec: ${info.codec}`);
-      }
-      if (info.fps) {
-        console.log(`  FPS: ${info.fps.toFixed(1)}`);
-      }
-    }
-  }
-
-  // Run benchmarks based on category for each input file
-  const categoryLower = category?.toLowerCase() ?? 'all';
-  let latencyMetrics;
-
-  for (const input of inputs) {
-    console.log(`\n${'='.repeat(60)}`);
-    console.log(`📁 Benchmarking: ${basename(input)}`);
-    console.log('='.repeat(60));
-
-    switch (categoryLower) {
-      case 'transcode':
-        await runAllTranscodeBenchmarks(input);
-        break;
-      case 'memory':
-        await runAllMemoryBenchmarks(input);
-        break;
-      case 'latency':
-        latencyMetrics = await measureAllLatencies(input, 10);
-        break;
-      case 'all':
-      default:
-        await runAllTranscodeBenchmarks(input);
-        await runAllMemoryBenchmarks(input);
-        // Only measure latency for first file (it's input-independent)
-        if (input === inputs[0]) {
-          latencyMetrics = await measureAllLatencies(input, 10);
-        }
-        break;
-    }
-  }
-
-  // Generate report if not disabled
-  if (!noReport) {
-    const results = runner.getResults();
-
-    const report: BenchmarkReport = {
-      systemInfo,
-      inputFileInfos,
-      transcodeResults: results.filter((r) => r.config.category === 'transcode'),
-      memoryResults: results.filter((r) => r.config.category === 'memory'),
-      latencyMetrics,
-      timestamp: new Date().toISOString(),
-    };
-
-    await writeReport(report);
-    saveResultsJSON(report);
-  }
-
-  console.log(`
-╔═══════════════════════════════════════════════════════════════╗
-║                    Benchmarks Complete                        ║
-╚═══════════════════════════════════════════════════════════════╝
-`);
-}
-
-// Run main
-main().catch((error) => {
-  console.error('Benchmark failed:', error);
-  process.exit(1);
-});

package/benchmarks/regen-report.ts

@@ -1,22 +0,0 @@
-/**
- * Regenerate BENCHMARK.md from existing results JSON
- */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { generateReport } from './utils/report.js';
-
-import type { BenchmarkReport } from './utils/report.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const resultsPath = resolve(__dirname, 'results/benchmark-results.json');
-const outputPath = resolve(__dirname, '../BENCHMARK.md');
-
-const report: BenchmarkReport = JSON.parse(readFileSync(resultsPath, 'utf-8'));
-report.timestamp = new Date().toISOString();
-
-const markdown = await generateReport(report);
-writeFileSync(outputPath, markdown, 'utf-8');
-
-console.log('✓ BENCHMARK.md regenerated');

package/benchmarks/results/.gitkeep

@@ -1,2 +0,0 @@
-# This directory stores benchmark results (JSON)
-# These files are gitignored to keep the repository clean

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();