webcodecs-node 0.2.2

package/examples/hardware-decoding.ts

@@ -0,0 +1,245 @@
+/**
+ * Hardware Accelerated Video Decoding Example
+ *
+ * Demonstrates GPU-accelerated decoding with VAAPI, NVDEC, or QSV.
+ *
+ * Run: npx tsx examples/hardware-decoding.ts
+ */
+
+import {
+  VideoEncoder,
+  VideoDecoder,
+  VideoFrame,
+  EncodedVideoChunk,
+} from '../src/index.js';
+import {
+  detectHardwareAcceleration,
+  getHardwareAccelerationSummary,
+} from '../src/index.js';
+
+interface BenchmarkResult {
+  mode: string;
+  decodeTime: number;
+  framesDecoded: number;
+  fps: number;
+}
+
+async function createTestChunks(
+  width: number,
+  height: number,
+  frameCount: number,
+  framerate: number
+): Promise<EncodedVideoChunk[]> {
+  const chunks: EncodedVideoChunk[] = [];
+
+  const encoder = new VideoEncoder({
+    output: (chunk) => chunks.push(chunk),
+    error: console.error,
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001E',
+    width,
+    height,
+    bitrate: 5_000_000,
+    framerate,
+  });
+
+  // Generate complex frames for realistic decoding load
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * 4;
+        rgba[idx] = (x * y + i * 17) % 256;
+        rgba[idx + 1] = (x + y * 2 + i * 23) % 256;
+        rgba[idx + 2] = ((x - y) * 3 + i * 31) % 256;
+        rgba[idx + 3] = 255;
+      }
+    }
+
+    const frame = new VideoFrame(rgba, {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate,
+    });
+
+    encoder.encode(frame, { keyFrame: i % framerate === 0 });
+    frame.close();
+  }
+
+  await encoder.flush();
+  encoder.close();
+
+  return chunks;
+}
+
+async function benchmarkDecode(
+  chunks: EncodedVideoChunk[],
+  width: number,
+  height: number,
+  hardwareAcceleration: 'no-preference' | 'prefer-hardware' | 'prefer-software'
+): Promise<BenchmarkResult> {
+  let framesDecoded = 0;
+
+  const decoder = new VideoDecoder({
+    output: (frame) => {
+      framesDecoded++;
+      frame.close();
+    },
+    error: console.error,
+  });
+
+  decoder.configure({
+    codec: 'avc1.42001E',
+    codedWidth: width,
+    codedHeight: height,
+    hardwareAcceleration,
+  });
+
+  const startTime = Date.now();
+
+  for (const chunk of chunks) {
+    decoder.decode(chunk);
+  }
+
+  await decoder.flush();
+  decoder.close();
+
+  const decodeTime = Date.now() - startTime;
+
+  return {
+    mode: hardwareAcceleration,
+    decodeTime,
+    framesDecoded,
+    fps: (framesDecoded * 1000) / decodeTime,
+  };
+}
+
+async function main() {
+  console.log('=== Hardware Accelerated Video Decoding ===\n');
+
+  // Detect available hardware acceleration
+  console.log('Detecting hardware acceleration...\n');
+
+  const summary = await getHardwareAccelerationSummary();
+  console.log(summary);
+  console.log('');
+
+  // Get detailed capabilities
+  const capabilities = await detectHardwareAcceleration();
+
+  if (capabilities.decoders.length > 0) {
+    console.log('Hardware decoders:');
+    for (const dec of capabilities.decoders) {
+      console.log(`  - ${dec}`);
+    }
+    console.log('');
+  } else {
+    console.log('No hardware decoders detected.\n');
+  }
+
+  // Benchmark parameters
+  const width = 1280;
+  const height = 720;
+  const frameCount = 120;
+  const framerate = 30;
+
+  console.log(`Creating ${frameCount} test frames at ${width}x${height}...`);
+  const chunks = await createTestChunks(width, height, frameCount, framerate);
+  console.log(`Created ${chunks.length} encoded chunks\n`);
+
+  const totalBytes = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+  console.log(`Total encoded size: ${(totalBytes / 1024).toFixed(2)} KB`);
+  console.log(`Average chunk size: ${(totalBytes / chunks.length).toFixed(0)} bytes\n`);
+
+  // Benchmark software decoding
+  console.log('Testing software decoding...');
+  const softwareResult = await benchmarkDecode(chunks, width, height, 'prefer-software');
+
+  // Benchmark hardware decoding
+  console.log('Testing hardware decoding...');
+  const hardwareResult = await benchmarkDecode(chunks, width, height, 'prefer-hardware');
+
+  // Display results
+  console.log('\n=== Benchmark Results ===\n');
+
+  console.log('Software Decoding (CPU):');
+  console.log(`  Decode time: ${softwareResult.decodeTime}ms`);
+  console.log(`  Frames decoded: ${softwareResult.framesDecoded}`);
+  console.log(`  Throughput: ${softwareResult.fps.toFixed(1)} fps`);
+  console.log(`  Real-time capable: ${softwareResult.fps >= framerate ? 'Yes' : 'No'}`);
+
+  console.log('\nHardware Decoding (GPU):');
+  console.log(`  Decode time: ${hardwareResult.decodeTime}ms`);
+  console.log(`  Frames decoded: ${hardwareResult.framesDecoded}`);
+  console.log(`  Throughput: ${hardwareResult.fps.toFixed(1)} fps`);
+  console.log(`  Real-time capable: ${hardwareResult.fps >= framerate ? 'Yes' : 'No'}`);
+
+  // Comparison
+  console.log('\n=== Comparison ===\n');
+
+  const speedup = softwareResult.decodeTime / hardwareResult.decodeTime;
+
+  if (speedup > 1.1) {
+    console.log(`Hardware decoding is ${speedup.toFixed(2)}x faster`);
+  } else if (speedup < 0.9) {
+    console.log(`Software decoding is ${(1 / speedup).toFixed(2)}x faster`);
+    console.log('(Hardware acceleration may not be available or configured)');
+  } else {
+    console.log('Performance is similar (hardware may not be available)');
+  }
+
+  // Calculate how many streams could be decoded in real-time
+  const softwareStreams = Math.floor(softwareResult.fps / framerate);
+  const hardwareStreams = Math.floor(hardwareResult.fps / framerate);
+
+  console.log(`\nConcurrent streams (real-time @ ${framerate}fps):`);
+  console.log(`  Software: ${softwareStreams} stream${softwareStreams !== 1 ? 's' : ''}`);
+  console.log(`  Hardware: ${hardwareStreams} stream${hardwareStreams !== 1 ? 's' : ''}`);
+
+  // Usage recommendations
+  console.log('\n=== When to Use Hardware Decoding ===\n');
+
+  console.log('Use prefer-hardware when:');
+  console.log('  - Decoding HD/4K video');
+  console.log('  - Multiple simultaneous streams');
+  console.log('  - Real-time playback');
+  console.log('  - Transcoding pipelines');
+  console.log('  - CPU resources are constrained');
+
+  console.log('\nUse prefer-software when:');
+  console.log('  - Maximum compatibility needed');
+  console.log('  - No compatible GPU available');
+  console.log('  - Decoding unusual/rare codecs');
+  console.log('  - Frame-accurate seeking required');
+
+  // Example configuration
+  console.log('\n=== Example Configuration ===\n');
+  console.log(`const decoder = new VideoDecoder({
+  output: (frame) => {
+    // Process decoded frame
+    processFrame(frame);
+    frame.close();
+  },
+  error: handleError,
+});
+
+decoder.configure({
+  codec: 'avc1.42001E',
+  codedWidth: 1920,
+  codedHeight: 1080,
+  hardwareAcceleration: 'prefer-hardware',
+});
+
+// Decode chunks
+for (const chunk of encodedChunks) {
+  decoder.decode(chunk);
+}
+
+await decoder.flush();
+decoder.close();`);
+}
+
+main().catch(console.error);

package/examples/hardware-encoding.ts

@@ -0,0 +1,231 @@
+/**
+ * Hardware Accelerated Video Encoding Example
+ *
+ * Demonstrates GPU-accelerated encoding with VAAPI, NVENC, or QSV.
+ *
+ * Run: npx tsx examples/hardware-encoding.ts
+ */
+
+import { VideoEncoder, VideoFrame, EncodedVideoChunk } from '../src/index.js';
+import {
+  detectHardwareAcceleration,
+  getHardwareAccelerationSummary,
+  getBestEncoder,
+} from '../src/index.js';
+
+interface BenchmarkResult {
+  mode: string;
+  encoder: string;
+  encodeTime: number;
+  totalBytes: number;
+  fps: number;
+}
+
+async function benchmark(
+  width: number,
+  height: number,
+  frameCount: number,
+  framerate: number,
+  hardwareAcceleration: 'no-preference' | 'prefer-hardware' | 'prefer-software'
+): Promise<BenchmarkResult> {
+  const chunks: EncodedVideoChunk[] = [];
+
+  const encoder = new VideoEncoder({
+    output: (chunk) => chunks.push(chunk),
+    error: console.error,
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001E',
+    width,
+    height,
+    bitrate: 5_000_000,
+    framerate,
+    hardwareAcceleration,
+  });
+
+  // Pre-generate all frame data to exclude from timing
+  const frames: Uint8Array[] = [];
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+    // Create complex pattern for realistic encoding load
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * 4;
+        // Animated noise pattern
+        rgba[idx] = (x * y + i * 17) % 256;
+        rgba[idx + 1] = (x + y * 2 + i * 23) % 256;
+        rgba[idx + 2] = ((x - y) * 3 + i * 31) % 256;
+        rgba[idx + 3] = 255;
+      }
+    }
+    frames.push(rgba);
+  }
+
+  // Time the encoding
+  const startTime = Date.now();
+
+  for (let i = 0; i < frameCount; i++) {
+    const frame = new VideoFrame(frames[i], {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate,
+    });
+
+    encoder.encode(frame, { keyFrame: i % framerate === 0 });
+    frame.close();
+  }
+
+  await encoder.flush();
+  encoder.close();
+
+  const encodeTime = Date.now() - startTime;
+  const totalBytes = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+
+  return {
+    mode: hardwareAcceleration,
+    encoder: hardwareAcceleration === 'prefer-hardware' ? 'GPU (if available)' : 'CPU',
+    encodeTime,
+    totalBytes,
+    fps: (frameCount * 1000) / encodeTime,
+  };
+}
+
+async function main() {
+  console.log('=== Hardware Accelerated Video Encoding ===\n');
+
+  // Detect available hardware acceleration
+  console.log('Detecting hardware acceleration...\n');
+
+  const summary = await getHardwareAccelerationSummary();
+  console.log(summary);
+  console.log('');
+
+  // Get detailed capabilities
+  const capabilities = await detectHardwareAcceleration();
+
+  if (capabilities.methods.length > 0) {
+    console.log('Available acceleration methods:');
+    for (const method of capabilities.methods) {
+      console.log(`  - ${method}`);
+    }
+    console.log('');
+  }
+
+  if (capabilities.encoders.length > 0) {
+    console.log('Hardware encoders:');
+    for (const enc of capabilities.encoders) {
+      console.log(`  - ${enc}`);
+    }
+    console.log('');
+  }
+
+  // Get best encoder for H.264
+  console.log('Finding best H.264 encoder...');
+  const bestH264 = await getBestEncoder('h264', 'prefer-hardware');
+  console.log(`  Best encoder: ${bestH264.encoder}`);
+  console.log(`  Hardware: ${bestH264.isHardware}`);
+  console.log('');
+
+  // Benchmark parameters
+  const width = 1280;
+  const height = 720;
+  const frameCount = 60;
+  const framerate = 30;
+
+  console.log(`\nBenchmarking ${width}x${height} @ ${framerate}fps (${frameCount} frames)...\n`);
+
+  // Benchmark software encoding
+  console.log('Testing software encoding...');
+  const softwareResult = await benchmark(
+    width,
+    height,
+    frameCount,
+    framerate,
+    'prefer-software'
+  );
+
+  // Benchmark hardware encoding
+  console.log('Testing hardware encoding...');
+  const hardwareResult = await benchmark(
+    width,
+    height,
+    frameCount,
+    framerate,
+    'prefer-hardware'
+  );
+
+  // Display results
+  console.log('\n=== Benchmark Results ===\n');
+
+  console.log('Software Encoding (CPU):');
+  console.log(`  Encode time: ${softwareResult.encodeTime}ms`);
+  console.log(`  Throughput: ${softwareResult.fps.toFixed(1)} fps`);
+  console.log(`  Output size: ${(softwareResult.totalBytes / 1024).toFixed(2)} KB`);
+  console.log(
+    `  Bitrate: ${((softwareResult.totalBytes * 8 * framerate) / frameCount / 1000).toFixed(0)} kbps`
+  );
+
+  console.log('\nHardware Encoding (GPU):');
+  console.log(`  Encode time: ${hardwareResult.encodeTime}ms`);
+  console.log(`  Throughput: ${hardwareResult.fps.toFixed(1)} fps`);
+  console.log(`  Output size: ${(hardwareResult.totalBytes / 1024).toFixed(2)} KB`);
+  console.log(
+    `  Bitrate: ${((hardwareResult.totalBytes * 8 * framerate) / frameCount / 1000).toFixed(0)} kbps`
+  );
+
+  // Comparison
+  console.log('\n=== Comparison ===\n');
+
+  const speedup = softwareResult.encodeTime / hardwareResult.encodeTime;
+  const sizeRatio = hardwareResult.totalBytes / softwareResult.totalBytes;
+
+  if (speedup > 1.1) {
+    console.log(`Hardware encoding is ${speedup.toFixed(2)}x faster`);
+  } else if (speedup < 0.9) {
+    console.log(`Software encoding is ${(1 / speedup).toFixed(2)}x faster`);
+    console.log('(Hardware acceleration may not be available or configured)');
+  } else {
+    console.log('Performance is similar (hardware may not be available)');
+  }
+
+  console.log(
+    `File size difference: ${((sizeRatio - 1) * 100).toFixed(1)}% ` +
+      `(${sizeRatio > 1 ? 'larger' : 'smaller'} with hardware)`
+  );
+
+  // Usage recommendations
+  console.log('\n=== When to Use Hardware Acceleration ===\n');
+
+  console.log('Use prefer-hardware when:');
+  console.log('  - Encoding HD/4K video');
+  console.log('  - Real-time streaming');
+  console.log('  - Batch processing many videos');
+  console.log('  - CPU resources are constrained');
+
+  console.log('\nUse prefer-software when:');
+  console.log('  - Maximum compression quality needed');
+  console.log('  - Archival purposes');
+  console.log('  - No compatible GPU available');
+  console.log('  - Encoding small/low-res content');
+
+  // Example configuration
+  console.log('\n=== Example Configuration ===\n');
+  console.log(`const encoder = new VideoEncoder({
+  output: handleChunk,
+  error: handleError,
+});
+
+encoder.configure({
+  codec: 'avc1.42001E',
+  width: 1920,
+  height: 1080,
+  bitrate: 5_000_000,
+  framerate: 30,
+  hardwareAcceleration: 'prefer-hardware',
+  latencyMode: 'realtime', // Combine with low-latency for streaming
+});`);
+}
+
+main().catch(console.error);

package/examples/image-decoding.ts

@@ -0,0 +1,145 @@
+/**
+ * Image Decoding Example
+ *
+ * Demonstrates how to decode images including animated GIFs.
+ *
+ * Run: npx tsx examples/image-decoding.ts
+ */
+
+import { ImageDecoder } from '../src/index.js';
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+async function decodeImage(imagePath: string) {
+  if (!existsSync(imagePath)) {
+    console.log(`File not found: ${imagePath}`);
+    return;
+  }
+
+  const data = readFileSync(imagePath);
+  const ext = imagePath.split('.').pop()?.toLowerCase();
+
+  // Map extension to MIME type
+  const mimeTypes: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    bmp: 'image/bmp',
+  };
+
+  const type = mimeTypes[ext || ''] || 'image/png';
+
+  console.log(`\nDecoding: ${imagePath}`);
+  console.log(`MIME type: ${type}`);
+  console.log(`File size: ${(data.length / 1024).toFixed(2)} KB`);
+
+  const decoder = new ImageDecoder({
+    type,
+    data,
+  });
+
+  // Wait for parsing to complete
+  await decoder.completed;
+
+  const track = decoder.tracks.selectedTrack;
+  if (!track) {
+    console.log('No image track found');
+    decoder.close();
+    return;
+  }
+
+  console.log(`\nImage properties:`);
+  console.log(`  Frames: ${track.frameCount}`);
+  console.log(`  Animated: ${track.animated}`);
+  if (track.animated) {
+    console.log(
+      `  Loop count: ${track.repetitionCount === Infinity ? 'infinite' : track.repetitionCount}`
+    );
+  }
+
+  // Decode each frame
+  console.log(`\nFrames:`);
+  for (let i = 0; i < track.frameCount; i++) {
+    const { image, complete } = await decoder.decode({ frameIndex: i });
+
+    console.log(
+      `  Frame ${i}: ${image.codedWidth}x${image.codedHeight}, ` +
+        `format: ${image.format}, ` +
+        `duration: ${(image.duration || 0) / 1000}ms`
+    );
+
+    image.close();
+  }
+
+  decoder.close();
+}
+
+async function main() {
+  console.log('=== Image Decoding Example ===');
+
+  // Check if ImageDecoder supports various formats
+  const formats = ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/avif'];
+
+  console.log('\nSupported formats:');
+  for (const format of formats) {
+    const supported = await ImageDecoder.isTypeSupported(format);
+    console.log(`  ${format}: ${supported ? 'yes' : 'no'}`);
+  }
+
+  // Try to decode sample images if they exist
+  const samplePaths = [
+    '/tmp/webcodecs-test-images/test.png',
+    '/tmp/webcodecs-test-images/test.gif',
+    '/tmp/webcodecs-test-images/test.webp',
+  ];
+
+  for (const path of samplePaths) {
+    if (existsSync(path)) {
+      await decodeImage(path);
+    }
+  }
+
+  // If no sample images, create a simple PNG in memory
+  if (!samplePaths.some(existsSync)) {
+    console.log('\nNo sample images found. Creating a test image in memory...');
+
+    // Minimal valid PNG (1x1 red pixel)
+    const minimalPng = Buffer.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
+      0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, // IHDR chunk
+      0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
+      0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53,
+      0xde, 0x00, 0x00, 0x00, 0x0c, 0x49, 0x44, 0x41, // IDAT chunk
+      0x54, 0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00,
+      0x00, 0x00, 0x03, 0x00, 0x01, 0x00, 0x18, 0xdd,
+      0x8d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, // IEND chunk
+      0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+    ]);
+
+    const decoder = new ImageDecoder({
+      type: 'image/png',
+      data: minimalPng,
+    });
+
+    await decoder.completed;
+
+    const track = decoder.tracks.selectedTrack;
+    console.log(`\nDecoded in-memory PNG:`);
+    console.log(`  Frames: ${track?.frameCount}`);
+
+    if (track && track.frameCount > 0) {
+      const { image } = await decoder.decode({ frameIndex: 0 });
+      console.log(`  Size: ${image.codedWidth}x${image.codedHeight}`);
+      console.log(`  Format: ${image.format}`);
+      image.close();
+    }
+
+    decoder.close();
+  }
+}
+
+main().catch(console.error);