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