node-av 3.1.3 → 4.0.0

package/dist/api/bitstream-filter.d.ts

@@ -1,10 +1,13 @@
-import { Packet } from '../lib/index.js';
-import type { Stream } from '../lib/index.js';
+import { Packet } from '../lib/packet.js';
+import { Muxer } from './muxer.js';
+import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
+import type { Stream } from '../lib/stream.js';
 /**
  * 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.
  *
@@ -15,8 +18,8 @@ import type { Stream } from '../lib/index.js';
  * // Create H.264 Annex B converter
  * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
  *
- * // Process packet
- * const outputPackets = await filter.process(inputPacket);
+ * // Filter packet
+ * const outputPackets = await filter.filterAll(inputPacket);
  * for (const packet of outputPackets) {
  *   await output.writePacket(packet);
  *   packet.free();
@@ -25,7 +28,7 @@ import type { Stream } from '../lib/index.js';
  *
  * @example
  * ```typescript
- * // Process packet stream
+ * // Filter packet stream
  * const filter = BitStreamFilterAPI.create('hevc_mp4toannexb', videoStream);
  *
  * for await (const packet of filter.packets(input.packets())) {
@@ -36,15 +39,21 @@ import type { Stream } from '../lib/index.js';
  *
  * @see {@link BitStreamFilter} For available filters
  * @see {@link BitStreamFilterContext} For low-level API
- * @see {@link MediaOutput} For writing filtered packets
+ * @see {@link Muxer} For writing filtered packets
  */
 export declare class BitStreamFilterAPI implements Disposable {
     private ctx;
-    private filter;
+    private bsf;
     private stream;
+    private packet;
     private isClosed;
+    private inputQueue;
+    private outputQueue;
+    private workerPromise;
+    private nextComponent;
+    private pipeToPromise;
     /**
-     * @param filter - Bitstream filter instance
+     * @param bsf - Bitstream filter
      *
      * @param ctx - Filter context
      *
@@ -113,7 +122,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * console.log(`Output codec: ${outputParams?.codecId}`);
      * ```
      */
-    get outputCodecParameters(): import("../lib/codec-parameters.js").CodecParameters | null;
+    get outputCodecParameters(): import("../index.js").CodecParameters | null;
     /**
      * Get output time base.
      *
@@ -125,7 +134,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * console.log(`Output timebase: ${tb?.num}/${tb?.den}`);
      * ```
      */
-    get outputTimeBase(): import("../lib/rational.js").Rational | null;
+    get outputTimeBase(): import("../index.js").Rational | null;
     /**
      * Check if filter is open.
      *
@@ -138,77 +147,137 @@ export declare class BitStreamFilterAPI implements Disposable {
      */
     get isBitstreamFilterOpen(): boolean;
     /**
-     * Process a packet through the filter.
+     * Filter a packet.
      *
-     * Applies bitstream filter to packet.
-     * May produce zero, one, or multiple output packets.
-     * Pass null to signal end-of-stream.
+     * Sends a packet to the filter and attempts to receive a filtered packet.
+     * Handles internal buffering - may return null if more packets needed.
+     *
+     * **Note**: This method receives only ONE packet per call.
+     * A single packet can produce multiple output packets (e.g., codec buffering).
+     * To receive all packets from a packet, use {@link filterAll} or {@link packets} instead.
      *
      * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
      *
-     * @param packet - Packet to filter or null for EOF
+     * @param packet - Packet to filter
      *
-     * @returns Array of filtered packets or null if filter is closed
+     * @returns Filtered packet, null if more data needed, or null if filter is closed
      *
      * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * const outputPackets = await filter.process(inputPacket);
-     * if (outputPackets) {
-     *   for (const packet of outputPackets) {
-     *     console.log(`Filtered packet: pts=${packet.pts}`);
-     *     packet.free();
-     *   }
+     * const outPacket = await filter.filter(inputPacket);
+     * if (outPacket) {
+     *   console.log(`Filtered packet: pts=${outPacket.pts}`);
+     *   await output.writePacket(outPacket);
+     *   outPacket.free();
      * }
      * ```
      *
+     * @see {@link filterAll} For multiple packet filtering
+     * @see {@link packets} For stream processing
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link filterSync} For synchronous version
+     */
+    filter(packet: Packet): Promise<Packet | null>;
+    /**
+     * Filter a packet synchronously.
+     * Synchronous version of filter.
+     *
+     * Sends a packet to the filter and attempts to receive a filtered packet.
+     * Handles internal buffering - may return null if more packets needed.
+     *
+     * **Note**: This method receives only ONE packet per call.
+     * A single packet can produce multiple output packets (e.g., codec buffering).
+     * To receive all packets from a packet, use {@link filterAllSync} or {@link packetsSync} instead.
+     *
+     * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
+     *
+     * @param packet - Packet to filter
+     *
+     * @returns Filtered packet, null if more data needed, or null if filter is closed
+     *
+     * @throws {FFmpegError} If filtering fails
+     *
      * @example
      * ```typescript
-     * // Flush filter
-     * const remaining = await filter.process(null);
+     * const outPacket = filter.filterSync(inputPacket);
+     * if (outPacket) {
+     *   console.log(`Filtered packet: pts=${outPacket.pts}`);
+     *   output.writePacketSync(outPacket);
+     *   outPacket.free();
+     * }
      * ```
      *
-     * @see {@link flush} For explicit flushing
-     * @see {@link packets} For stream processing
+     * @see {@link filterAllSync} For multiple packet filtering
+     * @see {@link packetsSync} For stream processing
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link filter} For async version
      */
-    process(packet: Packet | null): Promise<Packet[]>;
+    filterSync(packet: Packet): Packet | null;
     /**
-     * Process a packet through the filter synchronously.
-     * Synchronous version of process.
+     * Filter a packet to packets.
      *
-     * Applies bitstream filter to packet.
-     * May produce zero, one, or multiple output packets.
-     * Pass null to signal end-of-stream.
+     * 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().
      *
-     * @param packet - Packet to filter or null for EOF
+     * @param packet - Packet to filter
      *
-     * @returns Array of filtered packets or null if filter is closed
+     * @returns Array of filtered packets (empty if more data needed or filter is closed)
      *
      * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * const outputPackets = filter.processSync(inputPacket);
-     * if (outputPackets) {
-     *   for (const packet of outputPackets) {
-     *     console.log(`Filtered packet: pts=${packet.pts}`);
-     *     packet.free();
-     *   }
+     * const outputPackets = await filter.filterAll(inputPacket);
+     * for (const packet of outputPackets) {
+     *   console.log(`Filtered packet: pts=${packet.pts}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
      * }
      * ```
      *
+     * @see {@link filter} For single packet filtering
+     * @see {@link packets} For stream processing
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link filterAllSync} For synchronous version
+     */
+    filterAll(packet: Packet): Promise<Packet[]>;
+    /**
+     * 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().
+     *
+     * @param packet - Packet to filter
+     *
+     * @returns Array of filtered packets (empty if more data needed or filter is closed)
+     *
+     * @throws {FFmpegError} If filtering fails
+     *
      * @example
      * ```typescript
-     * // Flush filter
-     * const remaining = filter.processSync(null);
+     * const outputPackets = filter.filterAllSync(inputPacket);
+     * for (const packet of outputPackets) {
+     *   console.log(`Filtered packet: pts=${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
      * ```
      *
-     * @see {@link process} For async version
+     * @see {@link filterSync} For single packet filtering
+     * @see {@link packetsSync} For stream processing
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link filterAll} For async version
      */
-    processSync(packet: Packet | null): Packet[];
+    filterAllSync(packet: Packet): Packet[];
     /**
      * Process packet stream through filter.
      *
@@ -243,10 +312,10 @@ export declare class BitStreamFilterAPI implements Disposable {
      * }
      * ```
      *
-     * @see {@link process} For single packet filtering
+     * @see {@link filterAll} For filtering single packets
      * @see {@link flush} For end-of-stream handling
      */
-    packets(packets: AsyncIterable<Packet>): AsyncGenerator<Packet>;
+    packets(packets: AsyncIterable<Packet | null>): AsyncGenerator<Packet | null>;
     /**
      * Process packet stream through filter synchronously.
      * Synchronous version of packets.
@@ -284,93 +353,197 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @see {@link packets} For async version
      */
-    packetsSync(packets: Iterable<Packet>): Generator<Packet>;
+    packetsSync(packets: Iterable<Packet | null>): Generator<Packet | null>;
     /**
-     * Flush filter and get remaining packets.
+     * Flush filter and signal end-of-stream.
      *
-     * Signals end-of-stream and retrieves buffered packets.
-     * Also resets internal filter state.
+     * 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_flush().
+     * Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().
      *
-     * @returns Array of remaining packets or null if filter is closed
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * const remaining = await filter.flush();
-     * if (remaining) {
-     *   for (const packet of remaining) {
-     *     await output.writePacket(packet);
-     *     packet.free();
-     *   }
+     * // 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 {@link flushPackets} For async iteration
+     * @see {@link receive} For getting buffered packets
      * @see {@link reset} For state reset only
+     * @see {@link flushSync} For synchronous version
      */
-    flush(): Promise<Packet[]>;
+    flush(): Promise<void>;
     /**
-     * Flush filter and get remaining packets synchronously.
+     * Flush filter and signal end-of-stream synchronously.
      * Synchronous version of flush.
      *
-     * Signals end-of-stream and retrieves buffered packets.
-     * Also resets internal filter state.
+     * 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_flush().
+     * Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().
      *
-     * @returns Array of remaining packets or null if filter is closed
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * const remaining = filter.flushSync();
-     * if (remaining) {
-     *   for (const packet of remaining) {
-     *     output.writePacketSync(packet);
-     *     packet.free();
-     *   }
+     * // 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 {@link flushPacketsSync} For sync iteration
+     * @see {@link receiveSync} For getting buffered packets
+     * @see {@link reset} For state reset only
      * @see {@link flush} For async version
      */
-    flushSync(): Packet[];
+    flushSync(): void;
     /**
-     * Flush filter as async generator.
+     * 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 Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     *
+     * @example
+     * ```typescript
+     * const packet = await filter.receive();
+     * if (packet) {
+     *   console.log('Got filtered packet');
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```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 {@link filter} For filtering packets
+     * @see {@link flush} For signaling end-of-stream
+     * @see {@link receiveSync} For synchronous version
+     */
+    receive(): Promise<Packet | null>;
+    /**
+     * 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 Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
+     *
+     * @example
+     * ```typescript
+     * const packet = filter.receiveSync();
+     * if (packet) {
+     *   console.log('Got filtered packet');
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered packets
+     * let packet;
+     * while ((packet = filter.receiveSync()) !== null) {
+     *   console.log(`Packet PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link filterSync} For filtering packets
+     * @see {@link flushSync} For signaling end-of-stream
+     * @see {@link receive} For async version
+     */
+    receiveSync(): Packet | null;
+    /**
+     * Flush all buffered packets as async generator.
      *
      * Convenient async iteration over remaining packets.
-     * Combines flush and iteration.
+     * Automatically sends flush signal and retrieves buffered packets.
+     * Useful for end-of-stream processing.
      *
-     * @yields {Packet} Remaining packets
+     * @yields {Packet} 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 {@link flush} For array return
+     * @see {@link filter} For filtering packets
+     * @see {@link flush} For signaling end-of-stream
+     * @see {@link flushPacketsSync} For synchronous version
      */
     flushPackets(): AsyncGenerator<Packet>;
     /**
-     * Flush filter as generator synchronously.
+     * Flush all buffered packets as generator synchronously.
      * Synchronous version of flushPackets.
      *
      * Convenient sync iteration over remaining packets.
-     * Combines flush and iteration.
+     * Automatically retrieves buffered packets after flush.
+     * Useful for end-of-stream processing.
      *
-     * @yields {Packet} Remaining packets
+     * @yields {Packet} 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 {@link filterSync} For filtering packets
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link flushPackets} For async version
      */
     flushPacketsSync(): Generator<Packet>;
@@ -436,4 +609,72 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link close} For manual cleanup
      */
     [Symbol.dispose](): void;
+    /**
+     * Send packet to input queue.
+     *
+     * @param packet - Packet to send
+     *
+     * @internal
+     */
+    sendToQueue(packet: Packet): Promise<void>;
+    /**
+     * Receive packet from output queue.
+     *
+     * @returns Packet from queue or null if closed
+     *
+     * @internal
+     */
+    receiveFromQueue(): Promise<Packet | null>;
+    /**
+     * Worker loop for push-based processing.
+     *
+     * @internal
+     */
+    private runWorker;
+    /**
+     * Pipe output to another bitstream filter.
+     *
+     * Starts background worker for packet processing.
+     * Packets flow through: input → this filter → target filter.
+     *
+     * @param target - Target bitstream filter
+     *
+     * @returns 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);
+     * ```
+     */
+    pipeTo(target: BitStreamFilterAPI): Scheduler<Packet>;
+    /**
+     * Pipe output to muxer.
+     *
+     * Terminal stage - writes filtered packets to output file.
+     *
+     * @param output - Muxer to write to
+     *
+     * @param streamIndex - Stream index in output
+     *
+     * @returns Control interface for pipeline
+     *
+     * @example
+     * ```typescript
+     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * const control = filter.pipeTo(output, 0);
+     * await control.send(packet);
+     * ```
+     */
+    pipeTo(output: Muxer, streamIndex: number): SchedulerControl<Packet>;
+    /**
+     * Flush pipeline.
+     *
+     * Closes input queue, waits for worker to finish,
+     * then propagates flush to next component.
+     *
+     * @internal
+     */
+    flushPipeline(): Promise<void>;
 }