node-av 1.1.0 → 1.2.0

package/dist/api/filter-presets.d.ts

@@ -1,18 +1,17 @@
-/**
- * FilterPresets - Pre-defined filter configurations
- *
- * Provides convenient filter string builders for common operations.
- * Includes both software and hardware-accelerated filter presets.
- *
- * Simplifies filter creation with type-safe parameter handling.
- * Supports platform-specific hardware acceleration capabilities.
- *
- * @module api/filter-presets
- */
 import type { AVHWDeviceType, AVPixelFormat, AVSampleFormat } from '../constants/constants.js';
 /**
  * Hardware filter capabilities for different platforms.
  * Maps hardware types to their supported filter operations.
+ * Each capability indicates whether a specific filter operation is supported
+ * by the hardware acceleration type.
+ *
+ * Support varies significantly between hardware types:
+ * - CUDA: Comprehensive filter support with NPP integration
+ * - VAAPI: Good Linux support with Intel/AMD GPUs
+ * - QSV: Intel Quick Sync with basic filtering
+ * - VideoToolbox: macOS/iOS with CoreImage filters
+ * - Vulkan: Cross-platform with growing filter support
+ * - OpenCL: Cross-platform compute-based filtering
  */
 export interface HardwareFilterSupport {
     scale: boolean;
@@ -31,286 +30,883 @@ export interface HardwareFilterSupport {
 }
 /**
  * Base class for filter preset implementations.
- * Provides common filter building methods that can be overridden.
+ * Provides common filter building methods that can be overridden by hardware-specific implementations.
+ *
+ * This class defines the standard filter operations available in FFmpeg,
+ * with each method returning a filter string that can be used in a filter graph.
+ * Hardware-specific implementations may override these methods to use optimized
+ * hardware filters instead of software implementations.
+ *
+ * @example
+ * ```typescript
+ * class CustomPresets extends FilterPresetBase {
+ *   override scale(width: number, height: number): string | null {
+ *     return `custom_scale=${width}:${height}`;
+ *   }
+ * }
+ * ```
  */
 export declare abstract class FilterPresetBase {
     /**
-     * Scale video to specified dimensions.
+     * Creates a scale filter string.
+     *
+     * @param width - Target width in pixels
+     * @param height - Target height in pixels
+     * @param options - Additional scaling options (e.g., flags for algorithm)
      * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#scale | FFmpeg scale filter}
      */
     scale(width: number, height: number, options?: Record<string, any>): string | null;
     /**
-     * Crop video to specified dimensions.
+     * Creates a crop filter string.
+     *
+     * @param width - Width of the cropped area
+     * @param height - Height of the cropped area
+     * @param x - X coordinate of top-left corner (default: 0)
+     * @param y - Y coordinate of top-left corner (default: 0)
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#crop | FFmpeg crop filter}
      */
     crop(width: number, height: number, x?: number, y?: number): string | null;
     /**
-     * Change frame rate.
+     * Creates an FPS filter string to change frame rate.
+     *
+     * @param fps - Target frames per second
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#fps | FFmpeg fps filter}
      */
     fps(fps: number): string | null;
     /**
-     * Convert pixel format.
-     * Can accept a single format or an array of formats for fallback.
-     * Multiple formats will create a chain: format=fmt1,format=fmt2,...
+     * Creates a format filter string to convert pixel format.
+     *
+     * @param pixelFormat - Target pixel format(s) - can be string, AVPixelFormat enum, or array
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Single format
+     * presets.format('yuv420p');
+     * presets.format(AV_PIX_FMT_YUV420P);
+     *
+     * // Multiple formats (creates a chain)
+     * presets.format(['yuv420p', 'rgb24']);
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#format | FFmpeg format filter}
      */
     format(pixelFormat: string | AVPixelFormat | (string | AVPixelFormat)[]): string | null;
     /**
-     * Rotate video by angle.
+     * Creates a rotate filter string.
+     *
+     * @param angle - Rotation angle in degrees
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#rotate | FFmpeg rotate filter}
      */
     rotate(angle: number): string | null;
     /**
-     * Flip video horizontally.
+     * Creates a horizontal flip filter string.
+     *
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hflip | FFmpeg hflip filter}
      */
     hflip(): string | null;
     /**
-     * Flip video vertically.
+     * Creates a vertical flip filter string.
+     *
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#vflip | FFmpeg vflip filter}
      */
     vflip(): string | null;
     /**
-     * Apply fade effect.
+     * Creates a fade filter string for video.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#fade | FFmpeg fade filter}
      */
     fade(type: 'in' | 'out', start: number, duration: number): string | null;
     /**
-     * Overlay one video on another.
+     * Creates an overlay filter string to composite two video streams.
+     *
+     * @param x - X position for overlay (default: 0)
+     * @param y - Y position for overlay (default: 0)
+     * @param options - Additional overlay options
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Basic overlay at position
+     * presets.overlay(100, 50);
+     *
+     * // With additional options
+     * presets.overlay(0, 0, { format: 'yuv420' });
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#overlay | FFmpeg overlay filter}
      */
     overlay(x?: number, y?: number, options?: Record<string, string>): string | null;
     /**
-     * Adjust audio volume.
+     * Creates a volume filter string for audio.
+     *
+     * @param factor - Volume multiplication factor (1.0 = unchanged, 2.0 = double)
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#volume | FFmpeg volume filter}
      */
     volume(factor: number): string | null;
     /**
-     * Convert audio sample format.
+     * Creates an audio format filter string.
+     *
+     * @param sampleFormat - Target sample format (e.g., 's16', 'fltp')
+     * @param sampleRate - Target sample rate in Hz (optional)
+     * @param channelLayout - Target channel layout (optional)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Change sample format only
+     * presets.aformat('s16');
+     *
+     * // Change format and sample rate
+     * presets.aformat('fltp', 48000);
+     *
+     * // Full conversion
+     * presets.aformat('s16', 44100, 'stereo');
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#aformat | FFmpeg aformat filter}
      */
     aformat(sampleFormat: string | AVSampleFormat, sampleRate?: number, channelLayout?: string): string | null;
     /**
-     * Change audio tempo without changing pitch.
+     * Creates an atempo filter string to change audio playback speed.
+     * Factor must be between 0.5 and 2.0. For larger changes, chain multiple atempo filters.
+     *
+     * @param factor - Tempo factor (0.5 = half speed, 2.0 = double speed)
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#atempo | FFmpeg atempo filter}
      */
     atempo(factor: number): string | null;
     /**
-     * Apply audio fade.
+     * Creates an audio fade filter string.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#afade | FFmpeg afade filter}
      */
     afade(type: 'in' | 'out', start: number, duration: number): string | null;
     /**
-     * Mix multiple audio streams.
+     * Creates an amix filter string to mix multiple audio streams.
+     *
+     * @param inputs - Number of input streams to mix (default: 2)
+     * @param duration - How to determine output duration (default: 'longest')
+     * @returns Filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#amix | FFmpeg amix filter}
      */
     amix(inputs?: number, duration?: 'first' | 'longest' | 'shortest'): string | null;
 }
 /**
  * Filter chain builder for composing multiple filters.
- * Allows fluent API for building complex filter graphs.
+ * Allows fluent API for building complex filter graphs by chaining filter operations.
+ *
+ * @example
+ * ```typescript
+ * const chain = new FilterChain()
+ *   .add('scale=1920:1080')
+ *   .add('fps=30')
+ *   .custom('rotate=45*PI/180')
+ *   .build();
+ * // Result: "scale=1920:1080,fps=30,rotate=45*PI/180"
+ * ```
  */
 export declare class FilterChain {
     private filters;
     /**
-     * Add a filter to the chain.
-     * @param filter - Filter string or null/undefined (will be skipped)
+     * Adds a filter to the chain.
+     *
+     * @param filter - Filter string to add (ignored if null/undefined)
+     * @returns This instance for chaining
      */
     add(filter: string | null | undefined): this;
     /**
-     * Add a custom filter string.
+     * Adds a custom filter string to the chain.
+     *
+     * @param filter - Custom filter string
+     * @returns This instance for chaining
      */
     custom(filter: string): this;
     /**
-     * Build the filter chain string.
+     * Builds the final filter string.
+     *
      * @param separator - Separator between filters (default: ',')
+     * @returns Combined filter string
      */
     build(separator?: string): string;
     /**
-     * Get the filter array.
+     * Returns the filters as an array.
+     *
+     * @returns Array of filter strings
      */
     toArray(): string[];
 }
 /**
  * Base chain builder with common filter methods.
+ * Provides a fluent API for building filter chains using preset methods.
+ *
  * @template T The preset type this builder uses
+ *
+ * @example
+ * ```typescript
+ * const chain = new ChainBuilderBase(presets)
+ *   .scale(1920, 1080)
+ *   .fps(30)
+ *   .fade('in', 0, 2)
+ *   .build();
+ * ```
  */
 export declare abstract class ChainBuilderBase<T extends FilterPresetBase> extends FilterChain {
     protected readonly presets: T;
+    /**
+     * @param presets - The filter presets to use
+     * @internal
+     */
     constructor(presets: T);
+    /**
+     * Adds a scale filter to the chain.
+     *
+     * @param width - Target width
+     * @param height - Target height
+     * @param options - Additional scaling options
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.scale}
+     */
     scale(width: number, height: number, options?: Record<string, any>): this;
+    /**
+     * Adds a crop filter to the chain.
+     *
+     * @param width - Crop width
+     * @param height - Crop height
+     * @param x - X position (default: 0)
+     * @param y - Y position (default: 0)
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.crop}
+     */
     crop(width: number, height: number, x?: number, y?: number): this;
+    /**
+     * Adds an FPS filter to the chain.
+     *
+     * @param fps - Target frame rate
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.fps}
+     */
     fps(fps: number): this;
+    /**
+     * Adds a format filter to the chain.
+     *
+     * @param pixelFormat - Target pixel format(s)
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.format}
+     */
     format(pixelFormat: string | AVPixelFormat | (string | AVPixelFormat)[]): this;
+    /**
+     * Adds a rotate filter to the chain.
+     *
+     * @param angle - Rotation angle in degrees
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.rotate}
+     */
     rotate(angle: number): this;
+    /**
+     * Adds a horizontal flip filter to the chain.
+     *
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.hflip}
+     */
     hflip(): this;
+    /**
+     * Adds a vertical flip filter to the chain.
+     *
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.vflip}
+     */
     vflip(): this;
+    /**
+     * Adds a fade filter to the chain.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.fade}
+     */
     fade(type: 'in' | 'out', start: number, duration: number): this;
+    /**
+     * Adds an overlay filter to the chain.
+     *
+     * @param x - X position (default: 0)
+     * @param y - Y position (default: 0)
+     * @param options - Additional overlay options
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.overlay}
+     */
     overlay(x?: number, y?: number, options?: Record<string, string>): this;
+    /**
+     * Adds a volume filter to the chain.
+     *
+     * @param factor - Volume factor
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.volume}
+     */
     volume(factor: number): this;
+    /**
+     * Adds an audio format filter to the chain.
+     *
+     * @param sampleFormat - Target sample format
+     * @param sampleRate - Target sample rate (optional)
+     * @param channelLayout - Target channel layout (optional)
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.aformat}
+     */
     aformat(sampleFormat: string | AVSampleFormat, sampleRate?: number, channelLayout?: string): this;
+    /**
+     * Adds an atempo filter to the chain.
+     *
+     * @param factor - Tempo factor (0.5 to 2.0)
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.atempo}
+     */
     atempo(factor: number): this;
+    /**
+     * Adds an audio fade filter to the chain.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.afade}
+     */
     afade(type: 'in' | 'out', start: number, duration: number): this;
+    /**
+     * Adds an amix filter to the chain.
+     *
+     * @param inputs - Number of inputs (default: 2)
+     * @param duration - Duration mode (default: 'longest')
+     * @returns This instance for chaining
+     *
+     * @see {@link FilterPresetBase.amix}
+     */
     amix(inputs?: number, duration?: 'first' | 'longest' | 'shortest'): this;
+    /**
+     * Adds a transpose filter to the chain (hardware-specific).
+     * Only available for hardware presets that support transpose
+     *
+     * @param dir - Transpose direction (default: 0)
+     * @returns This instance for chaining
+     *
+     */
     transpose(dir?: number): this;
+    /**
+     * Adds a tonemap filter to the chain (hardware-specific).
+     * Only available for hardware presets that support tonemapping
+     *
+     * @param options - Tonemapping options
+     * @returns This instance for chaining
+     *
+     */
     tonemap(options?: Record<string, string>): this;
+    /**
+     * Adds a deinterlace filter to the chain (hardware-specific).
+     * Only available for hardware presets that support deinterlacing
+     *
+     * @param mode - Deinterlace mode (optional)
+     * @returns This instance for chaining
+     *
+     */
     deinterlace(mode?: string): this;
+    /**
+     * Adds a flip filter to the chain (hardware-specific).
+     * Falls back to hflip/vflip if hardware flip not available
+     *
+     * @param direction - Flip direction ('h' or 'v')
+     * @returns This instance for chaining
+     *
+     */
     flip(direction: 'h' | 'v'): this;
+    /**
+     * Adds a blur filter to the chain (hardware-specific).
+     * Only available for hardware presets that support blur
+     *
+     * @param type - Blur type (default: 'avg')
+     * @param radius - Blur radius (optional)
+     * @returns This instance for chaining
+     *
+     */
     blur(type?: 'avg' | 'gaussian' | 'box', radius?: number): this;
+    /**
+     * Adds a sharpen filter to the chain (hardware-specific).
+     * Only available for hardware presets that support sharpening
+     *
+     * @param amount - Sharpen amount (optional)
+     * @returns This instance for chaining
+     *
+     */
     sharpen(amount?: number): this;
+    /**
+     * Adds a stack filter to the chain (hardware-specific).
+     * Only available for hardware presets that support stacking
+     *
+     * @param type - Stack type ('h' for horizontal, 'v' for vertical, 'x' for grid)
+     * @param inputs - Number of inputs (default: 2)
+     * @returns This instance for chaining
+     *
+     */
     stack(type: 'h' | 'v' | 'x', inputs?: number): this;
+    /**
+     * Adds a hwupload filter to upload frames to hardware.
+     *
+     * @returns This instance for chaining
+     */
     hwupload(): this;
+    /**
+     * Adds a hwdownload filter to download frames from hardware.
+     *
+     * @returns This instance for chaining
+     */
     hwdownload(): this;
+    /**
+     * Adds a hwmap filter to map frames between hardware devices.
+     *
+     * @param derive - Device to derive from (optional)
+     * @returns This instance for chaining
+     */
     hwmap(derive?: string): this;
 }
 /**
  * Fluent filter chain builder with preset methods.
+ * Provides a convenient API for building filter chains using standard presets.
+ *
+ * @example
+ * ```typescript
+ * const filter = FilterPresets.chain()
+ *   .scale(1920, 1080)
+ *   .fps(30)
+ *   .fade('in', 0, 2)
+ *   .format('yuv420p')
+ *   .build();
+ * ```
  */
 export declare class FilterChainBuilder extends ChainBuilderBase<FilterPresets> {
 }
 /**
- * Common filter presets for convenience.
- *
- * Provides pre-defined filter strings for common operations.
- * Can be used with Filter.create() for quick setup.
+ * Standard filter presets for software filtering.
+ * Provides static methods for creating common filter strings and
+ * a chain builder for composing complex filter graphs.
  *
  * @example
  * ```typescript
- * const filter = await Filter.create(
- *   FilterPresets.scale(1280, 720),
- *   config
- * );
+ * // Static methods for individual filters
+ * const scaleFilter = FilterPresets.scale(1920, 1080);
+ * const fpsFilter = FilterPresets.fps(30);
  *
- * // Using chain builder
+ * // Chain builder for complex graphs
  * const chain = FilterPresets.chain()
  *   .scale(1920, 1080)
- *   .format('yuv420p')
- *   .custom('unsharp=5:5:1.0')
+ *   .fps(30)
+ *   .fade('in', 0, 2)
  *   .build();
  * ```
  */
 export declare class FilterPresets extends FilterPresetBase {
     private static instance;
     /**
-     * Create a new filter chain builder.
+     * Creates a new filter chain builder.
+     *
+     * @returns A new FilterChainBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.chain()
+     *   .scale(1280, 720)
+     *   .fps(30)
+     *   .build();
+     * ```
      */
     static chain(): FilterChainBuilder;
+    /**
+     * Creates a scale filter string.
+     *
+     * @param width - Target width
+     * @param height - Target height
+     * @param flags - Scaling algorithm flags (optional)
+     * @returns Scale filter string
+     */
     static scale(width: number, height: number, flags?: string): string;
+    /**
+     * Creates a crop filter string.
+     *
+     * @param width - Crop width
+     * @param height - Crop height
+     * @param x - X position (default: 0)
+     * @param y - Y position (default: 0)
+     * @returns Crop filter string
+     */
     static crop(width: number, height: number, x?: number, y?: number): string;
+    /**
+     * Creates an FPS filter string.
+     *
+     * @param fps - Target frame rate
+     * @returns FPS filter string
+     */
     static fps(fps: number): string;
+    /**
+     * Creates a format filter string.
+     *
+     * @param pixelFormat - Target pixel format(s)
+     * @returns Format filter string
+     */
     static format(pixelFormat: string | AVPixelFormat | (string | AVPixelFormat)[]): string;
+    /**
+     * Creates a rotate filter string.
+     *
+     * @param angle - Rotation angle in degrees
+     * @returns Rotate filter string
+     */
     static rotate(angle: number): string;
+    /**
+     * Creates a horizontal flip filter string.
+     *
+     * @returns Horizontal flip filter string
+     */
     static hflip(): string;
+    /**
+     * Creates a vertical flip filter string.
+     *
+     * @returns Vertical flip filter string
+     */
     static vflip(): string;
+    /**
+     * Creates a fade filter string.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns Fade filter string
+     */
     static fade(type: 'in' | 'out', start: number, duration: number): string;
+    /**
+     * Creates an overlay filter string.
+     *
+     * @param x - X position (default: 0)
+     * @param y - Y position (default: 0)
+     * @returns Overlay filter string
+     */
     static overlay(x?: number, y?: number): string;
+    /**
+     * Creates a volume filter string.
+     *
+     * @param factor - Volume multiplication factor
+     * @returns Volume filter string
+     */
     static volume(factor: number): string;
+    /**
+     * Creates an audio format filter string.
+     *
+     * @param sampleFormat - Target sample format
+     * @param sampleRate - Target sample rate (optional)
+     * @param channelLayout - Target channel layout (optional)
+     * @returns Audio format filter string
+     */
     static aformat(sampleFormat: string | AVSampleFormat, sampleRate?: number, channelLayout?: string): string;
+    /**
+     * Creates an atempo filter string.
+     *
+     * @param factor - Tempo factor (0.5 to 2.0)
+     * @returns Atempo filter string
+     */
     static atempo(factor: number): string;
+    /**
+     * Creates an audio fade filter string.
+     *
+     * @param type - Fade type ('in' or 'out')
+     * @param start - Start time in seconds
+     * @param duration - Fade duration in seconds
+     * @returns Audio fade filter string
+     */
     static afade(type: 'in' | 'out', start: number, duration: number): string;
+    /**
+     * Creates an amix filter string.
+     *
+     * @param inputs - Number of inputs (default: 2)
+     * @param duration - Duration mode (default: 'longest')
+     * @returns Amix filter string
+     */
     static amix(inputs?: number, duration?: 'first' | 'longest' | 'shortest'): string;
 }
 /**
  * Hardware-accelerated filter presets.
- *
- * Provides hardware-specific filter strings for accelerated processing.
- * Created and managed by HardwareContext for type-safe hardware operations.
+ * Provides optimized filter implementations for specific hardware types,
+ * with automatic fallback when operations aren't supported.
  *
  * @example
  * ```typescript
- * const hw = await HardwareContext.auto();
- * if (hw) {
- *   // Get hardware-specific scale filter (returns null if unsupported)
- *   const scaleFilter = hw.filterPresets.scale(1920, 1080);
+ * // Create hardware presets for CUDA
+ * const hw = new HardwareFilterPresets(AV_HWDEVICE_TYPE_CUDA, 'cuda');
  *
- *   // Build a filter chain (unsupported filters are skipped)
- *   const chain = hw.filterPresets.chain()
- *     .hwupload()
- *     .scale(1920, 1080)
- *     .tonemap()  // Skipped if not supported
- *     .custom('unsharp=5:5:1.0')
- *     .hwdownload()
- *     .build();
+ * // Check capabilities
+ * if (hw.support.scale) {
+ *   const scaleFilter = hw.scale(1920, 1080);
  * }
+ *
+ * // Use chain builder
+ * const chain = hw.chain()
+ *   .hwupload()
+ *   .scale(1920, 1080)
+ *   .tonemap()
+ *   .hwdownload()
+ *   .build();
  * ```
  */
 export declare class HardwareFilterPresets extends FilterPresetBase {
     private readonly deviceType;
-    private readonly deviceName;
+    private readonly deviceTypeName;
     readonly support: HardwareFilterSupport;
     /**
-     * Create hardware filter presets for a specific device type.
-     * @internal Used by HardwareContext
+     * @param deviceType - Hardware device type enum
+     * @param deviceTypeName - Hardware device type name (e.g., 'cuda', 'vaapi')
      */
-    constructor(deviceType: AVHWDeviceType, deviceName?: string | null);
+    constructor(deviceType: AVHWDeviceType, deviceTypeName: string);
     /**
-     * Check if a filter name is a hardware-accelerated filter.
-     * Uses FFmpeg's AVFILTER_FLAG_HWDEVICE flag to determine if a filter is hardware-accelerated.
-     * @param filterName - The filter name to check
-     * @returns True if it's a hardware filter, false otherwise
+     * Checks if a filter is hardware-accelerated.
+     *
+     * @param filterName - Name of the filter to check
+     * @returns True if the filter uses hardware acceleration
+     *
+     * @example
+     * ```typescript
+     * if (HardwareFilterPresets.isHardwareFilter('scale_cuda')) {
+     *   console.log('Hardware accelerated scaling');
+     * }
+     * ```
      */
     static isHardwareFilter(filterName: string): boolean;
     /**
-     * Create a new hardware filter chain builder.
+     * Creates a hardware filter chain builder.
+     *
+     * @returns A new HardwareFilterChainBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const filter = hw.chain()
+     *   .hwupload()
+     *   .scale(1920, 1080)
+     *   .hwdownload()
+     *   .build();
+     * ```
      */
     chain(): HardwareFilterChainBuilder;
     /**
-     * Hardware-accelerated scale filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated scale filter.
+     *
+     * Different hardware types use different scale filters:
+     * - CUDA: scale_cuda or scale_npp (with npp option)
+     * - VAAPI: scale_vaapi
+     * - QSV: scale_qsv
+     * - VideoToolbox: scale_vt
+     * - RKMPP: scale_rkrga
+     *
+     * @param width - Target width
+     * @param height - Target height
+     * @param options - Hardware-specific scaling options
+     * @returns Hardware scale filter string or null if not supported
+     *
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#scale_005fcuda | FFmpeg scale_cuda filter}
      */
     scale(width: number, height: number, options?: Record<string, any>): string | null;
     /**
-     * Hardware-accelerated overlay filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated overlay filter.
+     *
+     * @param x - X position (default: 0)
+     * @param y - Y position (default: 0)
+     * @param options - Hardware-specific overlay options
+     * @returns Hardware overlay filter string or null if not supported
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#overlay_005fcuda | FFmpeg overlay_cuda filter}
      */
     overlay(x?: number, y?: number, options?: Record<string, string>): string | null;
     /**
-     * Hardware-accelerated transpose filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated transpose filter.
+     *
+     * Direction values:
+     * - 0: 90 degrees counter-clockwise and vertical flip
+     * - 1: 90 degrees clockwise
+     * - 2: 90 degrees counter-clockwise
+     * - 3: 90 degrees clockwise and vertical flip
+     *
+     * @param dir - Transpose direction (default: 0)
+     * @returns Hardware transpose filter string or null if not supported
+     *
      */
     transpose(dir?: number): string | null;
     /**
-     * Hardware-accelerated tonemap filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated tonemap filter.
+     * Used for HDR to SDR conversion with hardware acceleration.
+     *
+     * @param options - Tonemapping options (algorithm, parameters)
+     * @returns Hardware tonemap filter string or null if not supported
+     *
      */
     tonemap(options?: Record<string, string>): string | null;
     /**
-     * Hardware-accelerated deinterlace filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated deinterlace filter.
+     *
+     * Different hardware types use different deinterlacers:
+     * - CUDA: yadif_cuda
+     * - VAAPI: deinterlace_vaapi
+     * - QSV: deinterlace_qsv
+     * - Vulkan: bwdif_vulkan
+     * - VideoToolbox: yadif_videotoolbox
+     *
+     * @param mode - Deinterlacing mode (optional)
+     * @returns Hardware deinterlace filter string or null if not supported
+     *
      */
     deinterlace(mode?: string): string | null;
     /**
-     * Hardware-accelerated flip filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated flip filter.
+     * Currently only Vulkan supports hardware flip filters.
+     *
+     * @param direction - Flip direction ('h' for horizontal, 'v' for vertical)
+     * @returns Hardware flip filter string or null if not supported
+     *
      */
     flip(direction: 'h' | 'v'): string | null;
     /**
-     * Hardware-accelerated blur filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated blur filter.
+     *
+     * Different hardware types support different blur filters:
+     * - CUDA: bilateral_cuda
+     * - Vulkan: avgblur_vulkan, gblur_vulkan
+     * - OpenCL: avgblur_opencl, boxblur_opencl
+     *
+     * @param type - Blur type ('avg', 'gaussian', or 'box', default: 'avg')
+     * @param radius - Blur radius (optional)
+     * @returns Hardware blur filter string or null if not supported
+     *
      */
     blur(type?: 'avg' | 'gaussian' | 'box', radius?: number): string | null;
     /**
-     * Hardware-accelerated sharpen filter.
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated sharpen filter.
+     *
+     * Hardware sharpening support:
+     * - VAAPI: sharpness_vaapi
+     * - OpenCL: unsharp_opencl
+     * - CUDA: sharpen_npp (NPP-based)
+     *
+     * @param amount - Sharpening amount (optional)
+     * @returns Hardware sharpen filter string or null if not supported
+     *
      */
     sharpen(amount?: number): string | null;
     /**
-     * Hardware-accelerated stack filters (hstack, vstack, xstack).
-     * @returns Filter string or null if not supported
+     * Creates a hardware-accelerated stack filter.
+     * Only VAAPI and QSV support hardware stacking.
+     *
+     * @param type - Stack type ('h' for horizontal, 'v' for vertical, 'x' for grid)
+     * @param inputs - Number of inputs to stack (default: 2)
+     * @returns Hardware stack filter string or null if not supported
+     *
      */
     stack(type: 'h' | 'v' | 'x', inputs?: number): string | null;
     /**
-     * Hardware upload filter to transfer frames to GPU.
+     * Creates a hwupload filter to upload frames to hardware memory.
+     * CUDA uses hwupload_cuda, others use generic hwupload.
+     *
+     * @returns Hardware upload filter string
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwupload | FFmpeg hwupload filter}
      */
     hwupload(): string | null;
     /**
-     * Hardware download filter to transfer frames from GPU.
+     * Creates a hwdownload filter to download frames from hardware memory.
+     *
+     * @returns Hardware download filter string
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwdownload | FFmpeg hwdownload filter}
      */
     hwdownload(): string | null;
     /**
-     * Format conversion for hardware frames.
+     * Creates a hwmap filter to map frames between hardware devices.
+     *
+     * @param derive - Device to derive from (optional)
+     * @returns Hardware map filter string
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwmap | FFmpeg hwmap filter}
      */
     hwmap(derive?: string): string | null;
     /**
-     * Get capabilities for this hardware type.
+     * Gets the filter capabilities for this hardware type.
+     *
+     * @returns Object describing which filters are supported
+     *
+     * @example
+     * ```typescript
+     * const caps = hw.getCapabilities();
+     * if (caps.scale && caps.overlay) {
+     *   console.log('Hardware supports scaling and overlay');
+     * }
+     * ```
      */
     getCapabilities(): HardwareFilterSupport;
     /**
-     * Get supported filters for this hardware type.
+     * Determines filter support for the hardware type.
+     *
+     * @returns Hardware filter support configuration
+     *
+     * @internal
      */
     private getSupport;
 }
 /**
  * Hardware filter chain builder with fluent API.
- * Automatically skips unsupported filters (returns null).
+ * Automatically skips unsupported filters (returns null) allowing graceful fallback.
+ *
+ * @example
+ * ```typescript
+ * const hw = new HardwareFilterPresets(AV_HWDEVICE_TYPE_CUDA, 'cuda');
+ * const chain = hw.chain()
+ *   .hwupload()
+ *   .scale(1920, 1080)
+ *   .tonemap()  // Skipped if not supported
+ *   .hwdownload()
+ *   .build();
+ * ```
  */
 export declare class HardwareFilterChainBuilder extends ChainBuilderBase<HardwareFilterPresets> {
 }