NodeAV

Appearance

node-av / lib / Frame

Class: Frame ​

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

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

Returns ​

Frame

Accessors ​

bestEffortTimestamp ​

Get Signature ​

get bestEffortTimestamp(): bigint

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

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

Parameters ​
value ​

bigint

Returns ​

void

channelLayout ​

Get Signature ​

get channelLayout(): ChannelLayout

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

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

Parameters ​
value ​

ChannelLayout

Returns ​

void

channels ​

Get Signature ​

get channels(): number

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

Number of audio channels.

Derived from channel layout.

Returns ​

number

chromaLocation ​

Get Signature ​

get chromaLocation(): AVChromaLocation

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

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

Parameters ​
value ​

AVChromaLocation

Returns ​

void

colorPrimaries ​

Get Signature ​

get colorPrimaries(): AVColorPrimaries

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

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

Parameters ​
value ​

AVColorPrimaries

Returns ​

void

colorRange ​

Get Signature ​

get colorRange(): AVColorRange

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

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

Parameters ​
value ​

AVColorRange

Returns ​

void

colorSpace ​

Get Signature ​

get colorSpace(): AVColorSpace

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

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

Parameters ​
value ​

AVColorSpace

Returns ​

void

colorTrc ​

Get Signature ​

get colorTrc(): AVColorTransferCharacteristic

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

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

Parameters ​
value ​

AVColorTransferCharacteristic

Returns ​

void

data ​

Get Signature ​

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

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

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

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

Parameters ​
value ​

number

Returns ​

void

duration ​

Get Signature ​

get duration(): bigint

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

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

Parameters ​
value ​

bigint

Returns ​

void

extendedData ​

Get Signature ​

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

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

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

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

Parameters ​
value ​

number

Returns ​

void

format ​

Get Signature ​

get format(): AVPixelFormat | AVSampleFormat

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

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

Parameters ​
value ​

AVPixelFormat | AVSampleFormat

Returns ​

void

height ​

Get Signature ​

get height(): number

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

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

Parameters ​
value ​

number

Returns ​

void

hwFramesCtx ​

Get Signature ​

get hwFramesCtx(): HardwareFramesContext | null

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

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

Parameters ​
value ​

HardwareFramesContext | null

Returns ​

void

isWritable ​

Get Signature ​

get isWritable(): boolean

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

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

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

Parameters ​
value ​

number

Returns ​

void

linesize ​

Get Signature ​

get linesize(): number[]

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

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

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

Parameters ​
value ​

number

Returns ​

void

pictType ​

Get Signature ​

get pictType(): AVPictureType

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

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

Parameters ​
value ​

AVPictureType

Returns ​

void

pktDts ​

Get Signature ​

get pktDts(): bigint

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

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

Parameters ​
value ​

bigint

Returns ​

void

pts ​

Get Signature ​

get pts(): bigint

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

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

Parameters ​
value ​

bigint

Returns ​

void

quality ​

Get Signature ​

get quality(): number

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

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

Parameters ​
value ​

number

Returns ​

void

repeatPict ​

Get Signature ​

get repeatPict(): number

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

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

Parameters ​
value ​

number

Returns ​

void

sampleAspectRatio ​

Get Signature ​

get sampleAspectRatio(): Rational

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

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

Parameters ​
value ​

Rational

Returns ​

void

sampleRate ​

Get Signature ​

get sampleRate(): number

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

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

Parameters ​
value ​

number

Returns ​

void

timeBase ​

Get Signature ​

get timeBase(): Rational

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

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

Parameters ​
value ​

Rational

Returns ​

void

width ​

Get Signature ​

get width(): number

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

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

Parameters ​
value ​

number

Returns ​

void

Methods ​

[dispose]() ​

[dispose](): void

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

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

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

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

applyCropping() ​

applyCropping(flags?): number

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

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

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

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

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

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

free() ​

free(): void

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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(): Buffer

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

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

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

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

fromVideoBuffer() ​

static fromVideoBuffer(buffer, props): Frame

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

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