Class: BitStreamFilterAPI | NodeAV
NodeAV

Appearance

node-av / api / BitStreamFilterAPI

Class: BitStreamFilterAPI ​

Defined in: src/api/bitstream-filter.ts:80

High-level bitstream filter for packet processing.

Provides simplified interface for applying bitstream filters to packets. Handles filter initialization, packet processing, and memory management. Supports both synchronous packet-by-packet filtering and async iteration over packets. Supports filters like h264_mp4toannexb, hevc_mp4toannexb, aac_adtstoasc. Essential for format conversion and stream compatibility in transcoding pipelines.

Examples ​

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

// Create H.264 Annex B converter
const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);

// Filter packet
const outputPackets = await filter.filterAll(inputPacket);
for (const packet of outputPackets) {
  await output.writePacket(packet);
  packet.free();
}
typescript
// Filter packet stream
const filter = BitStreamFilterAPI.create('hevc_mp4toannexb', videoStream);

for await (const packet of filter.packets(input.packets())) {
  await output.writePacket(packet);
  packet.free();
}

See ​

Implements ​

  • Disposable

Accessors ​

isBitstreamFilterOpen ​

Get Signature ​

get isBitstreamFilterOpen(): boolean

Defined in: src/api/bitstream-filter.ts:259

Check if filter is open.

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

boolean

isInitialized ​

Get Signature ​

get isInitialized(): boolean

Defined in: src/api/bitstream-filter.ts:276

Check if the filter has been initialized.

Initialization is lazy and happens on the first processed packet, after which outputCodecParameters reflect the filter's output.

Example ​
typescript
if (filter.isInitialized) {
  const params = filter.outputCodecParameters;
}
Returns ​

boolean

name ​

Get Signature ​

get name(): string

Defined in: src/api/bitstream-filter.ts:214

Get filter name.

Example ​
typescript
console.log(`Using filter: ${filter.name}`);
Returns ​

string

outputCodecParameters ​

Get Signature ​

get outputCodecParameters(): CodecParameters | null

Defined in: src/api/bitstream-filter.ts:230

Get output codec parameters.

Parameters after filter processing. May differ from input parameters.

Example ​
typescript
const outputParams = filter.outputCodecParameters;
console.log(`Output codec: ${outputParams?.codecId}`);
Returns ​

CodecParameters | null

outputTimeBase ​

Get Signature ​

get outputTimeBase(): Rational | null

Defined in: src/api/bitstream-filter.ts:245

Get output time base.

Time base after filter processing.

Example ​
typescript
const tb = filter.outputTimeBase;
console.log(`Output timebase: ${tb?.num}/${tb?.den}`);
Returns ​

Rational | null

Methods ​

[dispose]() ​

[dispose](): void

Defined in: src/api/bitstream-filter.ts:1199

Dispose of filter.

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

Returns ​

void

Example ​

typescript
{
  using filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
  // Use filter...
} // Automatically disposed

See ​

close For manual cleanup

Implementation of ​

Disposable.[dispose]

close() ​

close(): void

Defined in: src/api/bitstream-filter.ts:1166

Close filter and free resources.

Releases filter context and marks as closed. Safe to call multiple times.

Returns ​

void

Example ​

typescript
filter.close();

See ​

Symbol.dispose For automatic cleanup

filter() ​

filter(packet): Promise<void>

Defined in: src/api/bitstream-filter.ts:356

Send a packet to the filter.

Sends a packet to the filter for processing. Does not return filtered packets - use receive to retrieve packets. A single packet can produce zero, one, or multiple packets depending on filter.

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

Direct mapping to av_bsf_send_packet().

Parameters ​

packet ​

Packet | null

Packet to send to filter, or null to flush

Returns ​

Promise<void>

Throws ​

If sending fails

Examples ​

typescript
// Send packet and receive filtered packets
await filter.filter(inputPacket);

// Receive all available filtered packets
while (true) {
  const outPacket = await filter.receive();
  if (!outPacket) break;
  console.log(`Filtered packet with PTS: ${outPacket.pts}`);
  await output.writePacket(outPacket);
  outPacket.free();
}
typescript
for await (const packet of input.packets()) {
  // packet is null at end of stream - automatically flushes filter
  await filter.filter(packet);

  // Receive available filtered packets
  let outPacket;
  while ((outPacket = await filter.receive())) {
    await output.writePacket(outPacket);
    outPacket.free();
  }
}

See ​

filterAll() ​

filterAll(packet): Promise<Packet[]>

Defined in: src/api/bitstream-filter.ts:481

Filter a packet to packets.

Sends a packet to the filter and receives all available filtered packets. Returns array of packets - may be empty if filter needs more data. One packet can produce zero, one, or multiple packets depending on filter.

Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().

Parameters ​

packet ​

Packet | null

Packet to filter, or null to flush

Returns ​

Promise<Packet[]>

Array of filtered packets (empty if more data needed or filter is closed)

Throws ​

If filtering fails

Examples ​

typescript
const outputPackets = await filter.filterAll(inputPacket);
for (const packet of outputPackets) {
  console.log(`Filtered packet: pts=${packet.pts}`);
  await output.writePacket(packet);
  packet.free();
}
typescript
// Flush remaining packets at end of stream
const remaining = await filter.filterAll(null);
for (const packet of remaining) {
  await output.writePacket(packet);
  packet.free();
}

See ​

filterAllSync() ​

filterAllSync(packet): Packet[]

Defined in: src/api/bitstream-filter.ts:537

Filter a packet to packets synchronously. Synchronous version of filterAll.

Sends a packet to the filter and receives all available filtered packets. Returns array of packets - may be empty if filter needs more data. One packet can produce zero, one, or multiple packets depending on filter.

Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().

Parameters ​

packet ​

Packet | null

Packet to filter, or null to flush

Returns ​

Packet[]

Array of filtered packets (empty if more data needed or filter is closed)

Throws ​

If filtering fails

Examples ​

typescript
const outputPackets = filter.filterAllSync(inputPacket);
for (const packet of outputPackets) {
  console.log(`Filtered packet: pts=${packet.pts}`);
  output.writePacketSync(packet);
  packet.free();
}
typescript
// Flush remaining packets at end of stream
const remaining = filter.filterAllSync(null);
for (const packet of remaining) {
  output.writePacketSync(packet);
  packet.free();
}

See ​

filterSync() ​

filterSync(packet): void

Defined in: src/api/bitstream-filter.ts:426

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

Sends a packet to the filter for processing. Does not return filtered packets - use receiveSync to retrieve packets. A single packet can produce zero, one, or multiple packets depending on filter.

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

Direct mapping to av_bsf_send_packet().

Parameters ​

packet ​

Packet | null

Packet to send to filter, or null to flush

Returns ​

void

Throws ​

If sending fails

Examples ​

typescript
// Send packet and receive filtered packets
filter.filterSync(inputPacket);

// Receive all available filtered packets
while (true) {
  const outPacket = filter.receiveSync();
  if (!outPacket) break;
  console.log(`Filtered packet with PTS: ${outPacket.pts}`);
  output.writePacketSync(outPacket);
  outPacket.free();
}
typescript
for (const packet of packets) {
  // packet is null at end of stream - automatically flushes filter
  filter.filterSync(packet);

  // Receive available filtered packets
  let outPacket;
  while ((outPacket = filter.receiveSync())) {
    output.writePacketSync(outPacket);
    outPacket.free();
  }
}

See ​

flush() ​

flush(): Promise<void>

Defined in: src/api/bitstream-filter.ts:781

Flush filter and signal end-of-stream.

Sends null packet to filter to signal end-of-stream. Does nothing if filter is closed. Must call receive() or flushPackets() to get remaining buffered packets.

Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().

Returns ​

Promise<void>

Throws ​

If flush fails

Example ​

typescript
// Signal end of stream
await filter.flush();

// Then get remaining packets
let packet;
while ((packet = await filter.receive()) !== null) {
  console.log('Got buffered packet');
  await output.writePacket(packet);
  packet.free();
}

See ​

flushPackets() ​

flushPackets(): AsyncGenerator<Packet>

Defined in: src/api/bitstream-filter.ts:1089

Flush all buffered packets as async generator.

Convenient async iteration over remaining packets. Automatically sends flush signal and retrieves buffered packets. Useful for end-of-stream processing.

Returns ​

AsyncGenerator<Packet>

Yields ​

Buffered packets

Example ​

typescript
// Flush at end of filtering
for await (const packet of filter.flushPackets()) {
  console.log('Processing buffered packet');
  await output.writePacket(packet);
  packet.free();
}

See ​

flushPacketsSync() ​

flushPacketsSync(): Generator<Packet>

Defined in: src/api/bitstream-filter.ts:1121

Flush all buffered packets as generator synchronously. Synchronous version of flushPackets.

Convenient sync iteration over remaining packets. Automatically retrieves buffered packets after flush. Useful for end-of-stream processing.

Returns ​

Generator<Packet>

Yields ​

Buffered packets

Example ​

typescript
// Flush at end of filtering
for (const packet of filter.flushPacketsSync()) {
  console.log('Processing buffered packet');
  output.writePacketSync(packet);
  packet.free();
}

See ​

flushSync() ​

flushSync(): void

Defined in: src/api/bitstream-filter.ts:829

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

Sends null packet to filter to signal end-of-stream. Does nothing if filter is closed. Must call receiveSync() or flushPacketsSync() to get remaining buffered packets.

Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().

Returns ​

void

Throws ​

If flush fails

Example ​

typescript
// Signal end of stream
filter.flushSync();

// Then get remaining packets
let packet;
while ((packet = filter.receiveSync()) !== null) {
  console.log('Got buffered packet');
  output.writePacketSync(packet);
  packet.free();
}

See ​

getStream() ​

getStream(): Stream

Defined in: src/api/bitstream-filter.ts:297

Get associated stream.

Returns the stream this filter was created for. Only available when the filter was created from a Stream; filters created from an Encoder derive their parameters from the encoder's output instead.

Returns ​

Stream

Associated stream

Throws ​

If the filter was not created from a stream

Example ​

typescript
const stream = filter.getStream();
console.log(`Filtering stream ${stream.index}`);

packets() ​

packets(packets): AsyncGenerator<Packet | null>

Defined in: src/api/bitstream-filter.ts:610

Filter packet stream to filtered packet stream.

High-level async generator for complete filtering pipeline. 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 packets
  • Generator yields null after flushing when null is received
  • No automatic flushing - filter stays open until EOF or close()

Parameters ​

packets ​

Packet | AsyncIterable<Packet | null, any, any> | null

Async iterable of packets, single packet, or null to flush

Returns ​

AsyncGenerator<Packet | null>

Yields ​

Filtered packets, followed by null when explicitly flushed

Throws ​

If filtering fails

Examples ​

typescript
// Stream of packets with automatic EOF propagation
for await (const packet of filter.packets(input.packets())) {
  if (packet === null) {
    console.log('Filter flushed');
    break;
  }
  await output.writePacket(packet);
  packet.free(); // Must free output packets
}
typescript
// Single packet - no automatic flush
for await (const packet of filter.packets(singlePacket)) {
  await output.writePacket(packet);
  packet.free();
}
// Filter remains open, buffered packets not flushed
typescript
// Explicit flush with EOF
for await (const packet of filter.packets(null)) {
  if (packet === null) {
    console.log('All buffered packets flushed');
    break;
  }
  console.log('Buffered packet:', packet.pts);
  await output.writePacket(packet);
  packet.free();
}

See ​

packetsSync() ​

packetsSync(packets): Generator<Packet | null>

Defined in: src/api/bitstream-filter.ts:711

Filter packet stream to filtered packet stream synchronously. Synchronous version of packets.

High-level sync generator for complete filtering pipeline. 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 packets
  • Generator yields null after flushing when null is received
  • No automatic flushing - filter stays open until EOF or close()

Parameters ​

packets ​

Packet | Iterable<Packet | null, any, any> | null

Iterable of packets, single packet, or null to flush

Returns ​

Generator<Packet | null>

Yields ​

Filtered packets, followed by null when explicitly flushed

Throws ​

If filtering fails

Examples ​

typescript
// Stream of packets with automatic EOF propagation
for (const packet of filter.packetsSync(inputPackets)) {
  if (packet === null) {
    console.log('Filter flushed');
    break;
  }
  output.writePacketSync(packet);
  packet.free(); // Must free output packets
}
typescript
// Single packet - no automatic flush
for (const packet of filter.packetsSync(singlePacket)) {
  output.writePacketSync(packet);
  packet.free();
}
// Filter remains open, buffered packets not flushed
typescript
// Explicit flush with EOF
for (const packet of filter.packetsSync(null)) {
  if (packet === null) {
    console.log('All buffered packets flushed');
    break;
  }
  console.log('Buffered packet:', packet.pts);
  output.writePacketSync(packet);
  packet.free();
}

See ​

pipeTo() ​

Call Signature ​

pipeTo(target): Scheduler<Packet>

Defined in: src/api/bitstream-filter.ts:1004

Pipe output to another bitstream filter.

Starts background worker for packet processing. Packets flow through: input → this filter → target filter.

Parameters ​
target ​

BitStreamFilterAPI

Target bitstream filter

Returns ​

Scheduler<Packet>

Scheduler for continued chaining

Example ​
typescript
const filter1 = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
const filter2 = BitStreamFilterAPI.create('dump_extra', stream);
filter1.pipeTo(filter2).pipeTo(output, 0);

Call Signature ​

pipeTo(output, streamIndex): SchedulerControl<Packet>

Defined in: src/api/bitstream-filter.ts:1024

Pipe output to muxer.

Terminal stage - writes filtered packets to output file.

Parameters ​
output ​

Muxer

Muxer to write to

streamIndex ​

number

Stream index in output

Returns ​

SchedulerControl<Packet>

Control interface for pipeline

Example ​
typescript
const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
const control = filter.pipeTo(output, 0);
await control.send(packet);

receive() ​

receive(): Promise<Packet | null>

Defined in: src/api/bitstream-filter.ts:885

Receive packet from filter.

Gets filtered packets from the filter's internal buffer. Handles packet allocation and error checking. Returns null if filter is closed or no packets available. Call repeatedly until null to drain all buffered packets.

Direct mapping to av_bsf_receive_packet().

Returns ​

Promise<Packet | null>

Cloned packet or null if no packets available

Throws ​

If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF

Throws ​

If packet cloning fails (out of memory)

Examples ​

typescript
const packet = await filter.receive();
if (packet) {
  console.log('Got filtered packet');
  await output.writePacket(packet);
  packet.free();
}
typescript
// Drain all buffered packets
let packet;
while ((packet = await filter.receive()) !== null) {
  console.log(`Packet PTS: ${packet.pts}`);
  await output.writePacket(packet);
  packet.free();
}

See ​

receiveSync() ​

receiveSync(): Packet | null

Defined in: src/api/bitstream-filter.ts:958

Receive packet from filter synchronously. Synchronous version of receive.

Gets filtered packets from the filter's internal buffer. Handles packet allocation and error checking. Returns null if filter is closed or no packets available. Call repeatedly until null to drain all buffered packets.

Direct mapping to av_bsf_receive_packet().

Returns ​

Packet | null

Cloned packet or null if no packets available

Throws ​

If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF

Throws ​

If packet cloning fails (out of memory)

Examples ​

typescript
const packet = filter.receiveSync();
if (packet) {
  console.log('Got filtered packet');
  output.writePacketSync(packet);
  packet.free();
}
typescript
// Drain all buffered packets
let packet;
while ((packet = filter.receiveSync()) !== null) {
  console.log(`Packet PTS: ${packet.pts}`);
  output.writePacketSync(packet);
  packet.free();
}

See ​

reset() ​

reset(): void

Defined in: src/api/bitstream-filter.ts:1145

Reset filter state.

Clears internal buffers and resets filter. Does not dispose resources.

Direct mapping to av_bsf_flush().

Returns ​

void

Example ​

typescript
// Reset for new segment
filter.reset();

See ​

flush For reset with packet retrieval

create() ​

static create<N>(filterName, source, filterOptions?): BitStreamFilterAPI

Defined in: src/api/bitstream-filter.ts:161

Create a bitstream filter.

The input source provides the codec parameters the filter is configured with. Pass a Stream to filter its packets directly (stream copy), or an Encoder to filter that encoder's output (transcode) - parameters are derived from the encoder once it is open. Another BitStreamFilterAPI may be passed to chain filters.

Initialization is lazy: filter options are validated immediately, but the input parameters are bound and the filter is initialized on the first packet, so an Encoder source (opened lazily on its first frame) is ready in time.

Direct mapping to av_bsf_get_by_name() and av_bsf_alloc().

Type Parameters ​

N ​

N extends string & object | BsfName = string & object | BsfName

Parameters ​

filterName ​

N

Name of the bitstream filter

source ​

Stream | BitStreamFilterAPI | Encoder

Input source: a Stream (copy), Encoder (transcode), or upstream filter (chain)

filterOptions? ​

BitstreamFilterOptions<N>

Optional filter-specific options

Returns ​

BitStreamFilterAPI

Configured bitstream filter

Throws ​

If the filter is not found, allocation fails, or an option is invalid

Examples ​

typescript
// Stream copy: H.264 MP4 to Annex B conversion
const filter = BitStreamFilterAPI.create('h264_mp4toannexb', videoStream);
typescript
// Transcode: derive parameters from the encoder's output
const filter = BitStreamFilterAPI.create('h264_metadata', encoder, {
  options: { aud: 'remove', level: '4.1' },
});
pipeline(input, decoder, encoder, filter, output);

See ​