Packets

Encoded media packets for compressed data

EncodedPacket

Represents an encoded chunk of media. Used as an expressive wrapper around WebCodecs API’s EncodedVideoChunk and EncodedAudioChunk, but can also be used standalone.

Constructor

new EncodedPacket(
  data: Uint8Array,
  type: PacketType,
  timestamp: number,
  duration: number,
  sequenceNumber?: number,
  byteLength?: number,
  sideData?: EncodedPacketSideData
)

data · Uint8Array · required

The encoded data of this packet. For any given codec, this data must adhere to the format specified in the Mediabunny Codec Registry.

type · PacketType · required

The type of this packet: 'key' or 'delta'.

timestamp · number · required

The presentation timestamp of this packet in seconds. May be negative. Samples with negative end timestamps should not be presented.

duration · number · required

The duration of this packet in seconds.

sequenceNumber · number · default: "-1"

The sequence number indicates the decode order of the packets. Packet A must be decoded before packet B if A has a lower sequence number than B. If two packets have the same sequence number, they are the same packet. Negative sequence numbers mean the sequence number is undefined.

byteLength · number

The actual byte length of the data in this packet. This field is useful for metadata-only packets where the data field contains no bytes.

sideData · EncodedPacketSideData

Additional data carried with this packet.

Properties

data · Uint8Array

The encoded data of this packet.

type · PacketType

The type of this packet: 'key' or 'delta'.

timestamp · number

The presentation timestamp in seconds.

duration · number

The duration in seconds.

sequenceNumber · number

The sequence number for decode order.

byteLength · number

The actual byte length of the data.

sideData · EncodedPacketSideData

Additional data carried with this packet.

Methods

toEncodedVideoChunk()

Converts this packet to an EncodedVideoChunk.

toEncodedVideoChunk(): EncodedVideoChunk

toEncodedAudioChunk()

Converts this packet to an EncodedAudioChunk.

toEncodedAudioChunk(): EncodedAudioChunk

toEncodedChunk()

Converts this packet to either an EncodedVideoChunk or EncodedAudioChunk.

toEncodedChunk(kind: 'video' | 'audio'): EncodedVideoChunk | EncodedAudioChunk

PacketType

The type of a packet. Key packets can be decoded without previous packets, while delta packets depend on previous packets.

type PacketType = 'key' | 'delta'

key · string

Key (keyframe) packets can be decoded independently without previous packets.

delta · string

Delta packets depend on previous packets for decoding.

EncodedPacketSideData

Holds additional data accompanying an EncodedPacket.

type EncodedPacketSideData = {
  alpha?: Uint8Array;
  alphaByteLength?: number;
}

alpha · Uint8Array

An encoded alpha frame, encoded with the same codec as the packet. Typically used for transparent videos, where the alpha information is stored separately from the color information.

alphaByteLength · number

The actual byte length of the alpha data. This field is useful for metadata-only packets where the alpha field contains no bytes.

Example

import { EncodedPacket } from 'mediabunny';

// Create a key packet
const packet = new EncodedPacket(
  encodedData,        // Uint8Array of encoded data
  'key',              // Packet type
  0.0,                // Timestamp in seconds
  0.033,              // Duration in seconds (e.g., 30fps)
  0,                  // Sequence number
  encodedData.byteLength
);

// Convert to WebCodecs format
const videoChunk = packet.toEncodedVideoChunk();
const audioChunk = packet.toEncodedAudioChunk();

// Check packet properties
console.log(`Packet type: ${packet.type}`);
console.log(`Timestamp: ${packet.timestamp}s`);
console.log(`Duration: ${packet.duration}s`);
console.log(`Size: ${packet.byteLength} bytes`);

See also

• Samples - Raw unencoded media data
• EncodedPacketSource - Add pre-encoded packets to output
• EncodedPacketSink - Extract encoded packets from input