NodeAV

node-av / lib / Packet

Class: Packet ​

Defined in: src/lib/packet.ts:49

Container for compressed audio/video data.

Stores encoded data from demuxers or to be sent to muxers. Each packet contains a portion of compressed stream data, typically one video frame or several audio frames. Includes timing information (PTS/DTS), stream index, and flags. Essential for demuxing, muxing, and codec operations.

Direct mapping to FFmpeg's AVPacket.

Example ​

typescript
import { Packet, FFmpegError } from 'node-av';
import { AV_PKT_FLAG_KEY } from 'node-av/constants';

// Create and allocate packet
const packet = new Packet();
packet.alloc();

// Read packet from format context
const ret = await formatContext.readFrame(packet);
FFmpegError.throwIfError(ret, 'readFrame');

// Check packet properties
console.log(`Stream: ${packet.streamIndex}`);
console.log(`PTS: ${packet.pts}`);
console.log(`Size: ${packet.size} bytes`);
console.log(`Keyframe: ${packet.isKeyframe}`);

// Send to decoder
const ret2 = await codecContext.sendPacket(packet);
FFmpegError.throwIfError(ret2, 'sendPacket');

// Cleanup
packet.unref();

See ​

Implements ​

Constructors ​

Constructor ​

new Packet(): Packet

Defined in: src/lib/packet.ts:52

Returns ​

Packet

Accessors ​

data ​

Get Signature ​

get data(): Buffer<ArrayBufferLike> | null

Defined in: src/lib/packet.ts:202

Packet data buffer.

Contains the compressed audio/video data. May be null for packets signaling special conditions.

Assigning a Buffer replaces the payload with a copy of it; assigning null clears the payload. Either assignment drops any attached side data but preserves the packet's metadata (pts, dts, duration, pos, streamIndex, flags, timeBase), so assignment order does not matter.

Direct mapping to AVPacket->data.

Returns ​

Buffer<ArrayBufferLike> | null

Set Signature ​

set data(value): void

Defined in: src/lib/packet.ts:206

Parameters ​
value ​

Buffer<ArrayBufferLike> | null

Returns ​

void

dts ​

Get Signature ​

get dts(): bigint

Defined in: src/lib/packet.ts:96

Decompression timestamp.

Time when the packet should be decompressed. In stream time base units. AV_NOPTS_VALUE if unknown.

Direct mapping to AVPacket->dts.

Returns ​

bigint

Set Signature ​

set dts(value): void

Defined in: src/lib/packet.ts:100

Parameters ​
value ​

bigint

Returns ​

void

duration ​

Get Signature ​

get duration(): bigint

Defined in: src/lib/packet.ts:112

Duration of this packet.

Duration in stream time base units, 0 if unknown. Typically equal to next_pts - this_pts.

Direct mapping to AVPacket->duration.

Returns ​

bigint

Set Signature ​

set duration(value): void

Defined in: src/lib/packet.ts:116

Parameters ​
value ​

bigint

Returns ​

void

flags ​

Get Signature ​

get flags(): AVPacketFlag

Defined in: src/lib/packet.ts:181

Packet flags.

Combination of AV_PKT_FLAG values indicating packet properties (e.g., AV_PKT_FLAG_KEY for keyframes).

Direct mapping to AVPacket->flags.

Returns ​

AVPacketFlag

Set Signature ​

set flags(value): void

Defined in: src/lib/packet.ts:185

Parameters ​
value ​

AVPacketFlag

Returns ​

void

isKeyframe ​

Get Signature ​

get isKeyframe(): boolean

Defined in: src/lib/packet.ts:216

Check if packet contains a keyframe.

Convenience property that checks AV_PKT_FLAG_KEY flag. Keyframes can be decoded independently without reference frames.

Returns ​

boolean

Set Signature ​

set isKeyframe(value): void

Defined in: src/lib/packet.ts:220

Parameters ​
value ​

boolean

Returns ​

void

pos ​

Get Signature ​

get pos(): bigint

Defined in: src/lib/packet.ts:145

Byte position in stream.

Byte position of packet data in the input file. -1 if unknown.

Direct mapping to AVPacket->pos.

Returns ​

bigint

Set Signature ​

set pos(value): void

Defined in: src/lib/packet.ts:149

Parameters ​
value ​

bigint

Returns ​

void

pts ​

Get Signature ​

get pts(): bigint

Defined in: src/lib/packet.ts:80

Presentation timestamp.

Time when the decompressed packet should be presented to the user. In stream time base units. AV_NOPTS_VALUE if unknown.

Direct mapping to AVPacket->pts.

Returns ​

bigint

Set Signature ​

set pts(value): void

Defined in: src/lib/packet.ts:84

Parameters ​
value ​

bigint

Returns ​

void

reportedExternalMemory ​

Get Signature ​

get reportedExternalMemory(): number

Defined in: src/lib/packet.ts:169

Internal

Bytes of native payload this packet currently reports to V8's GC via napi_adjust_external_memory. Exposed only so the accounting can be asserted in tests; the value is not observable through V8 heap statistics.

Returns ​

number

size ​

Get Signature ​

get size(): number

Defined in: src/lib/packet.ts:158

Size of packet data in bytes.

Direct mapping to AVPacket->size.

Returns ​

number

streamIndex ​

Get Signature ​

get streamIndex(): number

Defined in: src/lib/packet.ts:64

Stream index this packet belongs to.

Identifies which stream in a format context this packet is from/for. Set automatically when reading, must be set manually when writing.

Direct mapping to AVPacket->stream_index.

Returns ​

number

Set Signature ​

set streamIndex(value): void

Defined in: src/lib/packet.ts:68

Parameters ​
value ​

number

Returns ​

void

timeBase ​

Get Signature ​

get timeBase(): Rational

Defined in: src/lib/packet.ts:128

Timebase for timestamps in this packet.

Used by av_interleaved_write_frame() to correctly sort packets from different streams. Must be set to the output stream's timebase before calling av_interleaved_write_frame().

Direct mapping to AVPacket->time_base.

Returns ​

Rational

Set Signature ​

set timeBase(value): void

Defined in: src/lib/packet.ts:133

Parameters ​
value ​

IRational

Returns ​

void

Methods ​

[dispose]() ​

[dispose](): void

Defined in: src/lib/packet.ts:653

Dispose of the packet.

Implements the Disposable interface for automatic cleanup. Equivalent to calling free().

Returns ​

void

Example ​

typescript
{
  using packet = new Packet();
  packet.alloc();
  // Use packet...
} // Automatically freed when leaving scope

Implementation of ​

Disposable.[dispose]

addSideData() ​

addSideData(type, data): number

Defined in: src/lib/packet.ts:491

Add side data to packet.

Attaches additional data to the packet. The data is copied.

Direct mapping to av_packet_add_side_data().

Parameters ​

type ​

AVPacketSideDataType

Type of side data

data ​

Buffer

Side data buffer

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure
  • AVERROR_EINVAL: Invalid parameters

Example ​

typescript
import { FFmpegError } from 'node-av';
import { AV_PKT_DATA_NEW_EXTRADATA } from 'node-av/constants';

const extradata = Buffer.from([...]);
const ret = packet.addSideData(AV_PKT_DATA_NEW_EXTRADATA, extradata);
FFmpegError.throwIfError(ret, 'addSideData');

See ​

alloc() ​

alloc(): void

Defined in: src/lib/packet.ts:243

Allocate a new packet.

Allocates the packet structure. Must be called before using the packet unless it was created by another function (e.g., clone()).

Direct mapping to av_packet_alloc().

Returns ​

void

Throws ​

If allocation fails (ENOMEM)

Example ​

typescript
const packet = new Packet();
packet.alloc();
// Packet is now ready for use

See ​

free To deallocate the packet

clearFlags() ​

clearFlags(...flags): void

Defined in: src/lib/packet.ts:590

Clear packet flags.

Clears one or more flags using bitwise AND NOT. Allows clearing multiple flags without manually performing bitwise operations.

Parameters ​

flags ​

...AVPacketFlag[]

One or more flag values to clear

Returns ​

void

Example ​

typescript
import { AV_PKT_FLAG_DISCARD } from 'node-av/constants';

// Clear specific flag
packet.clearFlags(AV_PKT_FLAG_DISCARD);

See ​

clone() ​

clone(): Packet | null

Defined in: src/lib/packet.ts:346

Clone the packet.

Creates an independent copy of the packet with its own data buffer. The new packet has the same content but can be modified independently.

Direct mapping to av_packet_clone().

Returns ​

Packet | null

New packet instance, or null on allocation failure

Example ​

typescript
const copy = packet.clone();
if (copy) {
  // Modify copy without affecting original
  copy.pts = packet.pts + 1000n;
}

See ​

ref To create reference instead of copy

free() ​

free(): void

Defined in: src/lib/packet.ts:262

Free the packet.

Deallocates the packet and its data. The packet becomes invalid after this.

Direct mapping to av_packet_free().

Returns ​

void

Example ​

typescript
packet.free();
// Packet is now invalid

See ​

unref To only free data, keeping structure

freeSideData() ​

freeSideData(): void

Defined in: src/lib/packet.ts:540

Free all side data.

Removes all side data attached to the packet.

Direct mapping to av_packet_free_side_data().

Returns ​

void

Example ​

typescript
packet.freeSideData();
// All side data removed

getNative() ​

getNative(): NativePacket

Defined in: src/lib/packet.ts:634

Internal

Get the underlying native Packet object.

Returns ​

NativePacket

The native Packet binding object

Implementation of ​

NativeWrapper.getNative

getSideData() ​

getSideData(type): Buffer<ArrayBufferLike> | null

Defined in: src/lib/packet.ts:459

Get packet side data.

Retrieves additional data associated with the packet (e.g., palette data, quality stats, encryption info).

Direct mapping to av_packet_get_side_data().

Parameters ​

type ​

AVPacketSideDataType

Type of side data to retrieve

Returns ​

Buffer<ArrayBufferLike> | null

Side data buffer, or null if not present

Example ​

typescript
import { AV_PKT_DATA_PALETTE } from 'node-av/constants';

const palette = packet.getSideData(AV_PKT_DATA_PALETTE);
if (palette) {
  console.log(`Palette size: ${palette.length} bytes`);
}

See ​

hasFlags() ​

hasFlags(...flags): boolean

Defined in: src/lib/packet.ts:618

Check if packet has specific flags.

Tests whether all specified flags are set using bitwise AND.

Parameters ​

flags ​

...AVPacketFlag[]

One or more flag values to check

Returns ​

boolean

true if all specified flags are set, false otherwise

Example ​

typescript
import { AV_PKT_FLAG_KEY } from 'node-av/constants';

if (packet.hasFlags(AV_PKT_FLAG_KEY)) {
  console.log('This is a keyframe packet');
}

See ​

makeRefcounted() ​

makeRefcounted(): number

Defined in: src/lib/packet.ts:404

Ensure packet data is reference counted.

Makes sure the packet data is stored in a reference-counted buffer. If not already reference-counted, allocates a new buffer and copies data.

Direct mapping to av_packet_make_refcounted().

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure
  • AVERROR_EINVAL: Invalid packet

Example ​

typescript
import { FFmpegError } from 'node-av';

const ret = packet.makeRefcounted();
FFmpegError.throwIfError(ret, 'makeRefcounted');

makeWritable() ​

makeWritable(): number

Defined in: src/lib/packet.ts:430

Ensure packet data is writable.

Creates a private copy of the data if it's shared with other packets. Call before modifying packet data to avoid affecting other references.

Direct mapping to av_packet_make_writable().

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure
  • AVERROR_EINVAL: Invalid packet

Example ​

typescript
import { FFmpegError } from 'node-av';

// Ensure we can safely modify data
const ret = packet.makeWritable();
FFmpegError.throwIfError(ret, 'makeWritable');
// Now safe to modify packet.data

newSideData() ​

newSideData(type, size): Buffer

Defined in: src/lib/packet.ts:523

Allocate new side data.

Allocates side data buffer attached to the packet. Returns buffer that can be written to directly.

Direct mapping to av_packet_new_side_data().

Parameters ​

type ​

AVPacketSideDataType

Type of side data

size ​

number

Size in bytes to allocate

Returns ​

Buffer

Allocated buffer for writing

Throws ​

If allocation fails

Example ​

typescript
import { AV_PKT_DATA_NEW_EXTRADATA } from 'node-av/constants';

// Allocate and write side data directly
const sideData = packet.newSideData(AV_PKT_DATA_NEW_EXTRADATA, 16);
sideData.writeUInt32LE(0x12345678, 0);

See ​

ref() ​

ref(src): number

Defined in: src/lib/packet.ts:300

Create a reference to another packet.

Sets up this packet as a reference to the source packet's data. Both packets will share the same data buffer.

Direct mapping to av_packet_ref().

IMPORTANT: per FFmpeg's contract, this packet (the destination) is completely overwritten - it MUST be unreferenced or freshly allocated before calling. Re-using a packet as the destination without unref first leaks its previous buffer and side data. When reusing one packet across a loop, call packet.unref() before each packet.ref(src).

Parameters ​

src ​

Packet

Source packet to reference

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure
  • AVERROR_EINVAL: Invalid parameters

Example ​

typescript
import { FFmpegError } from 'node-av';

// Reusing one packet across a loop: unref before re-referencing.
packet2.unref();
const ret = packet2.ref(packet1);
FFmpegError.throwIfError(ret, 'ref');
// packet2 now references packet1's data

See ​

  • unref To remove reference (call before re-referencing a reused packet)
  • clone To create independent copy

rescaleTs() ​

rescaleTs(srcTimebase, dstTimebase): void

Defined in: src/lib/packet.ts:380

Rescale packet timestamps.

Converts PTS, DTS, and duration from one time base to another. Essential when moving packets between streams with different time bases.

Direct mapping to av_packet_rescale_ts().

Parameters ​

srcTimebase ​

IRational

Source time base

dstTimebase ​

IRational

Destination time base

Returns ​

void

Example ​

typescript
import { Rational } from 'node-av';

// Convert from 1/25 fps to 1/1000 (milliseconds)
const src = new Rational(1, 25);
const dst = new Rational(1, 1000);
packet.rescaleTs(src, dst);

setFlags() ​

setFlags(...flags): void

Defined in: src/lib/packet.ts:564

Set packet flags.

Sets one or more flags using bitwise OR. Allows setting multiple flags without manually performing bitwise operations.

Parameters ​

flags ​

...AVPacketFlag[]

One or more flag values to set

Returns ​

void

Example ​

typescript
import { AV_PKT_FLAG_KEY, AV_PKT_FLAG_DISCARD } from 'node-av/constants';

// Set multiple flags at once
packet.setFlags(AV_PKT_FLAG_KEY, AV_PKT_FLAG_DISCARD);

See ​

unref() ​

unref(): void

Defined in: src/lib/packet.ts:321

Unreference the packet.

Frees the packet data if this was the last reference. The packet structure remains allocated and can be reused.

Direct mapping to av_packet_unref().

Returns ​

void

Example ​

typescript
packet.unref();
// Packet data is freed, structure can be reused

See ​

  • ref To create reference
  • free To free everything