VideoDecoder

The VideoDecoder class decodes compressed video data (EncodedVideoChunk) into raw video frames (VideoFrame). It supports H.264, VP8, VP9, HEVC, and AV1 codecs with optional hardware acceleration.

This class follows the W3C WebCodecs VideoDecoder specification.

Quick Example

import { VideoDecoder, EncodedVideoChunk } from 'node-webcodecs';

// Create decoder with output and error callbacks
const decoder = new VideoDecoder({
  output: (frame) => {
    console.log(`Decoded frame: ${frame.codedWidth}x${frame.codedHeight}`);
    console.log(`Timestamp: ${frame.timestamp}μs`);

    // Process the frame (display, save, re-encode, etc.)
    processFrame(frame);

    // IMPORTANT: Always close frames to prevent memory leaks
    frame.close();
  },
  error: (err) => {
    console.error('Decoding error:', err.message);
  }
});

// Configure for H.264 decoding
decoder.configure({
  codec: 'avc1.42001f',  // H.264 Baseline Level 3.1
  codedWidth: 1920,
  codedHeight: 1080,
});

// Decode a keyframe
const chunk = new EncodedVideoChunk({
  type: 'key',
  timestamp: 0,
  data: h264KeyframeData
});

decoder.decode(chunk);

// Wait for all frames to be decoded
await decoder.flush();
decoder.close();

Always call frame.close() in your output callback!VideoFrames hold native memory that is not visible to JavaScript’s garbage collector. Failing to close frames will cause memory leaks that can quickly exhaust system memory.

Constructor

Creates a new VideoDecoder instance.

new VideoDecoder(init: VideoDecoderInit)

init

VideoDecoderInit

required

Initialization object containing callbacks for decoded frames and errors.

Show VideoDecoderInit properties

output

(frame: VideoFrame) => void

required

Callback invoked when a frame is successfully decoded. The callback receives a VideoFrame that must be closed after use to prevent memory leaks.

error

(error: DOMException) => void

required

Callback invoked when a decoding error occurs. The decoder transitions to the closed state after an error.

Example: Creating a decoder

const decoder = new VideoDecoder({
  output: (frame) => {
    // Process the decoded frame
    const data = new Uint8Array(frame.allocationSize());
    await frame.copyTo(data);

    // MUST close to prevent memory leaks
    frame.close();
  },
  error: (err) => {
    console.error('Decoder error:', err.name, err.message);
  }
});

Properties

state

CodecState

required

Current state of the decoder. Possible values:

Value	Description
`'unconfigured'`	Initial state, or after calling `reset()`. Must call `configure()` before decoding.
`'configured'`	Ready to decode chunks via `decode()`.
`'closed'`	Decoder has been closed and cannot be used.

decodeQueueSize

number

required

Number of decode operations currently pending in the queue. Useful for implementing backpressure to avoid memory exhaustion when decoding faster than frames can be processed.

// Wait if queue gets too large
while (decoder.decodeQueueSize > 10) {
  await new Promise(resolve => {
    decoder.addEventListener('dequeue', resolve, { once: true });
  });
}

Static Methods

isConfigSupported()

Checks if a decoder configuration is supported by the current system.

static isConfigSupported(config: VideoDecoderConfig): Promise<VideoDecoderSupport>

config

VideoDecoderConfig

required

The decoder configuration to test for support.

Returns: Promise<VideoDecoderSupport> - Object indicating whether the config is supported.

Example: Checking codec support

const support = await VideoDecoder.isConfigSupported({
  codec: 'avc1.42001f',
  codedWidth: 1920,
  codedHeight: 1080
});

if (support.supported) {
  console.log('H.264 decoding is supported');
  decoder.configure(support.config);
} else {
  console.log('H.264 decoding is NOT supported');
}

Example: Testing hardware acceleration

// Check for hardware-accelerated decoding
const hwSupport = await VideoDecoder.isConfigSupported({
  codec: 'avc1.42001f',
  codedWidth: 3840,
  codedHeight: 2160,
  hardwareAcceleration: 'prefer-hardware'
});

if (!hwSupport.supported) {
  // Fallback to software decoder
  const swSupport = await VideoDecoder.isConfigSupported({
    codec: 'avc1.42001f',
    codedWidth: 3840,
    codedHeight: 2160,
    hardwareAcceleration: 'prefer-software'
  });
}

Methods

configure()

Configures the decoder with the specified codec and parameters.

configure(config: VideoDecoderConfig): void

config

VideoDecoderConfig

required

Configuration object specifying codec and video parameters.

Show VideoDecoderConfig properties

codec

string

required

Codec identifier string. Supports WebCodecs MIME types and FFmpeg codec names.Common values:

'avc1.42001f' - H.264 Baseline Level 3.1
'avc1.4d001f' - H.264 Main Level 3.1
'avc1.64001f' - H.264 High Level 3.1
'vp8' - VP8
'vp09.00.10.08' - VP9 Profile 0
'hev1.1.6.L93.B0' - HEVC Main
'av01.0.08M.08' - AV1 Main

codedWidth

number

Width of the coded video in pixels. Required for some codecs.

codedHeight

number

Height of the coded video in pixels. Required for some codecs.

displayAspectWidth

number

Display aspect width for non-square pixel video. Defaults to codedWidth.

displayAspectHeight

number

Display aspect height for non-square pixel video. Defaults to codedHeight.

colorSpace

object

Color space metadata for the decoded frames.

Show colorSpace properties

primaries

string

Color primaries (e.g., 'bt709', 'bt2020', 'smpte432').

transfer

string

Transfer characteristics (e.g., 'bt709', 'pq', 'hlg').

matrix

string

Matrix coefficients (e.g., 'bt709', 'bt2020-ncl').

fullRange

boolean

Whether to use full-range color values (true) or limited range (false).

hardwareAcceleration

'no-preference' | 'prefer-hardware' | 'prefer-software'

Hardware acceleration preference.

Value	Description
`'no-preference'`	Let the decoder decide (default)
`'prefer-hardware'`	Use GPU decoding if available
`'prefer-software'`	Force CPU-based decoding

optimizeForLatency

boolean

When true, optimize for low latency at the cost of throughput. Useful for real-time applications like video conferencing.

description

BufferSource

Codec-specific extradata (e.g., H.264 SPS/PPS NALUs, VP9 CodecPrivate). Required for some codecs and containers.

useWorkerThread

boolean

default:"true"

Use asynchronous decoding via worker threads. Set to false for synchronous decoding that blocks the event loop.

Throws:

InvalidStateError if the decoder is closed
NotSupportedError if the codec is not supported

Example: Basic H.264 configuration

decoder.configure({
  codec: 'avc1.42001f',
  codedWidth: 1920,
  codedHeight: 1080
});

Example: Configuration with extradata

// H.264 with SPS/PPS from container
decoder.configure({
  codec: 'avc1.64001f',
  codedWidth: 1920,
  codedHeight: 1080,
  description: spsAndPpsBuffer  // From MP4 avcC box or similar
});

Example: HDR video configuration

decoder.configure({
  codec: 'hev1.2.4.L153.B0',  // HEVC Main 10
  codedWidth: 3840,
  codedHeight: 2160,
  colorSpace: {
    primaries: 'bt2020',
    transfer: 'pq',           // HDR10 PQ transfer
    matrix: 'bt2020-ncl',
    fullRange: false
  },
  hardwareAcceleration: 'prefer-hardware'
});

decode()

Queues an encoded video chunk for decoding.

decode(chunk: EncodedVideoChunk): void

chunk

EncodedVideoChunk

required

The encoded video chunk to decode. Can be a keyframe (type: 'key') or delta frame (type: 'delta').

Throws:

InvalidStateError if the decoder is not configured
DataError if the chunk data is malformed

Example: Decoding a stream of chunks

// Decode a sequence of frames
for (const chunkData of encodedFrames) {
  const chunk = new EncodedVideoChunk({
    type: chunkData.isKeyframe ? 'key' : 'delta',
    timestamp: chunkData.timestamp,
    duration: chunkData.duration,
    data: chunkData.data
  });

  decoder.decode(chunk);

  // Implement backpressure
  if (decoder.decodeQueueSize > 10) {
    await decoder.flush();
  }
}

flush()

Waits for all pending decode operations to complete.

flush(): Promise<void>

Returns: Promise<void> - Resolves when all queued chunks have been decoded and all output callbacks have been invoked. Throws:

InvalidStateError if the decoder is not configured

Example: Ensuring all frames are decoded

// Decode all chunks
for (const chunk of chunks) {
  decoder.decode(chunk);
}

// Wait for decoding to complete
await decoder.flush();
console.log('All frames decoded!');

// Safe to close now
decoder.close();

reset()

Resets the decoder to the unconfigured state, discarding all pending work.

reset(): void

Aborts all pending decode operations and clears the decode queue. The decoder returns to the 'unconfigured' state and must be reconfigured before use. Throws:

InvalidStateError if the decoder is closed

Example: Resetting for new stream

// Abort current decoding and reconfigure
decoder.reset();

// Now reconfigure for a different video
decoder.configure({
  codec: 'vp09.00.10.08',
  codedWidth: 1280,
  codedHeight: 720
});

close()

Closes the decoder and releases all resources.

close(): void

After calling close(), the decoder cannot be used. Any pending decode operations are aborted.

Example: Proper cleanup

// Finish any pending work
await decoder.flush();

// Release resources
decoder.close();

// decoder.decode() will now throw InvalidStateError

addEventListener()

Adds an event listener for decoder events.

addEventListener(
  type: string,
  listener: () => void,
  options?: { once?: boolean }
): void

type

string

required

Event type. Currently only 'dequeue' is supported.

listener

() => void

required

Callback function to invoke when the event fires.

options

object

Event listener options.

Show options properties

once

boolean

If true, the listener is automatically removed after being invoked once.

Example: Backpressure using dequeue event

// Wait for queue to have space
async function waitForQueueSpace(decoder, maxQueueSize) {
  while (decoder.decodeQueueSize >= maxQueueSize) {
    await new Promise(resolve => {
      decoder.addEventListener('dequeue', resolve, { once: true });
    });
  }
}

// Use in decode loop
for (const chunk of chunks) {
  await waitForQueueSpace(decoder, 10);
  decoder.decode(chunk);
}

removeEventListener()

Removes a previously added event listener.

removeEventListener(type: string, listener: () => void): void

type

string

required

Event type (e.g., 'dequeue').

listener

() => void

required

The callback function to remove.

Example: Removing a listener

function onDequeue() {
  console.log('Queue size:', decoder.decodeQueueSize);
}

decoder.addEventListener('dequeue', onDequeue);

// Later, remove the listener
decoder.removeEventListener('dequeue', onDequeue);

Interfaces

VideoDecoderConfig

Configuration options for the video decoder.

interface VideoDecoderConfig {
  codec: string;                                    // Required
  codedWidth?: number;
  codedHeight?: number;
  displayAspectWidth?: number;
  displayAspectHeight?: number;
  colorSpace?: {
    primaries?: string;
    transfer?: string;
    matrix?: string;
    fullRange?: boolean;
  };
  hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
  optimizeForLatency?: boolean;
  description?: BufferSource;
  useWorkerThread?: boolean;                        // node-webcodecs extension
}

VideoDecoderInit

Initialization callbacks for the decoder constructor.

interface VideoDecoderInit {
  output: (frame: VideoFrame) => void;              // Required
  error: (error: DOMException) => void;             // Required
}

VideoDecoderSupport

Result of isConfigSupported().

interface VideoDecoderSupport {
  supported: boolean;                               // Whether config is supported
  config: VideoDecoderConfig;                       // The tested configuration
}

Hardware Decoding

Hardware-accelerated decoding uses GPU decoders for improved performance and reduced CPU usage. This is especially beneficial for 4K+ video or when processing multiple streams.

Hardware decoder availability depends on your system:

macOS: VideoToolbox (all Macs)
Windows/Linux: NVDEC (NVIDIA GPUs), VA-API (Intel/AMD)
Raspberry Pi: V4L2 M2M

// Request hardware acceleration
decoder.configure({
  codec: 'avc1.42001f',
  codedWidth: 3840,
  codedHeight: 2160,
  hardwareAcceleration: 'prefer-hardware'
});

// Check if hardware decoding is actually being used
const support = await VideoDecoder.isConfigSupported({
  codec: 'avc1.42001f',
  codedWidth: 3840,
  codedHeight: 2160,
  hardwareAcceleration: 'prefer-hardware'
});

if (support.supported) {
  console.log('Hardware decoding available');
} else {
  console.log('Falling back to software decoding');
}

VideoFrame

Raw video frame data output by the decoder

VideoEncoder

Encode VideoFrames into compressed video

EncodedVideoChunk

Compressed video data input to the decoder

Hardware Acceleration

Guide to GPU-accelerated encoding/decoding

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

VideoDecoder

VideoDecoder

Quick Example

Constructor

Properties

Static Methods

isConfigSupported()

Methods

configure()

decode()

flush()

reset()

close()

addEventListener()

removeEventListener()

Interfaces

VideoDecoderConfig

VideoDecoderInit

VideoDecoderSupport

Hardware Decoding

See Also

VideoFrame

VideoEncoder

EncodedVideoChunk

Hardware Acceleration

​VideoDecoder

​Quick Example

​Constructor

​Properties

​Static Methods

​isConfigSupported()

​Methods

​configure()

​decode()

​flush()

​reset()

​close()

​addEventListener()

​removeEventListener()

​Interfaces

​VideoDecoderConfig

​VideoDecoderInit

​VideoDecoderSupport

​Hardware Decoding

​See Also

VideoFrame

VideoEncoder

EncodedVideoChunk

Hardware Acceleration

VideoDecoder

Quick Example

Constructor

Properties

Static Methods

isConfigSupported()

Methods

configure()

decode()

flush()

reset()

close()

addEventListener()

removeEventListener()

Interfaces

VideoDecoderConfig

VideoDecoderInit

VideoDecoderSupport

Hardware Decoding

See Also