node-av / lib / BitStreamFilterContext

Class: BitStreamFilterContext

Defined in: src/lib/bitstream-filter-context.ts:56

Bitstream filter context for processing compressed video/audio streams.

Applies bitstream filters to modify or analyze compressed packets without full decoding/encoding. Common uses include format conversion (e.g., H.264 MP4 to Annex B), metadata extraction, parameter set manipulation, and packet splitting/merging. Essential for stream compatibility between different containers and decoders.

Direct mapping to FFmpeg's AVBSFContext.

Example

typescript

import { BitStreamFilterContext, BitStreamFilter, Packet, FFmpegError } from 'node-av';

// Create and initialize H.264 stream format converter
const ctx = new BitStreamFilterContext();
const filter = BitStreamFilter.getByName('h264_mp4toannexb');
if (!filter) {
  throw new Error('H.264 filter not available');
}

let ret = ctx.alloc(filter);
FFmpegError.throwIfError(ret, 'alloc');

ret = ctx.init();
FFmpegError.throwIfError(ret, 'init');

// Process packets
const inputPacket = new Packet();
const outputPacket = new Packet();

ret = await ctx.sendPacket(inputPacket);
FFmpegError.throwIfError(ret, 'sendPacket');

ret = await ctx.receivePacket(outputPacket);
if (ret >= 0) {
  // Process filtered packet
}

// Cleanup
ctx.free();

See

BitStreamFilter For available filter types
Packet For packet manipulation

Extends

OptionMember<NativeBitStreamFilterContext>

Implements

Disposable
NativeWrapper<NativeBitStreamFilterContext>

Constructors

Constructor

new BitStreamFilterContext(): BitStreamFilterContext

Defined in: src/lib/bitstream-filter-context.ts:59

Returns

BitStreamFilterContext

Overrides

OptionMember<NativeBitStreamFilterContext>.constructor

Properties

native

protected native: NativeBitStreamFilterContext

Defined in: src/lib/option.ts:1030

Inherited from

OptionMember.native

Accessors

filter

Get Signature

get filter(): BitStreamFilter | null

Defined in: src/lib/bitstream-filter-context.ts:150

The bitstream filter being used.

Reference to the filter descriptor allocated to this context.

Direct mapping to AVBSFContext->filter.

Returns

BitStreamFilter | null

inputCodecParameters

Get Signature

get inputCodecParameters(): CodecParameters | null

Defined in: src/lib/bitstream-filter-context.ts:81

Input codec parameters.

Parameters describing the input stream format. These are automatically configured from the input packets in most cases.

Direct mapping to AVBSFContext->par_in.

Returns

CodecParameters | null

inputTimeBase

Get Signature

get inputTimeBase(): Rational

Defined in: src/lib/bitstream-filter-context.ts:120

Input time base.

Time base of the input packets (timestamps per second). Must be set before init() for proper timestamp handling.

Direct mapping to AVBSFContext->time_base_in.

Returns

Rational

Set Signature

set inputTimeBase(value): void

Defined in: src/lib/bitstream-filter-context.ts:125

Parameters

value

Rational

Returns

void

isInitialized

Get Signature

get isInitialized(): boolean

Defined in: src/lib/bitstream-filter-context.ts:69

Check if the context has been initialized.

Returns true if init() has been successfully called. The context must be initialized before sending/receiving packets.

Returns

boolean

outputCodecParameters

Get Signature

get outputCodecParameters(): CodecParameters | null

Defined in: src/lib/bitstream-filter-context.ts:101

Output codec parameters.

Parameters describing the output stream format after filtering. These reflect any changes made by the bitstream filter.

Direct mapping to AVBSFContext->par_out.

Returns

CodecParameters | null

outputTimeBase

Get Signature

get outputTimeBase(): Rational | null

Defined in: src/lib/bitstream-filter-context.ts:137

Output time base.

Time base of the output packets after filtering. May differ from input if the filter modifies timing.

Direct mapping to AVBSFContext->time_base_out.

Returns

Rational | null

Methods

[dispose]()

[dispose](): void

Defined in: src/lib/bitstream-filter-context.ts:459

Dispose of the bitstream filter context.

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

Returns

void

Example

typescript

{
  using ctx = new BitStreamFilterContext();
  ctx.alloc(filter);
  ctx.init();
  // Use context...
} // Automatically freed when leaving scope

Implementation of

Disposable.[dispose]

alloc()

alloc(filter): number

Defined in: src/lib/bitstream-filter-context.ts:191

Allocate a bitstream filter context.

Allocates and configures the context for the specified filter. Must be called before init().

Direct mapping to av_bsf_alloc().

Parameters

filter

BitStreamFilter

The bitstream filter to use

Returns

number

0 on success, negative AVERROR on error:

AVERROR_ENOMEM: Memory allocation failure
AVERROR_EINVAL: Invalid filter

Example

typescript

import { FFmpegError } from 'node-av';

const filter = BitStreamFilter.getByName('h264_mp4toannexb');
if (!filter) {
  throw new Error('Filter not found');
}

const ret = ctx.alloc(filter);
FFmpegError.throwIfError(ret, 'alloc');

See

init To initialize after allocation
BitStreamFilter.getByName To get filter by name

flush()

flush(): void

Defined in: src/lib/bitstream-filter-context.ts:266

Flush the bitstream filter.

Resets the internal state and discards any buffered data. Useful when seeking or switching streams.

Direct mapping to av_bsf_flush().

Returns

void

Example

typescript

// Flush when seeking
ctx.flush();
// Now ready to process packets from new position

free()

free(): void

Defined in: src/lib/bitstream-filter-context.ts:246

Free the bitstream filter context.

Releases all resources associated with the context. The context becomes invalid after calling this.

Direct mapping to av_bsf_free().

Returns

void

Example

typescript

ctx.free();
// Context is now invalid

See

Symbol.dispose For automatic cleanup
alloc To allocate

getNative()

getNative(): NativeBitStreamFilterContext

Defined in: src/lib/bitstream-filter-context.ts:439

Internal

Get the underlying native BitStreamFilterContext object.

Returns

NativeBitStreamFilterContext

The native BitStreamFilterContext binding object

Implementation of

NativeWrapper.getNative

getOption()

Get an option value from this object.

Uses the AVOption API to retrieve options.

Direct mapping to av_opt_get* functions.

Param

Option name

Param

Option type (defaults to AV_OPT_TYPE_STRING)

Param

Search flags (default: AV_OPT_SEARCH_CHILDREN)

Example

typescript

import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT, AV_OPT_TYPE_INT64 } from 'node-av/constants';

// String options (default)
const preset = obj.getOption('preset');
const codec = obj.getOption('codec', AV_OPT_TYPE_STRING);

// Typed options
const framerate = obj.getOption('framerate', AV_OPT_TYPE_RATIONAL); // Returns {num, den}
const pixFmt = obj.getOption('pix_fmt', AV_OPT_TYPE_PIXEL_FMT); // Returns AVPixelFormat
const bitrate = obj.getOption('bitrate', AV_OPT_TYPE_INT64); // Returns bigint

Call Signature

getOption(name, type?, searchFlags?): string | null

Defined in: src/lib/option.ts:1259

Parameters

name

string

type?

AVOptionTypeString

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): string | null

Defined in: src/lib/option.ts:1260

Parameters

name

string

type

AVOptionTypeColor

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1263

Parameters

name

string

type

AVOptionTypeInt

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): bigint | null

Defined in: src/lib/option.ts:1264

Parameters

name

string

type

AVOptionTypeInt64

searchFlags?

AVOptionSearchFlags

Returns

bigint | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1265

Parameters

name

string

type

AVOptionTypeUint

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): bigint | null

Defined in: src/lib/option.ts:1266

Parameters

name

string

type

AVOptionTypeUint64

searchFlags?

AVOptionSearchFlags

Returns

bigint | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1267

Parameters

name

string

type

AVOptionTypeFlags

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): boolean | null

Defined in: src/lib/option.ts:1268

Parameters

name

string

type

AVOptionTypeBool

searchFlags?

AVOptionSearchFlags

Returns

boolean | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1269

Parameters

name

string

type

AVOptionTypeDuration

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1270

Parameters

name

string

type

AVOptionTypeConst

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1273

Parameters

name

string

type

AVOptionTypeDouble

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): number | null

Defined in: src/lib/option.ts:1274

Parameters

name

string

type

AVOptionTypeFloat

searchFlags?

AVOptionSearchFlags

Returns

number | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): IRational | null

Defined in: src/lib/option.ts:1277

Parameters

name

string

Call Signature

getOption(name, type, searchFlags?): IRational | null

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

Parameters

name

string

type

AVOptionTypeVideoRate

searchFlags?

AVOptionSearchFlags

Returns

IRational | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): AVPixelFormat | null

Defined in: src/lib/option.ts:1279

Parameters

name

string

type

AVOptionTypePixelFmt

searchFlags?

AVOptionSearchFlags

Returns

AVPixelFormat | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): AVSampleFormat | null

Defined in: src/lib/option.ts:1280

Parameters

name

string

type

AVOptionTypeSampleFmt

searchFlags?

AVOptionSearchFlags

Returns

AVSampleFormat | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): IDimension | null

Defined in: src/lib/option.ts:1281

Parameters

name

string

type

AVOptionTypeImageSize

searchFlags?

AVOptionSearchFlags

Returns

IDimension | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): ChannelLayout | null

Defined in: src/lib/option.ts:1282

Parameters

name

string

type

AVOptionTypeChLayout

searchFlags?

AVOptionSearchFlags

Returns

ChannelLayout | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): Dictionary | null

Defined in: src/lib/option.ts:1283

Parameters

name

string

type

AVOptionTypeDict

searchFlags?

AVOptionSearchFlags

Returns

Dictionary | null

Inherited from

OptionMember.getOption

Call Signature

getOption(name, type, searchFlags?): string | null

Defined in: src/lib/option.ts:1284

Parameters

name

string

type

AVOptionTypeBinary

searchFlags?

AVOptionSearchFlags

Returns

string | null

Inherited from

OptionMember.getOption

init()

init(): number

Defined in: src/lib/bitstream-filter-context.ts:225

Initialize the bitstream filter context.

Initializes the filter with the configured parameters. Must be called after alloc() and before processing packets.

Direct mapping to av_bsf_init().

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

// Allocate and initialize
const ret1 = ctx.alloc(filter);
FFmpegError.throwIfError(ret1, 'alloc');

// Set parameters if needed
ctx.inputTimeBase = new Rational(1, 25);

const ret2 = ctx.init();
FFmpegError.throwIfError(ret2, 'init');

See

alloc Must be called first
isInitialized To check initialization status

listOptions()

listOptions(): OptionInfo[]

Defined in: src/lib/option.ts:1400

List all available options for this object.

Uses the AVOption API to enumerate all options. Useful for discovering available settings and their types.

Direct mapping to av_opt_next() iteration.

Returns

OptionInfo[]

Array of option information objects

Example

typescript

const options = obj.listOptions();
for (const opt of options) {
  console.log(`${opt.name}: ${opt.help}`);
  console.log(`  Type: ${opt.type}, Default: ${opt.defaultValue}`);
  console.log(`  Range: ${opt.min} - ${opt.max}`);
}

See

OptionInfo For option metadata structure

Inherited from

OptionMember.listOptions

receivePacket()

receivePacket(packet): Promise<number>

Defined in: src/lib/bitstream-filter-context.ts:388

Receive a filtered packet from the bitstream filter.

Retrieves a packet that has been processed by the filter. May need to be called multiple times after each sendPacket().

Direct mapping to av_bsf_receive_packet().

Parameters

packet

Packet

Packet to receive filtered data into

Returns

Promise<number>

0 on success, negative AVERROR on error:

AVERROR_EAGAIN: Need more input
AVERROR_EOF: No more packets available
AVERROR_EINVAL: Invalid parameters

Example

typescript

import { FFmpegError } from 'node-av';
import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av';

// Receive all available packets
while (true) {
  const ret = await ctx.receivePacket(outputPacket);
  if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
    break;
  }
  FFmpegError.throwIfError(ret, 'receivePacket');

  // Process filtered packet
  console.log(`Filtered packet size: ${outputPacket.size}`);
}

See

sendPacket To submit packets for filtering

receivePacketSync()

receivePacketSync(packet): number

Defined in: src/lib/bitstream-filter-context.ts:428

Receive a filtered packet from the bitstream filter synchronously. Synchronous version of receivePacket.

Retrieves a packet that has been processed by the filter. May need to be called multiple times after each sendPacketSync().

Direct mapping to av_bsf_receive_packet().

Parameters

packet

Packet

Packet to receive filtered data into

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EAGAIN: Need more input
AVERROR_EOF: No more packets available

Example

typescript

import { FFmpegError } from 'node-av';
import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av/constants';

// Receive filtered packets
const outputPacket = new Packet();
let ret;
while ((ret = ctx.receivePacketSync(outputPacket)) >= 0) {
  // Process filtered packet
  console.log(`Filtered packet size: ${outputPacket.size}`);
  outputPacket.unref();
}

if (ret !== AVERROR_EAGAIN && ret !== AVERROR_EOF) {
  FFmpegError.throwIfError(ret, 'receivePacketSync');
}

See

receivePacket For async version

sendPacket()

sendPacket(packet): Promise<number>

Defined in: src/lib/bitstream-filter-context.ts:307

Send a packet to the bitstream filter.

Submits a packet for filtering. The filter may buffer the packet internally and require multiple calls to receivePacket() to retrieve all output. Send null to signal end of stream.

Direct mapping to av_bsf_send_packet().

Parameters

packet

Packet to filter, or null to signal EOF

Packet | null

Returns

Promise<number>

0 on success, negative AVERROR on error:

AVERROR_EAGAIN: Filter needs output to be consumed first
AVERROR_EOF: Filter has been flushed
AVERROR_EINVAL: Invalid parameters
AVERROR_ENOMEM: Memory allocation failure

Example

typescript

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

const ret = await ctx.sendPacket(inputPacket);
if (ret === AVERROR_EAGAIN) {
  // Need to receive packets first
  const ret2 = await ctx.receivePacket(outputPacket);
  FFmpegError.throwIfError(ret2, 'receivePacket');
} else {
  FFmpegError.throwIfError(ret, 'sendPacket');
}

// Send EOF
await ctx.sendPacket(null);

See

receivePacket To retrieve filtered packets

sendPacketSync()

sendPacketSync(packet): number

Defined in: src/lib/bitstream-filter-context.ts:349

Send a packet to the bitstream filter synchronously. Synchronous version of sendPacket.

Submits a packet for filtering. The filter may buffer packets internally and produce output with different timing.

Direct mapping to av_bsf_send_packet().

Parameters

packet

Packet to filter (null to drain)

Packet | null

Returns

number

0 on success, negative AVERROR on error:

AVERROR_EAGAIN: Need to receive packets first
AVERROR_EOF: Filter has been flushed
AVERROR_EINVAL: Invalid state
AVERROR(ENOMEM): Memory allocation failure

Example

typescript

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

// Send packet to filter
const ret = ctx.sendPacketSync(inputPacket);
if (ret === AVERROR_EAGAIN) {
  // Need to receive output first
  const outputPacket = new Packet();
  ctx.receivePacketSync(outputPacket);
} else {
  FFmpegError.throwIfError(ret, 'sendPacketSync');
}

// Drain filter
ctx.sendPacketSync(null);

See

sendPacket For async version

setOption()

Set an option on this object.

Uses the AVOption API to set options. Available options depend on the specific object type.

Direct mapping to av_opt_set* functions.

Param

Option name

Param

Option value

Param

Option type (defaults to AV_OPT_TYPE_STRING)

Param

Search flags (default: AV_OPT_SEARCH_CHILDREN)

Example

typescript

import { FFmpegError } from 'node-av';
import { AV_OPT_TYPE_STRING, AV_OPT_TYPE_INT64, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_PIXEL_FMT } from 'node-av/constants';

// String options (default)
let ret = obj.setOption('preset', 'fast');
FFmpegError.throwIfError(ret, 'set preset');

ret = obj.setOption('codec', 'h264', AV_OPT_TYPE_STRING);
FFmpegError.throwIfError(ret, 'set codec');

// Integer options
ret = obj.setOption('bitrate', 2000000, AV_OPT_TYPE_INT64);
FFmpegError.throwIfError(ret, 'set bitrate');

ret = obj.setOption('threads', 4, AV_OPT_TYPE_INT);
FFmpegError.throwIfError(ret, 'set threads');

// Complex types with proper types
ret = obj.setOption('framerate', {num: 30, den: 1}, AV_OPT_TYPE_RATIONAL);
FFmpegError.throwIfError(ret, 'set framerate');

ret = obj.setOption('pix_fmt', AV_PIX_FMT_YUV420P, AV_OPT_TYPE_PIXEL_FMT);
FFmpegError.throwIfError(ret, 'set pixel format');