node-av 5.0.4 → 5.1.0

package/BENCHMARK.md

@@ -0,0 +1,113 @@
+# node-av Benchmark Results
+
+> Generated: 2026-01-27T18:12:31.045Z
+
+## System Information
+
+| Property | Value |
+|----------|-------|
+| **OS** | darwin 25.1.0 |
+| **Architecture** | arm64 |
+| **CPU** | Apple M3 Max |
+| **CPU Cores** | 16 |
+| **RAM** | 48.0 GB |
+| **GPU** | Apple M3 Max |
+| **Node.js** | v24.8.0 |
+| **FFmpeg** | 8.0-Jellyfin |
+| **node-av** | 5.0.4 |
+
+
+## Test Inputs
+
+| File | Codec | Resolution | FPS | Duration |
+|------|-------|------------|-----|----------|
+| bbb-4k-av1.mp4 | av1 | 3840x2160 | 60 | 30.0s |
+| bbb-4k-h264.mp4 | h264 | 3840x2160 | 60 | 30.0s |
+| bbb-4k-hevc.mp4 | hevc | 3840x2160 | 60 | 30.0s |
+| bbb-4k-vp9.webm | vp9 | 3840x2160 | 60 | 30.0s |
+
+
+## Transcode Speed
+
+### Input: bbb-4k-av1.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 95.1 fps | 94.5 fps | 18.93s | 19.06s | -0.6% |
+| SW H.265 Transcode | 38.9 fps | 40.1 fps | 46.31s | 44.93s | +3.2% |
+| HW H.264 Transcode | 54.6 fps | 54.9 fps | 32.98s | 32.79s | +0.6% |
+| Stream Copy (Remux) | 50307.7 fps | 29472.5 fps | 36ms | 109ms | -41.4% |
+
+### Input: bbb-4k-h264.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.5 fps | 97.2 fps | 18.65s | 18.52s | +0.7% |
+| SW H.265 Transcode | 40.0 fps | 39.9 fps | 45.00s | 45.12s | -0.2% |
+| HW H.264 Transcode | 54.6 fps | 54.9 fps | 32.98s | 32.83s | +0.5% |
+| Stream Copy (Remux) | 38235.1 fps | 30884.8 fps | 48ms | 104ms | -19.2% |
+
+### Input: bbb-4k-hevc.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.3 fps | 95.9 fps | 18.70s | 18.78s | -0.4% |
+| SW H.265 Transcode | 41.4 fps | 41.8 fps | 43.49s | 43.06s | +1.0% |
+| HW H.264 Transcode | 54.5 fps | 54.9 fps | 33.00s | 32.82s | +0.6% |
+| Stream Copy (Remux) | 55110.3 fps | 30395.4 fps | 33ms | 106ms | -44.8% |
+
+### Input: bbb-4k-vp9.webm
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.5 fps | 96.1 fps | 18.66s | 18.75s | -0.4% |
+| SW H.265 Transcode | 41.6 fps | 42.0 fps | 43.23s | 42.90s | +0.8% |
+| HW H.264 Transcode | 54.6 fps | 54.8 fps | 32.98s | 32.85s | +0.4% |
+| Stream Copy (Remux) | 48635.3 fps | 31617.3 fps | 37ms | 105ms | -35.0% |
+
+
+## Memory Usage
+
+### Input: bbb-4k-av1.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.5 GB | 3.5 GB | -2.0% |
+| Memory: Stream Copy | 19.9 MB | 1.1 MB | -94.6% |
+
+### Input: bbb-4k-h264.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.7 GB | 3.4 GB | -6.0% |
+| Memory: Stream Copy | 40.7 MB | 1.9 MB | -95.2% |
+
+### Input: bbb-4k-hevc.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.8 GB | 3.5 GB | -5.4% |
+| Memory: Stream Copy | 20.5 MB | 320.0 KB | -98.5% |
+
+### Input: bbb-4k-vp9.webm
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.5 GB | 3.3 GB | -4.7% |
+| Memory: Stream Copy | 30.6 MB | 378.7 KB | -98.8% |
+
+*Note: FFmpeg CLI memory is measured via `/usr/bin/time` (macOS: `-l`, Linux: `-v`).
+
+
+## Latency
+
+| Metric | Mean | Min | Max | StdDev |
+|--------|------|-----|-----|--------|
+| Demuxer Open | 466µs | 430µs | 561µs | 41µs |
+| First Packet | 530µs | 491µs | 575µs | 30µs |
+| First Frame | 11.7ms | 7.2ms | 15.2ms | 2.7ms |
+| First Encoded Packet | 25.2ms | 23.9ms | 26.9ms | 856µs |
+| Pipeline Total | 25.8ms | 22.5ms | 27.3ms | 1.4ms |
+
+*Note: Each metric is measured independently. "First Encoded Packet" uses default encoder settings while "Pipeline Total" uses `tune=zerolatency` for low-latency output.*
+

package/README.md

@@ -35,6 +35,7 @@ Native Node.js bindings for FFmpeg with full TypeScript support. Provides direct
 - [Resource Management](#resource-management)
 - [FFmpeg Binary Access](#ffmpeg-binary-access)
 - [Performance](#performance)
+  - [Benchmarks](#benchmarks)
   - [Sync vs Async Operations](#sync-vs-async-operations)
 - [Memory Safety Considerations](#memory-safety-considerations)
 - [Examples](#examples)
@@ -426,6 +427,25 @@ The FFmpeg binary is automatically downloaded during installation from GitHub re
 
 NodeAV executes all media operations directly through FFmpeg's native C libraries. The Node.js bindings add minimal overhead - mostly just the JavaScript-to-C boundary crossings. During typical operations like transcoding or filtering, most processing time is spent in FFmpeg's optimized C code.
 
+### Benchmarks
+
+Performance comparison with FFmpeg CLI (4K 60fps, 30s test files on Apple M3 Max):
+
+| Operation | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|-----------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96 fps | 96 fps | 18.7s | 18.7s | ≈0% |
+| SW H.265 Transcode | 40 fps | 41 fps | 44.5s | 43.7s | **+1.5%** |
+| HW H.264 Transcode | 55 fps | 55 fps | 33.0s | 32.8s | **+0.5%** |
+| Stream Copy (Remux) | 48k fps | 31k fps | 38ms | 106ms | -35% |
+
+**Memory Usage:**
+| Operation | FFmpeg CLI | node-av | Difference |
+|-----------|-----------|---------|------------|
+| H.264 Transcode (4K) | 3.6 GB | 3.4 GB | **-5%** |
+| Stream Copy | 28 MB | 1 MB | **-96%** |
+
+📊 **[Full benchmark results](https://github.com/seydx/node-av/tree/main/BENCHMARK.md)**
+
 ### Sync vs Async Operations
 
 Every async method in NodeAV has a corresponding synchronous variant with the `Sync` suffix:
@@ -473,6 +493,7 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | `api-whisper-transcribe` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-whisper-transcribe.ts) |
 | `frame-utils` | | [✓](https://github.com/seydx/node-av/tree/main/examples/frame-utils.ts) | |
 | `avio-read-callback` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/avio_read_callback.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/avio-read-callback.ts) | |
+| `avio-async-read-callback` | | [✓](https://github.com/seydx/node-av/tree/main/examples/avio-async-read-callback.ts) | |
 | `decode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_audio.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/decode-audio.ts) | |
 | `decode-filter-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_audio.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/decode-filter-audio.ts) | |
 | `decode-filter-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_video.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/decode-filter-video.ts) | |
@@ -562,3 +583,24 @@ For issues and questions, please use the GitHub issue tracker.
 - [FFmpeg Doxygen](https://ffmpeg.org/doxygen/trunk/)
 - [Jellyfin FFmpeg](https://github.com/seydx/jellyfin-ffmpeg)
 - [FFmpeg MSVC](https://github.com/seydx/ffmpeg-msvc-prebuilt)
+
+## Star History
+
+<picture>
+  <source
+    media="(prefers-color-scheme: dark)"
+    srcset="
+      https://api.star-history.com/svg?repos=seydx/node-av&type=Date&theme=dark
+    "
+  />
+  <source
+    media="(prefers-color-scheme: light)"
+    srcset="
+      https://api.star-history.com/svg?repos=seydx/node-av&type=Date
+    "
+  />
+  <img
+    alt="Star History Chart"
+    src="https://api.star-history.com/svg?repos=seydx/node-av&type=Date"
+  />
+</picture>

package/benchmarks/cases/latency.ts

@@ -0,0 +1,361 @@
+/**
+ * Latency Benchmark Tests
+ *
+ * Measures various latency metrics for node-av:
+ * - Time to open a file and get first frame
+ * - Time to decode first frame
+ * - Time to encode first frame
+ * - End-to-end pipeline latency
+ */
+
+import { existsSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Decoder, Demuxer, Encoder, Muxer } from '../../src/api/index.js';
+import { FF_ENCODER_LIBX264 } from '../../src/constants/encoders.js';
+import { Timer, computeStats } from '../utils/measure.js';
+
+import type { Stats } from '../utils/measure.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Default paths
+const testDataDir = resolve(__dirname, '../../testdata');
+const resultsDir = resolve(__dirname, '../results');
+
+/**
+ * Latency measurement result
+ */
+export interface LatencyResult {
+  name: string;
+  description: string;
+  stats: Stats;
+  samples: number[];
+}
+
+/**
+ * All latency metrics collected
+ */
+export interface LatencyMetrics {
+  demuxerOpen: LatencyResult;
+  firstPacket: LatencyResult;
+  firstFrame: LatencyResult;
+  firstEncodedPacket: LatencyResult;
+  pipelineTotal: LatencyResult;
+}
+
+/**
+ * Measure latency with multiple iterations
+ */
+async function measureLatency(name: string, description: string, fn: () => Promise<void>, iterations = 10): Promise<LatencyResult> {
+  const samples: number[] = [];
+
+  // Warmup
+  await fn();
+
+  // Actual measurements
+  for (let i = 0; i < iterations; i++) {
+    const timer = new Timer();
+    timer.start();
+    await fn();
+    timer.stop();
+    samples.push(timer.getElapsedMs());
+  }
+
+  return {
+    name,
+    description,
+    stats: computeStats(samples),
+    samples,
+  };
+}
+
+/**
+ * Measure Demuxer.open() latency
+ */
+export async function measureDemuxerOpenLatency(inputFile?: string, iterations = 10): Promise<LatencyResult> {
+  const input = inputFile ?? join(testDataDir, 'video.mp4');
+
+  return measureLatency(
+    'Demuxer.open()',
+    'Time to open input file and parse headers',
+    async () => {
+      const demuxer = await Demuxer.open(input);
+      await demuxer.close();
+    },
+    iterations,
+  );
+}
+
+/**
+ * Measure time to first packet
+ */
+export async function measureFirstPacketLatency(inputFile?: string, iterations = 10): Promise<LatencyResult> {
+  const input = inputFile ?? join(testDataDir, 'video.mp4');
+
+  return measureLatency(
+    'First Packet',
+    'Time from open to receiving first packet',
+    async () => {
+      const demuxer = await Demuxer.open(input);
+      const videoStream = demuxer.video();
+      if (!videoStream) {
+        await demuxer.close();
+        throw new Error('No video stream found');
+      }
+
+      // Get first packet
+      for await (const packet of demuxer.packets(videoStream.index)) {
+        if (packet) break;
+      }
+
+      await demuxer.close();
+    },
+    iterations,
+  );
+}
+
+/**
+ * Measure time to first decoded frame
+ */
+export async function measureFirstFrameLatency(inputFile?: string, iterations = 10): Promise<LatencyResult> {
+  const input = inputFile ?? join(testDataDir, 'video.mp4');
+
+  return measureLatency(
+    'First Frame',
+    'Time from open to first decoded frame',
+    async () => {
+      const demuxer = await Demuxer.open(input);
+      const videoStream = demuxer.video();
+      if (!videoStream) {
+        await demuxer.close();
+        throw new Error('No video stream found');
+      }
+
+      const decoder = await Decoder.create(videoStream);
+
+      // Get first frame
+      let gotFrame = false;
+      for await (const packet of demuxer.packets(videoStream.index)) {
+        if (!packet) continue;
+
+        for await (const frame of decoder.frames(packet)) {
+          if (frame) {
+            gotFrame = true;
+            break;
+          }
+        }
+
+        if (gotFrame) break;
+      }
+
+      await demuxer.close();
+    },
+    iterations,
+  );
+}
+
+/**
+ * Measure time to first encoded packet
+ */
+export async function measureFirstEncodedPacketLatency(inputFile?: string, iterations = 10): Promise<LatencyResult> {
+  const input = inputFile ?? join(testDataDir, 'video.mp4');
+
+  return measureLatency(
+    'First Encoded Packet',
+    'Time from open to first re-encoded packet',
+    async () => {
+      const demuxer = await Demuxer.open(input);
+      const videoStream = demuxer.video();
+      if (!videoStream) {
+        await demuxer.close();
+        throw new Error('No video stream found');
+      }
+
+      const decoder = await Decoder.create(videoStream);
+      const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+        decoder,
+        options: { preset: 'ultrafast', tune: 'zerolatency' },
+      });
+
+      // Get first encoded packet
+      let gotPacket = false;
+      for await (const packet of demuxer.packets(videoStream.index)) {
+        if (!packet) continue;
+
+        for await (const frame of decoder.frames(packet)) {
+          if (!frame) continue;
+
+          for await (const encodedPacket of encoder.packets(frame)) {
+            if (encodedPacket) {
+              gotPacket = true;
+              break;
+            }
+          }
+
+          if (gotPacket) break;
+        }
+
+        if (gotPacket) break;
+      }
+
+      await demuxer.close();
+    },
+    iterations,
+  );
+}
+
+/**
+ * Measure end-to-end pipeline latency (first packet written to output)
+ */
+export async function measurePipelineLatency(inputFile?: string, iterations = 10): Promise<LatencyResult> {
+  const input = inputFile ?? join(testDataDir, 'video.mp4');
+  const output = join(resultsDir, 'latency-output.mp4');
+
+  return measureLatency(
+    'Pipeline Total',
+    'Time from open to first packet written to output',
+    async () => {
+      const demuxer = await Demuxer.open(input);
+      const videoStream = demuxer.video();
+      if (!videoStream) {
+        await demuxer.close();
+        throw new Error('No video stream found');
+      }
+
+      const decoder = await Decoder.create(videoStream);
+      const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+        decoder,
+        options: { preset: 'ultrafast', tune: 'zerolatency' },
+      });
+
+      const muxer = await Muxer.open(output);
+      const streamIndex = muxer.addStream(encoder);
+
+      // Get first packet written to output
+      let wrotePacket = false;
+      for await (const packet of demuxer.packets(videoStream.index)) {
+        if (!packet) continue;
+
+        for await (const frame of decoder.frames(packet)) {
+          if (!frame) continue;
+
+          for await (const encodedPacket of encoder.packets(frame)) {
+            if (encodedPacket) {
+              await muxer.writePacket(encodedPacket, streamIndex);
+              wrotePacket = true;
+              break;
+            }
+          }
+
+          if (wrotePacket) break;
+        }
+
+        if (wrotePacket) break;
+      }
+
+      await demuxer.close();
+      await muxer.close();
+
+      // Clean up the incomplete output file
+      if (existsSync(output)) {
+        unlinkSync(output);
+      }
+    },
+    iterations,
+  );
+}
+
+/**
+ * Run all latency measurements and collect metrics
+ */
+export async function measureAllLatencies(inputFile?: string, iterations = 10): Promise<LatencyMetrics> {
+  console.log('\n⏱️  Measuring Latency Metrics\n');
+  console.log('='.repeat(60));
+
+  console.log('Measuring Demuxer.open() latency...');
+  const demuxerOpen = await measureDemuxerOpenLatency(inputFile, iterations);
+
+  console.log('Measuring First Packet latency...');
+  const firstPacket = await measureFirstPacketLatency(inputFile, iterations);
+
+  console.log('Measuring First Frame latency...');
+  const firstFrame = await measureFirstFrameLatency(inputFile, iterations);
+
+  console.log('Measuring First Encoded Packet latency...');
+  const firstEncodedPacket = await measureFirstEncodedPacketLatency(inputFile, iterations);
+
+  console.log('Measuring Pipeline Total latency...');
+  const pipelineTotal = await measurePipelineLatency(inputFile, iterations);
+
+  const metrics = {
+    demuxerOpen,
+    firstPacket,
+    firstFrame,
+    firstEncodedPacket,
+    pipelineTotal,
+  };
+
+  // Print results
+  printLatencyResults(metrics);
+
+  return metrics;
+}
+
+/**
+ * Print latency results in a formatted table
+ */
+function printLatencyResults(metrics: LatencyMetrics): void {
+  console.log('\n📊 Latency Results:\n');
+  console.log('┌──────────────────────────┬──────────┬──────────┬──────────┬──────────┐');
+  console.log('│ Metric                   │ Mean     │ Min      │ Max      │ StdDev   │');
+  console.log('├──────────────────────────┼──────────┼──────────┼──────────┼──────────┤');
+
+  const results = [metrics.demuxerOpen, metrics.firstPacket, metrics.firstFrame, metrics.firstEncodedPacket, metrics.pipelineTotal];
+
+  for (const result of results) {
+    const name = result.name.padEnd(24);
+    const mean = formatMs(result.stats.mean).padStart(8);
+    const min = formatMs(result.stats.min).padStart(8);
+    const max = formatMs(result.stats.max).padStart(8);
+    const stdDev = formatMs(result.stats.stdDev).padStart(8);
+
+    console.log(`│ ${name} │ ${mean} │ ${min} │ ${max} │ ${stdDev} │`);
+  }
+
+  console.log('└──────────────────────────┴──────────┴──────────┴──────────┴──────────┘');
+  console.log('');
+
+  // Show breakdown
+  console.log('Latency Breakdown:');
+  console.log(`  Open → First Packet: ${formatMs(metrics.firstPacket.stats.mean - metrics.demuxerOpen.stats.mean)}`);
+  console.log(`  First Packet → First Frame: ${formatMs(metrics.firstFrame.stats.mean - metrics.firstPacket.stats.mean)}`);
+  console.log(`  First Frame → First Encoded: ${formatMs(metrics.firstEncodedPacket.stats.mean - metrics.firstFrame.stats.mean)}`);
+  console.log(`  First Encoded → Written: ${formatMs(metrics.pipelineTotal.stats.mean - metrics.firstEncodedPacket.stats.mean)}`);
+
+  console.log('\n' + '='.repeat(60));
+}
+
+/**
+ * Format milliseconds
+ */
+function formatMs(ms: number): string {
+  if (ms < 1) {
+    return `${(ms * 1000).toFixed(0)}µs`;
+  }
+  return `${ms.toFixed(1)}ms`;
+}
+
+/**
+ * Run all latency benchmarks
+ */
+export async function runAllLatencyBenchmarks(inputFile?: string): Promise<void> {
+  console.log('\n⚡ Running Latency Benchmarks\n');
+  console.log('='.repeat(60));
+
+  await measureAllLatencies(inputFile, 10);
+
+  console.log('\nLatency benchmarks completed\n');
+}