webcodecs-node 0.2.2

package/examples/streaming.ts

@@ -0,0 +1,151 @@
+/**
+ * Streaming Example
+ *
+ * Demonstrates real-time encoding with latencyMode comparison.
+ *
+ * Run: npx tsx examples/streaming.ts
+ */
+
+import { VideoEncoder, VideoFrame, EncodedVideoChunk } from '../src/index.js';
+
+interface EncodingResult {
+  mode: string;
+  chunks: number;
+  totalBytes: number;
+  keyFrames: number;
+  encodeTime: number;
+}
+
+async function encodeWithMode(
+  mode: 'quality' | 'realtime',
+  width: number,
+  height: number,
+  frameCount: number,
+  framerate: number
+): Promise<EncodingResult> {
+  const chunks: EncodedVideoChunk[] = [];
+  const startTime = Date.now();
+
+  const encoder = new VideoEncoder({
+    output: (chunk) => chunks.push(chunk),
+    error: console.error,
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001E',
+    width,
+    height,
+    bitrate: 1_000_000,
+    framerate,
+    latencyMode: mode,
+  });
+
+  // Generate frames
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+
+    // Create moving pattern for realistic encoding
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * 4;
+        rgba[idx] = ((x + i * 10) % 256); // R
+        rgba[idx + 1] = ((y + i * 5) % 256); // G
+        rgba[idx + 2] = (((x + y) / 2 + i * 3) % 256); // B
+        rgba[idx + 3] = 255; // A
+      }
+    }
+
+    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();
+
+  const encodeTime = Date.now() - startTime;
+
+  return {
+    mode,
+    chunks: chunks.length,
+    totalBytes: chunks.reduce((sum, c) => sum + c.byteLength, 0),
+    keyFrames: chunks.filter((c) => c.type === 'key').length,
+    encodeTime,
+  };
+}
+
+async function main() {
+  console.log('=== Streaming / Latency Mode Comparison ===\n');
+
+  const width = 640;
+  const height = 480;
+  const frameCount = 60;
+  const framerate = 30;
+
+  console.log(`Encoding ${frameCount} frames at ${width}x${height} @ ${framerate}fps\n`);
+
+  // Test quality mode
+  console.log('Testing quality mode...');
+  const qualityResult = await encodeWithMode('quality', width, height, frameCount, framerate);
+
+  // Test realtime mode
+  console.log('Testing realtime mode...');
+  const realtimeResult = await encodeWithMode('realtime', width, height, frameCount, framerate);
+
+  // Display results
+  console.log('\n=== Results ===\n');
+
+  console.log('Quality Mode (optimized for compression):');
+  console.log(`  Encode time: ${qualityResult.encodeTime}ms`);
+  console.log(`  Output size: ${(qualityResult.totalBytes / 1024).toFixed(2)} KB`);
+  console.log(`  Chunks: ${qualityResult.chunks}`);
+  console.log(`  Key frames: ${qualityResult.keyFrames}`);
+  console.log(
+    `  Bitrate: ${((qualityResult.totalBytes * 8 * framerate) / frameCount / 1000).toFixed(0)} kbps`
+  );
+
+  console.log('\nRealtime Mode (optimized for low latency):');
+  console.log(`  Encode time: ${realtimeResult.encodeTime}ms`);
+  console.log(`  Output size: ${(realtimeResult.totalBytes / 1024).toFixed(2)} KB`);
+  console.log(`  Chunks: ${realtimeResult.chunks}`);
+  console.log(`  Key frames: ${realtimeResult.keyFrames}`);
+  console.log(
+    `  Bitrate: ${((realtimeResult.totalBytes * 8 * framerate) / frameCount / 1000).toFixed(0)} kbps`
+  );
+
+  console.log('\n=== Comparison ===\n');
+
+  const sizeDiff =
+    ((realtimeResult.totalBytes - qualityResult.totalBytes) / qualityResult.totalBytes) * 100;
+  const timeDiff =
+    ((realtimeResult.encodeTime - qualityResult.encodeTime) / qualityResult.encodeTime) * 100;
+
+  console.log(
+    `Size difference: ${sizeDiff > 0 ? '+' : ''}${sizeDiff.toFixed(1)}% ` +
+      `(realtime uses ${sizeDiff > 0 ? 'more' : 'less'} space)`
+  );
+  console.log(
+    `Time difference: ${timeDiff > 0 ? '+' : ''}${timeDiff.toFixed(1)}% ` +
+      `(realtime is ${timeDiff < 0 ? 'faster' : 'slower'})`
+  );
+
+  console.log('\n=== When to use each mode ===\n');
+  console.log('Quality mode:');
+  console.log('  - File encoding for storage/distribution');
+  console.log('  - VOD (Video on Demand) content');
+  console.log('  - When file size matters more than latency');
+
+  console.log('\nRealtime mode:');
+  console.log('  - Live streaming');
+  console.log('  - Video conferencing');
+  console.log('  - Real-time screen sharing');
+  console.log('  - When latency matters more than compression');
+}
+
+main().catch(console.error);

package/examples/transparent-video.ts

@@ -0,0 +1,162 @@
+/**
+ * Transparent Video Example
+ *
+ * Demonstrates encoding video with alpha channel using VP9.
+ *
+ * Run: npx tsx examples/transparent-video.ts
+ */
+
+import { VideoEncoder, VideoFrame, EncodedVideoChunk } from '../src/index.js';
+
+async function main() {
+  const width = 256;
+  const height = 256;
+  const frameCount = 30;
+  const framerate = 30;
+
+  console.log('=== Transparent Video Encoding Example ===\n');
+
+  // Check if VP9 supports alpha
+  const support = await VideoEncoder.isConfigSupported({
+    codec: 'vp9',
+    width,
+    height,
+  });
+
+  if (!support.supported) {
+    console.log('VP9 encoding not supported');
+    return;
+  }
+
+  const chunks: EncodedVideoChunk[] = [];
+
+  const encoder = new VideoEncoder({
+    output: (chunk, metadata) => {
+      chunks.push(chunk);
+      console.log(`Encoded: ${chunk.type} frame, ${chunk.byteLength} bytes`);
+    },
+    error: console.error,
+  });
+
+  // Configure VP9 with alpha preservation
+  encoder.configure({
+    codec: 'vp9',
+    width,
+    height,
+    alpha: 'keep', // Preserve transparency
+    framerate,
+  });
+
+  console.log('Encoding frames with transparency...\n');
+
+  // Generate frames with animated transparency
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+
+    // Create a circular gradient with animated transparency
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const maxRadius = Math.min(width, height) / 2;
+    const animPhase = (i / frameCount) * Math.PI * 2;
+
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const idx = (y * width + x) * 4;
+
+        // Distance from center
+        const dx = x - centerX;
+        const dy = y - centerY;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+
+        // Animated radius
+        const radius = maxRadius * (0.5 + 0.3 * Math.sin(animPhase));
+
+        if (dist < radius) {
+          // Inside circle: solid color with gradient alpha
+          const alpha = 255 * (1 - dist / radius);
+          rgba[idx] = 100; // R
+          rgba[idx + 1] = 200; // G
+          rgba[idx + 2] = 255; // B
+          rgba[idx + 3] = Math.floor(alpha); // A
+        } else {
+          // Outside circle: fully transparent
+          rgba[idx] = 0;
+          rgba[idx + 1] = 0;
+          rgba[idx + 2] = 0;
+          rgba[idx + 3] = 0;
+        }
+      }
+    }
+
+    const frame = new VideoFrame(rgba, {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate,
+    });
+
+    encoder.encode(frame, { keyFrame: i === 0 });
+    frame.close();
+  }
+
+  await encoder.flush();
+  encoder.close();
+
+  // Statistics
+  const totalBytes = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+
+  console.log(`\nEncoding complete:`);
+  console.log(`  Codec: VP9 with alpha`);
+  console.log(`  Frames: ${frameCount}`);
+  console.log(`  Size: ${(totalBytes / 1024).toFixed(2)} KB`);
+
+  // Compare with discarded alpha
+  console.log('\n--- Comparison with alpha:discard ---\n');
+
+  const chunksNoAlpha: EncodedVideoChunk[] = [];
+
+  const encoderNoAlpha = new VideoEncoder({
+    output: (chunk) => chunksNoAlpha.push(chunk),
+    error: console.error,
+  });
+
+  encoderNoAlpha.configure({
+    codec: 'vp9',
+    width,
+    height,
+    alpha: 'discard', // Strip transparency
+    framerate,
+  });
+
+  // Encode same content without alpha
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+    rgba.fill(128); // Gray with full alpha
+    for (let j = 3; j < rgba.length; j += 4) {
+      rgba[j] = 255;
+    }
+
+    const frame = new VideoFrame(rgba, {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate,
+    });
+
+    encoderNoAlpha.encode(frame, { keyFrame: i === 0 });
+    frame.close();
+  }
+
+  await encoderNoAlpha.flush();
+  encoderNoAlpha.close();
+
+  const totalBytesNoAlpha = chunksNoAlpha.reduce((sum, c) => sum + c.byteLength, 0);
+
+  console.log(`Without alpha: ${(totalBytesNoAlpha / 1024).toFixed(2)} KB`);
+  console.log(`With alpha: ${(totalBytes / 1024).toFixed(2)} KB`);
+  console.log(
+    `Alpha overhead: ${(((totalBytes - totalBytesNoAlpha) / totalBytesNoAlpha) * 100).toFixed(1)}%`
+  );
+}
+
+main().catch(console.error);

package/examples/video-decoding.ts

@@ -0,0 +1,107 @@
+/**
+ * Video Decoding Example
+ *
+ * Demonstrates how to decode video chunks back to raw frames.
+ *
+ * Run: npx tsx examples/video-decoding.ts
+ */
+
+import {
+  VideoEncoder,
+  VideoDecoder,
+  VideoFrame,
+  EncodedVideoChunk,
+} from '../src/index.js';
+
+async function main() {
+  const width = 320;
+  const height = 240;
+  const frameCount = 10;
+  const framerate = 30;
+
+  // First, encode some frames to get chunks to decode
+  const chunks: EncodedVideoChunk[] = [];
+
+  const encoder = new VideoEncoder({
+    output: (chunk) => chunks.push(chunk),
+    error: console.error,
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001E',
+    width,
+    height,
+    bitrate: 500_000,
+    framerate,
+  });
+
+  console.log('Encoding frames...');
+
+  for (let i = 0; i < frameCount; i++) {
+    const rgba = new Uint8Array(width * height * 4);
+    // Create solid color frames for easy verification
+    const color = Math.floor((i / frameCount) * 255);
+    for (let j = 0; j < rgba.length; j += 4) {
+      rgba[j] = color; // R
+      rgba[j + 1] = 255 - color; // G
+      rgba[j + 2] = 128; // B
+      rgba[j + 3] = 255; // A
+    }
+
+    const frame = new VideoFrame(rgba, {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate,
+    });
+
+    encoder.encode(frame, { keyFrame: i === 0 });
+    frame.close();
+  }
+
+  await encoder.flush();
+  encoder.close();
+
+  console.log(`Encoded ${chunks.length} chunks\n`);
+
+  // Now decode the chunks
+  const decodedFrames: { timestamp: number; size: string }[] = [];
+
+  const decoder = new VideoDecoder({
+    output: (frame) => {
+      decodedFrames.push({
+        timestamp: frame.timestamp,
+        size: `${frame.codedWidth}x${frame.codedHeight}`,
+      });
+      console.log(
+        `Decoded frame: ${frame.codedWidth}x${frame.codedHeight}, ` +
+          `format: ${frame.format}, timestamp: ${frame.timestamp}`
+      );
+      frame.close();
+    },
+    error: (err) => {
+      console.error('Decoding error:', err);
+    },
+  });
+
+  decoder.configure({
+    codec: 'avc1.42001E',
+    codedWidth: width,
+    codedHeight: height,
+  });
+
+  console.log('Decoding chunks...');
+
+  for (const chunk of chunks) {
+    decoder.decode(chunk);
+  }
+
+  await decoder.flush();
+  decoder.close();
+
+  console.log(`\nDecoding complete:`);
+  console.log(`  Input chunks: ${chunks.length}`);
+  console.log(`  Output frames: ${decodedFrames.length}`);
+}
+
+main().catch(console.error);

package/examples/video-encoding.ts

@@ -0,0 +1,93 @@
+/**
+ * Video Encoding Example
+ *
+ * Demonstrates how to encode raw video frames to H.264.
+ *
+ * Run: npx tsx examples/video-encoding.ts
+ */
+
+import { VideoEncoder, VideoFrame, EncodedVideoChunk } from '../src/index.js';
+import { writeFileSync } from 'fs';
+
+async function main() {
+  const width = 320;
+  const height = 240;
+  const frameCount = 60;
+  const framerate = 30;
+
+  const chunks: EncodedVideoChunk[] = [];
+
+  // Create encoder with callbacks
+  const encoder = new VideoEncoder({
+    output: (chunk, metadata) => {
+      chunks.push(chunk);
+      console.log(
+        `Encoded frame: ${chunk.type} ${chunk.byteLength} bytes, timestamp: ${chunk.timestamp}`
+      );
+
+      // First chunk includes decoder configuration
+      if (metadata?.decoderConfig) {
+        console.log('Decoder config:', metadata.decoderConfig);
+      }
+    },
+    error: (err) => {
+      console.error('Encoding error:', err);
+    },
+  });
+
+  // Configure the encoder
+  encoder.configure({
+    codec: 'avc1.42001E', // H.264 Baseline
+    width,
+    height,
+    bitrate: 1_000_000,
+    framerate,
+    bitrateMode: 'variable', // VBR for better quality
+  });
+
+  console.log(`Encoding ${frameCount} frames at ${width}x${height}...`);
+
+  // Generate and encode frames
+  for (let i = 0; i < frameCount; i++) {
+    // Create a simple gradient frame
+    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;
+        // Animate color based on frame number
+        rgba[idx] = (x + i * 5) % 256; // R
+        rgba[idx + 1] = (y + i * 3) % 256; // G
+        rgba[idx + 2] = ((x + y) / 2 + i * 2) % 256; // B
+        rgba[idx + 3] = 255; // A
+      }
+    }
+
+    const frame = new VideoFrame(rgba, {
+      format: 'RGBA',
+      codedWidth: width,
+      codedHeight: height,
+      timestamp: (i * 1_000_000) / framerate, // microseconds
+    });
+
+    // Force keyframe every second
+    encoder.encode(frame, { keyFrame: i % framerate === 0 });
+    frame.close();
+  }
+
+  // Wait for all frames to be encoded
+  await encoder.flush();
+  encoder.close();
+
+  // Calculate total size
+  const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const keyFrames = chunks.filter((c) => c.type === 'key').length;
+
+  console.log(`\nEncoding complete:`);
+  console.log(`  Total chunks: ${chunks.length}`);
+  console.log(`  Key frames: ${keyFrames}`);
+  console.log(`  Total size: ${(totalBytes / 1024).toFixed(2)} KB`);
+  console.log(`  Avg bitrate: ${((totalBytes * 8 * framerate) / frameCount / 1000).toFixed(0)} kbps`);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "webcodecs-node",
+  "version": "0.2.2",
+  "description": "WebCodecs API implementation for Node.js using FFmpeg",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mediabunny/FFmpegVideoEncoder": {
+      "types": "./dist/mediabunny/FFmpegVideoEncoder.d.ts",
+      "import": "./dist/mediabunny/FFmpegVideoEncoder.js"
+    },
+    "./mediabunny/FFmpegVideoDecoder": {
+      "types": "./dist/mediabunny/FFmpegVideoDecoder.d.ts",
+      "import": "./dist/mediabunny/FFmpegVideoDecoder.js"
+    },
+    "./mediabunny/FFmpegAudioEncoder": {
+      "types": "./dist/mediabunny/FFmpegAudioEncoder.d.ts",
+      "import": "./dist/mediabunny/FFmpegAudioEncoder.js"
+    },
+    "./mediabunny/FFmpegAudioDecoder": {
+      "types": "./dist/mediabunny/FFmpegAudioDecoder.d.ts",
+      "import": "./dist/mediabunny/FFmpegAudioDecoder.js"
+    },
+    "./polyfill": {
+      "types": "./dist/polyfill.d.ts",
+      "import": "./dist/polyfill.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "demo": "node dist/demos/demo.js",
+    "demo:mediabunny": "node dist/demos/demo-mediabunny.js",
+    "demo:image": "node dist/demos/demo-image.js",
+    "demo:conversion": "node dist/demos/demo-conversion.js",
+    "demo:webcodecs": "node dist/demos/demo-webcodecs.js",
+    "demo:hwaccel": "node dist/demos/demo-hwaccel.js",
+    "demo:hwaccel-conversion": "node dist/demos/demo-hwaccel-conversion.js",
+    "demo:streaming": "node dist/demos/demo-streaming.js",
+    "demo:samples": "node dist/demos/demo-samples.js"
+  },
+  "keywords": [
+    "webcodecs",
+    "video",
+    "audio",
+    "encoder",
+    "decoder",
+    "ffmpeg",
+    "mediabunny",
+    "node",
+    "h264",
+    "hevc",
+    "vp9",
+    "av1",
+    "opus",
+    "aac",
+    "hardware-acceleration",
+    "vaapi",
+    "nvenc"
+  ],
+  "author": "Mohamed Ikbel Boulabiar boulabiar@gmail.com",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boulabiar/webcodecs-node"
+  },
+  "bugs": {
+    "url": ""
+  },
+  "homepage": "",
+  "dependencies": {
+    "mediabunny": "^1.25.3",
+    "sharp": "^0.32.6"
+  },
+  "peerDependencies": {
+    "mediabunny": ">=1.25.0"
+  },
+  "peerDependenciesMeta": {
+    "mediabunny": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.10.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}