---
title: "VideoDecoder"
description: "Decode EncodedVideoChunk objects into VideoFrame for playback and processing"
icon: "film"
---
# 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](https://www.w3.org/TR/webcodecs/#videodecoder-interface).
## Quick Example
```typescript
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.
```typescript
new VideoDecoder(init: VideoDecoderInit)
```
Initialization object containing callbacks for decoded frames and errors.
Callback invoked when a frame is successfully decoded. The callback receives a `VideoFrame` that must be closed after use to prevent memory leaks.
Callback invoked when a decoding error occurs. The decoder transitions to the `closed` state after an error.
```typescript
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
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. |
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.
```typescript
// 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.
```typescript
static isConfigSupported(config: VideoDecoderConfig): Promise
```
The decoder configuration to test for support.
**Returns:** `Promise` - Object indicating whether the config is supported.
```typescript
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');
}
```
```typescript
// 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.
```typescript
configure(config: VideoDecoderConfig): void
```
Configuration object specifying codec and video parameters.
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
Width of the coded video in pixels. Required for some codecs.
Height of the coded video in pixels. Required for some codecs.
Display aspect width for non-square pixel video. Defaults to `codedWidth`.
Display aspect height for non-square pixel video. Defaults to `codedHeight`.
Color space metadata for the decoded frames.
Color primaries (e.g., `'bt709'`, `'bt2020'`, `'smpte432'`).
Transfer characteristics (e.g., `'bt709'`, `'pq'`, `'hlg'`).
Matrix coefficients (e.g., `'bt709'`, `'bt2020-ncl'`).
Whether to use full-range color values (`true`) or limited range (`false`).
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 |
When `true`, optimize for low latency at the cost of throughput. Useful for real-time applications like video conferencing.
Codec-specific extradata (e.g., H.264 SPS/PPS NALUs, VP9 CodecPrivate). Required for some codecs and containers.
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
```typescript
decoder.configure({
codec: 'avc1.42001f',
codedWidth: 1920,
codedHeight: 1080
});
```
```typescript
// H.264 with SPS/PPS from container
decoder.configure({
codec: 'avc1.64001f',
codedWidth: 1920,
codedHeight: 1080,
description: spsAndPpsBuffer // From MP4 avcC box or similar
});
```
```typescript
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.
```typescript
decode(chunk: EncodedVideoChunk): void
```
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
```typescript
// 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.
```typescript
flush(): Promise
```
**Returns:** `Promise` - Resolves when all queued chunks have been decoded and all output callbacks have been invoked.
**Throws:**
- `InvalidStateError` if the decoder is not configured
```typescript
// 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.
```typescript
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
```typescript
// 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.
```typescript
close(): void
```
After calling `close()`, the decoder cannot be used. Any pending decode operations are aborted.
```typescript
// 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.
```typescript
addEventListener(
type: string,
listener: () => void,
options?: { once?: boolean }
): void
```
Event type. Currently only `'dequeue'` is supported.
Callback function to invoke when the event fires.
Event listener options.
If `true`, the listener is automatically removed after being invoked once.
```typescript
// 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.
```typescript
removeEventListener(type: string, listener: () => void): void
```
Event type (e.g., `'dequeue'`).
The callback function to remove.
```typescript
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.
```typescript
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.
```typescript
interface VideoDecoderInit {
output: (frame: VideoFrame) => void; // Required
error: (error: DOMException) => void; // Required
}
```
---
### VideoDecoderSupport
Result of `isConfigSupported()`.
```typescript
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
```typescript
// 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');
}
```
---
## See Also
Raw video frame data output by the decoder
Encode VideoFrames into compressed video
Compressed video data input to the decoder
Guide to GPU-accelerated encoding/decoding