webcodecs-node 0.5.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # webcodecs-node
 
-WebCodecs API implementation for Node.js using FFmpeg.
+WebCodecs API implementation for Node.js using node-av.
 
 This package provides a Node.js-compatible implementation of the [WebCodecs API](https://developer.mozilla.org/en-US/docs/Web/API/WebCodecs_API), enabling video and audio encoding/decoding in server-side JavaScript applications.
 
@@ -9,6 +9,7 @@ This package provides a Node.js-compatible implementation of the [WebCodecs API]
 - **VideoEncoder / VideoDecoder** - H.264, HEVC, VP8, VP9, AV1
 - **AudioEncoder / AudioDecoder** - AAC, Opus, MP3, FLAC, Vorbis
 - **ImageDecoder** - PNG, JPEG, WebP, GIF, AVIF, BMP, TIFF (including animated with frame timing)
+- **ImageEncoder** - Encode VideoFrames to PNG, JPEG, WebP
 - **VideoFrame / AudioData** - Frame-level data manipulation
 - **MediaCapabilities** - Query codec support, smooth playback, and power efficiency
 - **Hardware Acceleration** - VAAPI, NVENC, QSV support
@@ -16,7 +17,8 @@ This package provides a Node.js-compatible implementation of the [WebCodecs API]
 - **Latency Modes** - Configure for real-time streaming vs maximum compression
 - **Bitrate Modes** - Constant, variable, and quantizer (CRF) encoding modes
 - **Alpha Channel** - Preserve transparency with VP9 and AV1 codecs
-- **Mediabunny Integration** - Custom encoders/decoders for file conversion
+- **10-bit & HDR** - I420P10, P010 formats with HDR10 metadata support
+- **Container Support** - MP4, WebM demuxing/muxing utilities
 
 ## Documentation
 
@@ -28,17 +30,11 @@ This package provides a Node.js-compatible implementation of the [WebCodecs API]
 ## Requirements
 
 - Node.js 18+
-- FFmpeg with encoding libraries (libx264, libx265, libvpx, etc.)
+- The `node-av` package (automatically installed as a dependency)
 
 ```bash
-# Ubuntu/Debian
-sudo apt install ffmpeg
-
-# macOS
-brew install ffmpeg
-
-# Check installation
-ffmpeg -version
+# node-av provides native FFmpeg bindings - no separate FFmpeg installation required
+npm install webcodecs-node
 ```
 
 ## Installation
@@ -67,7 +63,7 @@ const encoder = new VideoEncoder({
   error: (e) => console.error(e),
 });
 
-await encoder.configure({
+encoder.configure({
   codec: 'avc1.42001E', // H.264 Baseline
   width: 1280,
   height: 720,
@@ -100,12 +96,12 @@ Encodes raw video frames to compressed video.
 const encoder = new VideoEncoder({
   output: (chunk, metadata) => {
     // chunk is EncodedVideoChunk
-    // metadata contains timing info
+    // metadata contains decoder config info
   },
   error: (e) => console.error(e),
 });
 
-await encoder.configure({
+encoder.configure({
   codec: 'avc1.42001E',  // H.264
   width: 1920,
   height: 1080,
@@ -114,7 +110,6 @@ await encoder.configure({
   bitrateMode: 'variable',                 // Optional: 'constant', 'variable', or 'quantizer'
   latencyMode: 'realtime',                 // Optional: 'realtime' for streaming, 'quality' for best compression
   hardwareAcceleration: 'prefer-hardware', // Optional: use GPU encoding
-  format: 'mp4',                           // Optional: 'annexb' (default) or 'mp4'
 });
 
 // Create a frame from raw RGBA data
@@ -153,7 +148,7 @@ const decoder = new VideoDecoder({
   error: (e) => console.error(e),
 });
 
-await decoder.configure({
+decoder.configure({
   codec: 'avc1.42001E',
   codedWidth: 1920,
   codedHeight: 1080,
@@ -177,12 +172,11 @@ const encoder = new AudioEncoder({
   error: (e) => console.error(e),
 });
 
-await encoder.configure({
+encoder.configure({
   codec: 'opus',
   sampleRate: 48000,
   numberOfChannels: 2,
   bitrate: 128000,
-  format: 'aac', // Optional: 'adts' (default for AAC) or 'aac'
 });
 
 // Create audio data from raw samples
@@ -221,8 +215,6 @@ const imageData = readFileSync('animation.gif');
 const decoder = new ImageDecoder({
   type: 'image/gif',
   data: imageData,
-  // Optional: transfer ownership for zero-copy
-  // transfer: [imageData.buffer],
 });
 
 // Wait for parsing to complete
@@ -247,21 +239,6 @@ for (let i = 0; i < track.frameCount; i++) {
 decoder.close();
 ```
 
-**Constructor options:**
-- `type` - MIME type (required)
-- `data` - ArrayBuffer, TypedArray, or ReadableStream (required)
-- `transfer` - ArrayBuffer[] for zero-copy ownership
-- `colorSpaceConversion` - 'none' | 'default'
-- `desiredWidth` / `desiredHeight` - Target dimensions
-- `preferAnimation` - Prefer animated track if available
-- `premultiplyAlpha` - 'none' | 'premultiply' | 'default'
-
-**Properties:**
-- `type` - MIME type string
-- `complete` - Boolean, true when data is buffered
-- `completed` - Promise that resolves when ready
-- `tracks` - ImageTrackList with track information
-
 **Supported formats:**
 - `image/png`, `image/apng`
 - `image/jpeg`
@@ -271,6 +248,36 @@ decoder.close();
 - `image/bmp`
 - `image/tiff`
 
+### ImageEncoder
+
+Encodes VideoFrames to image formats (PNG, JPEG, WebP). This is a utility class that mirrors ImageDecoder.
+
+```typescript
+import { ImageEncoder, VideoFrame } from 'webcodecs-node';
+
+// Check format support
+ImageEncoder.isTypeSupported('image/webp'); // true
+
+// Encode a frame to JPEG
+const result = await ImageEncoder.encode(frame, {
+  type: 'image/jpeg',
+  quality: 0.85,
+});
+
+fs.writeFileSync('output.jpg', Buffer.from(result.data));
+
+// Synchronous encoding
+const pngResult = ImageEncoder.encodeSync(frame, { type: 'image/png' });
+
+// Batch encode multiple frames
+const results = await ImageEncoder.encodeBatch(frames, { type: 'image/webp' });
+```
+
+**Supported output formats:**
+- `image/png` - Lossless, supports transparency
+- `image/jpeg` - Lossy, quality 0-1 (default: 0.92)
+- `image/webp` - Lossy/lossless, quality 0-1 (default: 0.8)
+
 ### MediaCapabilities API
 
 Query codec capabilities before encoding/decoding. Implements the standard [MediaCapabilities API](https://developer.mozilla.org/en-US/docs/Web/API/MediaCapabilities).
@@ -317,35 +324,6 @@ if (encodeInfo.supported && encodeInfo.powerEfficient) {
 }
 ```
 
-**Supported containers & codecs:**
-| Container | Video Codecs | Audio Codecs |
-|-----------|-------------|--------------|
-| video/mp4 | H.264, HEVC, AV1 | AAC |
-| video/webm | VP8, VP9, AV1 | Opus, Vorbis |
-| audio/mp4 | - | AAC |
-| audio/webm | - | Opus, Vorbis |
-| audio/ogg | - | Opus, Vorbis, FLAC |
-| audio/mpeg | - | MP3 |
-
-**Result properties:**
-- `supported` - Whether the configuration can be decoded/encoded
-- `smooth` - Whether playback/encoding will be smooth (no dropped frames)
-- `powerEfficient` - Whether hardware acceleration is available
-
-### MediaCapabilities Profiles
-
-By default, capability queries use heuristics (resolution, bitrate, detected hardware). You can provide a detailed profile generated from the local FFmpeg installation:
-
-```bash
-# Generate a JSON profile alongside the repo (builds first)
-npm run capabilities:generate -- ./webcodecs-capabilities.json
-
-# Point WebCodecs at the profile
-export WEBCODECS_CAPABILITIES_PROFILE=$(pwd)/webcodecs-capabilities.json
-```
-
-`decodingInfo` / `encodingInfo` will load that JSON (schema: `{ video: CapabilityProfileEntry[]; audio: CapabilityProfileEntry[] }`) and match codec/profile/level against those entries for precise limits. Without the env var the library falls back to its built-in heuristics.
-
 ### Hardware Acceleration
 
 Detect and use hardware encoding/decoding:
@@ -372,7 +350,7 @@ const best = await getBestEncoder('h264', 'prefer-hardware');
 console.log(`Using: ${best.encoder} (hardware: ${best.isHardware})`);
 
 // Use in VideoEncoder config
-await encoder.configure({
+encoder.configure({
   codec: 'avc1.42001E',
   width: 1920,
   height: 1080,
@@ -385,23 +363,38 @@ await encoder.configure({
 - **VAAPI** - Intel/AMD on Linux
 - **NVENC/NVDEC** - NVIDIA GPUs
 - **QSV** - Intel Quick Sync Video
-- **VideoToolbox** - macOS (planned)
+- **VideoToolbox** - macOS
 
-### Streaming & Latency Modes
+### Container Utilities
 
-For real-time streaming applications, use `latencyMode: 'realtime'` to minimize encoding latency:
+Import container demuxing/muxing utilities for working with MP4 and WebM files:
 
 ```typescript
-// Real-time streaming encoder
-const encoder = new VideoEncoder({
-  output: (chunk) => {
-    // Send chunk immediately over network
-    streamToClient(chunk);
-  },
-  error: console.error,
+import { Mp4Demuxer, WebmMuxer } from 'webcodecs-node/containers';
+
+// Demux an MP4 file
+const demuxer = new Mp4Demuxer(mp4Data);
+await demuxer.initialize();
+
+for await (const sample of demuxer.videoSamples()) {
+  // sample contains encoded video chunks
+}
+
+// Mux encoded chunks to WebM
+const muxer = new WebmMuxer({
+  video: { codec: 'vp9', width: 1920, height: 1080 },
 });
 
-await encoder.configure({
+muxer.addVideoChunk(encodedChunk, metadata);
+const webmData = muxer.finalize();
+```
+
+### Streaming & Latency Modes
+
+For real-time streaming applications, use `latencyMode: 'realtime'` to minimize encoding latency:
+
+```typescript
+encoder.configure({
   codec: 'avc1.42001E',
   width: 1280,
   height: 720,
@@ -409,40 +402,18 @@ await encoder.configure({
   framerate: 30,
   latencyMode: 'realtime', // Prioritize low latency
 });
-
-// Process frames as they arrive
-camera.on('frame', (frameData) => {
-  const frame = new VideoFrame(frameData, {
-    format: 'RGBA',
-    codedWidth: 1280,
-    codedHeight: 720,
-    timestamp: Date.now() * 1000,
-  });
-
-  encoder.encode(frame);
-  frame.close();
-});
 ```
 
 **Latency mode options:**
 - `'quality'` (default) - Best compression, higher latency (uses B-frames, lookahead)
 - `'realtime'` - Minimum latency for live streaming (no B-frames, zero-delay)
 
-**Codec-specific optimizations in realtime mode:**
-| Codec | Quality Mode | Realtime Mode |
-|-------|-------------|---------------|
-| H.264 | B-frames, rc-lookahead | zerolatency tune, no B-frames |
-| H.265 | B-frames, lookahead | zerolatency tune, no B-frames |
-| VP8   | Default settings | deadline=realtime, cpu-used=8 |
-| VP9   | row-mt, tile-columns | deadline=realtime, cpu-used=8 |
-| AV1   | Default settings | usage=realtime, cpu-used=8 |
-
 ### Bitrate Modes
 
 Control how bitrate is managed during encoding:
 
 ```typescript
-await encoder.configure({
+encoder.configure({
   codec: 'avc1.42001E',
   width: 1920,
   height: 1080,
@@ -451,7 +422,6 @@ await encoder.configure({
 });
 ```
 
-**Bitrate mode options:**
 | Mode | Description | Use Case |
 |------|-------------|----------|
 | `'variable'` | VBR - varies bitrate for quality (default) | General purpose |
@@ -463,8 +433,7 @@ await encoder.configure({
 Preserve transparency when encoding with VP9 or AV1:
 
 ```typescript
-// Encode video with alpha channel
-await encoder.configure({
+encoder.configure({
   codec: 'vp9',
   width: 1920,
   height: 1080,
@@ -482,72 +451,207 @@ const frame = new VideoFrame(rgbaWithAlpha, {
 encoder.encode(frame);
 ```
 
-**Alpha options:**
-- `'discard'` (default) - Strip alpha channel (works with all codecs)
-- `'keep'` - Preserve transparency (VP9 and AV1 only)
+### 10-bit Pixel Formats & HDR
+
+Support for high bit-depth content and HDR metadata:
 
-## Mediabunny Integration
+```typescript
+import {
+  VideoFrame,
+  VideoColorSpace,
+  createHdr10MasteringMetadata,
+  createContentLightLevel,
+  is10BitFormat,
+  getBitDepth,
+} from 'webcodecs-node';
+
+// Create a 10-bit frame
+const frame = new VideoFrame(yuv10bitData, {
+  format: 'I420P10',  // 10-bit YUV 4:2:0
+  codedWidth: 3840,
+  codedHeight: 2160,
+  timestamp: 0,
+  colorSpace: new VideoColorSpace({
+    primaries: 'bt2020',
+    transfer: 'pq',        // HDR10 PQ transfer
+    matrix: 'bt2020-ncl',
+  }),
+});
 
-For file-to-file conversion, use with [Mediabunny](https://mediabunny.dev):
+// Check format properties
+console.log(is10BitFormat('I420P10'));  // true
+console.log(getBitDepth('I420P10'));    // 10
+
+// HDR metadata for mastering display
+const hdrMetadata = {
+  smpteSt2086: createHdr10MasteringMetadata(1000, 0.0001), // max/min luminance
+  contentLightLevel: createContentLightLevel(800, 400),    // MaxCLL, MaxFALL
+};
+
+const colorSpace = new VideoColorSpace({
+  primaries: 'bt2020',
+  transfer: 'pq',
+  hdrMetadata,
+});
+
+console.log(colorSpace.isHdr);          // true
+console.log(colorSpace.hasHdrMetadata); // true
+```
+
+**10-bit pixel formats:**
+- `I420P10` - YUV 4:2:0 planar, 10-bit
+- `I422P10` - YUV 4:2:2 planar, 10-bit
+- `I444P10` - YUV 4:4:4 planar, 10-bit
+- `P010` - YUV 4:2:0 semi-planar, 10-bit
+
+**Pixel format utilities:**
+- `is10BitFormat(format)` - Check if format is 10-bit
+- `getBitDepth(format)` - Get bit depth (8 or 10)
+- `get8BitEquivalent(format)` - Get 8-bit version of a 10-bit format
+- `get10BitEquivalent(format)` - Get 10-bit version of an 8-bit format
+
+### Canvas Rendering (skia-canvas)
+
+GPU-accelerated 2D canvas rendering with automatic hardware detection:
 
 ```typescript
-import { ReadableStream, WritableStream, TransformStream } from 'stream/web';
-import { installWebCodecsPolyfill } from 'webcodecs-node';
+import {
+  createCanvas,
+  createFrameLoop,
+  detectGpuAcceleration,
+  isGpuAvailable,
+  getGpuApi,
+  ensureEvenDimensions,
+  VideoEncoder,
+} from 'webcodecs-node';
 
-// Polyfill Web Streams
-if (typeof globalThis.WritableStream === 'undefined') {
-  globalThis.WritableStream = WritableStream;
-}
-if (typeof globalThis.ReadableStream === 'undefined') {
-  globalThis.ReadableStream = ReadableStream;
+// Check GPU availability
+const gpuInfo = detectGpuAcceleration();
+console.log(`Renderer: ${gpuInfo.renderer}`); // 'GPU' or 'CPU'
+console.log(`API: ${getGpuApi()}`);           // 'Metal', 'Vulkan', 'D3D', or null
+
+// Create GPU-accelerated canvas
+const canvas = createCanvas({
+  width: 1920,
+  height: 1080,
+  gpu: true, // or omit for auto-detection
+});
+
+const ctx = canvas.getContext('2d');
+ctx.fillStyle = 'red';
+ctx.fillRect(0, 0, 1920, 1080);
+
+// Create VideoFrame directly from canvas
+const frame = new VideoFrame(canvas, { timestamp: 0 });
+```
+
+**FrameLoop helper** for animation with backpressure:
+
+```typescript
+const loop = createFrameLoop({
+  width: 1920,
+  height: 1080,
+  frameRate: 30,
+  maxQueueSize: 8, // Backpressure limit
+  onFrame: (ctx, timing) => {
+    // Draw each frame
+    ctx.fillStyle = `hsl(${timing.frameIndex % 360}, 100%, 50%)`;
+    ctx.fillRect(0, 0, 1920, 1080);
+  },
+});
+
+loop.start(300); // Generate 300 frames
+
+while (loop.getState() !== 'stopped' || loop.getQueueSize() > 0) {
+  const frame = loop.takeFrame();
+  if (frame) {
+    encoder.encode(frame);
+    frame.close(); // Always close frames!
+  }
 }
-if (typeof globalThis.TransformStream === 'undefined') {
-  globalThis.TransformStream = TransformStream;
+```
+
+**OffscreenCanvas polyfill** for browser-compatible code:
+
+```typescript
+import { installOffscreenCanvasPolyfill } from 'webcodecs-node';
+
+installOffscreenCanvasPolyfill();
+
+// Now use standard OffscreenCanvas API
+const canvas = new OffscreenCanvas(1920, 1080);
+const ctx = canvas.getContext('2d');
+const blob = await canvas.convertToBlob({ type: 'image/png' });
+```
+
+## Performance Tuning
+
+### Memory Management
+
+Always close VideoFrames and AudioData when done:
+
+```typescript
+const frame = new VideoFrame(buffer, { ... });
+try {
+  encoder.encode(frame);
+} finally {
+  frame.close(); // Prevent memory leaks
 }
+```
 
-// Install WebCodecs
-installWebCodecsPolyfill();
+### Even Dimensions
 
-import {
-  Input,
-  Output,
-  Conversion,
-  FilePathSource,
-  FilePathTarget,
-  Mp4OutputFormat,
-  ALL_FORMATS,
-  registerEncoder,
-  registerDecoder,
-} from 'mediabunny';
-
-import { FFmpegVideoEncoder } from 'webcodecs-node/mediabunny/FFmpegVideoEncoder';
-import { FFmpegVideoDecoder } from 'webcodecs-node/mediabunny/FFmpegVideoDecoder';
-import { FFmpegAudioEncoder } from 'webcodecs-node/mediabunny/FFmpegAudioEncoder';
-import { FFmpegAudioDecoder } from 'webcodecs-node/mediabunny/FFmpegAudioDecoder';
-
-// Register FFmpeg-backed encoders/decoders
-registerEncoder(FFmpegVideoEncoder);
-registerEncoder(FFmpegAudioEncoder);
-registerDecoder(FFmpegVideoDecoder);
-registerDecoder(FFmpegAudioDecoder);
-
-// Convert video
-const input = new Input({
-  formats: ALL_FORMATS,
-  source: new FilePathSource('input.mkv'),
-});
+Video codecs require even dimensions for YUV420 chroma subsampling:
+
+```typescript
+import { ensureEvenDimensions, validateEvenDimensions } from 'webcodecs-node';
+
+// Auto-fix odd dimensions (rounds up)
+const { width, height } = ensureEvenDimensions(1279, 719);
+// Returns { width: 1280, height: 720 }
+
+// Strict validation (throws if odd)
+validateEvenDimensions(1280, 720); // OK
+validateEvenDimensions(1279, 720); // Throws TypeError
+```
 
-const output = new Output({
-  format: new Mp4OutputFormat(),
-  target: new FilePathTarget('output.mp4'),
+### Backpressure Handling
+
+Monitor encoder queue to prevent memory exhaustion:
+
+```typescript
+encoder.addEventListener('dequeue', () => {
+  // Queue size decreased, safe to encode more
+  if (encoder.encodeQueueSize < 10) {
+    encodeNextFrame();
+  }
 });
+```
+
+### Raw Buffer Export
 
-const conversion = await Conversion.init({ input, output });
-await conversion.execute();
+For maximum performance, use raw RGBA buffers instead of PNG/JPEG:
 
-console.log('Conversion complete!');
+```typescript
+import { getRawPixels } from 'webcodecs-node';
+
+// Fast: raw RGBA buffer (no compression)
+const pixels = getRawPixels(canvas); // Returns Buffer
+
+// Slow: PNG encoding (avoid in hot paths)
+const png = await canvas.toBuffer('png');
 ```
 
+### GPU vs CPU Tradeoffs
+
+| Scenario | Recommendation |
+|----------|----------------|
+| HD/4K encoding | `hardwareAcceleration: 'prefer-hardware'` |
+| Real-time streaming | Hardware + `latencyMode: 'realtime'` |
+| Maximum quality | Software + `bitrateMode: 'quantizer'` |
+| Batch processing | Hardware for throughput |
+| Low-end systems | Software (more compatible) |
+
 ## Demos
 
 Run the included demos to test functionality:
@@ -555,27 +659,78 @@ Run the included demos to test functionality:
 ```bash
 npm run build
 
-# Basic WebCodecs demo
+# Basic demo
+npm run demo
+
+# WebCodecs API demo
 npm run demo:webcodecs
 
 # Image decoding demo (animated GIF/PNG/WebP with frame timing)
 npm run demo:image
 
-# Streaming demo (real-time encoding with latency comparison)
-npm run demo:streaming
-
-# File conversion with Mediabunny
-npm run demo:conversion
-
 # Hardware acceleration detection
 npm run demo:hwaccel
 
-# Hardware vs software encoding comparison
-npm run demo:hwaccel-conversion
+# Streaming demo (real-time encoding)
+npm run demo:streaming
+
+# Sample-based encoding demo
+npm run demo:samples
+
+# Container demuxing/muxing demo
+npm run demo:containers
 
-# Video quadrant compositor demo (WebGPU four-up render → MP4)
-# Requires Node 20+; set hardwareAcceleration in src/demos/demo-four-corners.ts to 'prefer-hardware' if VAAPI/NVENC/QSV are available
+# Video quadrant compositor demo (four-up render)
 npm run demo:fourcorners
+
+# 1080p transcoding demo
+npm run demo:1080p
+
+# DVD bouncing logo animation
+npm run demo:dvd
+
+# Audio visualizer with waveform and spectrum
+npm run demo:visualizer
+```
+
+## Benchmarking
+
+Compare software vs hardware encoding performance:
+
+```bash
+# Quick benchmark (30 frames, 360p)
+npm run bench:quick
+
+# Default benchmark (120 frames, 720p)
+npm run bench
+
+# Full benchmark (300 frames, 1080p)
+npm run bench:full
+
+# Custom options
+node scripts/encoding-benchmark.mjs --frames 100 --resolution 1080p --codecs h264,hevc
+```
+
+**Options:**
+- `--frames <n>` - Number of frames to encode (default: 120)
+- `--resolution <res>` - 360p, 480p, 720p, 1080p, 4k (default: 720p)
+- `--bitrate <bps>` - Target bitrate in bps
+- `--framerate <fps>` - Target framerate (default: 30)
+- `--codecs <list>` - Comma-separated: h264,hevc,vp9,av1
+- `--skip-software` - Only test hardware encoding
+- `--verbose` - Show detailed output
+
+**Example output:**
+```
+════════════════════════════════════════════════════════════════════════════════
+ENCODING BENCHMARK RESULTS (720p)
+════════════════════════════════════════════════════════════════════════════════
+Codec       Mode           FPS      Time   Latency        Size       Bitrate
+────────────────────────────────────────────────────────────────────────────────
+H.264/AVC   SW           213.6     562ms     391ms     2.00 MB     4.20 Mbps
+H.264/AVC   HW           370.4     324ms     187ms     2.11 MB     4.43 Mbps
+H.265/HEVC  SW           141.4     848ms     106ms     1.94 MB     4.06 Mbps
+H.265/HEVC  HW           589.0     204ms      61ms     2.16 MB     4.54 Mbps
 ```
 
 ## API Compatibility
@@ -600,12 +755,16 @@ This implementation follows the [WebCodecs specification](https://www.w3.org/TR/
 | bitrateMode | ✓ | ✓ |
 | alpha (transparency) | ✓ | ✓ (VP9, AV1) |
 | isConfigSupported() | ✓ | ✓ |
-| isTypeSupported() | ✓ | ✓ |
 
-**Notes:**
-- Hardware acceleration defaults to software encoding for reliability. Use `hardwareAcceleration: 'prefer-hardware'` to enable GPU acceleration.
-- ImageDecoder supports animated image frame timing (duration, timestamp) and loop count (repetitionCount).
+## Architecture
+
+This library uses **node-av** as its backend, which provides native bindings to FFmpeg's libav* libraries. This approach offers:
+
+- **Native performance** - Direct library calls instead of subprocess spawning
+- **Lower latency** - No IPC overhead between Node.js and FFmpeg
+- **Better resource management** - Native memory handling and cleanup
+- **Simplified deployment** - No need for separate FFmpeg installation
 
 ## License
 
-webcodecs-node is distributed under the GNU Affero General Public License v3.0. Files located under `src/mediabunny/` remain available under the MIT License to preserve compatibility with Mediabunny integrations. See `LICENSE` for full terms.
+webcodecs-node is distributed under the GNU Affero General Public License v3.0. See `LICENSE` for full terms.

package/dist/backends/types.d.ts

@@ -40,6 +40,8 @@ export interface VideoEncoderBackendConfig {
     latencyMode?: 'quality' | 'realtime';
     alpha?: 'discard' | 'keep';
     hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
+    /** Output format: 'annexb' for raw Annex B, 'mp4' for length-prefixed (AVCC/HVCC) */
+    format?: 'annexb' | 'mp4';
 }
 /**
  * Video decoder configuration