NodeAV

node-av / lib / Frame

Class: Frame ​

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

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:151

Returns ​

Frame

Accessors ​

alphaMode ​

Get Signature ​

get alphaMode(): AVAlphaMode

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

Alpha channel mode.

Specifies how the alpha channel relates to color values.

Direct mapping to AVFrame->alpha_mode.

Returns ​

AVAlphaMode

Set Signature ​

set alphaMode(value): void

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

Parameters ​
value ​

AVAlphaMode

Returns ​

void

bestEffortTimestamp ​

Get Signature ​

get bestEffortTimestamp(): bigint

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

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:511

Parameters ​
value ​

bigint

Returns ​

void

channelLayout ​

Get Signature ​

get channelLayout(): ChannelLayout

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

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:620

Parameters ​
value ​

ChannelLayout

Returns ​

void

channels ​

Get Signature ​

get channels(): number

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

Number of audio channels.

Derived from channel layout.

Returns ​

number

chromaLocation ​

Get Signature ​

get chromaLocation(): AVChromaLocation

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

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:715

Parameters ​
value ​

AVChromaLocation

Returns ​

void

colorPrimaries ​

Get Signature ​

get colorPrimaries(): AVColorPrimaries

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

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:670

Parameters ​
value ​

AVColorPrimaries

Returns ​

void

colorRange ​

Get Signature ​

get colorRange(): AVColorRange

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

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:655

Parameters ​
value ​

AVColorRange

Returns ​

void

colorSpace ​

Get Signature ​

get colorSpace(): AVColorSpace

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

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:700

Parameters ​
value ​

AVColorSpace

Returns ​

void

colorTrc ​

Get Signature ​

get colorTrc(): AVColorTransferCharacteristic

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

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:685

Parameters ​
value ​

AVColorTransferCharacteristic

Returns ​

void

data ​

Get Signature ​

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

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

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 ​

Buffer<ArrayBufferLike>[] | null

decodeErrorFlags ​

Get Signature ​

get decodeErrorFlags(): number

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

Decode error flags.

Indicates errors detected during decoding. Non-zero value means the frame may be corrupted.

Direct mapping to AVFrame->decode_error_flags.

Returns ​

number

Set Signature ​

set decodeErrorFlags(value): void

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

Parameters ​
value ​

number

Returns ​

void

duration ​

Get Signature ​

get duration(): bigint

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

Frame duration.

Duration of this frame in units of time_base. This is FFmpeg's best guess for how long the frame should be displayed. May be 0 if unknown or unavailable.

Direct mapping to AVFrame->duration.

Returns ​

bigint

Set Signature ​

set duration(value): void

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

Parameters ​
value ​

bigint

Returns ​

void

extendedData ​

Get Signature ​

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

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

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 ​

Buffer<ArrayBufferLike>[] | null

flags ​

Get Signature ​

get flags(): number

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

Frame flags.

Combination of AVFrameFlags (e.g., AV_FRAME_FLAG_CORRUPT, AV_FRAME_FLAG_KEY).

Direct mapping to AVFrame->flags.

Returns ​

number

Set Signature ​

set flags(value): void

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

Parameters ​
value ​

number

Returns ​

void

format ​

Get Signature ​

get format(): AVPixelFormat | AVSampleFormat

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

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:424

Parameters ​
value ​

AVPixelFormat | AVSampleFormat

Returns ​

void

height ​

Get Signature ​

get height(): number

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

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:450

Parameters ​
value ​

number

Returns ​

void

hwFramesCtx ​

Get Signature ​

get hwFramesCtx(): HardwareFramesContext | null

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

Hardware frames context.

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

Direct mapping to AVFrame->hw_frames_ctx.

Returns ​

HardwareFramesContext | null

Set Signature ​

set hwFramesCtx(value): void

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

Parameters ​
value ​

HardwareFramesContext | null

Returns ​

void

isWritable ​

Get Signature ​

get isWritable(): boolean

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

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:538

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:542

Parameters ​
value ​

number

Returns ​

void

linesize ​

Get Signature ​

get linesize(): number[]

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

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:459

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:463

Parameters ​
value ​

number

Returns ​

void

pictType ​

Get Signature ​

get pictType(): AVPictureType

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

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:557

Parameters ​
value ​

AVPictureType

Returns ​

void

pktDts ​

Get Signature ​

get pktDts(): bigint

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

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:495

Parameters ​
value ​

bigint

Returns ​

void

pts ​

Get Signature ​

get pts(): bigint

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

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:479

Parameters ​
value ​

bigint

Returns ​

void

quality ​

Get Signature ​

get quality(): number

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

Quality (between 1 (good) and FF_LAMBDA_MAX (bad)).

Set by libavcodec for some coded frames. Can be set before encoding to specify desired quality for encoders that support it. Used by FFmpeg CLI's frame_encode() to propagate encoder's global_quality setting.

Direct mapping to AVFrame->quality.

Returns ​

number

Set Signature ​

set quality(value): void

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

Parameters ​
value ​

number

Returns ​

void

repeatPict ​

Get Signature ​

get repeatPict(): number

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

Number of fields in this frame that should be repeated.

For interlaced video, indicates how many times the frame should be repeated when displayed. For progressive video, this is typically 0. Formula: display_time = (repeat_pict / (2*fps))

Direct mapping to AVFrame->repeat_pict.

Returns ​

number

Set Signature ​

set repeatPict(value): void

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

Parameters ​
value ​

number

Returns ​

void

reportedExternalMemory ​

Get Signature ​

get reportedExternalMemory(): number

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

Internal

Bytes of native buffer memory this frame 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

sampleAspectRatio ​

Get Signature ​

get sampleAspectRatio(): Rational

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

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:590

Parameters ​
value ​

Rational

Returns ​

void

sampleRate ​

Get Signature ​

get sampleRate(): number

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

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:605

Parameters ​
value ​

number

Returns ​

void

timeBase ​

Get Signature ​

get timeBase(): Rational

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

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:527

Parameters ​
value ​

IRational

Returns ​

void

width ​

Get Signature ​

get width(): number

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

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:437

Parameters ​
value ​

number

Returns ​

void

Methods ​

[dispose]() ​

[dispose](): void

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

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:1053

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:1223

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 Equivalent with an alignment parameter

applyCropping() ​

applyCropping(flags?): number

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

Apply cropping to the frame.

Crops the frame according to its crop metadata (AVFrame crop fields). This adjusts the frame dimensions and data pointers to reflect the cropped region. The cropped-out area is discarded, reducing frame size.

Direct mapping to av_frame_apply_cropping().

Parameters ​

flags? ​

number

Cropping flags (default: AV_FRAME_CROP_UNALIGNED = 1) AV_FRAME_CROP_UNALIGNED allows unaligned cropping for lavfi compatibility

Returns ​

number

0 on success, negative error code on failure

Example ​

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

const frame = new Frame();
// ... decode frame with crop metadata ...

// Apply cropping based on metadata
const ret = frame.applyCropping();
FFmpegError.throwIfError(ret, 'Failed to apply cropping');

// Frame dimensions are now updated to cropped size
console.log(`Cropped to ${frame.width}x${frame.height}`);

clearFlags() ​

clearFlags(...flags): void

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

Clear frame flags.

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

Parameters ​

flags ​

...number[]

One or more flag values to clear

Returns ​

void

Example ​

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

// Clear corrupt flag
frame.clearFlags(AV_FRAME_FLAG_CORRUPT);

See ​

clone() ​

clone(): Frame | null

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

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 ​

Frame | null

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:1312

Copy frame data.

Copies only data (but not 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 To copy non-format metadata
  • clone To create new frame with copy

copyProps() ​

copyProps(src): number

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

Copy non-layout frame properties without copying data.

Copies metadata like timestamp, duration, etc., but not the actual data. Layout-defining properties, such as width, height, channel count, format, etc., are not copied. 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 non-layout properties as srcFrame

See ​

copy To copy data

exportIOSurface() ​

exportIOSurface(): Buffer<ArrayBufferLike> | null

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

Export the IOSurface backing a decoded VideoToolbox frame (macOS only).

Returns the IOSurfaceRef carried by an AV_PIX_FMT_VIDEOTOOLBOX frame as an 8-byte pointer Buffer — the same handle format accepted by Frame.fromIOSurface. This enables zero-copy interop with Metal / CoreVideo (e.g. feeding a hardware-decoded frame into a GPU compositor) without a GPU→CPU readback.

Returns null when the frame is not a decoded VideoToolbox hardware frame, has no backing IOSurface, or on non-macOS platforms.

Lifetime: the IOSurface stays owned by the frame's CVPixelBuffer. Keep this Frame alive while using the handle. If the surface must outlive the frame, retain it separately (e.g. IOSurfaceIncrementUseCount).

Returns ​

Buffer<ArrayBufferLike> | null

IOSurfaceRef pointer as Buffer, or null if not available

Example ​

typescript
const handle = frame.exportIOSurface();
if (handle) {
  // Pass to a Metal-based compositor; keep `frame` alive while in use.
}

See ​

fromIOSurface For the inverse (import) direction

free() ​

free(): void

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

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:1337

Fill frame data from buffer.

Copies data from buffer into frame-owned data planes; the frame never references the source buffer, so it may be reused or garbage collected afterwards. Allocates the frame's buffers if not already allocated.

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:1193

Allocate data buffers for the frame.

Allocates buffers 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

0 on success, negative AVERROR on error:

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

Example ​

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

const ret = frame.getBuffer();
FFmpegError.throwIfError(ret, 'getBuffer');

See ​

allocBuffer Equivalent without alignment parameter

getMediaType() ​

getMediaType(): AVMediaType

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

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

getMetadata() ​

getMetadata(): Dictionary

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

Get frame metadata dictionary.

Returns metadata attached to the frame by filters or demuxers. Metadata is stored as key-value pairs in a Dictionary. Useful for reading filter-generated metadata (e.g., whisper transcription).

Direct mapping to AVFrame->metadata.

Returns ​

Dictionary

Dictionary containing frame metadata

Examples ​

typescript
// Read whisper filter metadata
const metadata = frame.getMetadata();
const text = metadata.get('lavfi.whisper.text');
const duration = metadata.get('lavfi.whisper.duration');

if (text) {
  console.log(`Transcribed: ${text}`);
  console.log(`Duration: ${duration}s`);
}
typescript
// Read scene detection metadata
const metadata = frame.getMetadata();
const score = metadata.get('lavfi.scene_score');
if (score) {
  console.log(`Scene change score: ${score}`);
}

See ​

Dictionary For metadata dictionary operations

getNative() ​

getNative(): NativeFrame

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

Internal

Get the underlying native Frame object.

Returns ​

NativeFrame

The native Frame binding object

Implementation of ​

NativeWrapper.getNative

getSideData() ​

getSideData(type): Buffer<ArrayBufferLike> | null

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

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 ​

Buffer<ArrayBufferLike> | null

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 ​

hasDecodeErrorFlags() ​

hasDecodeErrorFlags(...flags): boolean

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

Check if frame has decode errors.

Tests whether all specified decode error flags are set using bitwise AND.

Parameters ​

flags ​

...number[]

One or more decode error flag values to check

Returns ​

boolean

true if all specified error flags are set, false otherwise

Example ​

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

if (frame.hasDecodeErrorFlags(FF_DECODE_ERROR_INVALID_BITSTREAM)) {
  console.log('Frame has invalid bitstream error');
}

See ​

decodeErrorFlags For direct error flag access

hasFlags() ​

hasFlags(...flags): boolean

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

Check if frame has specific flags.

Tests whether all specified flags are set using bitwise AND.

Parameters ​

flags ​

...number[]

One or more flag values to check

Returns ​

boolean

true if all specified flags are set, false otherwise

Example ​

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

if (frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
  console.log('Frame is corrupted');
}

See ​

hwframeTransferData() ​

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

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

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:1467

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:1012

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:1488

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:1509

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:994

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:1249

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:1605

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:1110

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().

IMPORTANT: per FFmpeg's contract, this frame (the destination) MUST be unreferenced or freshly allocated before calling. Re-using a frame as the destination without unref first leaks its previous buffers (the old references are overwritten, not freed). When reusing one frame across a loop, call frame.unref() before each frame.ref(src).

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

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

See ​

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

removeSideData() ​

removeSideData(type): void

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

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 ​

setFlags() ​

setFlags(...flags): void

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

Set frame flags.

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

Parameters ​

flags ​

...number[]

One or more flag values to set

Returns ​

void

Example ​

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

// Mark frame as key frame
frame.setFlags(AV_FRAME_FLAG_KEY);

See ​

toBuffer() ​

toBuffer(output?): Buffer

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

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.

Parameters ​

output? ​

Buffer<ArrayBufferLike>

Optional Buffer to copy into instead of allocating one; it must hold at least the frame's size and must not overlap the frame's data

Returns ​

Buffer

Buffer containing frame data (a view of output when given)

Throws ​

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

Throws ​

If output is not a Buffer or is smaller than the frame data

Examples ​

Video frame to buffer

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

Audio frame to buffer

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.

Error handling

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:1131

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

fromAudioBuffer() ​

static fromAudioBuffer(buffer, props): Frame

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

Create an audio frame from a buffer with sample data.

Allocates frame buffers, sets properties, and copies buffer data. Convenience factory method that combines frame allocation and data copy.

Parameters ​

buffer ​

Buffer

Buffer containing raw audio samples

props ​

AudioFrame

Frame properties

Returns ​

Frame

Allocated frame with data from buffer

Throws ​

If allocation or buffer copy fails

Example ​

typescript
import { Frame, AV_SAMPLE_FMT_FLT, AV_CH_LAYOUT_STEREO, FFmpegError } from 'node-av';

const samples = Buffer.alloc(960 * 2 * 4); // 960 samples, stereo, float32
using frame = Frame.fromAudioBuffer(samples, {
  nbSamples: 960,
  format: AV_SAMPLE_FMT_FLT,
  sampleRate: 48000,
  channelLayout: AV_CH_LAYOUT_STEREO,
  timeBase: { num: 1, den: 48000 }
});

fromD3D11Texture() ​

static fromD3D11Texture(handle, props): Frame

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

Create a hardware frame from a D3D11 shared texture (Windows only).

Zero-copy: the frame references the shared GPU texture. Width and height are auto-detected from the texture descriptor.

Parameters ​

handle ​

Buffer

D3D11 shared texture handle as Buffer

props ​

D3D11TextureFrame

Hardware context and timing options

Returns ​

Frame

Hardware frame referencing the D3D11 texture

Throws ​

If the import fails (e.g., invalid handle, wrong platform)

Example ​

typescript
import { Frame, HardwareDeviceContext } from 'node-av/lib';

const frame = Frame.fromD3D11Texture(sharedTextureHandle, {
  hwDeviceCtx,
  pts: 0n,
  timeBase: { num: 1, den: 90000 },
});

fromDmaBuf() ​

static fromDmaBuf(dmaBuf, props): Frame

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

Create a DRM PRIME frame from DMA-BUF file descriptors (Linux only).

Zero-copy: the frame references the DMA-BUF GPU memory.

Parameters ​

dmaBuf ​

DmaBufPlanes

DMA-BUF plane descriptors

props ​

DmaBufFrame

Dimensions and timing options

Returns ​

Frame

Hardware frame referencing the DMA-BUF memory

Throws ​

If the import fails (e.g., invalid descriptors, wrong platform)

Example ​

typescript
import { Frame } from 'node-av/lib';

// Create DRM PRIME frame from DMA-BUF
const drmFrame = Frame.fromDmaBuf(dmaBufPlanes, {
  width: 1920,
  height: 1080,
  pts: 0n,
  timeBase: { num: 1, den: 90000 },
});

fromIOSurface() ​

static fromIOSurface(ioSurface, props): Frame

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

Create a hardware frame from an IOSurface handle (macOS only).

Zero-copy: the frame references the same GPU memory as the IOSurface. Width and height are auto-detected from the IOSurface.

Parameters ​

ioSurface ​

Buffer

IOSurfaceRef pointer as Buffer

props ​

IOSurfaceFrame

Hardware context and timing options

Returns ​

Frame

Hardware frame referencing the IOSurface GPU memory

Throws ​

If the import fails (e.g., invalid handle, wrong platform)

Example ​

typescript
import { Frame, HardwareFramesContext } from 'node-av/lib';

const frame = Frame.fromIOSurface(ioSurfaceBuffer, {
  hwFramesCtx,
  pts: 0n,
  timeBase: { num: 1, den: 90000 },
});

fromNSImage() ​

static fromNSImage(nsImageHandle, props?): Frame

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

Create a software frame from an NSImage native handle (macOS only).

Zero-copy: the frame references the NSBitmapImageRep pixel data directly. Width, height, and pixel format are auto-detected.

Parameters ​

nsImageHandle ​

Buffer

NSImage pointer as Buffer

props? ​

NSImageFrame

Timing options

Returns ​

Frame

Software frame referencing the NSImage pixel data

Throws ​

If the import fails (e.g., no NSBitmapImageRep, wrong platform)

Example ​

typescript
import { Frame } from 'node-av/lib';

// Electron: nativeImage.getNativeHandle() returns 8-byte NSImage* pointer
const frame = Frame.fromNSImage(nativeImage.getNativeHandle(), {
  pts: 0n,
  timeBase: { num: 1, den: 30 },
});

fromVideoBuffer() ​

static fromVideoBuffer(buffer, props): Frame

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

Create a video frame from a buffer with pixel data.

Allocates frame buffers, sets properties, and copies buffer data. Convenience factory method that combines frame allocation and data copy.

Parameters ​

buffer ​

Buffer

Buffer containing raw pixel data

props ​

VideoFrame

Video Frame properties

Returns ​

Frame

Allocated frame with data from buffer

Throws ​

If allocation or buffer copy fails

Example ​

typescript
import { Frame, AV_PIX_FMT_RGBA, FFmpegError } from 'node-av';

const rawPixels = Buffer.alloc(1920 * 1080 * 4); // RGBA data
using frame = Frame.fromVideoBuffer(rawPixels, {
  width: 1920,
  height: 1080,
  format: AV_PIX_FMT_RGBA,
  timeBase: { num: 1, den: 30 }
});