node-av 1.0.2 → 1.1.0

package/dist/api/filter.js

@@ -1,4 +1,17 @@
-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';
+/**
+ * Filter - High-level wrapper for media filtering
+ *
+ * Implements FFmpeg CLI's filter graph behavior with proper hardware context handling.
+ * Uses lazy initialization for hardware inputs: graph is built when first frame arrives
+ * with hw_frames_ctx. For software inputs, initializes immediately.
+ *
+ * Handles filter graph creation, frame processing, and format conversion.
+ * Supports complex filter chains and hardware-accelerated filters.
+ *
+ * @module api/filter
+ */
+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.
  *
@@ -6,11 +19,15 @@ import { AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, avGetPixFmtName, a
  * Supports both simple filter chains and complex filter graphs.
  * Handles automatic format negotiation and buffer management.
  *
+ * The filter graph uses lazy initialization for hardware inputs - it's built when
+ * the first frame arrives with hw_frames_ctx. This matches FFmpeg CLI behavior
+ * for proper hardware context propagation.
+ *
  * @example
  * ```typescript
- * import { FilterAPI, Frame } from 'node-av/api';
+ * import { FilterAPI, Frame } from '@seydx/av/api';
  *
- * // Create a simple video filter from a stream
+ * // Simple video filter from a stream
  * const videoStream = media.video();
  * const filter = await FilterAPI.create('scale=1280:720,format=yuv420p', videoStream);
  *
@@ -20,38 +37,56 @@ import { AVERROR_EAGAIN, AVERROR_EOF, AVFILTER_FLAG_HWDEVICE, avGetPixFmtName, a
  *
  * @example
  * ```typescript
- * // Create filter with hardware acceleration
+ * // Hardware acceleration (decoder -> hw filter -> encoder)
  * const hw = await HardwareContext.auto();
- * const filter = await FilterAPI.create('scale_vt=640:480', videoStream, {
+ * const decoder = await Decoder.create(stream, { hardware: hw });
+ * const filter = await FilterAPI.create('scale_vt=640:480', decoder.getOutputStreamInfo(), {
  *   hardware: hw
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Software decode -> hardware encode pipeline with hwupload
+ * const decoder = await Decoder.create(stream);
+ * const hw = await HardwareContext.auto();
+ * const filter = await FilterAPI.create('format=nv12,hwupload', decoder.getOutputStreamInfo(), {
+ *   hardware: hw  // Required for hwupload to create hw_frames_ctx
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hardware decode -> software encode pipeline with hwdownload
+ * const hw = await HardwareContext.auto();
+ * const decoder = await Decoder.create(stream, { hardware: hw });
+ * const filter = await FilterAPI.create('hwdownload,format=yuv420p', decoder.getOutputStreamInfo());
+ * ```
  */
 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 information from input stream
+     * @param description - Filter graph description
+     * @param options - Filter options including hardware context
      * @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.
@@ -59,9 +94,14 @@ export class FilterAPI {
      * Accepts either a Stream (from MediaInput/Decoder) or StreamInfo (for raw data).
      * Automatically sets up buffer source and sink filters.
      *
-     * 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").
+     * For hardware input formats: Uses lazy initialization, waits for first frame
+     * with hw_frames_ctx before configuring the filter graph.
+     * For software formats: Initializes immediately.
+     *
+     * Hardware context handling:
+     * - hwupload: Requires hardware context, creates its own hw_frames_ctx
+     * - hwdownload: Uses hw_frames_ctx propagated from previous filters
+     * - Other HW filters: Use propagated hw_frames_ctx or hwupload's output
      *
      * @param description - Filter graph description (e.g., "scale=1280:720" or complex chains)
      * @param input - Stream or StreamInfo describing the input
@@ -70,6 +110,7 @@ export class FilterAPI {
      * @returns Promise resolving to configured Filter instance
      *
      * @throws {FFmpegError} If filter creation or configuration fails
+     * @throws {Error} If hardware filter requires hardware context but none provided
      *
      * @example
      * ```typescript
@@ -78,9 +119,10 @@ export class FilterAPI {
      *
      * // Complex filter chain with hardware
      * const hw = await HardwareContext.auto();
+     * const decoder = await Decoder.create(stream, { hardware: hw });
      * const filter = await FilterAPI.create(
-     *   'format=nv12,hwupload,scale_vt=640:480,hwdownload,format=yuv420p',
-     *   videoStream,
+     *   'scale_vt=640:480,hwdownload,format=yuv420p',
+     *   decoder.getOutputStreamInfo(),
      *   { hardware: hw }
      * );
      *
@@ -96,106 +138,37 @@ export class FilterAPI {
      */
     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;
     }
     /**
@@ -204,11 +177,16 @@ export class FilterAPI {
      * Sends a frame through the filter graph and returns the filtered result.
      * May return null if the filter needs more input frames.
      *
+     * On first frame with hw_frames_ctx, initializes the filter graph (lazy initialization).
+     * Subsequent frames are processed normally. FFmpeg automatically propagates
+     * hw_frames_ctx through the filter chain.
+     *
      * @param frame - Input frame to filter
      *
-     * @returns Promise resolving to filtered frame or null
+     * @returns Promise resolving to filtered frame or null if more input needed
      *
      * @throws {FFmpegError} If processing fails
+     * @throws {Error} If filter not initialized or hardware frame required but not provided
      *
      * @example
      * ```typescript
@@ -219,29 +197,9 @@ export class FilterAPI {
      * ```
      */
     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');
@@ -419,7 +377,7 @@ export class FilterAPI {
      * ```typescript
      * for await (const filtered of filter.frames(decoder.frames())) {
      *   // Process filtered frame
-     *   filtered.free(); // Must free output frame
+     *   using _ = filtered; // Auto cleanup with using statement
      * }
      * ```
      */
@@ -453,6 +411,71 @@ export class FilterAPI {
             yield remaining;
         }
     }
+    /**
+     * 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.
+     *
+     * @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)');
+     * ```
+     */
+    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 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
+     * ```
+     */
+    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 the filter graph description.
      *
@@ -468,7 +491,7 @@ export class FilterAPI {
      * ```
      */
     getGraphDescription() {
-        if (!this.initialized) {
+        if (!this.initialized || !this.graph) {
             return null;
         }
         return this.graph.dump();
@@ -489,14 +512,6 @@ export class FilterAPI {
     getMediaType() {
         return this.mediaType;
     }
-    /**
-     * Get the filter configuration.
-     *
-     * @returns The filter configuration used to create this instance
-     */
-    getConfig() {
-        return this.config;
-    }
     /**
      * Free all filter resources.
      *
@@ -512,6 +527,7 @@ export class FilterAPI {
     free() {
         if (this.graph) {
             this.graph.free();
+            this.graph = null;
         }
         this.buffersrcCtx = null;
         this.buffersinkCtx = null;
@@ -523,34 +539,41 @@ export class FilterAPI {
      * Sets up buffer source, buffer sink, and parses the filter description.
      * Configures the graph for processing.
      *
+     * For hardware inputs: Uses hw_frames_ctx from first frame
+     * For software inputs: Initializes without hw_frames_ctx
+     *
      * @internal
      */
-    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,65 +585,69 @@ export class FilterAPI {
         this.initialized = true;
     }
     /**
-     * Create and configure the buffer source filter.
+     * Create buffer source with hardware frames context.
+     *
+     * @internal
+     */
+    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 and configure the buffer source filter without hw_frames_ctx.
      *
      * @internal
      */
     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');
         }
     }
     /**
@@ -629,12 +656,14 @@ export class FilterAPI {
      * @internal
      */
     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');
@@ -646,6 +675,9 @@ 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');
         }
@@ -657,12 +689,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,80 +702,74 @@ 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.
+     * Check if hardware context is required for the filter chain.
      *
-     * Allows runtime modification of filter parameters without recreating the graph.
-     * Not all filters support commands - check filter documentation.
+     * Validates that hardware context is provided when needed:
+     * - hwupload: Always requires hardware context
+     * - Hardware filters (AVFILTER_FLAG_HWDEVICE): Recommend hardware context
+     * - hwdownload: Warns if input is not hardware format
      *
-     * @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)');
-     * ```
+     * @internal
      */
-    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`);
+                }
+            }
+            // // Check if this is hwupload - always needs hardware context
+            // if (filterName === 'hwupload' || filterName === 'hwupload_cuda') {
+            //   if (!options.hardware) {
+            //     throw new Error(`Filter '${filterName}' requires a hardware context`);
+            //   }
+            // } else if (filterName === 'hwdownload') {
+            //   // Check if this is hwdownload - warn if input is not hardware format
+            //   if (this.config.type === 'video' && !avIsHardwarePixelFormat(this.config.pixelFormat)) {
+            //     // prettier-ignore
+            //     console.warn(
+            //       `Warning: 'hwdownload' filter used with software input format (${this.config.pixelFormat}). ` +
+            //       'This will likely fail at runtime. hwdownload expects hardware frames as input. ' +
+            //       'Consider removing hwdownload from your filter chain or ensuring hardware input.',
+            //     );
+            //   }
+            // } else if ((lowLevelFilter.flags & AVFILTER_FLAG_HWDEVICE) !== 0) {
+            //   // Check if this is a hardware filter
+            //   if (!options.hardware) {
+            //     // prettier-ignore
+            //     console.warn(
+            //       `Warning: Hardware filter '${filterName}' used without hardware context. ` +
+            //       "This may work if hw_frames_ctx is propagated from input, but it's recommended " +
+            //       'to pass { hardware: HardwareContext } in filter options.',
+            //     );
+            //   }
+            // }
         }
-        const ret = this.graph.queueCommand(target, cmd, arg, ts, flags);
-        FFmpegError.throwIfError(ret, 'Failed to queue filter command');
     }
     /**
      * Dispose of the filter.
@@ -763,114 +789,4 @@ export class FilterAPI {
         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