node-av 1.3.0 → 2.1.0

package/dist/api/filter.js

@@ -1,5 +1,6 @@
-import { AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
-import { avGetSampleFmtName, avIsHardwarePixelFormat, FFmpegError, Filter, FilterGraph, FilterInOut, Frame } from '../lib/index.js';
+import { AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE } from '../constants/constants.js';
+import { FFmpegError, Filter, FilterGraph, FilterInOut, Frame } from '../lib/index.js';
+import { avGetSampleFmtName } from '../lib/utilities.js';
 /**
  * High-level filter API for audio and video processing.
  *
@@ -12,10 +13,12 @@ import { avGetSampleFmtName, avIsHardwarePixelFormat, FFmpegError, Filter, Filte
  * ```typescript
  * import { FilterAPI } from 'node-av/api';
  *
- * // Create video filter
- * const filter = await FilterAPI.create('scale=1280:720', videoInfo);
+ * // Create video filter - initializes on first frame
+ * const filter = await FilterAPI.create('scale=1280:720', {
+ *   timeBase: video.timeBase,
+ * });
  *
- * // Process frame
+ * // Process frame - first frame configures filter graph
  * const output = await filter.process(inputFrame);
  * if (output) {
  *   console.log(`Filtered frame: ${output.width}x${output.height}`);
@@ -25,54 +28,51 @@ import { avGetSampleFmtName, avIsHardwarePixelFormat, FFmpegError, Filter, Filte
  *
  * @example
  * ```typescript
- * // Hardware-accelerated filtering
- * const hw = HardwareContext.auto();
- * const filter = await FilterAPI.create(
- *   'hwupload,scale_cuda=1920:1080,hwdownload',
- *   videoInfo,
- *   { hardware: hw }
- * );
+ * // Hardware-accelerated filtering - hw context detected from frame
+ * const filter = await FilterAPI.create('hwupload,scale_cuda=1920:1080,hwdownload', {
+ *   timeBase: video.timeBase,
+ * });
+ * // Hardware frames context will be automatically detected from first frame
  * ```
  *
  * @see {@link FilterGraph} For low-level filter graph API
- * @see {@link HardwareContext} For hardware acceleration
  * @see {@link Frame} For frame operations
  */
 export class FilterAPI {
-    graph = null;
+    graph;
+    description;
+    options;
     buffersrcCtx = null;
     buffersinkCtx = null;
-    config;
-    mediaType;
     initialized = false;
-    hardware;
-    description;
-    options;
+    isClosed = false;
     /**
-     * @param config - Stream configuration
+     * @param graph - Filter graph instance
+     *
      * @param description - Filter description string
+     *
      * @param options - Filter options
+     *
      * @internal
      */
-    constructor(config, description, options) {
-        this.config = config;
+    constructor(graph, description, options) {
+        this.graph = graph;
         this.description = description;
         this.options = options;
-        this.hardware = options.hardware;
-        this.mediaType = config.type === 'video' ? AVMEDIA_TYPE_VIDEO : AVMEDIA_TYPE_AUDIO;
     }
     /**
      * Create a filter with specified description and configuration.
      *
-     * Constructs filter graph from description string.
-     * Configures input/output buffers and threading.
-     * For video filters, uses lazy initialization to detect hardware frames.
+     * Creates and allocates filter graph immediately.
+     * Filter configuration is completed on first frame with frame properties.
+     * 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
-     * @param input - Input stream configuration
-     * @param options - Filter options
+     *
+     * @param options - Filter options including required timeBase
+     *
      * @returns Configured filter instance
      *
      * @throws {Error} If filter creation or configuration fails
@@ -82,78 +82,125 @@ export class FilterAPI {
      * @example
      * ```typescript
      * // Simple video filter
-     * const filter = await FilterAPI.create('scale=640:480', videoInfo);
+     * const filter = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
      * ```
      *
      * @example
      * ```typescript
      * // Complex filter chain
-     * const filter = await FilterAPI.create(
-     *   'crop=640:480:0:0,rotate=PI/4',
-     *   videoInfo
-     * );
+     * const filter = await FilterAPI.create('crop=640:480:0:0,rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
      * ```
      *
      * @example
      * ```typescript
      * // Audio filter
-     * const filter = await FilterAPI.create(
-     *   'volume=0.5,aecho=0.8:0.9:1000:0.3',
-     *   audioInfo
-     * );
+     * const filter = await FilterAPI.create('volume=0.5,aecho=0.8:0.9:1000:0.3', {
+     *   timeBase: audio.timeBase
+     * });
      * ```
      *
      * @see {@link process} For frame processing
      * @see {@link FilterOptions} For configuration options
      */
-    static async create(description, input, options = {}) {
-        let config;
-        if (input.type === 'video') {
-            config = {
-                type: 'video',
-                width: input.width,
-                height: input.height,
-                pixelFormat: input.pixelFormat,
-                timeBase: input.timeBase,
-                frameRate: input.frameRate,
-                sampleAspectRatio: input.sampleAspectRatio,
-            };
+    static async create(description, options) {
+        // Create graph
+        const graph = new FilterGraph();
+        graph.alloc();
+        // Configure threading
+        if (options.threads !== undefined) {
+            graph.nbThreads = options.threads;
         }
-        else {
-            config = {
-                type: 'audio',
-                sampleRate: input.sampleRate,
-                sampleFormat: input.sampleFormat,
-                channelLayout: input.channelLayout,
-                timeBase: input.timeBase,
-            };
-        }
-        const filter = new FilterAPI(config, description, options);
-        // Check if any filters in the chain require hardware context
-        if (config.type === 'video') {
-            filter.checkHardwareRequirements(description, options);
-        }
-        // For video filters, always use lazy initialization to properly detect hardware requirements
-        // For audio filters, initialize immediately (no hardware audio processing)
-        if (config.type === 'audio') {
-            await filter.initialize(null);
-        }
-        // For video: wait for first frame to detect if hw_frames_ctx is present
-        return filter;
+        // Configure scaler options
+        if (options.scaleSwsOpts) {
+            graph.scaleSwsOpts = options.scaleSwsOpts;
+        }
+        return new FilterAPI(graph, description, options);
+    }
+    /**
+     * Check if filter is open.
+     *
+     * @example
+     * ```typescript
+     * if (filter.isFilterOpen) {
+     *   const output = await filter.process(frame);
+     * }
+     * ```
+     */
+    get isFilterOpen() {
+        return !this.isClosed;
+    }
+    /**
+     * Check if filter has been initialized.
+     *
+     * Returns true after first frame has been processed and filter graph configured.
+     * Useful for checking if filter has received frame properties.
+     *
+     * @returns true if filter graph has been built from first frame
+     *
+     * @example
+     * ```typescript
+     * if (!filter.isFilterInitialized) {
+     *   console.log('Filter will initialize on first frame');
+     * }
+     * ```
+     */
+    get isFilterInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Check if filter is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (filter.isReady()) {
+     *   const output = await filter.process(frame);
+     * }
+     * ```
+     */
+    isReady() {
+        return this.initialized && this.buffersrcCtx !== null && this.buffersinkCtx !== null && !this.isClosed;
+    }
+    /**
+     * Get filter graph description.
+     *
+     * Returns human-readable graph structure.
+     * Useful for debugging filter chains.
+     *
+     * Direct mapping to avfilter_graph_dump().
+     *
+     * @returns Graph description or null if closed
+     *
+     * @example
+     * ```typescript
+     * const description = filter.getGraphDescription();
+     * console.log('Filter graph:', description);
+     * ```
+     */
+    getGraphDescription() {
+        return !this.isClosed && this.initialized ? this.graph.dump() : null;
     }
     /**
      * Process a frame through the filter.
      *
      * Applies filter operations to input frame.
+     * On first frame, automatically builds filter graph with frame properties.
      * May buffer frames internally before producing output.
-     * For video, performs lazy initialization on first frame.
+     * Hardware frames context is automatically detected from frame.
+     * Returns null if filter is closed and frame is null.
      *
      * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @param frame - Input frame to process
+     * @param frame - Input frame to process (or null to flush)
+     *
      * @returns Filtered frame or null if buffered
      *
-     * @throws {Error} If filter not ready
+     * @throws {Error} If filter is closed with non-null frame
      *
      * @throws {FFmpegError} If processing fails
      *
@@ -168,26 +215,33 @@ export class FilterAPI {
      *
      * @example
      * ```typescript
-     * // Process and drain
+     * // Process frame - may buffer internally
      * const output = await filter.process(frame);
-     * if (output) yield output;
-     *
-     * // Drain buffered frames
-     * let buffered;
-     * while ((buffered = await filter.receive()) !== null) {
-     *   yield buffered;
+     * if (output) {
+     *   // Got output immediately
+     *   yield output;
      * }
+     * // For buffered frames, use the frames() async generator
      * ```
      *
-     * @see {@link receive} For draining buffered frames
-     * @see {@link frames} For stream processing
+     * @see {@link frames} For processing frame streams
+     * @see {@link flush} For end-of-stream handling
      */
     async process(frame) {
-        // Lazy initialization for video filters (detect hardware from first frame)
-        if (!this.initialized && this.config.type === 'video') {
+        if (this.isClosed) {
+            if (!frame) {
+                return null;
+            }
+            throw new Error('Filter is closed');
+        }
+        // Open filter if not already done
+        if (!this.initialized) {
+            if (!frame) {
+                return null;
+            }
             await this.initialize(frame);
         }
-        if (!this.initialized || !this.buffersrcCtx || !this.buffersinkCtx) {
+        if (!this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Filter not initialized');
         }
         // Send frame to filter
@@ -211,6 +265,86 @@ export class FilterAPI {
             return null;
         }
     }
+    /**
+     * Process a frame through the filter synchronously.
+     * Synchronous version of process.
+     *
+     * Applies filter operations to input frame.
+     * 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.
+     *
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
+     *
+     * @param frame - Input frame to process (or null to flush)
+     *
+     * @returns Filtered frame or null if buffered
+     *
+     * @throws {Error} If filter is closed with non-null frame
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * const output = filter.processSync(inputFrame);
+     * if (output) {
+     *   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 process} For async version
+     */
+    processSync(frame) {
+        if (this.isClosed) {
+            if (!frame) {
+                return null;
+            }
+            throw new Error('Filter is closed');
+        }
+        // Open filter if not already done
+        if (!this.initialized) {
+            if (!frame) {
+                return null;
+            }
+            this.initializeSync(frame);
+        }
+        if (!this.buffersrcCtx || !this.buffersinkCtx) {
+            throw new Error('Filter not initialized');
+        }
+        // Send frame to filter
+        const addRet = this.buffersrcCtx.buffersrcAddFrameSync(frame);
+        FFmpegError.throwIfError(addRet, 'Failed to add frame to filter');
+        // Try to get filtered frame
+        const outputFrame = new Frame();
+        outputFrame.alloc();
+        const getRet = this.buffersinkCtx.buffersinkGetFrameSync(outputFrame);
+        if (getRet >= 0) {
+            return outputFrame;
+        }
+        else if (getRet === AVERROR_EAGAIN) {
+            // Need more input
+            outputFrame.free();
+            return null;
+        }
+        else {
+            outputFrame.free();
+            FFmpegError.throwIfError(getRet, 'Failed to get frame from filter');
+            return null;
+        }
+    }
     /**
      * Process multiple frames at once.
      *
@@ -218,6 +352,7 @@ export class FilterAPI {
      * Useful for filters that buffer multiple frames.
      *
      * @param frames - Array of input frames
+     *
      * @returns Array of all output frames
      *
      * @throws {Error} If filter not ready
@@ -253,81 +388,258 @@ export class FilterAPI {
         return outputFrames;
     }
     /**
-     * Receive buffered frame from filter.
+     * Process multiple frames at once synchronously.
+     * Synchronous version of processMultiple.
      *
-     * Drains frames buffered by the filter.
-     * Call repeatedly until null to get all buffered frames.
+     * Processes batch of frames and drains all output.
+     * Useful for filters that buffer multiple frames.
      *
-     * Direct mapping to av_buffersink_get_frame().
+     * @param frames - Array of input frames
      *
-     * @returns Buffered frame or null if none available
+     * @returns Array of all output frames
+     *
+     * @throws {Error} If filter not ready
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * const outputs = filter.processMultipleSync([frame1, frame2, frame3]);
+     * for (const output of outputs) {
+     *   console.log(`Output frame: pts=${output.pts}`);
+     *   output.free();
+     * }
+     * ```
+     *
+     * @see {@link processMultiple} For async version
+     */
+    processMultipleSync(frames) {
+        const outputFrames = [];
+        for (const frame of frames) {
+            const output = this.processSync(frame);
+            if (output) {
+                outputFrames.push(output);
+            }
+            // Drain any additional frames
+            while (true) {
+                const additional = this.receiveSync();
+                if (!additional)
+                    break;
+                outputFrames.push(additional);
+            }
+        }
+        return outputFrames;
+    }
+    /**
+     * Process frame stream through filter.
+     *
+     * High-level async generator for filtering frame streams.
+     * Automatically handles buffering and flushing.
+     * Frees input frames after processing.
+     *
+     * @param frames - Async generator of input frames
+     *
+     * @yields {Frame} Filtered frames
+     *
+     * @throws {Error} If filter not ready
+     *
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * // Filter decoded frames
+     * for await (const frame of filter.frames(decoder.frames(packets))) {
+     *   await encoder.encode(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
+     * const filter2 = await FilterAPI.create('rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
+     *
+     * for await (const frame of filter2.frames(filter1.frames(input))) {
+     *   // Process filtered frames
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link process} For single frame processing
+     * @see {@link flush} For end-of-stream handling
+     */
+    async *frames(frames) {
+        for await (const frame of frames) {
+            try {
+                // Process input frame
+                const output = await this.process(frame);
+                if (output) {
+                    yield output;
+                }
+                // Drain any buffered frames
+                while (true) {
+                    const buffered = await this.receive();
+                    if (!buffered)
+                        break;
+                    yield buffered;
+                }
+            }
+            finally {
+                // Free the input frame after processing
+                frame.free();
+            }
+        }
+        // Flush and get remaining frames
+        await this.flush();
+        while (true) {
+            const remaining = await this.receive();
+            if (!remaining)
+                break;
+            yield remaining;
+        }
+    }
+    /**
+     * 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.
+     *
+     * @param frames - Generator of input frames
+     *
+     * @yields {Frame} Filtered frames
      *
      * @throws {Error} If filter not ready
      *
-     * @throws {FFmpegError} If receive fails
+     * @throws {FFmpegError} If processing fails
+     *
+     * @example
+     * ```typescript
+     * // Filter decoded frames
+     * for (const frame of filter.framesSync(decoder.framesSync(packets))) {
+     *   encoder.encodeSync(frame);
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', {
+     *   timeBase: video.timeBase
+     * });
+     * const filter2 = await FilterAPI.create('rotate=PI/4', {
+     *   timeBase: video.timeBase
+     * });
+     *
+     * for (const frame of filter2.framesSync(filter1.framesSync(input))) {
+     *   // Process filtered frames
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link frames} For async version
+     */
+    *framesSync(frames) {
+        for (const frame of frames) {
+            try {
+                // Process input frame
+                const output = this.processSync(frame);
+                if (output) {
+                    yield output;
+                }
+                // Drain any buffered frames
+                while (true) {
+                    const buffered = this.receiveSync();
+                    if (!buffered)
+                        break;
+                    yield buffered;
+                }
+            }
+            finally {
+                // Free the input frame after processing
+                frame.free();
+            }
+        }
+        // Flush and get remaining frames
+        this.flushSync();
+        while (true) {
+            const remaining = this.receiveSync();
+            if (!remaining)
+                break;
+            yield remaining;
+        }
+    }
+    /**
+     * Flush filter and signal end-of-stream.
+     *
+     * Sends null frame to flush buffered data.
+     * Must call receive() to get flushed frames.
+     * Does nothing if filter is closed or was never initialized.
+     *
+     * Direct mapping to av_buffersrc_add_frame(NULL).
+     *
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * // Drain buffered frames
+     * await filter.flush();
+     * // Get remaining frames
      * let frame;
      * while ((frame = await filter.receive()) !== null) {
-     *   console.log(`Buffered frame: pts=${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link process} For input processing
-     * @see {@link flush} For end-of-stream
+     * @see {@link flushFrames} For async iteration
+     * @see {@link frames} For complete pipeline
      */
-    async receive() {
-        if (!this.initialized || !this.buffersinkCtx) {
-            throw new Error('Filter not initialized');
-        }
-        const frame = new Frame();
-        frame.alloc();
-        const ret = await this.buffersinkCtx.buffersinkGetFrame(frame);
-        if (ret >= 0) {
-            return frame;
+    async flush() {
+        if (this.isClosed || !this.initialized || !this.buffersrcCtx) {
+            return;
         }
-        else {
-            frame.free();
-            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-                return null;
-            }
-            FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
-            return null;
+        // Send flush frame (null)
+        const ret = await this.buffersrcCtx.buffersrcAddFrame(null);
+        if (ret < 0 && ret !== AVERROR_EOF) {
+            FFmpegError.throwIfError(ret, 'Failed to flush filter');
         }
     }
     /**
-     * Flush filter and signal end-of-stream.
+     * Flush filter and signal end-of-stream synchronously.
+     * Synchronous version of flush.
      *
      * Sends null frame to flush buffered data.
-     * Must call receive() to get flushed frames.
+     * Must call receiveSync() to get flushed frames.
+     * Does nothing if filter is closed or was never initialized.
      *
      * Direct mapping to av_buffersrc_add_frame(NULL).
      *
-     * @throws {Error} If filter not ready
-     *
      * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * await filter.flush();
+     * filter.flushSync();
      * // Get remaining frames
      * let frame;
-     * while ((frame = await filter.receive()) !== null) {
+     * while ((frame = filter.receiveSync()) !== null) {
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link flushFrames} For async iteration
-     * @see {@link receive} For draining frames
+     * @see {@link flush} For async version
      */
-    async flush() {
-        if (!this.initialized || !this.buffersrcCtx) {
-            throw new Error('Filter not initialized');
+    flushSync() {
+        if (this.isClosed || !this.initialized || !this.buffersrcCtx) {
+            return;
         }
-        const ret = await this.buffersrcCtx.buffersrcAddFrame(null);
+        // Send flush frame (null)
+        const ret = this.buffersrcCtx.buffersrcAddFrameSync(null);
         if (ret < 0 && ret !== AVERROR_EOF) {
             FFmpegError.throwIfError(ret, 'Failed to flush filter');
         }
@@ -337,9 +649,9 @@ export class FilterAPI {
      *
      * Convenient async generator for flushing.
      * Combines flush and receive operations.
+     * Returns immediately if filter is closed or was never initialized.
      *
-     * @yields Remaining frames from filter
-     * @throws {Error} If filter not ready
+     * @yields {Frame} Remaining frames from filter
      *
      * @throws {FFmpegError} If flush fails
      *
@@ -355,9 +667,6 @@ export class FilterAPI {
      * @see {@link frames} For complete pipeline
      */
     async *flushFrames() {
-        if (!this.initialized || !this.buffersrcCtx) {
-            throw new Error('Filter not initialized');
-        }
         // Send flush signal
         await this.flush();
         // Yield all remaining frames
@@ -367,70 +676,119 @@ export class FilterAPI {
         }
     }
     /**
-     * Process frame stream through filter.
+     * Flush filter and yield remaining frames synchronously.
+     * Synchronous version of flushFrames.
      *
-     * High-level async generator for filtering frame streams.
-     * Automatically handles buffering and flushing.
-     * Frees input frames after processing.
+     * Convenient sync generator for flushing.
+     * Combines flush and receive operations.
+     * Returns immediately if filter is closed or was never initialized.
      *
-     * @param frames - Async generator of input frames
-     * @yields Filtered frames
-     * @throws {Error} If filter not ready
+     * @yields {Frame} Remaining frames from filter
      *
-     * @throws {FFmpegError} If processing fails
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * // Filter decoded frames
-     * for await (const frame of filter.frames(decoder.frames(packets))) {
-     *   await encoder.encode(frame);
+     * for (const frame of filter.flushFramesSync()) {
+     *   console.log(`Flushed frame: pts=${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
+     * @see {@link flushFrames} For async version
+     */
+    *flushFramesSync() {
+        // Send flush signal
+        this.flushSync();
+        // Yield all remaining frames
+        let frame;
+        while ((frame = this.receiveSync()) !== null) {
+            yield frame;
+        }
+    }
+    /**
+     * 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.
+     *
+     * Direct mapping to av_buffersink_get_frame().
+     *
+     * @returns Buffered frame or null if none available
+     *
+     * @throws {FFmpegError} If receiving fails
+     *
      * @example
      * ```typescript
-     * // Chain filters
-     * const filter1 = await FilterAPI.create('scale=640:480', info);
-     * const filter2 = await FilterAPI.create('rotate=PI/4', info);
+     * let frame;
+     * while ((frame = await filter.receive()) !== null) {
+     *   console.log(`Received frame: pts=${frame.pts}`);
+     *   frame.free();
+     * }
+     * ```
+     */
+    async receive() {
+        if (this.isClosed || !this.initialized || !this.buffersinkCtx) {
+            return null;
+        }
+        const frame = new Frame();
+        frame.alloc();
+        const ret = await this.buffersinkCtx.buffersinkGetFrame(frame);
+        if (ret >= 0) {
+            return frame;
+        }
+        else {
+            frame.free();
+            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
+                return null;
+            }
+            FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
+            return null;
+        }
+    }
+    /**
+     * Receive buffered frame from filter synchronously.
+     * Synchronous version of receive.
      *
-     * for await (const frame of filter2.frames(filter1.frames(input))) {
-     *   // Process filtered frames
+     * 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.
+     *
+     * Direct mapping to av_buffersink_get_frame().
+     *
+     * @returns Buffered frame or null if none available
+     *
+     * @throws {FFmpegError} If receiving fails
+     *
+     * @example
+     * ```typescript
+     * let frame;
+     * while ((frame = filter.receiveSync()) !== null) {
+     *   console.log(`Received frame: pts=${frame.pts}`);
      *   frame.free();
      * }
      * ```
      *
-     * @see {@link process} For single frame processing
-     * @see {@link flush} For end-of-stream handling
+     * @see {@link receive} For async version
      */
-    async *frames(frames) {
-        for await (const frame of frames) {
-            try {
-                // Process input frame
-                const output = await this.process(frame);
-                if (output) {
-                    yield output;
-                }
-                // Drain any buffered frames
-                while (true) {
-                    const buffered = await this.receive();
-                    if (!buffered)
-                        break;
-                    yield buffered;
-                }
-            }
-            finally {
-                // Free the input frame after processing
-                frame.free();
-            }
+    receiveSync() {
+        if (this.isClosed || !this.initialized || !this.buffersinkCtx) {
+            return null;
         }
-        // Flush and get remaining frames
-        await this.flush();
-        while (true) {
-            const remaining = await this.receive();
-            if (!remaining)
-                break;
-            yield remaining;
+        const frame = new Frame();
+        frame.alloc();
+        const ret = this.buffersinkCtx.buffersinkGetFrameSync(frame);
+        if (ret >= 0) {
+            return frame;
+        }
+        else {
+            frame.free();
+            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
+                return null;
+            }
+            FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
+            return null;
         }
     }
     /**
@@ -442,9 +800,13 @@ export class FilterAPI {
      * Direct mapping to avfilter_graph_send_command().
      *
      * @param target - Target filter name
+     *
      * @param cmd - Command name
+     *
      * @param arg - Command argument
+     *
      * @param flags - Command flags
+     *
      * @returns Response string from filter
      *
      * @throws {Error} If filter not ready
@@ -461,7 +823,10 @@ export class FilterAPI {
      * @see {@link queueCommand} For delayed commands
      */
     sendCommand(target, cmd, arg, flags) {
-        if (!this.initialized || !this.graph) {
+        if (this.isClosed) {
+            throw new Error('Filter is closed');
+        }
+        if (!this.initialized) {
             throw new Error('Filter not initialized');
         }
         const result = this.graph.sendCommand(target, cmd, arg, flags);
@@ -479,10 +844,15 @@ export class FilterAPI {
      * Direct mapping to avfilter_graph_queue_command().
      *
      * @param target - Target filter name
+     *
      * @param cmd - Command name
+     *
      * @param arg - Command argument
+     *
      * @param ts - Timestamp for execution
+     *
      * @param flags - Command flags
+     *
      * @throws {Error} If filter not ready
      *
      * @throws {FFmpegError} If queue fails
@@ -496,64 +866,15 @@ export class FilterAPI {
      * @see {@link sendCommand} For immediate commands
      */
     queueCommand(target, cmd, arg, ts, flags) {
-        if (!this.initialized || !this.graph) {
+        if (this.isClosed) {
+            throw new Error('Filter is closed');
+        }
+        if (!this.initialized) {
             throw new Error('Filter not initialized');
         }
         const ret = this.graph.queueCommand(target, cmd, arg, ts, flags);
         FFmpegError.throwIfError(ret, 'Failed to queue filter command');
     }
-    /**
-     * Get filter graph description.
-     *
-     * Returns human-readable graph structure.
-     * Useful for debugging filter chains.
-     *
-     * Direct mapping to avfilter_graph_dump().
-     *
-     * @returns Graph description or null if not initialized
-     *
-     * @example
-     * ```typescript
-     * const description = filter.getGraphDescription();
-     * console.log('Filter graph:', description);
-     * ```
-     */
-    getGraphDescription() {
-        if (!this.initialized || !this.graph) {
-            return null;
-        }
-        return this.graph.dump();
-    }
-    /**
-     * Check if filter is ready for processing.
-     *
-     * @returns true if initialized and ready
-     *
-     * @example
-     * ```typescript
-     * if (filter.isReady()) {
-     *   const output = await filter.process(frame);
-     * }
-     * ```
-     */
-    isReady() {
-        return this.initialized && this.buffersrcCtx !== null && this.buffersinkCtx !== null;
-    }
-    /**
-     * Get media type of filter.
-     *
-     * @returns AVMEDIA_TYPE_VIDEO or AVMEDIA_TYPE_AUDIO
-     *
-     * @example
-     * ```typescript
-     * if (filter.getMediaType() === AVMEDIA_TYPE_VIDEO) {
-     *   console.log('Video filter');
-     * }
-     * ```
-     */
-    getMediaType() {
-        return this.mediaType;
-    }
     /**
      * Free filter resources.
      *
@@ -562,27 +883,29 @@ export class FilterAPI {
      *
      * @example
      * ```typescript
-     * filter.free();
+     * filter.close();
      * ```
      *
      * @see {@link Symbol.dispose} For automatic cleanup
      */
-    free() {
-        if (this.graph) {
-            this.graph.free();
-            this.graph = null;
+    close() {
+        if (this.isClosed) {
+            return;
         }
+        this.isClosed = true;
+        this.graph.free();
         this.buffersrcCtx = null;
         this.buffersinkCtx = null;
         this.initialized = false;
     }
     /**
-     * Initialize filter graph.
+     * Initialize filter graph from first frame.
      *
      * Creates and configures filter graph components.
-     * For video, may use hardware frames context from first frame.
+     * Sets buffer source parameters from frame properties.
+     * Automatically configures hardware frames context if present.
      *
-     * @param firstFrame - First frame for hardware detection (video only)
+     * @param frame - First frame to process, provides format and hw context
      *
      * @throws {Error} If initialization fails
      *
@@ -590,38 +913,20 @@ export class FilterAPI {
      *
      * @internal
      */
-    async initialize(firstFrame) {
-        // Create 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;
-        }
-        // Create buffer source with hw_frames_ctx if needed
-        if (firstFrame?.hwFramesCtx && this.config.type === 'video') {
-            this.createBufferSourceWithHwFrames(firstFrame);
-        }
-        else {
-            this.createBufferSource();
-        }
+    async initialize(frame) {
+        // Create buffer source
+        this.createBufferSource(frame);
         // Create buffer sink
-        this.createBufferSink();
+        this.createBufferSink(frame);
         // Parse filter description
         this.parseFilterDescription(this.description);
         // Set hw_device_ctx on hardware filters
-        if (this.hardware?.deviceContext) {
-            const filters = this.graph.filters;
-            if (filters) {
-                for (const filterCtx of filters) {
-                    const filter = filterCtx.filter;
-                    if (filter && (filter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
-                        filterCtx.hwDeviceCtx = this.hardware.deviceContext;
-                    }
+        const filters = this.graph.filters;
+        if (filters) {
+            for (const filterCtx of filters) {
+                const filter = filterCtx.filter;
+                if (filter && (filter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
+                    filterCtx.hwDeviceCtx = frame.hwFramesCtx?.deviceRef ?? this.options.hardware?.deviceContext ?? null;
                 }
             }
         }
@@ -631,91 +936,111 @@ export class FilterAPI {
         this.initialized = true;
     }
     /**
-     * Create buffer source with hardware frames context.
+     * Initialize filter graph from first frame synchronously.
+     * Synchronous version of initialize.
      *
-     * @param frame - Frame with hw_frames_ctx
+     * Creates and configures filter graph components.
+     * Sets buffer source parameters from frame properties.
+     * Automatically configures hardware frames context if present.
      *
-     * @throws {Error} If creation fails
+     * @param frame - First frame to process, provides format and hw context
+     *
+     * @throws {Error} If initialization fails
      *
      * @throws {FFmpegError} If configuration fails
      *
      * @internal
+     *
+     * @see {@link initialize} For async version
      */
-    createBufferSourceWithHwFrames(frame) {
-        const filterName = 'buffer';
-        const bufferFilter = Filter.getByName(filterName);
-        if (!bufferFilter) {
-            throw new Error(`${filterName} filter not found`);
+    initializeSync(frame) {
+        // Create buffer source
+        this.createBufferSource(frame);
+        // Create buffer sink
+        this.createBufferSink(frame);
+        // Parse filter description
+        this.parseFilterDescription(this.description);
+        // Set hw_device_ctx on hardware filters
+        const filters = this.graph.filters;
+        if (filters) {
+            for (const filterCtx of filters) {
+                const filter = filterCtx.filter;
+                if (filter && (filter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
+                    filterCtx.hwDeviceCtx = frame.hwFramesCtx?.deviceRef ?? this.options.hardware?.deviceContext ?? null;
+                }
+            }
         }
-        // Allocate filter without args
-        this.buffersrcCtx = this.graph.allocFilter(bufferFilter, 'in');
-        if (!this.buffersrcCtx) {
-            throw new Error('Failed to allocate buffer source');
-        }
-        // Set parameters including hw_frames_ctx
-        const cfg = this.config;
-        const ret = this.buffersrcCtx.buffersrcParametersSet({
-            width: cfg.width,
-            height: cfg.height,
-            format: cfg.pixelFormat,
-            timeBase: cfg.timeBase,
-            frameRate: cfg.frameRate,
-            sampleAspectRatio: cfg.sampleAspectRatio,
-            hwFramesCtx: frame.hwFramesCtx ?? undefined,
-        });
-        FFmpegError.throwIfError(ret, 'Failed to set buffer source parameters');
-        // Initialize filter
-        const initRet = this.buffersrcCtx.init(null);
-        FFmpegError.throwIfError(initRet, 'Failed to initialize buffer source');
+        // Configure the graph
+        const ret = this.graph.configSync();
+        FFmpegError.throwIfError(ret, 'Failed to configure filter graph');
+        this.initialized = true;
     }
     /**
-     * Create standard buffer source.
+     * Create buffer source with frame parameters.
+     *
+     * Configures buffer source with frame properties including hardware context.
+     * Automatically detects video/audio and sets appropriate parameters.
+     *
+     * @param frame - Frame providing format, dimensions, and hw_frames_ctx
      *
      * @throws {Error} If creation fails
      *
+     * @throws {FFmpegError} If configuration fails
+     *
      * @internal
      */
-    createBufferSource() {
-        const filterName = this.config.type === 'video' ? 'buffer' : 'abuffer';
+    createBufferSource(frame) {
+        const filterName = frame.isVideo() ? 'buffer' : 'abuffer';
         const bufferFilter = Filter.getByName(filterName);
         if (!bufferFilter) {
             throw new Error(`${filterName} filter not found`);
         }
-        // Build args string
-        let args;
-        if (this.config.type === 'video') {
-            const cfg = this.config;
-            args = `video_size=${cfg.width}x${cfg.height}:pix_fmt=${cfg.pixelFormat}:time_base=${cfg.timeBase.num}/${cfg.timeBase.den}`;
-            if (cfg.frameRate) {
-                args += `:frame_rate=${cfg.frameRate.num}/${cfg.frameRate.den}`;
-            }
-            if (cfg.sampleAspectRatio) {
-                args += `:pixel_aspect=${cfg.sampleAspectRatio.num}/${cfg.sampleAspectRatio.den}`;
+        // For audio, create with args. For video, use allocFilter + buffersrcParametersSet
+        if (frame.isVideo()) {
+            // Allocate filter without args
+            this.buffersrcCtx = this.graph.allocFilter(bufferFilter, 'in');
+            if (!this.buffersrcCtx) {
+                throw new Error('Failed to allocate buffer source');
             }
+            const ret = this.buffersrcCtx.buffersrcParametersSet({
+                width: frame.width,
+                height: frame.height,
+                format: frame.format,
+                timeBase: this.options.timeBase,
+                frameRate: this.options.frameRate ?? frame.timeBase,
+                sampleAspectRatio: frame.sampleAspectRatio,
+                colorRange: frame.colorRange,
+                colorSpace: frame.colorSpace,
+                hwFramesCtx: frame.hwFramesCtx,
+            });
+            FFmpegError.throwIfError(ret, 'Failed to set buffer source parameters');
+            // Initialize filter
+            const initRet = this.buffersrcCtx.init(null);
+            FFmpegError.throwIfError(initRet, 'Failed to initialize buffer source');
         }
         else {
-            const cfg = this.config;
-            const sampleFmtName = avGetSampleFmtName(cfg.sampleFormat);
-            const channelLayout = cfg.channelLayout.mask === 0n ? 'stereo' : cfg.channelLayout.mask.toString();
-            args = `sample_rate=${cfg.sampleRate}:sample_fmt=${sampleFmtName}:channel_layout=${channelLayout}:time_base=${cfg.timeBase.num}/${cfg.timeBase.den}`;
-        }
-        this.buffersrcCtx = this.graph.createFilter(bufferFilter, 'in', args);
-        if (!this.buffersrcCtx) {
-            throw new Error('Failed to create buffer source');
+            // For audio, create with args string
+            const formatName = avGetSampleFmtName(frame.format);
+            const channelLayout = frame.channelLayout.mask === 0n ? 'stereo' : frame.channelLayout.mask.toString();
+            // eslint-disable-next-line @stylistic/max-len
+            const args = `time_base=${this.options.timeBase.num}/${this.options.timeBase.den}:sample_rate=${frame.sampleRate}:sample_fmt=${formatName}:channel_layout=${channelLayout}`;
+            this.buffersrcCtx = this.graph.createFilter(bufferFilter, 'in', args);
+            if (!this.buffersrcCtx) {
+                throw new Error('Failed to create audio buffer source');
+            }
         }
     }
     /**
      * Create buffer sink.
      *
+     * @param frame - Frame
+     *
      * @throws {Error} If creation fails
      *
      * @internal
      */
-    createBufferSink() {
-        if (!this.graph) {
-            throw new Error('Filter graph not initialized');
-        }
-        const filterName = this.config.type === 'video' ? 'buffersink' : 'abuffersink';
+    createBufferSink(frame) {
+        const filterName = frame.isVideo() ? 'buffersink' : 'abuffersink';
         const sinkFilter = Filter.getByName(filterName);
         if (!sinkFilter) {
             throw new Error(`${filterName} filter not found`);
@@ -737,9 +1062,6 @@ export class FilterAPI {
      * @internal
      */
     parseFilterDescription(description) {
-        if (!this.graph) {
-            throw new Error('Filter graph not initialized');
-        }
         if (!this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Buffer filters not initialized');
         }
@@ -768,63 +1090,24 @@ export class FilterAPI {
         inputs.free();
         outputs.free();
     }
-    /**
-     * Check hardware requirements for filters.
-     *
-     * @param description - Filter description
-     * @param options - Filter options
-     *
-     * @throws {Error} If hardware requirements not met
-     *
-     * @internal
-     */
-    checkHardwareRequirements(description, options) {
-        if (this.config.type !== 'video') {
-            return;
-        }
-        // Parse filter names from description
-        const filterNames = description
-            .split(',')
-            .map((f) => {
-            // Extract filter name (before = or : or whitespace)
-            const match = /^([a-zA-Z0-9_]+)/.exec(f.trim());
-            return match ? match[1] : null;
-        })
-            .filter(Boolean);
-        for (const filterName of filterNames) {
-            const lowLevelFilter = Filter.getByName(filterName);
-            if (!lowLevelFilter) {
-                // Filter will be validated later during graph parsing
-                continue;
-            }
-            if (!options.hardware) {
-                if (filterName === 'hwupload' || filterName === 'hwupload_cuda' || (lowLevelFilter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
-                    throw new Error(`Filter '${filterName}' requires a hardware context`);
-                }
-                else if (filterName === 'hwdownload' && !avIsHardwarePixelFormat(this.config.pixelFormat)) {
-                    throw new Error(`Pixel Format '${this.config.pixelFormat}' is not hardware compatible`);
-                }
-            }
-        }
-    }
     /**
      * Dispose of filter.
      *
      * Implements Disposable interface for automatic cleanup.
-     * Equivalent to calling free().
+     * Equivalent to calling close().
      *
      * @example
      * ```typescript
      * {
-     *   using filter = await FilterAPI.create('scale=640:480', info);
+     *   using filter = await FilterAPI.create('scale=640:480', { ... });
      *   // Use filter...
      * } // Automatically freed
      * ```
      *
-     * @see {@link free} For manual cleanup
+     * @see {@link close} For manual cleanup
      */
     [Symbol.dispose]() {
-        this.free();
+        this.close();
     }
 }
 //# sourceMappingURL=filter.js.map