Package Exports

node-webcodecs
node-webcodecs/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (node-webcodecs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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
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
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();

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

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();

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

Building from Source

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

License

MIT