Skip to content

Latest commit

 

History

History
247 lines (186 loc) · 6.82 KB

EncodedVideoChunk.mdx

File metadata and controls

247 lines (186 loc) · 6.82 KB
title EncodedVideoChunk
description Represents a chunk of encoded video data (keyframe or delta frame)
icon film

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](https://www.w3.org/TR/webcodecs/#encodedvideochunk-interface).

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)
Configuration object for the encoded chunk. The frame type. Use `'key'` for keyframes (I-frames) that can be decoded independently, or `'delta'` for frames that depend on previous frames (P/B-frames).
<ParamField body="timestamp" type="number" required>
  Presentation timestamp in **microseconds**. This determines when the frame should be displayed.
</ParamField>

<ParamField body="duration" type="number">
  Duration of the frame in **microseconds**. For 30fps video, this is typically `33333` (1/30 second).
</ParamField>

<ParamField body="data" type="BufferSource" required>
  The encoded video data as an `ArrayBuffer` or `TypedArray` (e.g., `Uint8Array`).
  The data is copied internally, so you can reuse the source buffer.
</ParamField>
The `type` must be exactly `'key'` or `'delta'`. Any other value will throw a `TypeError`.

Properties

All properties are readonly after construction.

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
Presentation timestamp in microseconds. Determines when this frame should be displayed relative to the start of the video. Duration of this frame in microseconds, or `null` if not specified during construction. 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
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.

```typescript 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);

</Accordion>

---

## Type Definitions

### EncodedVideoChunkType

```typescript
type EncodedVideoChunkType = 'key' | 'delta';
Value Description
'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

The audio equivalent for encoded audio data Encodes VideoFrames into EncodedVideoChunks Decodes EncodedVideoChunks into VideoFrames Raw video frame data