Skip to main content

​
API Reference

The node-webcodecs API follows the W3C WebCodecs specification, providing native video and audio encoding/decoding in Node.js.
All classes and types are exported from the main node-webcodecs package:
import { VideoEncoder, VideoDecoder, VideoFrame, ... } from 'node-webcodecs';

​
Core Classes

​
Video Processing

VideoEncoder

Encode raw VideoFrame objects into compressed video chunks (H.264, H.265, VP9, AV1)

VideoDecoder

Decode compressed video chunks back into VideoFrame objects

VideoFrame

Raw video frame data with pixel format, dimensions, and color space

EncodedVideoChunk

A chunk of compressed video data (keyframe or delta frame)

​
Audio Processing

AudioEncoder

Encode raw AudioData into compressed audio (AAC, MP3, Opus, FLAC)

AudioDecoder

Decode compressed audio chunks back into AudioData objects

AudioData

Raw audio samples with sample rate, channel count, and format

EncodedAudioChunk

A chunk of compressed audio data

​
Image & Color

ImageDecoder

Decode image files (JPEG, PNG, WebP, GIF) into VideoFrame objects

VideoColorSpace

Color space information (primaries, transfer, matrix coefficients)

​
Utility Functions

​
FFmpeg Information

import { getFFmpegVersion, listCodecs, hasCodec, isNativeAvailable } from 'node-webcodecs';
Returns FFmpeg version information, or null if native module unavailable.
const version = getFFmpegVersion();
// { avcodec: 'libavcodec 60.31.102', avcodecVersion: '60.31.102' }
Lists all available encoders and decoders.
const codecs = listCodecs();
// { encoders: [...], decoders: [...] }
Check if a specific codec is available.
hasCodec('libx264', 'encoder');  // true
hasCodec('h264', 'decoder');     // true
Check if the native FFmpeg addon loaded successfully.
if (isNativeAvailable()) {
  console.log('Native encoding available');
}

​
Supported Codecs

​
Video Codecs

CodecWebCodecs StringEncodingDecodingHardware Accel
H.264/AVCavc1.42001f✅✅✅ VideoToolbox, NVENC
H.265/HEVChvc1.1.6.L93.B0✅✅✅ VideoToolbox, NVENC
VP8vp8✅✅❌
VP9vp09.00.10.08✅✅❌
AV1av01.0.04M.08✅✅❌

​
Audio Codecs

CodecWebCodecs StringEncodingDecoding
AACmp4a.40.2✅✅
MP3mp3✅✅
Opusopus✅✅
FLACflac✅✅
Vorbisvorbis✅✅

​
Type Definitions

For detailed type information, see the Types Reference.

​
Common Types

// Codec state lifecycle
type CodecState = 'unconfigured' | 'configured' | 'closed';

// Buffer input type
type BufferSource = ArrayBuffer | ArrayBufferView;

// Video pixel formats
type VideoPixelFormat =
  | 'I420' | 'I420A' | 'I422' | 'I444'
  | 'NV12' | 'RGBA' | 'RGBX' | 'BGRA' | 'BGRX';

// Audio sample formats
type AudioSampleFormat =
  | 'u8' | 's16' | 's32' | 'f32'
  | 'u8-planar' | 's16-planar' | 's32-planar' | 'f32-planar';

​
Quick Reference

​
Encoding Pipeline

// 1. Create encoder with output callback
const encoder = new VideoEncoder({
  output: (chunk, metadata) => { /* handle encoded chunk */ },
  error: (e) => console.error(e)
});

// 2. Configure codec settings
encoder.configure({
  codec: 'avc1.42001f',
  width: 1920,
  height: 1080,
  bitrate: 5_000_000
});

// 3. Feed frames
encoder.encode(frame);

// 4. Finish encoding
await encoder.flush();
encoder.close();

​
Decoding Pipeline

// 1. Create decoder with output callback
const decoder = new VideoDecoder({
  output: (frame) => { /* handle decoded frame */ },
  error: (e) => console.error(e)
});

// 2. Configure with codec info
decoder.configure({
  codec: 'avc1.42001f',
  codedWidth: 1920,
  codedHeight: 1080
});

// 3. Feed chunks
decoder.decode(chunk);

// 4. Finish decoding
await decoder.flush();
decoder.close();