Skip to content

Latest commit

 

History

History
637 lines (495 loc) · 16.1 KB

VideoDecoder.mdx

File metadata and controls

637 lines (495 loc) · 16.1 KB
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

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)
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.
<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>
```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); } });

</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 });
    });
  }

Static Methods

isConfigSupported()

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

static isConfigSupported(config: VideoDecoderConfig): Promise<VideoDecoderSupport>
The decoder configuration to test for support.

Returns: Promise<VideoDecoderSupport> - 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'); }

</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'
  });
}

Methods

configure()

Configures the decoder with the specified codec and parameters.

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
</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:

  • 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.

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

</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:

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

</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:

  • 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 });

</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.

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

// 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
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); }

</Accordion>

---

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

</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
}

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

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