| title | VideoDecoder |
|---|---|
| description | Decode EncodedVideoChunk objects into VideoFrame for playback and processing |
| icon | film |
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.
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();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.
Creates a new VideoDecoder instance.
new VideoDecoder(init: VideoDecoderInit)<ParamField body="error" type="(error: DOMException) => void" required>
Callback invoked when a decoding error occurs. The decoder transitions to the `closed` state after an error.
</ParamField>
// MUST close to prevent memory leaks
frame.close();
}, error: (err) => { console.error('Decoder error:', err.name, err.message); } });
</Accordion>
---
## Properties
<ResponseField name="state" type="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. |
</ResponseField>
<ResponseField name="decodeQueueSize" type="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.
```typescript
// Wait if queue gets too large
while (decoder.decodeQueueSize > 10) {
await new Promise(resolve => {
decoder.addEventListener('dequeue', resolve, { once: true });
});
}
Checks if a decoder configuration is supported by the current system.
static isConfigSupported(config: VideoDecoderConfig): Promise<VideoDecoderSupport>Returns: Promise<VideoDecoderSupport> - Object indicating whether the config is supported.
if (support.supported) { console.log('H.264 decoding is supported'); decoder.configure(support.config); } else { console.log('H.264 decoding is NOT supported'); }
</Accordion>
<Accordion title="Example: Testing hardware acceleration">
```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'
});
}
Configures the decoder with the specified codec and parameters.
configure(config: VideoDecoderConfig): void **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
</ParamField>
<ParamField body="codedWidth" type="number">
Width of the coded video in pixels. Required for some codecs.
</ParamField>
<ParamField body="codedHeight" type="number">
Height of the coded video in pixels. Required for some codecs.
</ParamField>
<ParamField body="displayAspectWidth" type="number">
Display aspect width for non-square pixel video. Defaults to `codedWidth`.
</ParamField>
<ParamField body="displayAspectHeight" type="number">
Display aspect height for non-square pixel video. Defaults to `codedHeight`.
</ParamField>
<ParamField body="colorSpace" type="object">
Color space metadata for the decoded frames.
<Expandable title="colorSpace properties">
<ParamField body="primaries" type="string">
Color primaries (e.g., `'bt709'`, `'bt2020'`, `'smpte432'`).
</ParamField>
<ParamField body="transfer" type="string">
Transfer characteristics (e.g., `'bt709'`, `'pq'`, `'hlg'`).
</ParamField>
<ParamField body="matrix" type="string">
Matrix coefficients (e.g., `'bt709'`, `'bt2020-ncl'`).
</ParamField>
<ParamField body="fullRange" type="boolean">
Whether to use full-range color values (`true`) or limited range (`false`).
</ParamField>
</Expandable>
</ParamField>
<ParamField body="hardwareAcceleration" type="'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 |
</ParamField>
<ParamField body="optimizeForLatency" type="boolean">
When `true`, optimize for low latency at the cost of throughput. Useful for real-time applications like video conferencing.
</ParamField>
<ParamField body="description" type="BufferSource">
Codec-specific extradata (e.g., H.264 SPS/PPS NALUs, VP9 CodecPrivate). Required for some codecs and containers.
</ParamField>
<ParamField body="useWorkerThread" type="boolean" default="true">
Use asynchronous decoding via worker threads. Set to `false` for synchronous decoding that blocks the event loop.
</ParamField>
Throws:
InvalidStateErrorif the decoder is closedNotSupportedErrorif the codec is not supported
Queues an encoded video chunk for decoding.
decode(chunk: EncodedVideoChunk): voidThrows:
InvalidStateErrorif the decoder is not configuredDataErrorif the chunk data is malformed
decoder.decode(chunk);
// Implement backpressure if (decoder.decodeQueueSize > 10) { await decoder.flush(); } }
</Accordion>
---
### flush()
Waits for all pending decode operations to complete.
```typescript
flush(): Promise<void>
Returns: Promise<void> - Resolves when all queued chunks have been decoded and all output callbacks have been invoked.
Throws:
InvalidStateErrorif the decoder is not configured
// Wait for decoding to complete await decoder.flush(); console.log('All frames decoded!');
// Safe to close now decoder.close();
</Accordion>
---
### 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:
InvalidStateErrorif the decoder is closed
// Now reconfigure for a different video decoder.configure({ codec: 'vp09.00.10.08', codedWidth: 1280, codedHeight: 720 });
</Accordion>
---
### 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.
// Release resources decoder.close();
// decoder.decode() will now throw InvalidStateError
</Accordion>
---
### addEventListener()
Adds an event listener for decoder events.
```typescript
addEventListener(
type: string,
listener: () => void,
options?: { once?: boolean }
): void
// Use in decode loop for (const chunk of chunks) { await waitForQueueSpace(decoder, 10); decoder.decode(chunk); }
</Accordion>
---
### removeEventListener()
Removes a previously added event listener.
```typescript
removeEventListener(type: string, listener: () => void): void
decoder.addEventListener('dequeue', onDequeue);
// Later, remove the listener decoder.removeEventListener('dequeue', onDequeue);
</Accordion>
---
## 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
}
Initialization callbacks for the decoder constructor.
interface VideoDecoderInit {
output: (frame: VideoFrame) => void; // Required
error: (error: DOMException) => void; // Required
}Result of isConfigSupported().
interface VideoDecoderSupport {
supported: boolean; // Whether config is supported
config: VideoDecoderConfig; // The tested configuration
}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');
}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