Skip to main content

​
EncodedVideoChunk

The EncodedVideoChunk class represents a single chunk of encoded video data. Each chunk is either a keyframe (can be decoded independently) or a delta frame (requires previous frames to decode).
This class follows the W3C WebCodecs EncodedVideoChunk specification.

​
Quick Example

import { EncodedVideoChunk } from 'node-webcodecs';

// Create from encoded H.264 data
const chunk = new EncodedVideoChunk({
  type: 'key',           // 'key' for keyframe, 'delta' for P/B frames
  timestamp: 0,          // Presentation time in microseconds
  duration: 33333,       // Frame duration in microseconds (30fps = ~33333μs)
  data: encodedH264Data  // Uint8Array or ArrayBuffer
});

// Access properties
console.log(chunk.type);       // 'key'
console.log(chunk.timestamp);  // 0
console.log(chunk.byteLength); // Size of encoded data

// Copy data to another buffer
const buffer = new Uint8Array(chunk.byteLength);
chunk.copyTo(buffer);

​
Constructor

Creates a new EncodedVideoChunk from initialization data. 
new EncodedVideoChunk(init: EncodedVideoChunkInit)
​
init
EncodedVideoChunkInit
required
Configuration object for the encoded chunk.
The type must be exactly 'key' or 'delta'. Any other value will throw a TypeError.

​
Properties

All properties are readonly after construction.
​
type
'key' | 'delta'
required
The chunk type indicating whether this is a keyframe or delta frame.
  • 'key' - Keyframe (I-frame) that can be decoded without any other frames
  • 'delta' - Delta frame (P/B-frame) that requires previous frames
​
timestamp
number
required
Presentation timestamp in microseconds. Determines when this frame should be displayed relative to the start of the video.
​
duration
number | null
required
Duration of this frame in microseconds, or null if not specified during construction.
​
byteLength
number
required
Size of the encoded data in bytes. Use this to allocate a buffer for copyTo().

​
Methods

​
copyTo()

Copies the encoded video data to a destination buffer. 
chunk.copyTo(destination: BufferSource): void
​
destination
BufferSource
required
An ArrayBuffer or TypedArray to copy the data into. Must have at least byteLength bytes available.
Throws: TypeError if the destination buffer is smaller than byteLength. 
const chunk = new EncodedVideoChunk({
  type: 'key',
  timestamp: 0,
  data: someEncodedData
});

// Allocate buffer with exact size needed
const buffer = new Uint8Array(chunk.byteLength);
chunk.copyTo(buffer);

// Now buffer contains a copy of the encoded data
console.log(`Copied ${buffer.length} bytes`);

​
Type Definitions

​
EncodedVideoChunkType

type EncodedVideoChunkType = 'key' | 'delta';
ValueDescription
'key'Keyframe (I-frame) - can be decoded independently
'delta'Delta frame (P/B-frame) - requires reference frames

​
EncodedVideoChunkInit

interface EncodedVideoChunkInit {
  type: EncodedVideoChunkType;  // Required: 'key' or 'delta'
  timestamp: number;            // Required: microseconds
  duration?: number;            // Optional: microseconds
  data: BufferSource;           // Required: encoded data
}

​
Usage with VideoEncoder

EncodedVideoChunk objects are typically created by VideoEncoder and passed to your output callback: 
import { VideoEncoder, VideoFrame } from 'node-webcodecs';

const encoder = new VideoEncoder({
  output: (chunk, metadata) => {
    // chunk is an EncodedVideoChunk
    console.log(`Got ${chunk.type} frame at ${chunk.timestamp}μs`);
    console.log(`Size: ${chunk.byteLength} bytes`);

    // Copy to your own buffer for storage/transmission
    const data = new Uint8Array(chunk.byteLength);
    chunk.copyTo(data);

    // First keyframe includes decoder config in metadata
    if (metadata?.decoderConfig) {
      console.log('Decoder config:', metadata.decoderConfig);
    }
  },
  error: (e) => console.error('Encoding error:', e)
});

encoder.configure({
  codec: 'avc1.42001f',  // H.264 Baseline
  width: 1920,
  height: 1080,
  bitrate: 5_000_000
});

​
Usage with VideoDecoder

Pass EncodedVideoChunk objects to VideoDecoder.decode(): 
import { VideoDecoder, EncodedVideoChunk } from 'node-webcodecs';

const decoder = new VideoDecoder({
  output: (frame) => {
    console.log(`Decoded frame: ${frame.codedWidth}x${frame.codedHeight}`);
    frame.close();  // Don't forget to close frames!
  },
  error: (e) => console.error('Decoding error:', e)
});

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

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

decoder.decode(chunk);
await decoder.flush();

​
See Also

EncodedAudioChunk

The audio equivalent for encoded audio data

VideoEncoder

Encodes VideoFrames into EncodedVideoChunks

VideoDecoder

Decodes EncodedVideoChunks into VideoFrames

VideoFrame

Raw video frame data