Class: FilterAPI | NodeAV
NodeAV

Appearance

node-av / api / FilterAPI

Class: FilterAPI ​

Defined in: src/api/filter.ts:217

High-level filter API for audio and video processing.

Provides simplified interface for applying FFmpeg filters to frames. Handles filter graph construction, frame buffering, and command control. Supports both software and hardware-accelerated filtering operations. Essential component for effects, transformations, and format conversions.

Examples ​

typescript
import { FilterAPI } from 'node-av/api';

// Create video filter - initializes on first frame
const filter = FilterAPI.create('scale=1280:720', {
  timeBase: video.timeBase,
});

// Process frame - first frame configures filter graph
const output = await filter.process(inputFrame);
if (output) {
  console.log(`Filtered frame: ${output.width}x${output.height}`);
  output.free();
}
typescript
// Hardware-accelerated filtering - hw context detected from frame
const filter = FilterAPI.create('hwupload,scale_cuda=1920:1080,hwdownload', {
  timeBase: video.timeBase,
});
// Hardware frames context will be automatically detected from first frame

See ​

Implements ​

  • Disposable

Accessors ​

buffersink ​

Get Signature ​

get buffersink(): FilterContext | null

Defined in: src/api/filter.ts:384

Get buffersink filter context.

Provides access to the buffersink filter context for advanced operations. Returns null if filter is not initialized.

Example ​
typescript
const sink = filter.buffersink;
if (sink) {
  const fr = sink.buffersinkGetFrameRate();
  console.log(`Output frame rate: ${fr.num}/${fr.den}`);
}
Returns ​

FilterContext | null

Buffersink context or null

channelLayout ​

Get Signature ​

get channelLayout(): ChannelLayout | null

Defined in: src/api/filter.ts:546

Output channel layout from filter graph (audio only).

Returns the channel layout of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_ch_layout() behavior. Only meaningful for audio filters.

Direct mapping to av_buffersink_get_ch_layout().

Example ​
typescript
const layout = filter.channelLayout;
if (layout) {
  console.log(`Filter output channels: ${layout.nbChannels}`);
}
Returns ​

ChannelLayout | null

Channel layout or null if not initialized

colorRange ​

Get Signature ​

get colorRange(): AVColorRange | null

Defined in: src/api/filter.ts:598

Output color range from filter graph (video only).

Returns the color range of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_color_range() behavior. Only meaningful for video filters.

Direct mapping to av_buffersink_get_color_range().

Example ​
typescript
const colorRange = filter.colorRange;
if (colorRange !== null) {
  console.log(`Filter output color range: ${colorRange}`);
}
Returns ​

AVColorRange | null

Color range or null if not initialized

colorSpace ​

Get Signature ​

get colorSpace(): AVColorSpace | null

Defined in: src/api/filter.ts:572

Output color space from filter graph (video only).

Returns the color space of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_colorspace() behavior. Only meaningful for video filters.

Direct mapping to av_buffersink_get_colorspace().

Example ​
typescript
const colorSpace = filter.colorSpace;
if (colorSpace !== null) {
  console.log(`Filter output color space: ${colorSpace}`);
}
Returns ​

AVColorSpace | null

Color space or null if not initialized

dimensions ​

Get Signature ​

get dimensions(): IDimension | null

Defined in: src/api/filter.ts:491

Output dimensions from filter graph (video only).

Returns the width and height of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_w() and av_buffersink_get_h() behavior. Only meaningful for video filters.

Direct mapping to av_buffersink_get_w() and av_buffersink_get_h().

Example ​
typescript
const dims = filter.dimensions;
if (dims) {
  console.log(`Filter output: ${dims.width}x${dims.height}`);
}
Returns ​

IDimension | null

Dimensions object or null if not initialized

format ​

Get Signature ​

get format(): AVPixelFormat | AVSampleFormat | null

Defined in: src/api/filter.ts:465

Output format from filter graph.

Returns the pixel format (video) or sample format (audio) of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_format() behavior.

Direct mapping to av_buffersink_get_format().

Example ​
typescript
const format = filter.format;
if (format !== null) {
  console.log(`Filter output format: ${format}`);
}
Returns ​

AVPixelFormat | AVSampleFormat | null

Pixel format or sample format, or null if not initialized

frameRate ​

Get Signature ​

get frameRate(): IRational | null

Defined in: src/api/filter.ts:408

Output frame rate from filter graph.

Returns the frame rate determined by the filter graph output. Returns null if filter is not initialized or frame rate is not set.

Direct mapping to av_buffersink_get_frame_rate().

Example ​
typescript
const frameRate = filter.frameRate;
if (frameRate) {
  console.log(`Filter output: ${frameRate.num}/${frameRate.den} fps`);
}
See ​

timeBase For output timebase

Returns ​

IRational | null

Frame rate or null if not available

isFilterInitialized ​

Get Signature ​

get isFilterInitialized(): boolean

Defined in: src/api/filter.ts:363

Check if filter has been initialized.

Returns true after first frame has been processed and filter graph configured. Useful for checking if filter has received frame properties.

Example ​
typescript
if (!filter.isFilterInitialized) {
  console.log('Filter will initialize on first frame');
}
Returns ​

boolean

true if filter graph has been built from first frame

isFilterOpen ​

Get Signature ​

get isFilterOpen(): boolean

Defined in: src/api/filter.ts:344

Check if filter is open.

Example ​
typescript
if (filter.isFilterOpen) {
  const output = await filter.process(frame);
}
Returns ​

boolean

sampleAspectRatio ​

Get Signature ​

get sampleAspectRatio(): IRational | null

Defined in: src/api/filter.ts:624

Output sample aspect ratio from filter graph (video only).

Returns the sample aspect ratio of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_sample_aspect_ratio() behavior. Only meaningful for video filters.

Direct mapping to av_buffersink_get_sample_aspect_ratio().

Example ​
typescript
const sar = filter.sampleAspectRatio;
if (sar) {
  console.log(`Filter output SAR: ${sar.num}:${sar.den}`);
}
Returns ​

IRational | null

Sample aspect ratio or null if not initialized

sampleRate ​

Get Signature ​

get sampleRate(): number | null

Defined in: src/api/filter.ts:520

Output sample rate from filter graph (audio only).

Returns the sample rate of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_sample_rate() behavior. Only meaningful for audio filters.

Direct mapping to av_buffersink_get_sample_rate().

Example ​
typescript
const sampleRate = filter.sampleRate;
if (sampleRate) {
  console.log(`Filter output sample rate: ${sampleRate} Hz`);
}
Returns ​

number | null

Sample rate or null if not initialized

timeBase ​

Get Signature ​

get timeBase(): IRational | null

Defined in: src/api/filter.ts:440

Output time base from filter graph.

Returns the time base of the buffersink output. Matches FFmpeg CLI's av_buffersink_get_time_base() behavior.

Direct mapping to av_buffersink_get_time_base().

Example ​
typescript
const timeBase = filter.timeBase;
if (timeBase) {
  console.log(`Filter timebase: ${timeBase.num}/${timeBase.den}`);
}
See ​

frameRate For output frame rate

Returns ​

IRational | null

Time base or null if not initialized

Methods ​

[dispose]() ​

[dispose](): void

Defined in: src/api/filter.ts:2231

Dispose of filter.

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

Returns ​

void

Example ​

typescript
{
  using filter = FilterAPI.create('scale=640:480', { ... });
  // Use filter...
} // Automatically freed

See ​

close For manual cleanup

Implementation of ​

Disposable.[dispose]

close() ​

close(): void

Defined in: src/api/filter.ts:1648

Free filter resources.

Releases filter graph and contexts. Safe to call multiple times.

Returns ​

void

Example ​

typescript
filter.close();

See ​

Symbol.dispose For automatic cleanup

flush() ​

flush(): Promise<void>

Defined in: src/api/filter.ts:1212

Flush filter and signal end-of-stream.

Sends null frame to flush buffered data. Must call receive() to get flushed frames. Does nothing if filter is closed or was never initialized.

Direct mapping to av_buffersrc_add_frame(NULL).

Returns ​

Promise<void>

Throws ​

If flush fails

Example ​

typescript
await filter.flush();
// Get remaining frames
let frame;
while ((frame = await filter.receive()) !== null) {
  frame.free();
}

See ​

flushFrames() ​

flushFrames(): AsyncGenerator<Frame>

Defined in: src/api/filter.ts:1287

Flush filter and yield remaining frames.

Convenient async generator for flushing. Combines flush and receive operations. Returns immediately if filter is closed or was never initialized.

Returns ​

AsyncGenerator<Frame>

Yields ​

Remaining frames from filter

Throws ​

If flush fails

Example ​

typescript
for await (const frame of filter.flushFrames()) {
  console.log(`Flushed frame: pts=${frame.pts}`);
  frame.free();
}

See ​

flushFramesSync() ​

flushFramesSync(): Generator<Frame>

Defined in: src/api/filter.ts:1323

Flush filter and yield remaining frames synchronously. Synchronous version of flushFrames.

Convenient sync generator for flushing. Combines flush and receive operations. Returns immediately if filter is closed or was never initialized.

Returns ​

Generator<Frame>

Yields ​

Remaining frames from filter

Throws ​

If flush fails

Example ​

typescript
for (const frame of filter.flushFramesSync()) {
  console.log(`Flushed frame: pts=${frame.pts}`);
  frame.free();
}

See ​

flushSync() ​

flushSync(): void

Defined in: src/api/filter.ts:1252

Flush filter and signal end-of-stream synchronously. Synchronous version of flush.

Sends null frame to flush buffered data. Must call receiveSync() to get flushed frames. Does nothing if filter is closed or was never initialized.

Direct mapping to av_buffersrc_add_frame(NULL).

Returns ​

void

Throws ​

If flush fails

Example ​

typescript
filter.flushSync();
// Get remaining frames
let frame;
while ((frame = filter.receiveSync()) !== null) {
  frame.free();
}

See ​

frames() ​

frames(frames): AsyncGenerator<Frame | null>

Defined in: src/api/filter.ts:1035

Process frame stream through filter.

High-level async generator for filtering frame streams. Filter is only flushed when EOF (null) signal is explicitly received. Primary interface for stream-based filtering.

EOF Handling:

  • Send null to flush filter and get remaining buffered frames
  • Generator yields null after flushing when null is received
  • No automatic flushing - filter stays open until EOF or close()

Parameters ​

frames ​

Frame | AsyncIterable<Frame | null, any, any> | null

Async iterable of frames, single frame, or null to flush

Returns ​

AsyncGenerator<Frame | null>

Yields ​

Filtered frames, followed by null when explicitly flushed

Throws ​

If filter not ready

Throws ​

If processing fails

Examples ​

typescript
// Stream of frames with automatic EOF propagation
for await (const frame of filter.frames(decoder.frames(packets))) {
  if (frame === null) {
    console.log('Filter flushed');
    break;
  }
  await encoder.encode(frame);
  frame.free();
}
typescript
// Single frame - no automatic flush
for await (const frame of filter.frames(singleFrame)) {
  await encoder.encode(frame);
  frame.free();
}
// Filter remains open, buffered frames not flushed
typescript
// Explicit flush with EOF
for await (const frame of filter.frames(null)) {
  if (frame === null) {
    console.log('All buffered frames flushed');
    break;
  }
  console.log('Buffered frame:', frame.pts);
  frame.free();
}

See ​

framesSync() ​

framesSync(frames): Generator<Frame | null>

Defined in: src/api/filter.ts:1138

Process frame stream through filter synchronously. Synchronous version of frames.

High-level sync generator for filtering frame streams. Filter is only flushed when EOF (null) signal is explicitly received. Primary interface for stream-based filtering.

EOF Handling:

  • Send null to flush filter and get remaining buffered frames
  • Generator yields null after flushing when null is received
  • No automatic flushing - filter stays open until EOF or close()

Parameters ​

frames ​

Frame | Iterable<Frame | null, any, any> | null

Iterable of frames, single frame, or null to flush

Returns ​

Generator<Frame | null>

Yields ​

Filtered frames, followed by null when explicitly flushed

Throws ​

If filter not ready

Throws ​

If processing fails

Examples ​

typescript
// Stream of frames with automatic EOF propagation
for (const frame of filter.framesSync(decoder.framesSync(packets))) {
  if (frame === null) {
    console.log('Filter flushed');
    break;
  }
  encoder.encodeSync(frame);
  frame.free();
}
typescript
// Single frame - no automatic flush
for (const frame of filter.framesSync(singleFrame)) {
  encoder.encodeSync(frame);
  frame.free();
}
// Filter remains open, buffered frames not flushed
typescript
// Explicit flush with EOF
for (const frame of filter.framesSync(null)) {
  if (frame === null) {
    console.log('All buffered frames flushed');
    break;
  }
  console.log('Buffered frame:', frame.pts);
  frame.free();
}

See ​

getGraphDescription() ​

getGraphDescription(): string | null

Defined in: src/api/filter.ts:663

Get filter graph description.

Returns human-readable graph structure. Useful for debugging filter chains.

Direct mapping to avfilter_graph_dump().

Returns ​

string | null

Graph description or null if closed

Example ​

typescript
const description = filter.getGraphDescription();
console.log('Filter graph:', description);

isReady() ​

isReady(): boolean

Defined in: src/api/filter.ts:643

Check if filter is ready for processing.

Returns ​

boolean

true if initialized and ready

Example ​

typescript
if (filter.isReady()) {
  const output = await filter.process(frame);
}

pipeTo() ​

Call Signature ​

pipeTo(target): Scheduler<Frame>

Defined in: src/api/filter.ts:1611

Pipe decoded frames to a filter component or encoder.

Parameters ​
target ​

FilterAPI

Filter to receive frames or encoder to encode frames

Returns ​

Scheduler<Frame>

Scheduler for continued chaining

Example ​
typescript
decoder.pipeTo(filter).pipeTo(encoder)

Call Signature ​

pipeTo(target): Scheduler<Frame>

Defined in: src/api/filter.ts:1612

Pipe decoded frames to a filter component or encoder.

Parameters ​
target ​

Encoder

Filter to receive frames or encoder to encode frames

Returns ​

Scheduler<Frame>

Scheduler for continued chaining

Example ​
typescript
decoder.pipeTo(filter).pipeTo(encoder)

process() ​

process(frame): Promise<void>

Defined in: src/api/filter.ts:722

Send a frame to the filter.

Sends a frame to the filter for processing. Does not return filtered frames - use receive to retrieve frames. On first frame, automatically builds filter graph with frame properties. A single input frame can produce zero, one, or multiple output frames.

Important: This method only SENDS the frame to the filter. You must call receive separately (potentially multiple times) to get filtered frames.

Direct mapping to av_buffersrc_add_frame().

Parameters ​

frame ​

Frame | null

Input frame to send to filter, or null to flush

Returns ​

Promise<void>

Throws ​

If filter could not be initialized

Throws ​

If sending frame fails

Examples ​

typescript
// Send frame and receive filtered frames
await filter.process(inputFrame);

// Receive all available filtered frames
while (true) {
  const output = await filter.receive();
  if (!output) break;
  console.log(`Got filtered frame: pts=${output.pts}`);
  output.free();
}
typescript
for await (const frame of decoder.frames(input.packets())) {
  // Send frame
  await filter.process(frame);

  // Receive available filtered frames
  let output;
  while ((output = await filter.receive())) {
    await encoder.encode(output);
    output.free();
  }
  frame.free();
}

See ​

processAll() ​

processAll(frame): Promise<Frame[]>

Defined in: src/api/filter.ts:903

Process a frame through the filter.

Applies filter operations to input frame and receives all available output frames. Returns array of frames - may be empty if filter needs more input. On first frame, automatically builds filter graph with frame properties. One input frame can produce zero, one, or multiple output frames depending on filter. Hardware frames context is automatically detected from frame.

Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().

Parameters ​

frame ​

Frame | null

Input frame to process

Returns ​

Promise<Frame[]>

Array of filtered frames (empty if buffered or filter closed)

Throws ​

If filter could not be initialized

Throws ​

If processing fails

Examples ​

typescript
const frames = await filter.processAll(inputFrame);
for (const output of frames) {
  console.log(`Got filtered frame: pts=${output.pts}`);
  output.free();
}
typescript
// Process frame - may return multiple frames (e.g. fps filter)
const frames = await filter.processAll(frame);
for (const output of frames) {
  yield output;
}

See ​

processAllSync() ​

processAllSync(frame): Frame[]

Defined in: src/api/filter.ts:961

Process a frame through the filter synchronously. Synchronous version of processAll.

Applies filter operations to input frame and receives all available output frames. Returns array of frames - may be empty if filter needs more input. On first frame, automatically builds filter graph with frame properties. One input frame can produce zero, one, or multiple output frames depending on filter. Hardware frames context is automatically detected from frame.

Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().

Parameters ​

frame ​

Frame

Input frame to process

Returns ​

Frame[]

Array of filtered frames (empty if buffered or filter closed)

Throws ​

If filter could not be initialized

Throws ​

If processing fails

Examples ​

typescript
const outputs = filter.processAllSync(inputFrame);
for (const output of outputs) {
  console.log(`Got filtered frame: pts=${output.pts}`);
  output.free();
}
typescript
// Process frame - may return multiple frames (e.g. fps filter)
const outputs = filter.processAllSync(frame);
for (const output of outputs) {
  yield output;
}

See ​

processSync() ​

processSync(frame): void

Defined in: src/api/filter.ts:812

Send a frame to the filter synchronously. Synchronous version of process.

Sends a frame to the filter for processing. Does not return filtered frames - use receiveSync to retrieve frames. On first frame, automatically builds filter graph with frame properties. A single input frame can produce zero, one, or multiple output frames.

Important: This method only SENDS the frame to the filter. You must call receiveSync separately (potentially multiple times) to get filtered frames.

Direct mapping to av_buffersrc_add_frame().

Parameters ​

frame ​

Frame | null

Input frame to send to filter, or null to flush

Returns ​

void

Throws ​

If filter could not be initialized

Throws ​

If sending frame fails

Example ​

typescript
// Send frame and receive filtered frames
filter.processSync(inputFrame);

// Receive all available filtered frames
let output;
while ((output = filter.receiveSync())) {
  console.log(`Got filtered frame: pts=${output.pts}`);
  output.free();
}

See ​

queueCommand() ​

queueCommand(target, cmd, arg, ts, flags?): void

Defined in: src/api/filter.ts:1586

Queue command for later execution.

Schedules command to execute at specific timestamp. Useful for synchronized parameter changes.

Direct mapping to avfilter_graph_queue_command().

Parameters ​

target ​

string

Target filter name

cmd ​

string

Command name

arg ​

string

Command argument

ts ​

number

Timestamp for execution

flags? ​

AVFilterCmdFlag

Command flags

Returns ​

void

Throws ​

If filter not ready

Throws ​

If queue fails

Example ​

typescript
// Queue volume change at 10 seconds
filter.queueCommand('volume', 'volume', '0.8', 10.0);

See ​

sendCommand For immediate commands

receive() ​

receive(): Promise<Frame | null | undefined>

Defined in: src/api/filter.ts:1385

Receive buffered frame from filter.

Drains frames buffered by the filter. Call repeatedly until null or EOF to get all buffered frames. Implements FFmpeg's send/receive pattern.

Return Values:

  • Frame - Successfully received frame (AVERROR >= 0)
  • null - Need more input data (AVERROR_EAGAIN), or filter not initialized
  • undefined - End of stream reached (AVERROR_EOF), or filter is closed

Direct mapping to av_buffersink_get_frame().

Returns ​

Promise<Frame | null | undefined>

Buffered frame, null if need more data, or undefined if stream ended

Throws ​

If receiving fails

Throws ​

If frame cloning fails (out of memory)

Examples ​

typescript
// Process all buffered frames
while (true) {
  const frame = await filter.receive();
  if (!frame) break; // Stop on EAGAIN or EOF
  console.log(`Received frame: pts=${frame.pts}`);
  frame.free();
}
typescript
// Handle each return value explicitly
const frame = await filter.receive();
if (frame === EOF) {
  console.log('Filter stream ended');
} else if (frame === null) {
  console.log('Need more input data');
} else {
  console.log(`Got frame: pts=${frame.pts}`);
  frame.free();
}

See ​

receiveSync() ​

receiveSync(): Frame | null | undefined

Defined in: src/api/filter.ts:1472

Receive buffered frame from filter synchronously. Synchronous version of receive.

Drains frames buffered by the filter. Call repeatedly until null or EOF to get all buffered frames. Implements FFmpeg's send/receive pattern.

Return Values:

  • Frame - Successfully received frame (AVERROR >= 0)
  • null - Need more input data (AVERROR_EAGAIN), or filter not initialized
  • undefined - End of stream reached (AVERROR_EOF), or filter is closed

Direct mapping to av_buffersink_get_frame().

Returns ​

Frame | null | undefined

Buffered frame, null if need more data, or undefined if stream ended

Throws ​

If receiving fails

Throws ​

If frame cloning fails (out of memory)

Examples ​

typescript
// Process all buffered frames
while (true) {
  const frame = filter.receiveSync();
  if (!frame) break; // Stop on EAGAIN or EOF
  console.log(`Received frame: pts=${frame.pts}`);
  frame.free();
}
typescript
// Handle each return value explicitly
const frame = filter.receiveSync();
if (frame === EOF) {
  console.log('Filter stream ended');
} else if (frame === null) {
  console.log('Need more input data');
} else {
  console.log(`Got frame: pts=${frame.pts}`);
  frame.free();
}

See ​

sendCommand() ​

sendCommand(target, cmd, arg, flags?): string

Defined in: src/api/filter.ts:1537

Send command to filter.

Sends runtime command to specific filter in graph. Allows dynamic parameter adjustment.

Direct mapping to avfilter_graph_send_command().

Parameters ​

target ​

string

Target filter name

cmd ​

string

Command name

arg ​

string

Command argument

flags? ​

AVFilterCmdFlag

Command flags

Returns ​

string

Response string from filter

Throws ​

If filter not ready

Throws ​

If command fails

Example ​

typescript
// Change volume at runtime
const response = filter.sendCommand('volume', 'volume', '0.5');
console.log(`Volume changed: ${response}`);

See ​

queueCommand For delayed commands

create() ​

static create(description, options?): FilterAPI

Defined in: src/api/filter.ts:304

Create a filter with specified description and configuration.

Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().

Parameters ​

description ​

string

Filter graph description

options? ​

FilterOptions = {}

Filter options

Returns ​

FilterAPI

Configured filter instance

Throws ​

If cfr=true but framerate is not set

Examples ​

typescript
// Simple video filter (VFR mode, auto timeBase)
const filter = FilterAPI.create('scale=640:480');
typescript
// CFR mode with constant framerate
const filter = FilterAPI.create('scale=1920:1080', {
  cfr: true,
  framerate: { num: 25, den: 1 }
});
typescript
// Audio filter with resampling
const filter = FilterAPI.create('aformat=sample_fmts=s16:sample_rates=44100', {
  audioResampleOpts: 'async=1'
});

See ​