node-av 4.0.0 → 5.0.0

package/dist/api/filter.js

@@ -51,7 +51,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 /* eslint-disable @stylistic/indent-binary-ops */
-import { AV_BUFFERSRC_FLAG_PUSH, AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE } from '../constants/constants.js';
+import { AV_BUFFERSRC_FLAG_PUSH, AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, EOF } from '../constants/constants.js';
 import { FFmpegError } from '../lib/error.js';
 import { FilterGraph } from '../lib/filter-graph.js';
 import { FilterInOut } from '../lib/filter-inout.js';
@@ -138,11 +138,6 @@ export class FilterAPI {
     /**
      * 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
@@ -252,7 +247,6 @@ export class FilterAPI {
      * 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().
@@ -518,32 +512,33 @@ export class FilterAPI {
         return !this.isClosed && this.initialized ? this.graph.dump() : 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.
+     * A single input frame can produce zero, one, or multiple output frames.
      *
-     * **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.
+     * **Important**: This method only SENDS the frame to the filter.
+     * You must call {@link receive} separately (potentially multiple times) to get filtered frames.
      *
-     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
+     * Direct mapping to av_buffersrc_add_frame().
      *
-     * @param frame - Input frame to process (or null to flush)
-     *
-     * @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();
      * }
@@ -551,53 +546,51 @@ export class FilterAPI {
      *
      * @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
      */
     async process(frame) {
         if (this.isClosed) {
-            return null;
+            return;
         }
         // Open filter if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return null;
-            }
-            this.initializePromise ??= this.initialize(frame);
-        }
+        this.initializePromise ??= this.initialize(frame);
         await this.initializePromise;
-        if (!this.initialized) {
-            return null;
-        }
         if (!this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Could not initialize filter contexts');
         }
         // Check for frame property changes (FFmpeg: dropOnChange/allowReinit logic)
-        if (frame && !this.checkFramePropertiesChanged(frame)) {
+        if (!this.checkFramePropertiesChanged(frame)) {
             // Frame dropped due to property change
-            return null;
+            return;
         }
         // If reinitialized, reinitialize now
-        if (!this.initialized && frame) {
+        if (!this.initialized) {
             this.initializePromise = this.initialize(frame);
             await this.initializePromise;
-            if (!this.buffersrcCtx || !this.buffersinkCtx) {
-                throw new Error('Could not reinitialize filter contexts');
-            }
+        }
+        if (!this.buffersrcCtx || !this.buffersinkCtx) {
+            throw new Error('Could not reinitialize filter contexts');
         }
         // Rescale timestamps to filter's timeBase
-        if (frame && this.calculatedTimeBase) {
+        if (this.calculatedTimeBase) {
             const originalTimeBase = frame.timeBase;
             frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
             frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
@@ -606,89 +599,71 @@ export class FilterAPI {
         // Send frame to filter with PUSH flag for immediate processing
         const addRet = await this.buffersrcCtx.buffersrcAddFrame(frame, AV_BUFFERSRC_FLAG_PUSH);
         FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-        // Try to get filtered frame using receive()
-        return await this.receive();
     }
     /**
-     * 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.
+     * A single input frame can produce zero, one, or multiple output frames.
      *
-     * **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.
+     * **Important**: This method only SENDS the frame to the filter.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get filtered frames.
      *
-     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
-     *
-     * @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) {
         if (this.isClosed) {
-            return null;
+            return;
         }
         // Open filter if not already done
         if (!this.initialized) {
-            if (!frame) {
-                return null;
-            }
             this.initializeSync(frame);
         }
-        if (!this.initialized) {
-            return null;
-        }
         if (!this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Could not initialize filter contexts');
         }
         // Check for frame property changes (FFmpeg: dropOnChange/allowReinit logic)
-        if (frame && !this.checkFramePropertiesChanged(frame)) {
+        if (!this.checkFramePropertiesChanged(frame)) {
             // Frame dropped due to property change
-            return null;
+            return;
         }
         // If reinitialized, reinitialize now
-        if (!this.initialized && frame) {
+        if (!this.initialized) {
             this.initializeSync(frame);
-            if (!this.buffersrcCtx || !this.buffersinkCtx) {
-                throw new Error('Could not reinitialize filter contexts');
-            }
+        }
+        if (!this.buffersrcCtx || !this.buffersinkCtx) {
+            throw new Error('Could not reinitialize filter contexts');
         }
         // Rescale timestamps to filter's timeBase
-        if (frame && this.calculatedTimeBase) {
+        if (this.calculatedTimeBase) {
             const originalTimeBase = frame.timeBase;
             frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
             frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
@@ -697,8 +672,6 @@ export class FilterAPI {
         // Send frame to filter with PUSH flag for immediate processing
         const addRet = this.buffersrcCtx.buffersrcAddFrameSync(frame, AV_BUFFERSRC_FLAG_PUSH);
         FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-        // Try to get filtered frame using receiveSync()
-        return this.receiveSync();
     }
     /**
      * Process a frame through the filter.
@@ -711,7 +684,7 @@ export class FilterAPI {
      *
      * 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)
      *
@@ -743,40 +716,19 @@ export class FilterAPI {
      * @see {@link processAllSync} For synchronous version
      */
     async processAll(frame) {
-        if (this.isClosed) {
-            return [];
-        }
-        // Open filter if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return [];
-            }
-            this.initializePromise ??= this.initialize(frame);
-        }
-        await this.initializePromise;
-        if (!this.initialized) {
-            return [];
+        if (frame) {
+            await this.process(frame);
         }
-        if (!this.buffersrcCtx || !this.buffersinkCtx) {
-            throw new Error('Could not initialize filter contexts');
-        }
-        // Rescale timestamps to filter's timeBase
-        if (frame && this.calculatedTimeBase) {
-            const originalTimeBase = frame.timeBase;
-            frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
-            frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
-            frame.timeBase = new Rational(this.calculatedTimeBase.num, this.calculatedTimeBase.den);
+        else {
+            await this.flush();
         }
-        // Send frame to filter with PUSH flag for immediate processing
-        const addRet = await this.buffersrcCtx.buffersrcAddFrame(frame, AV_BUFFERSRC_FLAG_PUSH);
-        FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-        // Receive all available frames using receive()
+        // Receive all available frames
         const frames = [];
         while (true) {
             const outputFrame = await this.receive();
             if (!outputFrame)
-                break;
-            frames.push(outputFrame);
+                break; // Stop on EAGAIN or EOF
+            frames.push(outputFrame); // Only push actual frames
         }
         return frames;
     }
@@ -792,7 +744,7 @@ export class FilterAPI {
      *
      * 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)
      *
@@ -824,36 +776,19 @@ export class FilterAPI {
      * @see {@link process} For async version
      */
     processAllSync(frame) {
-        if (this.isClosed) {
-            return [];
+        if (frame) {
+            this.processSync(frame);
         }
-        // Open filter if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return [];
-            }
-            this.initializeSync(frame);
-        }
-        if (!this.buffersrcCtx || !this.buffersinkCtx) {
-            throw new Error('Could not initialize filter contexts');
-        }
-        // Rescale timestamps to filter's timeBase
-        if (frame && this.calculatedTimeBase) {
-            const originalTimeBase = frame.timeBase;
-            frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
-            frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
-            frame.timeBase = new Rational(this.calculatedTimeBase.num, this.calculatedTimeBase.den);
+        else {
+            this.flushSync();
         }
-        // Send frame to filter with PUSH flag for immediate processing
-        const addRet = this.buffersrcCtx.buffersrcAddFrameSync(frame, AV_BUFFERSRC_FLAG_PUSH);
-        FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-        // Receive all available frames using receiveSync()
+        // Receive all available frames
         const frames = [];
         while (true) {
             const outputFrame = this.receiveSync();
             if (!outputFrame)
-                break;
-            frames.push(outputFrame);
+                break; // Stop on EAGAIN or EOF
+            frames.push(outputFrame); // Only push actual frames
         }
         return frames;
     }
@@ -861,12 +796,17 @@ export class FilterAPI {
      * 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
      *
@@ -874,8 +814,12 @@ export class FilterAPI {
      *
      * @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();
      * }
@@ -883,16 +827,23 @@ export class FilterAPI {
      *
      * @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();
      * }
      * ```
@@ -902,55 +853,39 @@ export class FilterAPI {
      * @see {@link framesSync} For sync version
      */
     async *frames(frames) {
+        const self = this;
+        const processFrame = async function* (frame) {
+            await self.process(frame);
+            while (true) {
+                const filtered = await self.receive();
+                if (!filtered)
+                    break;
+                yield filtered;
+            }
+        }.bind(this);
+        const finalize = async function* () {
+            for await (const remaining of self.flushFrames()) {
+                yield remaining;
+            }
+            yield null;
+        }.bind(this);
+        if (frames === null) {
+            yield* finalize();
+            return;
+        }
+        if (frames instanceof Frame) {
+            yield* processFrame(frames);
+            return;
+        }
         for await (const frame_1 of frames) {
             const env_1 = { stack: [], error: void 0, hasError: false };
             try {
                 const frame = __addDisposableResource(env_1, frame_1, false);
-                // Handle EOF signal
                 if (frame === null) {
-                    // Flush filter
-                    await this.flush();
-                    while (true) {
-                        const remaining = await this.receive();
-                        if (!remaining)
-                            break;
-                        yield remaining;
-                    }
-                    // Signal EOF and stop processing
-                    yield null;
+                    yield* finalize();
                     return;
                 }
-                if (this.isClosed) {
-                    break;
-                }
-                // Open filter if not already done
-                if (!this.initialized) {
-                    this.initializePromise ??= this.initialize(frame);
-                }
-                await this.initializePromise;
-                if (!this.initialized) {
-                    continue;
-                }
-                if (!this.buffersrcCtx || !this.buffersinkCtx) {
-                    throw new Error('Could not initialize filter contexts');
-                }
-                // Rescale timestamps to filter's timeBase
-                if (this.calculatedTimeBase) {
-                    const originalTimeBase = frame.timeBase;
-                    frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
-                    frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
-                    frame.timeBase = new Rational(this.calculatedTimeBase.num, this.calculatedTimeBase.den);
-                }
-                // Send frame to filter
-                const addRet = await this.buffersrcCtx.buffersrcAddFrame(frame, AV_BUFFERSRC_FLAG_PUSH);
-                FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-                // Receive all available frames
-                while (true) {
-                    const buffered = await this.receive();
-                    if (!buffered)
-                        break;
-                    yield buffered;
-                }
+                yield* processFrame(frame);
             }
             catch (e_1) {
                 env_1.error = e_1;
@@ -960,28 +895,23 @@ export class FilterAPI {
                 __disposeResources(env_1);
             }
         }
-        // Flush and get remaining frames (fallback if no null was sent)
-        await this.flush();
-        while (true) {
-            const remaining = await this.receive();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
-        // Signal EOF
-        yield 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.
+     *
+     * **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 - Generator of input frames
+     * @param frames - 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
      *
@@ -989,8 +919,12 @@ export class FilterAPI {
      *
      * @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();
      * }
@@ -998,16 +932,23 @@ export class FilterAPI {
      *
      * @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();
      * }
      * ```
@@ -1017,54 +958,47 @@ export class FilterAPI {
      * @see {@link frames} For async version
      */
     *framesSync(frames) {
+        const self = this;
+        // Helper: Process frame and yield all available filtered frames (filters out EAGAIN nulls)
+        const processFrame = function* (frame) {
+            self.processSync(frame);
+            // Receive ALL filtered frames (filter out null/EAGAIN)
+            while (true) {
+                const filtered = self.receiveSync();
+                if (!filtered)
+                    break; // EAGAIN or EOF - no more frames available
+                yield filtered; // Only yield actual frames, not null
+            }
+        }.bind(this);
+        // Helper: Flush filter and signal EOF
+        const finalize = function* () {
+            for (const remaining of self.flushFramesSync()) {
+                yield remaining; // Only yield actual frames
+            }
+            yield null; // Signal end-of-stream
+        }.bind(this);
+        // Case 1: EOF input -> flush only
+        if (frames === null) {
+            yield* finalize();
+            return;
+        }
+        // Case 2: Single frame
+        if (frames instanceof Frame) {
+            yield* processFrame(frames);
+            // No automatic flush - only flush on explicit EOF
+            return;
+        }
+        // Case 3: Iterable of frames
         for (const frame_2 of frames) {
             const env_2 = { stack: [], error: void 0, hasError: false };
             try {
                 const frame = __addDisposableResource(env_2, frame_2, false);
-                // Handle EOF signal
+                // Check for EOF signal from upstream
                 if (frame === null) {
-                    // Flush filter
-                    this.flushSync();
-                    while (true) {
-                        const remaining = this.receiveSync();
-                        if (!remaining)
-                            break;
-                        yield remaining;
-                    }
-                    // Signal EOF and stop processing
-                    yield null;
+                    yield* finalize();
                     return;
                 }
-                if (this.isClosed) {
-                    break;
-                }
-                // Open filter if not already done
-                if (!this.initialized) {
-                    this.initializeSync(frame);
-                }
-                if (!this.initialized) {
-                    continue;
-                }
-                if (!this.buffersrcCtx || !this.buffersinkCtx) {
-                    throw new Error('Could not initialize filter contexts');
-                }
-                // Rescale timestamps to filter's timeBase
-                if (this.calculatedTimeBase) {
-                    const originalTimeBase = frame.timeBase;
-                    frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
-                    frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
-                    frame.timeBase = new Rational(this.calculatedTimeBase.num, this.calculatedTimeBase.den);
-                }
-                // Send frame to filter
-                const addRet = this.buffersrcCtx.buffersrcAddFrameSync(frame, AV_BUFFERSRC_FLAG_PUSH);
-                FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
-                // Receive all available frames
-                while (true) {
-                    const buffered = this.receiveSync();
-                    if (!buffered)
-                        break;
-                    yield buffered;
-                }
+                yield* processFrame(frame);
             }
             catch (e_2) {
                 env_2.error = e_2;
@@ -1074,16 +1008,7 @@ export class FilterAPI {
                 __disposeResources(env_2);
             }
         }
-        // Flush and get remaining frames (fallback if no null was sent)
-        this.flushSync();
-        while (true) {
-            const remaining = this.receiveSync();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
-        // Signal EOF
-        yield null;
+        // No automatic flush - only flush on explicit EOF
     }
     /**
      * Flush filter and signal end-of-stream.
@@ -1182,10 +1107,12 @@ export class FilterAPI {
     async *flushFrames() {
         // Send flush signal
         await this.flush();
-        // Yield all remaining frames
-        let frame;
-        while ((frame = await this.receive()) !== null) {
-            yield frame;
+        // Yield all remaining frames (filter out null/EAGAIN and EOF)
+        while (true) {
+            const frame = await this.receive();
+            if (!frame)
+                break; // Stop on EAGAIN or EOF
+            yield frame; // Only yield actual frames
         }
     }
     /**
@@ -1215,40 +1142,67 @@ export class FilterAPI {
     *flushFramesSync() {
         // Send flush signal
         this.flushSync();
-        // Yield all remaining frames
-        let frame;
-        while ((frame = this.receiveSync()) !== null) {
-            yield frame;
+        // Yield all remaining frames (filter out null/EAGAIN and EOF)
+        while (true) {
+            const frame = this.receiveSync();
+            if (!frame)
+                break; // Stop on EAGAIN or EOF
+            yield frame; // Only yield actual frames
         }
     }
     /**
      * 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
      */
     async receive() {
-        if (this.isClosed || !this.initialized || !this.buffersinkCtx) {
+        if (this.isClosed) {
+            return EOF;
+        }
+        if (!this.initialized || !this.buffersinkCtx) {
             return null;
         }
         // Reuse frame - but alloc() instead of unref() for buffersink
@@ -1261,10 +1215,15 @@ export class FilterAPI {
             // Clone for user (keeps internal frame for reuse)
             return this.frame.clone();
         }
+        else if (ret === AVERROR_EAGAIN) {
+            // Need more data
+            return null;
+        }
+        else if (ret === AVERROR_EOF) {
+            // End of stream
+            return EOF;
+        }
         else {
-            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-                return null;
-            }
             FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
             return null;
         }
@@ -1274,30 +1233,55 @@ export class FilterAPI {
      * 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() {
-        if (this.isClosed || !this.initialized || !this.buffersinkCtx) {
+        if (this.isClosed) {
+            return EOF;
+        }
+        if (!this.initialized || !this.buffersinkCtx) {
             return null;
         }
         // Reuse frame - but alloc() instead of unref() for buffersink
@@ -1310,10 +1294,13 @@ export class FilterAPI {
             // Clone for user (keeps internal frame for reuse)
             return this.frame.clone();
         }
+        else if (ret === AVERROR_EAGAIN) {
+            return null; // Need more data
+        }
+        else if (ret === AVERROR_EOF) {
+            return EOF; // End of stream
+        }
         else {
-            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-                return null;
-            }
             FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
             return null;
         }
@@ -1463,33 +1450,13 @@ export class FilterAPI {
                     const frame = __addDisposableResource(env_3, await this.inputQueue.receive(), false);
                     if (!frame)
                         break;
-                    // Open filter if not already done
-                    if (!this.initialized) {
-                        this.initializePromise ??= this.initialize(frame);
-                    }
-                    await this.initializePromise;
-                    if (!this.initialized) {
-                        continue;
-                    }
-                    if (!this.buffersrcCtx || !this.buffersinkCtx) {
-                        throw new Error('Could not initialize filter contexts');
-                    }
-                    // Rescale timestamps to filter's timeBase
-                    if (this.calculatedTimeBase) {
-                        const originalTimeBase = frame.timeBase;
-                        frame.pts = avRescaleQ(frame.pts, originalTimeBase, this.calculatedTimeBase);
-                        frame.duration = avRescaleQ(frame.duration, originalTimeBase, this.calculatedTimeBase);
-                        frame.timeBase = new Rational(this.calculatedTimeBase.num, this.calculatedTimeBase.den);
-                    }
-                    // Send frame to filter
-                    const addRet = await this.buffersrcCtx.buffersrcAddFrame(frame, AV_BUFFERSRC_FLAG_PUSH);
-                    FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
+                    await this.process(frame);
                     // Receive all available frames
                     while (!this.outputQueue.isClosed) {
                         const buffered = await this.receive();
                         if (!buffered)
-                            break;
-                        await this.outputQueue.send(buffered);
+                            break; // Stop on EAGAIN or EOF
+                        await this.outputQueue.send(buffered); // Only send actual frames
                     }
                 }
                 catch (e_3) {
@@ -1505,8 +1472,8 @@ export class FilterAPI {
             while (!this.outputQueue.isClosed) {
                 const frame = await this.receive();
                 if (!frame)
-                    break;
-                await this.outputQueue.send(frame);
+                    break; // Stop on EAGAIN or EOF
+                await this.outputQueue.send(frame); // Only send actual frames
             }
         }
         catch {
@@ -1518,14 +1485,54 @@ export class FilterAPI {
         }
     }
     /**
-     * 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)
+     *
+     * Used by scheduler system for pipeline control.
      *
-     * @param frame - Frame to send
+     * @param frame - Frame to send, or null to flush
      *
      * @internal
      */
     async sendToQueue(frame) {
-        await this.inputQueue.send(frame);
+        if (frame) {
+            await this.inputQueue.send(frame);
+        }
+        else {
+            // Close input queue to signal end of stream to worker
+            this.inputQueue.close();
+            // Wait for worker to finish processing all frames (if exists)
+            if (this.workerPromise) {
+                await this.workerPromise;
+            }
+            // Flush filter at end (like FFmpeg does)
+            await this.flush();
+            // Send all flushed frames to output queue
+            while (true) {
+                const frame = await this.receive();
+                if (!frame)
+                    break; // Stop on EAGAIN or EOF
+                await this.outputQueue.send(frame); // Only send actual frames
+            }
+            // Close output queue to signal end of stream to pipeTo() task
+            this.outputQueue.close();
+            // Wait for pipeTo() task to finish processing all frames (if exists)
+            if (this.pipeToPromise) {
+                await this.pipeToPromise;
+            }
+            // Then propagate flush to next component
+            if (this.nextComponent) {
+                await this.nextComponent.sendToQueue(null);
+            }
+        }
     }
     /**
      * Receive frame from output queue.
@@ -1537,40 +1544,6 @@ export class FilterAPI {
     async receiveFrame() {
         return await this.outputQueue.receive();
     }
-    /**
-     * Flush the entire filter pipeline.
-     *
-     * Propagates flush through worker, output queue, and next component.
-     *
-     * @internal
-     */
-    async flushPipeline() {
-        // Close input queue to signal end of stream to worker
-        this.inputQueue.close();
-        // Wait for worker to finish processing all frames (if exists)
-        if (this.workerPromise) {
-            await this.workerPromise;
-        }
-        // Flush filter at end (like FFmpeg does)
-        await this.flush();
-        // Send all flushed frames to output queue
-        while (true) {
-            const frame = await this.receive();
-            if (!frame)
-                break;
-            await this.outputQueue.send(frame);
-        }
-        // Close output queue to signal end of stream to pipeTo() task
-        this.outputQueue.close();
-        // Wait for pipeTo() task to finish processing all frames (if exists)
-        if (this.pipeToPromise) {
-            await this.pipeToPromise;
-        }
-        // Then propagate flush to next component
-        if (this.nextComponent) {
-            await this.nextComponent.flushPipeline();
-        }
-    }
     /**
      * Initialize filter graph from first frame.
      *
@@ -1698,10 +1671,19 @@ export class FilterAPI {
                 `Format: ${this.lastFrameProps.format}->${frame.format}, ` +
                 `Size: ${this.lastFrameProps.width}x${this.lastFrameProps.height}->${frame.width}x${frame.height}`);
         }
-        // Reinit is allowed - reinitialize filtergraph
         // Close current graph and reinitialize
         this.graph.free();
+        // Create new graph
         this.graph = new FilterGraph();
+        this.graph.alloc();
+        // Configure threading
+        if (this.options.threads !== undefined) {
+            this.graph.nbThreads = this.options.threads;
+        }
+        // Configure scaler options
+        if (this.options.scaleSwsOpts) {
+            this.graph.scaleSwsOpts = this.options.scaleSwsOpts;
+        }
         this.buffersrcCtx = null;
         this.buffersinkCtx = null;
         this.initialized = false;