node-av 4.0.0 → 5.0.0

package/dist/api/filter.d.ts

@@ -1,6 +1,6 @@
 import { Frame } from '../lib/frame.js';
 import { Scheduler } from './utilities/scheduler.js';
-import type { AVColorRange, AVColorSpace, AVFilterCmdFlag, AVPixelFormat, AVSampleFormat } from '../constants/index.js';
+import type { AVColorRange, AVColorSpace, AVFilterCmdFlag, AVPixelFormat, AVSampleFormat, EOFSignal } from '../constants/index.js';
 import type { FilterContext } from '../lib/filter-context.js';
 import type { ChannelLayout, IDimension, IRational } from '../lib/types.js';
 import type { Encoder } from './encoder.js';
@@ -72,11 +72,6 @@ export declare class FilterAPI implements Disposable {
     /**
      * Create a filter with specified description and configuration.
      *
-     * Creates and allocates filter graph immediately.
-     * Filter configuration is completed on first frame with frame properties.
-     * TimeBase is automatically calculated from first frame based on CFR option.
-     * Hardware frames context is automatically detected from input frames.
-     *
      * Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().
      *
      * @param description - Filter graph description
@@ -163,7 +158,6 @@ export declare class FilterAPI implements Disposable {
      * Output frame rate from filter graph.
      *
      * Returns the frame rate determined by the filter graph output.
-     * Matches FFmpeg CLI's av_buffersink_get_frame_rate() behavior.
      * Returns null if filter is not initialized or frame rate is not set.
      *
      * Direct mapping to av_buffersink_get_frame_rate().
@@ -372,32 +366,33 @@ export declare class FilterAPI implements Disposable {
      */
     getGraphDescription(): string | null;
     /**
-     * Process a frame through the filter.
+     * Send a frame to the filter.
      *
-     * Applies filter operations to input frame.
+     * Sends a frame to the filter for processing.
+     * Does not return filtered frames - use {@link receive} to retrieve frames.
      * On first frame, automatically builds filter graph with frame properties.
-     * May buffer frames internally before producing output.
-     * Hardware frames context is automatically detected from frame.
-     * Returns null if filter is closed and frame is null.
-     *
-     * **Note**: This method receives only ONE frame per call.
-     * A single input frame can produce multiple output frames (e.g., fps filter, deinterlace).
-     * To receive all frames from an input, use {@link processAll} or {@link frames} instead.
+     * A single input frame can produce zero, one, or multiple output frames.
      *
-     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
+     * **Important**: This method only SENDS the frame to the filter.
+     * You must call {@link receive} separately (potentially multiple times) to get filtered frames.
      *
-     * @param frame - Input frame to process (or null to flush)
+     * Direct mapping to av_buffersrc_add_frame().
      *
-     * @returns Filtered frame or null if buffered
+     * @param frame - Input frame to send to filter
      *
      * @throws {Error} If filter could not be initialized
      *
-     * @throws {FFmpegError} If processing fails
+     * @throws {FFmpegError} If sending frame fails
      *
      * @example
      * ```typescript
-     * const output = await filter.process(inputFrame);
-     * if (output) {
+     * // 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();
      * }
@@ -405,71 +400,67 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Process frame - may buffer internally
-     * const output = await filter.process(frame);
-     * if (output) {
-     *   // Got output immediately
-     *   yield output;
+     * 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();
      * }
-     * // For buffered frames, use the frames() async generator
      * ```
      *
-     * @see {@link processAll} For processing multiple output frames
+     * @see {@link receive} For receiving filtered frames
+     * @see {@link processAll} For combined send+receive operation
      * @see {@link frames} For processing frame streams
      * @see {@link flush} For end-of-stream handling
      * @see {@link processSync} For synchronous version
      */
-    process(frame: Frame | null): Promise<Frame | null>;
+    process(frame: Frame): Promise<void>;
     /**
-     * Process a frame through the filter synchronously.
+     * Send a frame to the filter synchronously.
      * Synchronous version of process.
      *
-     * Applies filter operations to input frame.
+     * Sends a frame to the filter for processing.
+     * Does not return filtered frames - use {@link receiveSync} to retrieve frames.
      * On first frame, automatically builds filter graph with frame properties.
-     * May buffer frames internally before producing output.
-     * Hardware frames context is automatically detected from frame.
-     * Returns null if filter is closed and frame is null.
-     *
-     * **Note**: This method receives only ONE frame per call.
-     * A single input frame can produce multiple output frames (e.g., fps filter, deinterlace).
-     * To receive all frames from an input, use {@link processAllSync} or {@link framesSync} instead.
+     * A single input frame can produce zero, one, or multiple output frames.
      *
-     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
+     * **Important**: This method only SENDS the frame to the filter.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get filtered frames.
      *
-     * @param frame - Input frame to process (or null to flush)
+     * Direct mapping to av_buffersrc_add_frame().
      *
-     * @returns Filtered frame or null if buffered
+     * @param frame - Input frame to send to filter
      *
      * @throws {Error} If filter could not be initialized
      *
-     * @throws {FFmpegError} If processing fails
+     * @throws {FFmpegError} If sending frame fails
      *
      * @example
      * ```typescript
-     * const output = filter.processSync(inputFrame);
-     * if (output) {
+     * // 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();
      * }
      * ```
      *
-     * @example
-     * ```typescript
-     * // Process frame - may buffer internally
-     * const output = filter.processSync(frame);
-     * if (output) {
-     *   // Got output immediately
-     *   yield output;
-     * }
-     * // For buffered frames, use the framesSync() generator
-     * ```
-     *
-     * @see {@link processAllSync} For processing multiple output frames
+     * @see {@link receiveSync} For receiving filtered frames
+     * @see {@link processAllSync} For combined send+receive operation
      * @see {@link framesSync} For processing frame streams
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link process} For async version
      */
-    processSync(frame: Frame | null): Frame | null;
+    processSync(frame: Frame): void;
     /**
      * Process a frame through the filter.
      *
@@ -481,7 +472,7 @@ export declare class FilterAPI implements Disposable {
      *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @param frame - Input frame to process (or null to flush)
+     * @param frame - Input frame to process
      *
      * @returns Array of filtered frames (empty if buffered or filter closed)
      *
@@ -525,7 +516,7 @@ export declare class FilterAPI implements Disposable {
      *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @param frame - Input frame to process (or null to flush)
+     * @param frame - Input frame to process
      *
      * @returns Array of filtered frames (empty if buffered or filter closed)
      *
@@ -556,17 +547,22 @@ export declare class FilterAPI implements Disposable {
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link process} For async version
      */
-    processAllSync(frame: Frame | null): Frame[];
+    processAllSync(frame: Frame): Frame[];
     /**
      * Process frame stream through filter.
      *
      * High-level async generator for filtering frame streams.
-     * Automatically handles buffering and flushing.
-     * Frees input frames after processing.
+     * 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()
      *
-     * @param frames - Async generator of input frames
+     * @param frames - Async iterable of frames, single frame, or null to flush
      *
-     * @yields {Frame} Filtered frames
+     * @yields {Frame | null} Filtered frames, followed by null when explicitly flushed
      *
      * @throws {Error} If filter not ready
      *
@@ -574,8 +570,12 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Filter decoded frames
+     * // 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();
      * }
@@ -583,16 +583,23 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Chain filters
-     * const filter1 = FilterAPI.create('scale=640:480', {
-     *   timeBase: video.timeBase
-     * });
-     * const filter2 = FilterAPI.create('rotate=PI/4', {
-     *   timeBase: video.timeBase
-     * });
+     * // 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
+     * ```
      *
-     * for await (const frame of filter2.frames(filter1.frames(input))) {
-     *   // Process filtered frames
+     * @example
+     * ```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();
      * }
      * ```
@@ -601,18 +608,23 @@ export declare class FilterAPI implements Disposable {
      * @see {@link Decoder.frames} For frames source
      * @see {@link framesSync} For sync version
      */
-    frames(frames: AsyncIterable<Frame | null>): AsyncGenerator<Frame | null>;
+    frames(frames: AsyncIterable<Frame | null> | Frame | null): AsyncGenerator<Frame | null>;
     /**
      * Process frame stream through filter synchronously.
      * Synchronous version of frames.
      *
      * High-level sync generator for filtering frame streams.
-     * Automatically handles buffering and flushing.
-     * Frees input frames after processing.
+     * Filter is only flushed when EOF (null) signal is explicitly received.
+     * Primary interface for stream-based filtering.
      *
-     * @param frames - Generator of input frames
+     * **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()
      *
-     * @yields {Frame} Filtered frames
+     * @param frames - Iterable of frames, single frame, or null to flush
+     *
+     * @yields {Frame | null} Filtered frames, followed by null when explicitly flushed
      *
      * @throws {Error} If filter not ready
      *
@@ -620,8 +632,12 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Filter decoded frames
+     * // 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();
      * }
@@ -629,16 +645,23 @@ export declare class FilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Chain filters
-     * const filter1 = FilterAPI.create('scale=640:480', {
-     *   timeBase: video.timeBase
-     * });
-     * const filter2 = FilterAPI.create('rotate=PI/4', {
-     *   timeBase: video.timeBase
-     * });
+     * // Single frame - no automatic flush
+     * for (const frame of filter.framesSync(singleFrame)) {
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * // Filter remains open, buffered frames not flushed
+     * ```
      *
-     * for (const frame of filter2.framesSync(filter1.framesSync(input))) {
-     *   // Process filtered frames
+     * @example
+     * ```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();
      * }
      * ```
@@ -647,7 +670,7 @@ export declare class FilterAPI implements Disposable {
      * @see {@link Decoder.framesSync} For frames source
      * @see {@link frames} For async version
      */
-    framesSync(frames: Generator<Frame | null>): Generator<Frame | null>;
+    framesSync(frames: Iterable<Frame | null> | Frame | null): Generator<Frame | null>;
     /**
      * Flush filter and signal end-of-stream.
      *
@@ -754,57 +777,101 @@ export declare class FilterAPI implements Disposable {
      * Receive buffered frame from filter.
      *
      * Drains frames buffered by the filter.
-     * Call repeatedly until null to get all buffered frames.
-     * Returns null if filter is closed, not initialized, or no frames available.
+     * 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 Buffered frame or null if none available
+     * @returns Buffered frame, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receiving fails
      *
      * @example
      * ```typescript
-     * let frame;
-     * while ((frame = await filter.receive()) !== null) {
+     * // 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();
      * }
      * ```
      *
+     * @example
+     * ```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 {@link process} For frame processing
      * @see {@link flush} For flushing filter
      * @see {@link receiveSync} For synchronous version
+     * @see {@link EOF} For end-of-stream signal
      */
-    receive(): Promise<Frame | null>;
+    receive(): Promise<Frame | EOFSignal | null>;
     /**
      * Receive buffered frame from filter synchronously.
      * Synchronous version of receive.
      *
      * Drains frames buffered by the filter.
-     * Call repeatedly until null to get all buffered frames.
-     * Returns null if filter is closed, not initialized, or no frames available.
+     * 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 Buffered frame or null if none available
+     * @returns Buffered frame, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receiving fails
      *
      * @example
      * ```typescript
-     * let frame;
-     * while ((frame = filter.receiveSync()) !== null) {
+     * // 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();
      * }
      * ```
      *
+     * @example
+     * ```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 {@link processSync} For frame processing
      * @see {@link flushSync} For flushing filter
      * @see {@link receive} For async version
+     * @see {@link EOF} For end-of-stream signal
      */
-    receiveSync(): Frame | null;
+    receiveSync(): Frame | EOFSignal | null;
     /**
      * Send command to filter.
      *
@@ -903,9 +970,20 @@ export declare class FilterAPI implements Disposable {
      */
     private runWorker;
     /**
-     * Send frame to input queue.
+     * Send frame to input queue or flush the pipeline.
+     *
+     * When frame is provided, queues it for filtering.
+     * When null is provided, triggers flush sequence:
+     * - Closes input queue
+     * - Waits for worker completion
+     * - Flushes filter and sends remaining frames to output queue
+     * - Closes output queue
+     * - Waits for pipeTo task completion
+     * - Propagates flush to next component (if any)
      *
-     * @param frame - Frame to send
+     * Used by scheduler system for pipeline control.
+     *
+     * @param frame - Frame to send, or null to flush
      *
      * @internal
      */
@@ -918,14 +996,6 @@ export declare class FilterAPI implements Disposable {
      * @internal
      */
     private receiveFrame;
-    /**
-     * Flush the entire filter pipeline.
-     *
-     * Propagates flush through worker, output queue, and next component.
-     *
-     * @internal
-     */
-    private flushPipeline;
     /**
      * Initialize filter graph from first frame.
      *