node-av 1.0.3 → 1.2.0

package/dist/api/filter.js

@@ -1,247 +1,189 @@
-import { AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, avGetPixFmtName, avGetSampleFmtName, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, FFmpegError, Frame, Filter as LowLevelFilter, FilterGraph as LowLevelFilterGraph, FilterInOut as LowLevelFilterInOut, Stream, } from '../lib/index.js';
+import { AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
+import { AVERROR_EAGAIN, avGetSampleFmtName, avIsHardwarePixelFormat, FFmpegError, Filter, FilterGraph, FilterInOut, Frame } from '../lib/index.js';
 /**
- * High-level filter API for media processing.
+ * High-level filter API for audio and video processing.
  *
- * Provides a simplified interface for FFmpeg's filter system.
- * Supports both simple filter chains and complex filter graphs.
- * Handles automatic format negotiation and buffer management.
+ * Provides simplified interface for applying FFmpeg filters to frames.
+ * Handles filter graph construction, frame buffering, and command control.
+ * Supports both software and hardware-accelerated filtering operations.
+ * Essential component for effects, transformations, and format conversions.
  *
  * @example
  * ```typescript
- * import { FilterAPI, Frame } from 'node-av/api';
+ * import { FilterAPI } from 'node-av/api';
  *
- * // Create a simple video filter from a stream
- * const videoStream = media.video();
- * const filter = await FilterAPI.create('scale=1280:720,format=yuv420p', videoStream);
+ * // Create video filter
+ * const filter = await FilterAPI.create('scale=1280:720', videoInfo);
  *
- * // Process frames
- * const outputFrame = await filter.process(inputFrame);
+ * // Process frame
+ * const output = await filter.process(inputFrame);
+ * if (output) {
+ *   console.log(`Filtered frame: ${output.width}x${output.height}`);
+ *   output.free();
+ * }
  * ```
  *
  * @example
  * ```typescript
- * // Create filter with hardware acceleration
- * const hw = await HardwareContext.auto();
- * const filter = await FilterAPI.create('scale_vt=640:480', videoStream, {
- *   hardware: hw
- * });
+ * // Hardware-accelerated filtering
+ * const hw = HardwareContext.auto();
+ * const filter = await FilterAPI.create(
+ *   'hwupload,scale_cuda=1920:1080,hwdownload',
+ *   videoInfo,
+ *   { hardware: hw }
+ * );
  * ```
+ *
+ * @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;
+    graph = null;
     buffersrcCtx = null;
     buffersinkCtx = null;
     config;
     mediaType;
     initialized = false;
-    needsHardware = false; // Track if this filter REQUIRES hardware
-    hardware; // Store reference for hardware context
-    pendingInit; // For delayed init
+    hardware;
+    description;
+    options;
     /**
-     * Create a new Filter instance.
-     *
-     * The filter is uninitialized until setup with a filter description.
-     * Use the static factory methods for easier creation.
-     *
-     * @param config - Filter configuration
-     * @param hardware - Optional hardware context for late framesContext binding
+     * @param config - Stream configuration
+     * @param description - Filter description string
+     * @param options - Filter options
      * @internal
      */
-    constructor(config, hardware) {
+    constructor(config, description, options) {
         this.config = config;
-        this.hardware = hardware;
+        this.description = description;
+        this.options = options;
+        this.hardware = options.hardware;
         this.mediaType = config.type === 'video' ? AVMEDIA_TYPE_VIDEO : AVMEDIA_TYPE_AUDIO;
-        this.graph = new LowLevelFilterGraph();
     }
     /**
-     * Create a filter from a filter description string.
+     * Create a filter with specified description and configuration.
      *
-     * Accepts either a Stream (from MediaInput/Decoder) or StreamInfo (for raw data).
-     * Automatically sets up buffer source and sink filters.
+     * Constructs filter graph from description string.
+     * Configures input/output buffers and threading.
+     * For video filters, uses lazy initialization to detect hardware frames.
      *
-     * Handles complex filter chains with multiple filters. Automatically detects if ANY
-     * filter in the chain requires hardware acceleration (e.g., scale_vt in
-     * "format=nv12,hwupload,scale_vt=640:480").
+     * Direct mapping to avfilter_graph_parse_ptr() and avfilter_graph_config().
      *
-     * @param description - Filter graph description (e.g., "scale=1280:720" or complex chains)
-     * @param input - Stream or StreamInfo describing the input
-     * @param options - Optional filter options including hardware context
+     * @param description - Filter graph description
+     * @param input - Input stream configuration
+     * @param options - Filter options
+     * @returns Configured filter instance
      *
-     * @returns Promise resolving to configured Filter instance
-     *
-     * @throws {FFmpegError} If filter creation or configuration fails
+     * @throws {Error} If filter creation or configuration fails
+     * @throws {FFmpegError} If graph parsing or config fails
      *
      * @example
      * ```typescript
-     * // Simple filter
-     * const filter = await FilterAPI.create('scale=640:480', videoStream);
+     * // Simple video filter
+     * const filter = await FilterAPI.create('scale=640:480', videoInfo);
+     * ```
      *
-     * // Complex filter chain with hardware
-     * const hw = await HardwareContext.auto();
+     * @example
+     * ```typescript
+     * // Complex filter chain
      * const filter = await FilterAPI.create(
-     *   'format=nv12,hwupload,scale_vt=640:480,hwdownload,format=yuv420p',
-     *   videoStream,
-     *   { hardware: hw }
+     *   'crop=640:480:0:0,rotate=PI/4',
+     *   videoInfo
      * );
+     * ```
      *
-     * // From StreamInfo (for raw data)
-     * const filter = await FilterAPI.create('scale=640:480', {
-     *   type: 'video',
-     *   width: 1920,
-     *   height: 1080,
-     *   pixelFormat: AV_PIX_FMT_YUV420P,
-     *   timeBase: { num: 1, den: 30 }
-     * });
+     * @example
+     * ```typescript
+     * // Audio filter
+     * const filter = await FilterAPI.create(
+     *   'volume=0.5,aecho=0.8:0.9:1000:0.3',
+     *   audioInfo
+     * );
      * ```
+     *
+     * @see {@link process} For frame processing
+     * @see {@link FilterOptions} For configuration options
      */
     static async create(description, input, options = {}) {
         let config;
-        if (input instanceof Stream) {
-            if (input.codecpar.codecType === AVMEDIA_TYPE_VIDEO) {
-                config = {
-                    type: 'video',
-                    width: input.codecpar.width,
-                    height: input.codecpar.height,
-                    pixelFormat: input.codecpar.format,
-                    timeBase: input.timeBase,
-                    frameRate: input.rFrameRate,
-                    sampleAspectRatio: input.codecpar.sampleAspectRatio,
-                };
-            }
-            else if (input.codecpar.codecType === AVMEDIA_TYPE_AUDIO) {
-                config = {
-                    type: 'audio',
-                    sampleRate: input.codecpar.sampleRate,
-                    sampleFormat: input.codecpar.format,
-                    channelLayout: input.codecpar.channelLayout.mask,
-                    timeBase: input.timeBase,
-                };
-            }
-            else {
-                throw new Error('Unsupported codec type');
-            }
-        }
-        else {
-            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,
-                };
-            }
-            else {
-                config = {
-                    type: 'audio',
-                    sampleRate: input.sampleRate,
-                    sampleFormat: input.sampleFormat,
-                    channelLayout: typeof input.channelLayout === 'bigint' ? input.channelLayout : input.channelLayout.mask || 3n,
-                    timeBase: input.timeBase,
-                };
-            }
-        }
-        const filter = new FilterAPI(config, options.hardware);
-        // Parse the entire filter chain to check if ANY filter requires hardware
-        // Split by comma to get individual filters, handle complex chains like:
-        // "format=nv12,hwupload,scale_vt=100:100,hwdownload,format=yuv420p"
-        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);
-        // Check if chain contains hwupload (which creates hw frames context)
-        const hasHwDownload = filterNames.some((name) => name === 'hwdownload');
-        const hasHwUpload = filterNames.some((name) => name === 'hwupload');
-        // Check each filter in the chain
-        let needsHardwareFramesContext = false;
-        let needsHardwareDevice = false;
-        for (const filterName of filterNames) {
-            if (!filterName)
-                continue;
-            const lowLevelFilter = LowLevelFilter.getByName(filterName);
-            if (lowLevelFilter) {
-                // Check if this filter needs hardware
-                if ((lowLevelFilter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
-                    needsHardwareDevice = true;
-                    // Only non-hwupload filters need frames context from decoder
-                    if (filterName !== 'hwupload' && filterName !== 'hwdownload') {
-                        needsHardwareFramesContext = true;
-                    }
-                }
-            }
-        }
-        // If we have hwupload, we don't need hardware frames context from decoder
-        filter.needsHardware = hasHwDownload || (needsHardwareFramesContext && !hasHwUpload);
-        // Validation: Hardware filter MUST have HardwareContext
-        if (needsHardwareDevice && !options.hardware) {
-            throw new Error('Hardware filter in chain requires a hardware context. ' + 'Please provide one via options.hardware');
-        }
-        // Check if we can initialize immediately
-        // Initialize if: (1) we don't need hardware, OR (2) we need hardware AND have framesContext
-        if (!filter.needsHardware || (filter.needsHardware && options.hardware?.framesContext)) {
-            // Can initialize now
-            if (options.hardware?.framesContext && config.type === 'video') {
-                config.hwFramesCtx = options.hardware.framesContext;
-            }
-            await filter.initialize(description, options);
-            filter.initialized = true;
+        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,
+            };
         }
         else {
-            // Delay initialization until first frame (hardware needed but no framesContext yet)
-            filter.pendingInit = { description, options };
-        }
+            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;
     }
     /**
-     * Process a single frame through the filter.
+     * Process a frame through the filter.
      *
-     * Sends a frame through the filter graph and returns the filtered result.
-     * May return null if the filter needs more input frames.
+     * Applies filter operations to input frame.
+     * May buffer frames internally before producing output.
+     * For video, performs lazy initialization on first frame.
      *
-     * @param frame - Input frame to filter
+     * Direct mapping to av_buffersrc_add_frame() and av_buffersink_get_frame().
      *
-     * @returns Promise resolving to filtered frame or null
+     * @param frame - Input frame to process
+     * @returns Filtered frame or null if buffered
      *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputFrame = await filter.process(inputFrame);
-     * if (outputFrame) {
-     *   // Process the filtered frame
+     * const output = await filter.process(inputFrame);
+     * if (output) {
+     *   console.log(`Got filtered frame: pts=${output.pts}`);
+     *   output.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Process and drain
+     * const output = await filter.process(frame);
+     * if (output) yield output;
+     *
+     * // Drain buffered frames
+     * let buffered;
+     * while ((buffered = await filter.receive()) !== null) {
+     *   yield buffered;
      * }
      * ```
+     *
+     * @see {@link receive} For draining buffered frames
+     * @see {@link frames} For stream processing
      */
     async process(frame) {
-        // Check for delayed initialization
-        if (!this.initialized && this.pendingInit) {
-            // Check if hardware frames context became available
-            if (this.hardware?.framesContext && this.config.type === 'video') {
-                this.config.hwFramesCtx = this.hardware.framesContext;
-                // Update pixel format to match hardware frames if using hardware
-                if (this.needsHardware) {
-                    this.config.pixelFormat = this.hardware.getHardwarePixelFormat();
-                }
-                // Now we can initialize
-                await this.initialize(this.pendingInit.description, this.pendingInit.options);
-                this.pendingInit = undefined;
-                this.initialized = true;
-            }
-            else if (this.needsHardware) {
-                throw new Error('Hardware filter requires frames context which is not yet available');
-            }
-            else {
-                // Software filter or hardware not required, can initialize now
-                await this.initialize(this.pendingInit.description, this.pendingInit.options);
-                this.pendingInit = undefined;
-                this.initialized = true;
-            }
+        // Lazy initialization for video filters (detect hardware from first frame)
+        if (!this.initialized && this.config.type === 'video') {
+            await this.initialize(frame);
         }
         if (!this.initialized || !this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Filter not initialized');
@@ -256,7 +198,7 @@ export class FilterAPI {
         if (getRet >= 0) {
             return outputFrame;
         }
-        else if (FFmpegError.is(getRet, AVERROR_EAGAIN)) {
+        else if (getRet === AVERROR_EAGAIN) {
             // Need more input
             outputFrame.free();
             return null;
@@ -268,21 +210,27 @@ export class FilterAPI {
         }
     }
     /**
-     * Process multiple frames through the filter.
+     * Process multiple frames at once.
      *
-     * Batch processing for better performance.
-     * Returns all available output frames.
+     * Processes batch of frames and drains all output.
+     * Useful for filters that buffer multiple frames.
      *
      * @param frames - Array of input frames
+     * @returns Array of all output frames
      *
-     * @returns Promise resolving to array of filtered frames
-     *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If processing fails
      *
      * @example
      * ```typescript
-     * const outputFrames = await filter.processMultiple(inputFrames);
+     * const outputs = await filter.processMultiple([frame1, frame2, frame3]);
+     * for (const output of outputs) {
+     *   console.log(`Output frame: pts=${output.pts}`);
+     *   output.free();
+     * }
      * ```
+     *
+     * @see {@link process} For single frame processing
      */
     async processMultiple(frames) {
         const outputFrames = [];
@@ -302,24 +250,30 @@ export class FilterAPI {
         return outputFrames;
     }
     /**
-     * Receive a filtered frame without sending input.
+     * Receive buffered frame from filter.
      *
-     * Used to drain buffered frames from the filter.
-     * Returns null when no more frames are available.
+     * Drains frames buffered by the filter.
+     * Call repeatedly until null to get all buffered frames.
      *
-     * @returns Promise resolving to filtered frame or null
+     * Direct mapping to av_buffersink_get_frame().
      *
-     * @throws {FFmpegError} If receiving fails
+     * @returns Buffered frame or null if none available
+     *
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If receive fails
      *
      * @example
      * ```typescript
-     * // Drain all buffered frames
-     * while (true) {
-     *   const frame = await filter.receive();
-     *   if (!frame) break;
-     *   // Process frame
+     * // Drain buffered 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
      */
     async receive() {
         if (!this.initialized || !this.buffersinkCtx) {
@@ -333,7 +287,7 @@ export class FilterAPI {
         }
         else {
             frame.free();
-            if (FFmpegError.is(ret, AVERROR_EAGAIN) || FFmpegError.is(ret, AVERROR_EOF)) {
+            if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
                 return null;
             }
             FFmpegError.throwIfError(ret, 'Failed to receive frame from filter');
@@ -341,53 +295,58 @@ export class FilterAPI {
         }
     }
     /**
-     * Flush the filter by sending null frame.
+     * Flush filter and signal end-of-stream.
      *
-     * Signals end of stream to the filter.
-     * Use receive() to get any remaining frames.
+     * Sends null frame to flush buffered data.
+     * Must call receive() to get flushed frames.
      *
-     * @returns Promise resolving when flush is complete
+     * Direct mapping to av_buffersrc_add_frame(NULL).
      *
+     * @throws {Error} If filter not ready
      * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
      * await filter.flush();
      * // Get remaining frames
-     * while (true) {
-     *   const frame = await filter.receive();
-     *   if (!frame) break;
-     *   // Process final frames
+     * let frame;
+     * while ((frame = await filter.receive()) !== null) {
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link flushFrames} For async iteration
+     * @see {@link receive} For draining frames
      */
     async flush() {
         if (!this.initialized || !this.buffersrcCtx) {
             throw new Error('Filter not initialized');
         }
         const ret = await this.buffersrcCtx.buffersrcAddFrame(null);
-        if (ret < 0 && !FFmpegError.is(ret, AVERROR_EOF)) {
+        if (ret < 0 && ret !== AVERROR_EOF) {
             FFmpegError.throwIfError(ret, 'Failed to flush filter');
         }
     }
     /**
-     * Flush filter and yield all remaining frames as a generator.
-     *
-     * More convenient than calling flush() + receive() in a loop.
-     * Automatically sends flush signal and yields all buffered frames.
+     * Flush filter and yield remaining frames.
      *
-     * @returns Async generator of remaining frames
+     * Convenient async generator for flushing.
+     * Combines flush and receive operations.
      *
-     * @throws {Error} If filter is not initialized
+     * @yields Remaining frames from filter
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If flush fails
      *
      * @example
      * ```typescript
-     * // Process all remaining frames with generator
      * for await (const frame of filter.flushFrames()) {
-     *   // Process final frame
-     *   using _ = frame; // Auto cleanup
+     *   console.log(`Flushed frame: pts=${frame.pts}`);
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link flush} For manual flush
+     * @see {@link frames} For complete pipeline
      */
     async *flushFrames() {
         if (!this.initialized || !this.buffersrcCtx) {
@@ -402,26 +361,40 @@ export class FilterAPI {
         }
     }
     /**
-     * Process frames as an async generator.
+     * Process frame stream through filter.
      *
-     * Provides a convenient iterator interface for filtering.
-     * Automatically handles buffering and draining.
-     * Input frames are automatically freed after processing.
+     * High-level async generator for filtering frame streams.
+     * Automatically handles buffering and flushing.
+     * Frees input frames after processing.
      *
-     * IMPORTANT: The yielded frames MUST be freed by the caller!
-     * Input frames are automatically freed after processing.
-     *
-     * @param frames - Async generator of input frames (will be freed automatically)
+     * @param frames - Async generator of input frames
+     * @yields Filtered frames
+     * @throws {Error} If filter not ready
+     * @throws {FFmpegError} If processing fails
      *
-     * @returns Async generator of filtered frames (ownership transferred to caller)
+     * @example
+     * ```typescript
+     * // Filter decoded frames
+     * for await (const frame of filter.frames(decoder.frames(packets))) {
+     *   await encoder.encode(frame);
+     *   frame.free();
+     * }
+     * ```
      *
      * @example
      * ```typescript
-     * for await (const filtered of filter.frames(decoder.frames())) {
-     *   // Process filtered frame
-     *   filtered.free(); // Must free output frame
+     * // Chain filters
+     * const filter1 = await FilterAPI.create('scale=640:480', info);
+     * const filter2 = await FilterAPI.create('rotate=PI/4', info);
+     *
+     * 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) {
@@ -454,103 +427,186 @@ export class FilterAPI {
         }
     }
     /**
-     * Get the filter graph description.
+     * Send command to filter.
+     *
+     * Sends runtime command to specific filter in graph.
+     * Allows dynamic parameter adjustment.
      *
-     * Returns a string representation of the filter graph in DOT format.
-     * Useful for debugging and visualization.
+     * 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
+     * @throws {FFmpegError} If command fails
+     *
+     * @example
+     * ```typescript
+     * // Change volume at runtime
+     * const response = filter.sendCommand('volume', 'volume', '0.5');
+     * console.log(`Volume changed: ${response}`);
+     * ```
+     *
+     * @see {@link queueCommand} For delayed commands
+     */
+    sendCommand(target, cmd, arg, flags) {
+        if (!this.initialized || !this.graph) {
+            throw new Error('Filter not initialized');
+        }
+        const result = this.graph.sendCommand(target, cmd, arg, flags);
+        if (typeof result === 'number') {
+            FFmpegError.throwIfError(result, 'Failed to send filter command');
+        }
+        return result.response;
+    }
+    /**
+     * Queue command for later execution.
+     *
+     * Schedules command to execute at specific timestamp.
+     * Useful for synchronized parameter changes.
+     *
+     * 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
+     *
+     * @example
+     * ```typescript
+     * // Queue volume change at 10 seconds
+     * filter.queueCommand('volume', 'volume', '0.8', 10.0);
+     * ```
+     *
+     * @see {@link sendCommand} For immediate commands
+     */
+    queueCommand(target, cmd, arg, ts, flags) {
+        if (!this.initialized || !this.graph) {
+            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(description);
+     * console.log('Filter graph:', description);
      * ```
      */
     getGraphDescription() {
-        if (!this.initialized) {
+        if (!this.initialized || !this.graph) {
             return null;
         }
         return this.graph.dump();
     }
     /**
-     * Check if the filter is initialized and ready.
+     * Check if filter is ready for processing.
      *
-     * @returns true if the 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 the media type of this filter.
+     * Get media type of filter.
      *
-     * @returns The media type (video or audio)
+     * @returns AVMEDIA_TYPE_VIDEO or AVMEDIA_TYPE_AUDIO
+     *
+     * @example
+     * ```typescript
+     * if (filter.getMediaType() === AVMEDIA_TYPE_VIDEO) {
+     *   console.log('Video filter');
+     * }
+     * ```
      */
     getMediaType() {
         return this.mediaType;
     }
     /**
-     * Get the filter configuration.
+     * Free filter resources.
      *
-     * @returns The filter configuration used to create this instance
-     */
-    getConfig() {
-        return this.config;
-    }
-    /**
-     * Free all filter resources.
-     *
-     * Releases the filter graph and all associated filters.
-     * The filter instance cannot be used after calling this.
+     * Releases filter graph and contexts.
+     * Safe to call multiple times.
      *
      * @example
      * ```typescript
      * filter.free();
-     * // filter is now invalid
      * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
     free() {
         if (this.graph) {
             this.graph.free();
+            this.graph = null;
         }
         this.buffersrcCtx = null;
         this.buffersinkCtx = null;
         this.initialized = false;
     }
     /**
-     * Initialize the filter graph.
+     * Initialize filter graph.
      *
-     * Sets up buffer source, buffer sink, and parses the filter description.
-     * Configures the graph for processing.
+     * Creates and configures filter graph components.
+     * For video, may use hardware frames context from first frame.
      *
-     * @internal
+     * @param firstFrame - First frame for hardware detection (video only)
+     * @throws {Error} If initialization fails
+     * @throws {FFmpegError} If configuration fails
      */
-    async initialize(description, options) {
-        // Allocate graph
+    async initialize(firstFrame) {
+        // Create graph
+        this.graph = new FilterGraph();
         this.graph.alloc();
         // Configure threading
-        if (options.threads !== undefined) {
-            this.graph.nbThreads = options.threads;
+        if (this.options.threads !== undefined) {
+            this.graph.nbThreads = this.options.threads;
         }
         // Configure scaler options
-        if (options.scaleSwsOpts) {
-            this.graph.scaleSwsOpts = options.scaleSwsOpts;
+        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();
         }
-        // Create buffer source
-        this.createBufferSource();
         // Create buffer sink
         this.createBufferSink();
         // Parse filter description
-        this.parseFilterDescription(description);
-        // Set hw_device_ctx on hardware filters if we have hardware context
+        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) {
-                    // Check if this filter needs hardware device context
                     const filter = filterCtx.filter;
                     if (filter && (filter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
-                        // Set hardware device context on this filter
                         filterCtx.hwDeviceCtx = this.hardware.deviceContext;
                     }
                 }
@@ -562,90 +618,103 @@ export class FilterAPI {
         this.initialized = true;
     }
     /**
-     * Create and configure the buffer source filter.
+     * Create buffer source with hardware frames context.
      *
-     * @internal
+     * @param frame - Frame with hw_frames_ctx
+     * @throws {Error} If creation fails
+     * @throws {FFmpegError} If configuration fails
+     */
+    createBufferSourceWithHwFrames(frame) {
+        const filterName = 'buffer';
+        const bufferFilter = Filter.getByName(filterName);
+        if (!bufferFilter) {
+            throw new Error(`${filterName} filter not found`);
+        }
+        // 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');
+    }
+    /**
+     * Create standard buffer source.
+     *
+     * @throws {Error} If creation fails
      */
     createBufferSource() {
         const filterName = this.config.type === 'video' ? 'buffer' : 'abuffer';
-        const bufferFilter = LowLevelFilter.getByName(filterName);
+        const bufferFilter = Filter.getByName(filterName);
         if (!bufferFilter) {
             throw new Error(`${filterName} filter not found`);
         }
-        // Check if we have hardware frames context for video
-        const hasHwFrames = this.config.type === 'video' && this.config.hwFramesCtx;
-        if (hasHwFrames) {
-            // For hardware frames, allocate filter without initialization
-            this.buffersrcCtx = this.graph.allocFilter(bufferFilter, 'in');
-            if (!this.buffersrcCtx) {
-                throw new Error('Failed to allocate buffer source');
+        // 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}`;
             }
-            // Set parameters including hardware frames context (BEFORE init)
-            const videoConfig = this.config;
-            const ret = this.buffersrcCtx.buffersrcParametersSet({
-                width: videoConfig.width,
-                height: videoConfig.height,
-                format: videoConfig.pixelFormat,
-                timeBase: videoConfig.timeBase,
-                frameRate: videoConfig.frameRate,
-                sampleAspectRatio: videoConfig.sampleAspectRatio,
-                hwFramesCtx: videoConfig.hwFramesCtx,
-            });
-            FFmpegError.throwIfError(ret, 'Failed to set buffer source parameters with hardware frames context');
-            // Initialize filter AFTER setting parameters
-            const initRet = this.buffersrcCtx.init(null);
-            FFmpegError.throwIfError(initRet, 'Failed to initialize buffer source');
         }
         else {
-            // Build initialization string based on media type
-            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}`;
-                }
-            }
-            else {
-                const cfg = this.config;
-                // Use sample format name from utilities
-                const sampleFmtName = avGetSampleFmtName(cfg.sampleFormat);
-                // Handle invalid channel layout (0) by using stereo as default
-                const channelLayout = cfg.channelLayout === 0n ? 'stereo' : cfg.channelLayout.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');
-            }
+            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');
         }
     }
     /**
-     * Create and configure the buffer sink filter.
+     * Create buffer sink.
      *
-     * @internal
+     * @throws {Error} If creation fails
      */
     createBufferSink() {
+        if (!this.graph) {
+            throw new Error('Filter graph not initialized');
+        }
         const filterName = this.config.type === 'video' ? 'buffersink' : 'abuffersink';
-        const sinkFilter = LowLevelFilter.getByName(filterName);
+        const sinkFilter = Filter.getByName(filterName);
         if (!sinkFilter) {
             throw new Error(`${filterName} filter not found`);
         }
-        // Create sink filter - no automatic format conversion
         this.buffersinkCtx = this.graph.createFilter(sinkFilter, 'out', null);
         if (!this.buffersinkCtx) {
             throw new Error('Failed to create buffer sink');
         }
     }
     /**
-     * Parse and connect the filter description.
+     * Parse filter description and build graph.
      *
-     * @internal
+     * @param description - Filter description string
+     * @throws {Error} If parsing fails
+     * @throws {FFmpegError} If graph construction fails
      */
     parseFilterDescription(description) {
+        if (!this.graph) {
+            throw new Error('Filter graph not initialized');
+        }
         if (!this.buffersrcCtx || !this.buffersinkCtx) {
             throw new Error('Buffer filters not initialized');
         }
@@ -657,12 +726,12 @@ export class FilterAPI {
             return;
         }
         // Set up inputs and outputs for parsing
-        const outputs = new LowLevelFilterInOut();
+        const outputs = new FilterInOut();
         outputs.alloc();
         outputs.name = 'in';
         outputs.filterCtx = this.buffersrcCtx;
         outputs.padIdx = 0;
-        const inputs = new LowLevelFilterInOut();
+        const inputs = new FilterInOut();
         inputs.alloc();
         inputs.name = 'out';
         inputs.filterCtx = this.buffersinkCtx;
@@ -670,207 +739,64 @@ export class FilterAPI {
         // Parse the filter graph
         const ret = this.graph.parsePtr(description, inputs, outputs);
         FFmpegError.throwIfError(ret, 'Failed to parse filter description');
-        // Clean up FilterInOut structures
+        // Clean up
         inputs.free();
         outputs.free();
     }
     /**
-     * Send a command to a filter in the graph.
-     *
-     * Allows runtime modification of filter parameters without recreating the graph.
-     * Not all filters support commands - check filter documentation.
+     * Check hardware requirements for filters.
      *
-     * @param target - Filter name or "all" to send to all filters
-     * @param cmd - Command name (e.g., "volume", "hue", "brightness")
-     * @param arg - Command argument value
-     * @param flags - Optional command flags
-     *
-     * @returns Command response
-     *
-     * @example
-     * ```typescript
-     * // Change volume dynamically
-     * const response = filter.sendCommand('volume', 'volume', '0.5');
-     * if (response) {
-     *   console.log('Volume changed successfully');
-     * }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Enable/disable all filters at runtime
-     * filter.sendCommand('all', 'enable', 'expr=gte(t,10)');
-     * ```
+     * @param description - Filter description
+     * @param options - Filter options
+     * @throws {Error} If hardware requirements not met
      */
-    sendCommand(target, cmd, arg, flags) {
-        if (!this.initialized) {
-            throw new Error('Filter not initialized');
-        }
-        const result = this.graph.sendCommand(target, cmd, arg, flags);
-        if (typeof result === 'number') {
-            FFmpegError.throwIfError(result, 'Failed to send filter command');
+    checkHardwareRequirements(description, options) {
+        if (this.config.type !== 'video') {
+            return;
         }
-        return result.response;
-    }
-    /**
-     * Queue a command to be executed at a specific time.
-     *
-     * Commands are executed when processing frames with matching timestamps.
-     * Useful for scripted filter changes synchronized with media playback.
-     *
-     * @param target - Filter name or "all" to send to all filters
-     * @param cmd - Command name (e.g., "volume", "hue", "brightness")
-     * @param arg - Command argument value
-     * @param ts - Timestamp when command should execute (in seconds)
-     * @param flags - Optional command flags
-     *
-     * @example
-     * ```typescript
-     * // Schedule volume changes at specific times
-     * filter.queueCommand('volume', 'volume', '0.5', 5.0);  // At 5 seconds
-     * filter.queueCommand('volume', 'volume', '0.8', 10.0); // At 10 seconds
-     * filter.queueCommand('volume', 'volume', '0.2', 15.0); // At 15 seconds
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Fade effect at specific timestamp
-     * filter.queueCommand('fade', 'alpha', '0.5', 30.0);
-     * ```
-     */
-    queueCommand(target, cmd, arg, ts, flags) {
-        if (!this.initialized) {
-            throw new Error('Filter not initialized');
+        // 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`);
+                }
+            }
         }
-        const ret = this.graph.queueCommand(target, cmd, arg, ts, flags);
-        FFmpegError.throwIfError(ret, 'Failed to queue filter command');
     }
     /**
-     * Dispose of the filter.
+     * Dispose of filter.
      *
-     * Implements the Disposable interface for automatic cleanup.
+     * Implements Disposable interface for automatic cleanup.
      * Equivalent to calling free().
      *
      * @example
      * ```typescript
      * {
-     *   using filter = await Filter.create('scale=1280:720', config);
-     *   // ... use filter
-     * } // Automatically freed when leaving scope
+     *   using filter = await FilterAPI.create('scale=640:480', info);
+     *   // Use filter...
+     * } // Automatically freed
      * ```
+     *
+     * @see {@link free} For manual cleanup
      */
     [Symbol.dispose]() {
         this.free();
     }
 }
-/**
- * Common filter presets for convenience.
- *
- * Provides pre-defined filter strings for common operations.
- * Can be used with Filter.create() for quick setup.
- *
- * @example
- * ```typescript
- * const filter = await Filter.create(
- *   FilterPresets.scale(1280, 720),
- *   config
- * );
- * ```
- */
-export class FilterPresets {
-    /**
-     * Scale video to specified dimensions.
-     */
-    static scale(width, height, flags) {
-        const base = `scale=${width}:${height}`;
-        return flags ? `${base}:flags=${flags}` : base;
-    }
-    /**
-     * Crop video to specified dimensions.
-     */
-    static crop(width, height, x = 0, y = 0) {
-        return `crop=${width}:${height}:${x}:${y}`;
-    }
-    /**
-     * Change frame rate.
-     */
-    static fps(fps) {
-        return `fps=${fps}`;
-    }
-    /**
-     * Convert pixel format.
-     * Can accept either format name string or AVPixelFormat enum.
-     */
-    static format(pixelFormat) {
-        const formatName = typeof pixelFormat === 'string' ? pixelFormat : (avGetPixFmtName(pixelFormat) ?? 'yuv420p');
-        return `format=${formatName}`;
-    }
-    /**
-     * Rotate video by angle.
-     */
-    static rotate(angle) {
-        return `rotate=${angle}*PI/180`;
-    }
-    /**
-     * Flip video horizontally.
-     */
-    static hflip() {
-        return 'hflip';
-    }
-    /**
-     * Flip video vertically.
-     */
-    static vflip() {
-        return 'vflip';
-    }
-    /**
-     * Apply fade effect.
-     */
-    static fade(type, start, duration) {
-        return `fade=t=${type}:st=${start}:d=${duration}`;
-    }
-    /**
-     * Overlay one video on another.
-     */
-    static overlay(x = 0, y = 0) {
-        return `overlay=${x}:${y}`;
-    }
-    /**
-     * Adjust audio volume.
-     */
-    static volume(factor) {
-        return `volume=${factor}`;
-    }
-    /**
-     * Convert audio sample format.
-     * Can accept either format name string or AVSampleFormat enum.
-     */
-    static aformat(sampleFormat, sampleRate, channelLayout) {
-        const formatName = typeof sampleFormat === 'string' ? sampleFormat : (avGetSampleFmtName(sampleFormat) ?? 's16');
-        let filter = `aformat=sample_fmts=${formatName}`;
-        if (sampleRate)
-            filter += `:sample_rates=${sampleRate}`;
-        if (channelLayout)
-            filter += `:channel_layouts=${channelLayout}`;
-        return filter;
-    }
-    /**
-     * Change audio tempo without changing pitch.
-     */
-    static atempo(factor) {
-        return `atempo=${factor}`;
-    }
-    /**
-     * Apply audio fade.
-     */
-    static afade(type, start, duration) {
-        return `afade=t=${type}:st=${start}:d=${duration}`;
-    }
-    /**
-     * Mix multiple audio streams.
-     */
-    static amix(inputs = 2, duration = 'longest') {
-        return `amix=inputs=${inputs}:duration=${duration}`;
-    }
-}
 //# sourceMappingURL=filter.js.map