webcodecs-node 0.5.2 → 0.7.1

package/docs/configuration.md

@@ -5,6 +5,7 @@ This guide covers all configuration options for video and audio encoding in webc
 ## Table of Contents
 
 - [Bitrate Mode](#bitrate-mode)
+- [Non-standard Quality Overrides](#non-standard-quality-overrides)
 - [Alpha Channel Handling](#alpha-channel-handling)
 - [Latency Mode](#latency-mode)
 - [Hardware Acceleration](#hardware-acceleration)
@@ -95,6 +96,32 @@ encoder.configure({
 
 ---
 
+## Non-standard Quality Overrides
+
+`crf` and `preset` are **extensions** (not part of the WebCodecs spec). They are loaded globally from a JS file and passed to FFmpeg when supported.
+
+Edit `ffmpeg-quality.js` in the project root:
+
+```javascript
+export default {
+  // Global overrides:
+  // crf: 28,
+  // preset: 'veryfast',
+
+  // Per-codec overrides:
+  // perCodec: {
+  //   h264: { crf: 30, preset: 'veryfast' },
+  //   hevc: { crf: 28, preset: 'medium' },
+  // },
+};
+```
+
+**Notes:**
+- If the file is missing, no overrides are applied.
+- The file is loaded from `process.cwd()` or from `WEB_CODECS_FFMPEG_QUALITY`.
+
+---
+
 ## Alpha Channel Handling
 
 The `alpha` option controls how transparent pixels are handled during encoding.

package/examples/README.md

@@ -22,6 +22,8 @@ npx tsx examples/transparent-video.ts
 npx tsx examples/streaming.ts
 npx tsx examples/hardware-encoding.ts
 npx tsx examples/hardware-decoding.ts
+npx tsx examples/canvas-encoding.ts
+npx tsx examples/offscreen-canvas.ts
 ```
 
 ## Examples
@@ -87,6 +89,27 @@ GPU-accelerated decoding. Demonstrates:
 - Benchmarking hardware vs software decoding
 - Real-time decoding capability analysis
 
+### canvas-encoding.ts
+
+GPU-accelerated canvas rendering with skia-canvas. Demonstrates:
+- GPU acceleration detection (Metal/Vulkan/D3D)
+- Creating GPU-accelerated canvas with `createCanvas()`
+- Using `FrameLoop` with backpressure for smooth encoding
+- Animated canvas drawing with gradients and shapes
+- Proper memory lifecycle (frame closing)
+- Real-time encoding speed measurement
+
+### offscreen-canvas.ts
+
+Browser-compatible OffscreenCanvas API. Demonstrates:
+- Using `OffscreenCanvasPolyfill` (matches browser API)
+- Installing polyfill globally with `installOffscreenCanvasPolyfill()`
+- `ImageDataPolyfill` with `Uint8ClampedArray`
+- `createPixelBuffer()` utilities for pixel manipulation
+- `convertToBlob()` for PNG/JPEG/WebP export
+- `validateEvenDimensions()` for YUV420 compatibility
+- Direct `VideoFrame` creation from OffscreenCanvas
+
 ## Additional Demos
 
 The `demos/` folder contains more complete demos that can be run via npm scripts:
@@ -95,6 +118,10 @@ The `demos/` folder contains more complete demos that can be run via npm scripts
 npm run demo:webcodecs      # Basic WebCodecs demo
 npm run demo:image          # Image decoding demo
 npm run demo:streaming      # Streaming comparison
-npm run demo:conversion     # File conversion with Mediabunny
 npm run demo:hwaccel        # Hardware acceleration detection
+npm run demo:fourcorners    # Video quadrant compositor
+npm run demo:containers     # Container demuxing/muxing
+npm run demo:1080p          # 1080p transcoding benchmark
+npm run demo:dvd            # Bouncing DVD logo animation
+npm run demo:visualizer     # Audio visualizer with waveform
 ```

package/examples/canvas-encoding.ts

@@ -0,0 +1,222 @@
+/**
+ * Canvas Encoding Example
+ *
+ * Demonstrates GPU-accelerated canvas rendering with skia-canvas
+ * and encoding to H.264 video using the FrameLoop helper.
+ *
+ * Features shown:
+ * - GPU acceleration detection (Metal/Vulkan/D3D)
+ * - Creating GPU-accelerated canvas
+ * - FrameLoop with backpressure for smooth encoding
+ * - Animated canvas drawing
+ * - Proper memory lifecycle (frame closing)
+ *
+ * Run: npx tsx examples/canvas-encoding.ts
+ */
+
+import {
+  VideoEncoder,
+  EncodedVideoChunk,
+  createCanvas,
+  createFrameLoop,
+  detectGpuAcceleration,
+  isGpuAvailable,
+  getGpuApi,
+  ensureEvenDimensions,
+} from '../src/index.js';
+
+async function main() {
+  // ============================================
+  // 1. Detect GPU Acceleration
+  // ============================================
+  console.log('=== GPU Detection ===\n');
+
+  const gpuInfo = detectGpuAcceleration();
+  console.log(`Renderer: ${gpuInfo.renderer}`);
+  console.log(`GPU Available: ${isGpuAvailable()}`);
+
+  const gpuApi = getGpuApi();
+  if (gpuApi) {
+    console.log(`GPU API: ${gpuApi}`);
+    if (gpuInfo.device) {
+      console.log(`Device: ${gpuInfo.device}`);
+    }
+  } else {
+    console.log('GPU API: None (CPU fallback)');
+  }
+
+  // ============================================
+  // 2. Setup Video Parameters
+  // ============================================
+  console.log('\n=== Video Setup ===\n');
+
+  // Ensure even dimensions for YUV420 compatibility
+  const { width, height } = ensureEvenDimensions(1280, 720);
+  const frameRate = 30;
+  const totalFrames = 90; // 3 seconds
+  const maxQueueSize = 8; // Backpressure limit
+
+  console.log(`Resolution: ${width}x${height}`);
+  console.log(`Frame Rate: ${frameRate} fps`);
+  console.log(`Total Frames: ${totalFrames}`);
+  console.log(`Duration: ${(totalFrames / frameRate).toFixed(1)}s`);
+
+  // ============================================
+  // 3. Create Encoder
+  // ============================================
+  const chunks: EncodedVideoChunk[] = [];
+  let encodedCount = 0;
+
+  const encoder = new VideoEncoder({
+    output: (chunk, metadata) => {
+      chunks.push(chunk);
+      encodedCount++;
+
+      if (metadata?.decoderConfig) {
+        console.log('\nDecoder config received');
+      }
+    },
+    error: (err) => {
+      console.error('Encoding error:', err);
+    },
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001f', // H.264 Baseline Level 3.1
+    width,
+    height,
+    bitrate: 5_000_000, // 5 Mbps
+    framerate: frameRate,
+    bitrateMode: 'variable',
+  });
+
+  // ============================================
+  // 4. Create FrameLoop with Canvas Drawing
+  // ============================================
+  console.log('\n=== Encoding ===\n');
+
+  const startTime = Date.now();
+
+  const loop = createFrameLoop({
+    width,
+    height,
+    frameRate,
+    maxQueueSize,
+    gpu: isGpuAvailable(), // Use GPU if available
+
+    // This callback draws each frame
+    onFrame: (ctx, timing) => {
+      const { frameIndex, timestamp } = timing;
+      const t = frameIndex / totalFrames; // Progress 0-1
+
+      // Background gradient that shifts over time
+      const gradient = ctx.createLinearGradient(0, 0, width, height);
+      gradient.addColorStop(0, `hsl(${(frameIndex * 3) % 360}, 70%, 20%)`);
+      gradient.addColorStop(1, `hsl(${(frameIndex * 3 + 180) % 360}, 70%, 40%)`);
+      ctx.fillStyle = gradient;
+      ctx.fillRect(0, 0, width, height);
+
+      // Animated circles
+      const numCircles = 5;
+      for (let i = 0; i < numCircles; i++) {
+        const phase = (i / numCircles) * Math.PI * 2;
+        const x = width / 2 + Math.cos(frameIndex * 0.05 + phase) * 200;
+        const y = height / 2 + Math.sin(frameIndex * 0.07 + phase) * 150;
+        const radius = 30 + Math.sin(frameIndex * 0.1 + i) * 20;
+
+        ctx.beginPath();
+        ctx.arc(x, y, radius, 0, Math.PI * 2);
+        ctx.fillStyle = `hsla(${(i * 72 + frameIndex * 2) % 360}, 80%, 60%, 0.7)`;
+        ctx.fill();
+      }
+
+      // Central pulsing circle
+      const pulseRadius = 80 + Math.sin(frameIndex * 0.15) * 30;
+      ctx.beginPath();
+      ctx.arc(width / 2, height / 2, pulseRadius, 0, Math.PI * 2);
+      ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+      ctx.fill();
+
+      // Frame counter text
+      ctx.fillStyle = 'white';
+      ctx.font = 'bold 24px sans-serif';
+      ctx.textAlign = 'left';
+      ctx.textBaseline = 'top';
+      ctx.fillText(`Frame: ${frameIndex + 1}/${totalFrames}`, 20, 20);
+
+      // Timestamp
+      ctx.font = '18px sans-serif';
+      ctx.fillText(`Time: ${(timestamp / 1_000_000).toFixed(3)}s`, 20, 50);
+
+      // GPU status
+      ctx.textAlign = 'right';
+      ctx.fillText(`GPU: ${gpuApi || 'CPU'}`, width - 20, 20);
+    },
+  });
+
+  // ============================================
+  // 5. Generate and Encode Frames
+  // ============================================
+
+  // Start frame generation
+  loop.start(totalFrames);
+
+  // Process frames as they become available
+  let processedCount = 0;
+
+  while (loop.getState() !== 'stopped' || loop.getQueueSize() > 0) {
+    const frame = loop.takeFrame();
+
+    if (frame) {
+      try {
+        // Request keyframe every second
+        const keyFrame = processedCount % frameRate === 0;
+        encoder.encode(frame, { keyFrame });
+        processedCount++;
+
+        // Progress indicator
+        if (processedCount % 10 === 0 || processedCount === totalFrames) {
+          process.stdout.write(`\rProcessed: ${processedCount}/${totalFrames} frames`);
+        }
+      } finally {
+        // Always close the frame to free memory
+        frame.close();
+      }
+    } else {
+      // No frame available, wait briefly
+      await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+  }
+
+  console.log('\n');
+
+  // ============================================
+  // 6. Flush and Close
+  // ============================================
+  await encoder.flush();
+  encoder.close();
+
+  const endTime = Date.now();
+  const elapsed = (endTime - startTime) / 1000;
+
+  // ============================================
+  // 7. Results
+  // ============================================
+  console.log('=== Results ===\n');
+
+  const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const keyFrames = chunks.filter((c) => c.type === 'key').length;
+  const deltaFrames = chunks.filter((c) => c.type === 'delta').length;
+  const actualBitrate = (totalBytes * 8) / (totalFrames / frameRate);
+
+  console.log(`Total chunks: ${chunks.length}`);
+  console.log(`Key frames: ${keyFrames}`);
+  console.log(`Delta frames: ${deltaFrames}`);
+  console.log(`Total size: ${(totalBytes / 1024).toFixed(2)} KB`);
+  console.log(`Actual bitrate: ${(actualBitrate / 1000).toFixed(0)} kbps`);
+  console.log(`Encoding time: ${elapsed.toFixed(2)}s`);
+  console.log(`Speed: ${(totalFrames / elapsed).toFixed(1)} fps`);
+  console.log(`Realtime: ${((totalFrames / frameRate) / elapsed).toFixed(2)}x`);
+}
+
+main().catch(console.error);

package/examples/offscreen-canvas.ts

@@ -0,0 +1,230 @@
+/**
+ * OffscreenCanvas Example
+ *
+ * Demonstrates using the OffscreenCanvas polyfill for browser-compatible
+ * canvas code in Node.js. This makes porting browser code trivial.
+ *
+ * Features shown:
+ * - OffscreenCanvasPolyfill (browser API compatible)
+ * - ImageDataPolyfill with Uint8ClampedArray
+ * - createPixelBuffer utilities
+ * - convertToBlob for image export
+ * - VideoFrame integration
+ *
+ * Run: npx tsx examples/offscreen-canvas.ts
+ */
+
+import {
+  VideoEncoder,
+  VideoFrame,
+  EncodedVideoChunk,
+} from '../src/index.js';
+
+import {
+  OffscreenCanvasPolyfill,
+  ImageDataPolyfill,
+  installOffscreenCanvasPolyfill,
+} from '../src/polyfills/OffscreenCanvas.js';
+
+import {
+  createPixelBuffer,
+  createPixelBufferWithColor,
+  ensureEvenDimensions,
+  validateEvenDimensions,
+} from '../src/canvas/index.js';
+
+import { writeFileSync } from 'fs';
+
+async function main() {
+  console.log('=== OffscreenCanvas Polyfill Demo ===\n');
+
+  // ============================================
+  // 1. Install Polyfill Globally (Optional)
+  // ============================================
+  // This makes OffscreenCanvas available globally like in browsers
+  installOffscreenCanvasPolyfill();
+  console.log('Polyfill installed globally');
+  console.log(`  globalThis.OffscreenCanvas: ${typeof (globalThis as any).OffscreenCanvas}`);
+  console.log(`  globalThis.ImageData: ${typeof (globalThis as any).ImageData}`);
+  console.log(`  globalThis.VideoFrame: ${typeof (globalThis as any).VideoFrame}`);
+
+  // ============================================
+  // 2. Create OffscreenCanvas (Browser-Style)
+  // ============================================
+  console.log('\n=== Creating OffscreenCanvas ===\n');
+
+  const { width, height } = ensureEvenDimensions(640, 480);
+  const canvas = new OffscreenCanvasPolyfill(width, height);
+
+  console.log(`Canvas created: ${canvas.width}x${canvas.height}`);
+  console.log(`GPU enabled: ${canvas.gpu}`);
+
+  // Get 2D context (just like in browser)
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to get 2D context');
+  }
+
+  // ============================================
+  // 3. Draw on Canvas
+  // ============================================
+  console.log('\n=== Drawing ===\n');
+
+  // Background
+  ctx.fillStyle = '#1a1a2e';
+  ctx.fillRect(0, 0, width, height);
+
+  // Gradient rectangle
+  const gradient = ctx.createLinearGradient(50, 50, 250, 250);
+  gradient.addColorStop(0, '#e94560');
+  gradient.addColorStop(1, '#0f3460');
+  ctx.fillStyle = gradient;
+  ctx.fillRect(50, 50, 200, 200);
+
+  // Circle
+  ctx.beginPath();
+  ctx.arc(450, 200, 100, 0, Math.PI * 2);
+  ctx.fillStyle = '#16213e';
+  ctx.fill();
+  ctx.strokeStyle = '#e94560';
+  ctx.lineWidth = 4;
+  ctx.stroke();
+
+  // Text
+  ctx.fillStyle = 'white';
+  ctx.font = 'bold 32px sans-serif';
+  ctx.textAlign = 'center';
+  ctx.fillText('OffscreenCanvas', width / 2, height - 80);
+
+  ctx.font = '20px sans-serif';
+  ctx.fillStyle = '#888';
+  ctx.fillText('Node.js + skia-canvas', width / 2, height - 50);
+
+  console.log('Drawing complete');
+
+  // ============================================
+  // 4. Export to Blob (PNG, JPEG, WebP)
+  // ============================================
+  console.log('\n=== Export to Blob ===\n');
+
+  // PNG export
+  const pngBlob = await canvas.convertToBlob({ type: 'image/png' });
+  console.log(`PNG: ${pngBlob.size} bytes, type: ${pngBlob.type}`);
+
+  // JPEG export with quality
+  const jpegBlob = await canvas.convertToBlob({ type: 'image/jpeg', quality: 0.8 });
+  console.log(`JPEG: ${jpegBlob.size} bytes, type: ${jpegBlob.type}`);
+
+  // WebP export
+  const webpBlob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.85 });
+  console.log(`WebP: ${webpBlob.size} bytes, type: ${webpBlob.type}`);
+
+  // ============================================
+  // 5. ImageData Operations
+  // ============================================
+  console.log('\n=== ImageData Operations ===\n');
+
+  // Create empty ImageData
+  const imageData = new ImageDataPolyfill(100, 100);
+  console.log(`Empty ImageData: ${imageData.width}x${imageData.height}`);
+  console.log(`Data type: ${imageData.data.constructor.name}`);
+  console.log(`Data length: ${imageData.data.length} bytes`);
+  console.log(`Color type: ${imageData.colorType} (for skia-canvas)`);
+
+  // Fill with gradient using direct pixel manipulation
+  for (let y = 0; y < imageData.height; y++) {
+    for (let x = 0; x < imageData.width; x++) {
+      const idx = (y * imageData.width + x) * 4;
+      imageData.data[idx] = (x * 255) / imageData.width; // R
+      imageData.data[idx + 1] = (y * 255) / imageData.height; // G
+      imageData.data[idx + 2] = 128; // B
+      imageData.data[idx + 3] = 255; // A
+    }
+  }
+
+  // Draw ImageData to canvas
+  ctx.putImageData(imageData as any, 270, 280);
+  console.log('ImageData drawn to canvas');
+
+  // ============================================
+  // 6. Pixel Buffer Utilities
+  // ============================================
+  console.log('\n=== Pixel Buffer Utilities ===\n');
+
+  // Create empty buffer
+  const emptyBuffer = createPixelBuffer(64, 64);
+  console.log(`createPixelBuffer(64, 64): ${emptyBuffer.length} bytes`);
+  console.log(`Type: ${emptyBuffer.constructor.name}`);
+
+  // Create solid color buffer
+  const redBuffer = createPixelBufferWithColor(64, 64, 255, 0, 0);
+  console.log(`createPixelBufferWithColor (red): first pixel = [${redBuffer[0]}, ${redBuffer[1]}, ${redBuffer[2]}, ${redBuffer[3]}]`);
+
+  // Demonstrate Uint8ClampedArray auto-clamping
+  const testBuffer = createPixelBuffer(1, 1);
+  testBuffer[0] = 300; // Will be clamped to 255
+  testBuffer[1] = -50; // Will be clamped to 0
+  console.log(`Auto-clamping: 300 -> ${testBuffer[0]}, -50 -> ${testBuffer[1]}`);
+
+  // ============================================
+  // 7. Dimension Validation
+  // ============================================
+  console.log('\n=== Dimension Validation ===\n');
+
+  // ensureEvenDimensions rounds up
+  const dims = ensureEvenDimensions(1279, 719);
+  console.log(`ensureEvenDimensions(1279, 719) = ${dims.width}x${dims.height}`);
+
+  // validateEvenDimensions throws for odd dimensions
+  try {
+    validateEvenDimensions(1279, 720);
+  } catch (err: any) {
+    console.log(`validateEvenDimensions(1279, 720) threw: "${err.message.split('.')[0]}..."`);
+  }
+
+  // ============================================
+  // 8. VideoFrame Integration
+  // ============================================
+  console.log('\n=== VideoFrame Integration ===\n');
+
+  // Create VideoFrame directly from OffscreenCanvas
+  const frame = new VideoFrame(canvas as any, {
+    timestamp: 0,
+  });
+
+  console.log(`VideoFrame from OffscreenCanvas:`);
+  console.log(`  Size: ${frame.displayWidth}x${frame.displayHeight}`);
+  console.log(`  Format: ${frame.format}`);
+  console.log(`  Timestamp: ${frame.timestamp}`);
+
+  // Use with encoder
+  const chunks: EncodedVideoChunk[] = [];
+  const encoder = new VideoEncoder({
+    output: (chunk) => chunks.push(chunk),
+    error: console.error,
+  });
+
+  encoder.configure({
+    codec: 'avc1.42001f',
+    width,
+    height,
+    bitrate: 2_000_000,
+    framerate: 30,
+  });
+
+  encoder.encode(frame, { keyFrame: true });
+  frame.close();
+
+  await encoder.flush();
+  encoder.close();
+
+  console.log(`Encoded to ${chunks.length} chunk(s), ${chunks[0].byteLength} bytes`);
+
+  // ============================================
+  // 9. Save Sample Output
+  // ============================================
+  console.log('\n=== Done ===\n');
+  console.log('OffscreenCanvas polyfill provides full browser API compatibility!');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcodecs-node",
-  "version": "0.5.2",
+  "version": "0.7.1",
   "description": "WebCodecs API implementation for Node.js using node-av",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,12 @@
     "demo:samples": "node dist/demos/demo-samples.js",
     "demo:fourcorners": "node dist/demos/demo-four-corners.js",
     "demo:containers": "node dist/demos/demo-containers.js",
-    "demo:1080p": "node dist/demos/demo-1080p-transcode.js"
+    "demo:1080p": "node dist/demos/demo-1080p-transcode.js",
+    "demo:dvd": "node dist/demos/demo-dvd-logo.js",
+    "demo:visualizer": "node dist/demos/demo-audio-visualizer.js",
+    "bench": "node scripts/encoding-benchmark.mjs",
+    "bench:quick": "node scripts/encoding-benchmark.mjs --frames 30 --resolution 360p",
+    "bench:full": "node scripts/encoding-benchmark.mjs --frames 300 --resolution 1080p"
   },
   "keywords": [
     "webcodecs",
@@ -73,7 +78,8 @@
   "homepage": "",
   "dependencies": {
     "node-av": "^5.0.2",
-    "sharp": "^0.32.6"
+    "node-webpmux": "^3.2.1",
+    "skia-canvas": "^2.0.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",