API Reference

Complete API reference for node-webcodecs

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';

getFFmpegVersion()

Returns FFmpeg version information, or null if native module unavailable.

const version = getFFmpegVersion();
// { avcodec: 'libavcodec 60.31.102', avcodecVersion: '60.31.102' }

listCodecs()

Lists all available encoders and decoders.

const codecs = listCodecs();
// { encoders: [...], decoders: [...] }

hasCodec(codecName, type)

Check if a specific codec is available.

hasCodec('libx264', 'encoder');  // true
hasCodec('h264', 'decoder');     // true

isNativeAvailable()

Check if the native FFmpeg addon loaded successfully.

if (isNativeAvailable()) {
  console.log('Native encoding available');
}

---

Supported Codecs

Video Codecs

Codec	WebCodecs String	Encoding	Decoding	Hardware Accel
H.264/AVC	avc1.42001f	✅	✅	✅ VideoToolbox, NVENC
H.265/HEVC	hvc1.1.6.L93.B0	✅	✅	✅ VideoToolbox, NVENC
VP8	vp8	✅	✅	❌
VP9	vp09.00.10.08	✅	✅	❌
AV1	av01.0.04M.08	✅	✅	❌

Audio Codecs

Codec	WebCodecs String	Encoding	Decoding
AAC	mp4a.40.2	✅	✅
MP3	mp3	✅	✅
Opus	opus	✅	✅
FLAC	flac	✅	✅
Vorbis	vorbis	✅	✅

---

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