NodeAV

Appearance

node-av / lib / Frame

Class: Frame ​

Defined in: src/lib/frame.ts:63

Container for uncompressed audio/video data.

Stores decoded audio samples or video pixels. Each frame contains raw data for a single video frame or a set of audio samples. Includes format information, timing data, and metadata. Supports both software and hardware (GPU) frames. Essential for decoding, encoding, and filter operations.

Direct mapping to FFmpeg's AVFrame.

Example ​

typescript
import { Frame, FFmpegError } from 'node-av';
import { AV_PIX_FMT_YUV420P } from 'node-av/constants';

// Create and allocate frame
const frame = new Frame();
frame.alloc();

// Configure video frame
frame.format = AV_PIX_FMT_YUV420P;
frame.width = 1920;
frame.height = 1080;
const ret = frame.allocBuffer();
FFmpegError.throwIfError(ret, 'allocBuffer');

// Receive decoded frame
const ret2 = await codecContext.receiveFrame(frame);
if (ret2 >= 0) {
  console.log(`Frame PTS: ${frame.pts}`);
  console.log(`Frame type: ${frame.pictType}`);
  console.log(`Keyframe: ${frame.keyFrame}`);
}

// Cleanup
frame.unref();

See ​

Implements ​

Constructors ​

Constructor ​

new Frame(): Frame

Defined in: src/lib/frame.ts:67

Returns ​

Frame

Accessors ​

bestEffortTimestamp ​

Get Signature ​

get bestEffortTimestamp(): bigint

Defined in: src/lib/frame.ts:163

Best effort timestamp.

Frame timestamp estimated using various heuristics. In time base units.

Direct mapping to AVFrame->best_effort_timestamp.

Returns ​

bigint

Set Signature ​

set bestEffortTimestamp(value): void

Defined in: src/lib/frame.ts:167

Parameters ​
value ​

bigint

Returns ​

void

channelLayout ​

Get Signature ​

get channelLayout(): ChannelLayout

Defined in: src/lib/frame.ts:255

Audio channel layout.

Describes the channel configuration.

Direct mapping to AVFrame->ch_layout.

Returns ​

ChannelLayout

Set Signature ​

set channelLayout(value): void

Defined in: src/lib/frame.ts:259

Parameters ​
value ​

ChannelLayout

Returns ​

void

channels ​

Get Signature ​

get channels(): number

Defined in: src/lib/frame.ts:268

Number of audio channels.

Derived from channel layout.

Returns ​

number

chromaLocation ​

Get Signature ​

get chromaLocation(): AVChromaLocation

Defined in: src/lib/frame.ts:350

Chroma sample location.

Position of chroma samples.

Direct mapping to AVFrame->chroma_location.

Returns ​

AVChromaLocation

Set Signature ​

set chromaLocation(value): void

Defined in: src/lib/frame.ts:354

Parameters ​
value ​

AVChromaLocation

Returns ​

void

colorPrimaries ​

Get Signature ​

get colorPrimaries(): AVColorPrimaries

Defined in: src/lib/frame.ts:305

Color primaries.

Chromaticity coordinates of the source primaries.

Direct mapping to AVFrame->color_primaries.

Returns ​

AVColorPrimaries

Set Signature ​

set colorPrimaries(value): void

Defined in: src/lib/frame.ts:309

Parameters ​
value ​

AVColorPrimaries

Returns ​

void

colorRange ​

Get Signature ​

get colorRange(): AVColorRange

Defined in: src/lib/frame.ts:290

Color range.

MPEG (limited) or JPEG (full) range.

Direct mapping to AVFrame->color_range.

Returns ​

AVColorRange

Set Signature ​

set colorRange(value): void

Defined in: src/lib/frame.ts:294

Parameters ​
value ​

AVColorRange

Returns ​

void

colorSpace ​

Get Signature ​

get colorSpace(): AVColorSpace

Defined in: src/lib/frame.ts:335

YUV color space.

Color space type for YUV content.

Direct mapping to AVFrame->colorspace.

Returns ​

AVColorSpace

Set Signature ​

set colorSpace(value): void

Defined in: src/lib/frame.ts:339

Parameters ​
value ​

AVColorSpace

Returns ​

void

colorTrc ​

Get Signature ​

get colorTrc(): AVColorTransferCharacteristic

Defined in: src/lib/frame.ts:320

Color transfer characteristic.

Transfer function (gamma).

Direct mapping to AVFrame->color_trc.

Returns ​

AVColorTransferCharacteristic

Set Signature ​

set colorTrc(value): void

Defined in: src/lib/frame.ts:324

Parameters ​
value ​

AVColorTransferCharacteristic

Returns ​

void

data ​

Get Signature ​

get data(): null | Buffer<ArrayBufferLike>[]

Defined in: src/lib/frame.ts:366

Raw frame data planes.

Array of buffers containing the frame data. One buffer per plane (e.g., Y, U, V for YUV420P).

Direct mapping to AVFrame->data.

Returns ​

null | Buffer<ArrayBufferLike>[]

extendedData ​

Get Signature ​

get extendedData(): null | Buffer<ArrayBufferLike>[]

Defined in: src/lib/frame.ts:378

Extended data planes.

For audio with >8 channels or planar audio. Points to data planes beyond the first 8.

Direct mapping to AVFrame->extended_data.

Returns ​

null | Buffer<ArrayBufferLike>[]

format ​

Get Signature ​

get format(): AVPixelFormat | AVSampleFormat

Defined in: src/lib/frame.ts:76

Pixel format for video frames or sample format for audio.

Direct mapping to AVFrame->format.

Returns ​

AVPixelFormat | AVSampleFormat

Set Signature ​

set format(value): void

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

Parameters ​
value ​

AVPixelFormat | AVSampleFormat

Returns ​

void

height ​

Get Signature ​

get height(): number

Defined in: src/lib/frame.ts:102

Height of video frame in pixels.

Direct mapping to AVFrame->height.

Returns ​

number

Set Signature ​

set height(value): void

Defined in: src/lib/frame.ts:106

Parameters ​
value ​

number

Returns ​

void

hwFramesCtx ​

Get Signature ​

get hwFramesCtx(): null | HardwareFramesContext

Defined in: src/lib/frame.ts:399

Hardware frames context.

Reference to hardware frames context for GPU frames. Null for software frames.

Direct mapping to AVFrame->hw_frames_ctx.

Returns ​

null | HardwareFramesContext

Set Signature ​

set hwFramesCtx(value): void

Defined in: src/lib/frame.ts:418

Parameters ​
value ​

null | HardwareFramesContext

Returns ​

void

isWritable ​

Get Signature ​

get isWritable(): boolean

Defined in: src/lib/frame.ts:387

Check if frame data is writable.

True if the frame data can be modified.

Returns ​

boolean

keyFrame ​

Get Signature ​

get keyFrame(): number

Defined in: src/lib/frame.ts:194

Whether this frame is a keyframe.

1 if keyframe, 0 otherwise.

Direct mapping to AVFrame->key_frame.

Returns ​

number

Set Signature ​

set keyFrame(value): void

Defined in: src/lib/frame.ts:198

Parameters ​
value ​

number

Returns ​

void

linesize ​

Get Signature ​

get linesize(): number[]

Defined in: src/lib/frame.ts:279

Line sizes for each plane.

Number of bytes per line for each data plane.

Direct mapping to AVFrame->linesize.

Returns ​

number[]

nbSamples ​

Get Signature ​

get nbSamples(): number

Defined in: src/lib/frame.ts:115

Number of audio samples per channel.

Direct mapping to AVFrame->nb_samples.

Returns ​

number

Set Signature ​

set nbSamples(value): void

Defined in: src/lib/frame.ts:119

Parameters ​
value ​

number

Returns ​

void

pictType ​

Get Signature ​

get pictType(): AVPictureType

Defined in: src/lib/frame.ts:209

Picture type of the frame.

Type of frame (I, P, B, etc.).

Direct mapping to AVFrame->pict_type.

Returns ​

AVPictureType

Set Signature ​

set pictType(value): void

Defined in: src/lib/frame.ts:213

Parameters ​
value ​

AVPictureType

Returns ​

void

pktDts ​

Get Signature ​

get pktDts(): bigint

Defined in: src/lib/frame.ts:147

DTS from the packet that produced this frame.

Copy of packet DTS for reference. In time base units. AV_NOPTS_VALUE if unknown.

Direct mapping to AVFrame->pkt_dts.

Returns ​

bigint

Set Signature ​

set pktDts(value): void

Defined in: src/lib/frame.ts:151

Parameters ​
value ​

bigint

Returns ​

void

pts ​

Get Signature ​

get pts(): bigint

Defined in: src/lib/frame.ts:131

Presentation timestamp.

Time when the frame should be presented. In time base units. AV_NOPTS_VALUE if unknown.

Direct mapping to AVFrame->pts.

Returns ​

bigint

Set Signature ​

set pts(value): void

Defined in: src/lib/frame.ts:135

Parameters ​
value ​

bigint

Returns ​

void

sampleAspectRatio ​

Get Signature ​

get sampleAspectRatio(): Rational

Defined in: src/lib/frame.ts:224

Sample aspect ratio.

Pixel width/height ratio. 0/1 if unknown.

Direct mapping to AVFrame->sample_aspect_ratio.

Returns ​

Rational

Set Signature ​

set sampleAspectRatio(value): void

Defined in: src/lib/frame.ts:229

Parameters ​
value ​

Rational

Returns ​

void

sampleRate ​

Get Signature ​

get sampleRate(): number

Defined in: src/lib/frame.ts:240

Audio sample rate.

Number of samples per second.

Direct mapping to AVFrame->sample_rate.

Returns ​

number

Set Signature ​

set sampleRate(value): void

Defined in: src/lib/frame.ts:244

Parameters ​
value ​

number

Returns ​

void

timeBase ​

Get Signature ​

get timeBase(): Rational

Defined in: src/lib/frame.ts:178

Time base for timestamps.

Defines the unit of the timestamps (seconds per tick).

Direct mapping to AVFrame->time_base.

Returns ​

Rational

Set Signature ​

set timeBase(value): void

Defined in: src/lib/frame.ts:183

Parameters ​
value ​

Rational

Returns ​

void

width ​

Get Signature ​

get width(): number

Defined in: src/lib/frame.ts:89

Width of video frame in pixels.

Direct mapping to AVFrame->width.

Returns ​

number

Set Signature ​

set width(value): void

Defined in: src/lib/frame.ts:93

Parameters ​
value ​

number

Returns ​

void

Methods ​

[dispose]() ​

[dispose](): void

Defined in: src/lib/frame.ts:1055

Dispose of the frame.

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

Returns ​

void

Example ​

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

Implementation of ​

Disposable.[dispose]

alloc() ​

alloc(): void

Defined in: src/lib/frame.ts:497

Allocate a new frame.

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

Direct mapping to av_frame_alloc().

Returns ​

void

Throws ​

If allocation fails (ENOMEM)

Example ​

typescript
const frame = new Frame();
frame.alloc();
// Frame structure is now ready

See ​

allocBuffer() ​

allocBuffer(): number

Defined in: src/lib/frame.ts:661

Allocate data buffers for the frame.

Allocates buffers based on frame format and dimensions. Frame parameters must be set before calling.

Direct mapping to av_frame_get_buffer().

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid frame parameters
  • AVERROR_ENOMEM: Memory allocation failure

Example ​

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

frame.format = AV_PIX_FMT_YUV420P;
frame.width = 1920;
frame.height = 1080;
const ret = frame.allocBuffer();
FFmpegError.throwIfError(ret, 'allocBuffer');

See ​

getBuffer To get required size

clone() ​

clone(): null | Frame

Defined in: src/lib/frame.ts:595

Clone the frame.

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

Direct mapping to av_frame_clone().

Returns ​

null | Frame

New frame instance, or null on allocation failure

Example ​

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

See ​

  • ref To create reference instead of copy
  • copy To copy into existing frame

copy() ​

copy(src): number

Defined in: src/lib/frame.ts:749

Copy frame data and properties.

Copies both data and metadata from source frame. Destination must have allocated buffers of correct size.

Direct mapping to av_frame_copy().

Parameters ​

src ​

Frame

Source frame to copy from

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Incompatible frames

Example ​

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

// Allocate destination with same format
dstFrame.format = srcFrame.format;
dstFrame.width = srcFrame.width;
dstFrame.height = srcFrame.height;
dstFrame.allocBuffer();

const ret = dstFrame.copy(srcFrame);
FFmpegError.throwIfError(ret, 'copy');

See ​

copyProps() ​

copyProps(src): number

Defined in: src/lib/frame.ts:715

Copy frame properties without copying data.

Copies metadata, timestamps, format info, etc. but not the actual data. Useful for preparing output frames with same properties.

Direct mapping to av_frame_copy_props().

Parameters ​

src ​

Frame

Source frame to copy properties from

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure

Example ​

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

const ret = dstFrame.copyProps(srcFrame);
FFmpegError.throwIfError(ret, 'copyProps');
// dstFrame now has same properties as srcFrame

See ​

copy To copy both properties and data

free() ​

free(): void

Defined in: src/lib/frame.ts:516

Free the frame.

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

Direct mapping to av_frame_free().

Returns ​

void

Example ​

typescript
frame.free();
// Frame is now invalid

See ​

unref To only free data, keeping structure

fromBuffer() ​

fromBuffer(buffer): number

Defined in: src/lib/frame.ts:773

Fill frame data from buffer.

Copies data from buffer into frame data planes. Frame must have allocated buffers.

Parameters ​

buffer ​

Buffer

Source buffer with frame data

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters

Example ​

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

const buffer = Buffer.from(rawVideoData);
const ret = frame.fromBuffer(buffer);
FFmpegError.throwIfError(ret, 'fromBuffer');

getBuffer() ​

getBuffer(align): number

Defined in: src/lib/frame.ts:631

Get required buffer size for the frame.

Calculates the required buffer size based on frame parameters. Must set format, width/height (video) or format, nb_samples, channel_layout (audio) first.

Direct mapping to av_frame_get_buffer().

Parameters ​

align ​

number = 0

Buffer size alignment (0 for default)

Returns ​

number

Required buffer size in bytes, or negative AVERROR:

  • AVERROR_EINVAL: Invalid frame parameters

Example ​

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

const size = frame.getBuffer();
FFmpegError.throwIfError(size, 'getBuffer');
console.log(`Buffer size: ${size} bytes`);

See ​

allocBuffer To allocate the buffer

getMediaType() ​

getMediaType(): AVMediaType

Defined in: src/lib/frame.ts:471

Get the media type of this frame.

Returns ​

AVMediaType

AVMEDIA_TYPE_VIDEO for video frames, AVMEDIA_TYPE_AUDIO for audio frames, or AVMEDIA_TYPE_UNKNOWN

Example ​

typescript
const type = frame.getMediaType();
console.log(`Frame type: ${type}`);

getNative() ​

getNative(): NativeFrame

Defined in: src/lib/frame.ts:1036

Internal

Get the underlying native Frame object.

Returns ​

NativeFrame

The native Frame binding object

Implementation of ​

NativeWrapper.getNative

getSideData() ​

getSideData(type): null | Buffer<ArrayBufferLike>

Defined in: src/lib/frame.ts:966

Get frame side data.

Retrieves additional data associated with the frame (e.g., motion vectors, film grain, HDR metadata).

Direct mapping to av_frame_get_side_data().

Parameters ​

type ​

AVFrameSideDataType

Type of side data to retrieve

Returns ​

null | Buffer<ArrayBufferLike>

Side data buffer, or null if not present

Example ​

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

const motionVectors = frame.getSideData(AV_FRAME_DATA_MOTION_VECTORS);
if (motionVectors) {
  console.log(`Motion data size: ${motionVectors.length} bytes`);
}

See ​

hwframeTransferData() ​

hwframeTransferData(dst, flags?): Promise<number>

Defined in: src/lib/frame.ts:861

Transfer data between hardware and software frames.

Copies frame data between GPU and system memory. Direction depends on source and destination frame types.

Direct mapping to av_hwframe_transfer_data().

Parameters ​

dst ​

Frame

Destination frame (software or hardware)

flags? ​

number

Transfer flags (0 for default)

Returns ​

Promise<number>

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters
  • AVERROR_ENOMEM: Memory allocation failure

Example ​

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

// Download from GPU to CPU
const swFrame = new Frame();
swFrame.alloc();
const ret = await hwFrame.hwframeTransferData(swFrame);
FFmpegError.throwIfError(ret, 'hwframeTransferData');

See ​

hwframeTransferDataSync() ​

hwframeTransferDataSync(dst, flags?): number

Defined in: src/lib/frame.ts:895

Transfer data between hardware and software frames synchronously. Synchronous version of hwframeTransferData.

Copies frame data between GPU and system memory. Direction depends on source and destination frame types.

Direct mapping to av_hwframe_transfer_data().

Parameters ​

dst ​

Frame

Destination frame (software or hardware)

flags? ​

number

Transfer flags (0 for default)

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_EINVAL: Invalid parameters
  • AVERROR_ENOMEM: Memory allocation failure

Example ​

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

// Download from GPU to CPU
const swFrame = new Frame();
swFrame.alloc();
const ret = hwFrame.hwframeTransferData(swFrame);
FFmpegError.throwIfError(ret, 'hwframeTransferData');

See ​

hwframeTransferData For async version

isAudio() ​

isAudio(): boolean

Defined in: src/lib/frame.ts:456

Check if this is an audio frame.

Audio frames have sampleRate > 0 and nbSamples > 0.

Returns ​

boolean

true if this is an audio frame

Example ​

typescript
if (frame.isAudio()) {
  console.log(`Audio frame: ${frame.sampleRate}Hz, ${frame.nbSamples} samples`);
}

isHwFrame() ​

isHwFrame(): boolean

Defined in: src/lib/frame.ts:916

Check if this is a hardware frame.

Returns true if frame data is in GPU memory.

Returns ​

boolean

True if hardware frame, false otherwise

Example ​

typescript
if (frame.isHwFrame()) {
  console.log('Frame is in GPU memory');
}

See ​

isSwFrame() ​

isSwFrame(): boolean

Defined in: src/lib/frame.ts:937

Check if this is a software frame.

Returns true if frame data is in system memory.

Returns ​

boolean

True if software frame, false otherwise

Example ​

typescript
if (frame.isSwFrame()) {
  console.log('Frame is in system memory');
}

See ​

isVideo() ​

isVideo(): boolean

Defined in: src/lib/frame.ts:438

Check if this is a video frame.

Video frames have width and height > 0.

Returns ​

boolean

true if this is a video frame

Example ​

typescript
if (frame.isVideo()) {
  console.log(`Video frame: ${frame.width}x${frame.height}`);
}

makeWritable() ​

makeWritable(): number

Defined in: src/lib/frame.ts:687

Ensure frame data is writable.

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

Direct mapping to av_frame_make_writable().

Returns ​

number

0 on success, negative AVERROR on error:

  • AVERROR_ENOMEM: Memory allocation failure
  • AVERROR_EINVAL: Invalid frame

Example ​

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

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

newSideData() ​

newSideData(type, size): Buffer

Defined in: src/lib/frame.ts:1001

Allocate new side data.

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

Direct mapping to av_frame_new_side_data().

Parameters ​

type ​

AVFrameSideDataType

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_FRAME_DATA_MASTERING_DISPLAY_METADATA } from 'node-av/constants';

// Allocate and write HDR metadata
const hdrData = frame.newSideData(
  AV_FRAME_DATA_MASTERING_DISPLAY_METADATA,
  40
);
// Write metadata to buffer...

See ​

ref() ​

ref(src): number

Defined in: src/lib/frame.ts:548

Create a reference to another frame.

Sets up this frame as a reference to the source frame's data. Both frames will share the same data buffers.

Direct mapping to av_frame_ref().

Parameters ​

src ​

Frame

Source frame 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';

const frame2 = new Frame();
frame2.alloc();
const ret = frame2.ref(frame1);
FFmpegError.throwIfError(ret, 'ref');
// frame2 now references frame1's data

See ​

  • unref To remove reference
  • clone To create independent copy

removeSideData() ​

removeSideData(type): void

Defined in: src/lib/frame.ts:1025

Remove side data from frame.

Removes specific type of side data.

Direct mapping to av_frame_remove_side_data().

Parameters ​

type ​

AVFrameSideDataType

Type of side data to remove

Returns ​

void

Example ​

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

frame.removeSideData(AV_FRAME_DATA_MOTION_VECTORS);
// Motion vectors removed

See ​

toBuffer() ​

toBuffer(): Buffer

Defined in: src/lib/frame.ts:827

Convert frame data to buffer.

Copies frame data into a single contiguous buffer. For video frames, converts all planes into packed format. For audio frames, handles both planar and interleaved formats. Cannot be used with hardware frames - use hwframeTransferData first.

Returns ​

Buffer

Buffer containing frame data

Throws ​

If frame is not allocated, has no data, or is a hardware frame

Examples ​

typescript
// Get YUV420P video frame as buffer
const buffer = frame.toBuffer();
console.log(`Frame buffer size: ${buffer.length} bytes`);
// Buffer contains Y plane, then U plane, then V plane
typescript
// Get audio samples as buffer
const audioBuffer = frame.toBuffer();
console.log(`Audio buffer size: ${audioBuffer.length} bytes`);
// For planar audio: channel 0 samples, then channel 1 samples, etc.
// For interleaved audio: sample0_ch0, sample0_ch1, sample1_ch0, sample1_ch1, etc.
typescript
try {
  const buffer = frame.toBuffer();
  // Process buffer...
} catch (error) {
  if (frame.isHwFrame()) {
    // Transfer to software first
    const swFrame = new Frame();
    swFrame.alloc();
    await frame.hwframeTransferData(swFrame);
    const buffer = swFrame.toBuffer();
  }
}

See ​

unref() ​

unref(): void

Defined in: src/lib/frame.ts:569

Unreference the frame.

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

Direct mapping to av_frame_unref().

Returns ​

void

Example ​

typescript
frame.unref();
// Frame data is freed, structure can be reused

See ​

  • ref To create reference
  • free To free everything