node-webcodecs

Native WebCodecs API implementation for Node.js, using FFmpeg for encoding and decoding.

Features

• W3C WebCodecs API compatible - Same API as the browser WebCodecs
• Non-blocking async encoding/decoding - Worker thread pool keeps the event loop responsive
• Hardware acceleration - VideoToolbox (macOS), NVENC (NVIDIA), QSV (Intel), VAAPI (Linux)
• Video codecs: H.264/AVC, H.265/HEVC, VP8, VP9, AV1
• Audio codecs: AAC, Opus, FLAC, MP3
• ImageDecoder - Decode JPEG, PNG, GIF, WebP, BMP images with ReadableStream support
• Native codec probing - isConfigSupported actually tests codec availability
• HDR support - BT.2020, PQ (HDR10), HLG color spaces
• Alpha channel - VP8/VP9 with transparency (alpha: 'keep')
• Scalability modes - Temporal layer SVC (L1T1, L1T2, L1T3)
• Latency modes - 'quality' vs 'realtime' encoding
• Bitrate modes - 'constant', 'variable', 'quantizer'
• High performance - Native C++ bindings with FFmpeg
• Backpressure support - encodeQueueSize, decodeQueueSize, and dequeue events
• TypeScript support - Full type definitions included

Requirements

• Node.js 18+
• FFmpeg libraries (libavcodec, libavutil, libswscale, libswresample)
• pkg-config (for finding FFmpeg during build)
• A C++ compiler (Xcode Command Line Tools on macOS, build-essential on Linux)

Installing Dependencies

macOS (Homebrew):

brew install ffmpeg pkg-config

# Ensure Homebrew is in your PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="/opt/homebrew/bin:$PATH"

Ubuntu/Debian:

sudo apt-get install build-essential pkg-config libavcodec-dev libavutil-dev libswscale-dev libswresample-dev

Windows: Install FFmpeg and add to PATH, or use vcpkg. Ensure pkg-config is available.

Installation

npm install node-webcodecs

Quick Start

Video Encoding

const { VideoEncoder, VideoFrame } = require('node-webcodecs');

const encoder = new VideoEncoder({
  output: (chunk, metadata) => {
    console.log(`Encoded: ${chunk.byteLength} bytes`);
  },
  error: (err) => console.error(err),
});

encoder.configure({
  codec: 'avc1.42E01E',  // H.264 Baseline
  width: 640,
  height: 480,
  bitrate: 1_000_000,
});

// Create frame from RGBA buffer
const frame = new VideoFrame(rgbaBuffer, {
  format: 'RGBA',
  codedWidth: 640,
  codedHeight: 480,
  timestamp: 0,
});

encoder.encode(frame, { keyFrame: true });
frame.close();

await encoder.flush();
encoder.close();

Video Decoding

const { VideoDecoder, EncodedVideoChunk } = require('node-webcodecs');

const decoder = new VideoDecoder({
  output: (frame) => {
    console.log(`Decoded: ${frame.codedWidth}x${frame.codedHeight}`);
    frame.close();
  },
  error: (err) => console.error(err),
});

decoder.configure({
  codec: 'avc1.42E01E',
  codedWidth: 640,
  codedHeight: 480,
});

// Decode an encoded chunk
decoder.decode(encodedChunk);
await decoder.flush();
decoder.close();

Audio Encoding

const { AudioEncoder, AudioData } = require('node-webcodecs');

const encoder = new AudioEncoder({
  output: (chunk, metadata) => {
    console.log(`Encoded: ${chunk.byteLength} bytes`);
  },
  error: (err) => console.error(err),
});

encoder.configure({
  codec: 'mp4a.40.2',  // AAC-LC
  sampleRate: 48000,
  numberOfChannels: 2,
  bitrate: 128000,
});

const audio = new AudioData({
  format: 'f32',
  sampleRate: 48000,
  numberOfFrames: 1024,
  numberOfChannels: 2,
  timestamp: 0,
  data: floatSamples,
});

encoder.encode(audio);
audio.close();

await encoder.flush();
encoder.close();

Image Decoding

const { ImageDecoder } = require('node-webcodecs');
const fs = require('fs');

const imageData = fs.readFileSync('photo.jpg');

const decoder = new ImageDecoder({
  data: imageData,
  type: 'image/jpeg',
});

await decoder.completed;

console.log(`Image: ${decoder.tracks.selectedTrack.frameCount} frame(s)`);

const result = await decoder.decode({ frameIndex: 0 });
const frame = result.image;

console.log(`Decoded: ${frame.codedWidth}x${frame.codedHeight}`);
frame.close();
decoder.close();

Advanced Encoding Options

// HDR encoding with BT.2020 + PQ
encoder.configure({
  codec: 'hvc1',
  width: 3840,
  height: 2160,
  bitrate: 20_000_000,
  colorSpace: {
    primaries: 'bt2020',
    transfer: 'pq',        // HDR10
    matrix: 'bt2020-ncl',
    fullRange: false,
  },
});

// Low-latency realtime encoding
encoder.configure({
  codec: 'avc1.42E01E',
  width: 1280,
  height: 720,
  bitrate: 2_000_000,
  latencyMode: 'realtime',
  bitrateMode: 'constant',
});

// VP9 with alpha channel
encoder.configure({
  codec: 'vp09.00.10.08',
  width: 640,
  height: 480,
  bitrate: 1_000_000,
  alpha: 'keep',  // Preserve alpha channel
});

// Temporal layer SVC
encoder.configure({
  codec: 'vp09.00.10.08',
  width: 1280,
  height: 720,
  bitrate: 2_000_000,
  scalabilityMode: 'L1T2',  // 1 spatial, 2 temporal layers
});

Supported Codecs

Video Codecs

| Codec String | Description | SW Encoder | HW Encoder | |--------------|-------------|------------|------------| | avc1.PPCCLL | H.264/AVC | libx264 | VideoToolbox, NVENC, QSV | | hvc1, hev1 | H.265/HEVC | libx265 | VideoToolbox, NVENC, QSV | | vp8 | VP8 | libvpx | - | | vp9, vp09.PP.LL.DD | VP9 | libvpx-vp9 | VAAPI, QSV | | av01 | AV1 | libsvtav1 | NVENC (RTX 40+), QSV |

Hardware Acceleration

Hardware encoders are automatically selected when available. You can control this with the hardwareAcceleration option:

encoder.configure({
  codec: 'avc1.42E01E',
  width: 1920,
  height: 1080,
  bitrate: 5_000_000,
  hardwareAcceleration: 'prefer-hardware',  // 'no-preference' | 'prefer-hardware' | 'prefer-software'
});

Supported Hardware Accelerators

| Platform | Accelerator | H.264 | HEVC | VP9 | AV1 | |----------|-------------|-------|------|-----|-----| | macOS | VideoToolbox | Encode/Decode | Encode/Decode | - | - | | Windows/Linux | NVIDIA NVENC | Encode | Encode | - | Encode (RTX 40+) | | Windows/Linux | Intel QuickSync | Encode/Decode | Encode/Decode | Encode | Encode | | Linux | VA-API | Encode/Decode | Encode/Decode | Encode | Encode |

Async Worker Threads

By default, encoding and decoding operations run on a dedicated worker thread to avoid blocking the Node.js event loop. This keeps your application responsive during heavy video processing.

// Async mode (default) - event loop stays responsive
encoder.configure({
  codec: 'avc1.42E01E',
  width: 1920,
  height: 1080,
  bitrate: 5_000_000,
  useWorkerThread: true,  // default
});

// Sync mode - blocks event loop (legacy behavior)
encoder.configure({
  codec: 'avc1.42E01E',
  width: 1920,
  height: 1080,
  bitrate: 5_000_000,
  useWorkerThread: false,
});

Benchmark results show async mode allows 3100% more event loop iterations compared to sync mode, meaning your HTTP servers, timers, and I/O operations continue running smoothly during encoding.

Audio Codecs

| Codec String | Description | Encoder | Decoder | |--------------|-------------|---------|---------| | mp4a.40.2 | AAC-LC | aac | aac | | opus | Opus | libopus | opus | | flac | FLAC (lossless) | flac | flac | | mp3 | MP3 | libmp3lame | mp3 |

API Reference

VideoEncoder

const encoder = new VideoEncoder(init: VideoEncoderInit);
encoder.configure(config: VideoEncoderConfig);
encoder.encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions);
await encoder.flush();
encoder.close();
encoder.reset();

// Static method to check codec support
const support = await VideoEncoder.isConfigSupported(config);

VideoDecoder

const decoder = new VideoDecoder(init: VideoDecoderInit);
decoder.configure(config: VideoDecoderConfig);
decoder.decode(chunk: EncodedVideoChunk);
await decoder.flush();
decoder.close();
decoder.reset();

// Static method to check codec support
const support = await VideoDecoder.isConfigSupported(config);

AudioEncoder

const encoder = new AudioEncoder(init: AudioEncoderInit);
encoder.configure(config: AudioEncoderConfig);
encoder.encode(data: AudioData);
await encoder.flush();
encoder.close();
encoder.reset();

AudioDecoder

const decoder = new AudioDecoder(init: AudioDecoderInit);
decoder.configure(config: AudioDecoderConfig);
decoder.decode(chunk: EncodedAudioChunk);
await decoder.flush();
decoder.close();
decoder.reset();

ImageDecoder

const decoder = new ImageDecoder(init: ImageDecoderInit);
await decoder.completed;              // Promise that resolves when ready
decoder.type;                         // MIME type
decoder.tracks;                       // ImageTrackList with frame info
const result = await decoder.decode({ frameIndex: 0 });
decoder.close();

// Supported types: image/jpeg, image/png, image/gif, image/webp, image/bmp

VideoFrame

const frame = new VideoFrame(data: BufferSource, init: VideoFrameBufferInit);
frame.codedWidth;
frame.codedHeight;
frame.timestamp;
frame.duration;
frame.format;
frame.allocationSize(options?);
frame.copyTo(destination, options?);
frame.clone();
frame.close();

AudioData

const audio = new AudioData(init: AudioDataInit);
audio.sampleRate;
audio.numberOfFrames;
audio.numberOfChannels;
audio.format;
audio.timestamp;
audio.duration;
audio.allocationSize(options?);
audio.copyTo(destination, options?);
audio.clone();
audio.close();

Examples

See the examples/ directory for more usage examples:

• basic-video-encode.js - Simple video encoding
• basic-audio-encode.js - Simple audio encoding
• encode-decode-roundtrip.js - Full encode/decode cycle

Runtime Support

| Runtime | Version | Status | |---------|---------|--------| | Node.js | 18+ | Supported | | Bun | 1.0+ | Supported |

Bun Installation

bun add node-webcodecs

If the native binary doesn't compile automatically, you may need to trust the package:

bun pm trust node-webcodecs

Building from Source

git clone https://github.com/caseymanos/node-webcodecs.git
cd node-webcodecs
npm install
npm run build
npm test

License

MIT