node-av 1.2.0 → 1.3.0

package/dist/api/filter-presets.js

@@ -1,5 +1,6 @@
 import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_D3D11VA, AV_HWDEVICE_TYPE_D3D12VA, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_DXVA2, AV_HWDEVICE_TYPE_MEDIACODEC, AV_HWDEVICE_TYPE_OPENCL, AV_HWDEVICE_TYPE_QSV, AV_HWDEVICE_TYPE_RKMPP, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VDPAU, AV_HWDEVICE_TYPE_VIDEOTOOLBOX, AV_HWDEVICE_TYPE_VULKAN, AVFILTER_FLAG_HWDEVICE, } from '../constants/constants.js';
 import { Filter } from '../lib/filter.js';
+import { HardwareDeviceContext } from '../lib/hardware-device-context.js';
 import { avGetPixFmtName, avGetSampleFmtName } from '../lib/utilities.js';
 /**
  * Base class for filter preset implementations.
@@ -28,6 +29,12 @@ export class FilterPresetBase {
      * @param options - Additional scaling options (e.g., flags for algorithm)
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.scale(1920, 1080)  // Scale to Full HD
+     * presets.scale(640, 480, { flags: 'lanczos' })  // With specific algorithm
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#scale | FFmpeg scale filter}
      */
     scale(width, height, options) {
@@ -44,6 +51,12 @@ export class FilterPresetBase {
      * @param y - Y coordinate of top-left corner (default: 0)
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.crop(640, 480, 100, 100)  // Crop 640x480 area starting at (100,100)
+     * presets.crop(1280, 720)  // Crop from top-left corner
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#crop | FFmpeg crop filter}
      */
     crop(width, height, x = 0, y = 0) {
@@ -55,6 +68,12 @@ export class FilterPresetBase {
      * @param fps - Target frames per second
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.fps(30)  // Convert to 30 FPS
+     * presets.fps(23.976)  // Film frame rate
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#fps | FFmpeg fps filter}
      */
     fps(fps) {
@@ -96,6 +115,12 @@ export class FilterPresetBase {
      * @param angle - Rotation angle in degrees
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.rotate(90)  // Rotate 90 degrees clockwise
+     * presets.rotate(-45)  // Rotate 45 degrees counter-clockwise
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#rotate | FFmpeg rotate filter}
      */
     rotate(angle) {
@@ -106,6 +131,11 @@ export class FilterPresetBase {
      *
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.hflip()  // Mirror horizontally
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hflip | FFmpeg hflip filter}
      */
     hflip() {
@@ -116,6 +146,11 @@ export class FilterPresetBase {
      *
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.vflip()  // Flip upside down
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#vflip | FFmpeg vflip filter}
      */
     vflip() {
@@ -129,6 +164,12 @@ export class FilterPresetBase {
      * @param duration - Fade duration in seconds
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.fade('in', 0, 2)  // 2-second fade in from start
+     * presets.fade('out', 10, 1)  // 1-second fade out at 10 seconds
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#fade | FFmpeg fade filter}
      */
     fade(type, start, duration) {
@@ -168,6 +209,12 @@ export class FilterPresetBase {
      * @param factor - Volume multiplication factor (1.0 = unchanged, 2.0 = double)
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.volume(0.5)  // Reduce volume by 50%
+     * presets.volume(1.5)  // Increase volume by 50%
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#volume | FFmpeg volume filter}
      */
     volume(factor) {
@@ -204,6 +251,29 @@ export class FilterPresetBase {
             filter += `:channel_layouts=${channelLayout}`;
         return filter;
     }
+    /**
+     * Creates an asetnsamples filter string to set the number of samples per frame.
+     * This is crucial for encoders like Opus that require specific frame sizes.
+     *
+     * @param samples - Number of samples per frame
+     * @param padding - Whether to pad or drop samples (default: true)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // For Opus encoder (requires 960 samples)
+     * presets.asetnsamples(960);
+     *
+     * // Drop samples instead of padding
+     * presets.asetnsamples(1024, false);
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#asetnsamples | FFmpeg asetnsamples filter}
+     */
+    asetnsamples(samples, padding = true) {
+        const p = padding ? 1 : 0;
+        return `asetnsamples=n=${samples}:p=${p}`;
+    }
     /**
      * 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.
@@ -211,6 +281,12 @@ export class FilterPresetBase {
      * @param factor - Tempo factor (0.5 = half speed, 2.0 = double speed)
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.atempo(1.5)  // 1.5x speed
+     * presets.atempo(0.8)  // Slow down to 80% speed
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#atempo | FFmpeg atempo filter}
      */
     atempo(factor) {
@@ -224,6 +300,12 @@ export class FilterPresetBase {
      * @param duration - Fade duration in seconds
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.afade('in', 0, 3)  // 3-second audio fade in
+     * presets.afade('out', 20, 2)  // 2-second fade out at 20s
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#afade | FFmpeg afade filter}
      */
     afade(type, start, duration) {
@@ -236,11 +318,360 @@ export class FilterPresetBase {
      * @param duration - How to determine output duration (default: 'longest')
      * @returns Filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * presets.amix(3, 'longest')  // Mix 3 audio streams
+     * presets.amix(2, 'first')  // Mix 2 streams, use first's duration
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#amix | FFmpeg amix filter}
      */
     amix(inputs = 2, duration = 'longest') {
         return `amix=inputs=${inputs}:duration=${duration}`;
     }
+    /**
+     * Creates a pad filter string to add padding to video.
+     * Essential for aspect ratio adjustments and letterboxing.
+     *
+     * @param width - Output width (can use expressions like 'iw+100')
+     * @param height - Output height (can use expressions like 'ih+100')
+     * @param x - X position of input video (default: '(ow-iw)/2' for center)
+     * @param y - Y position of input video (default: '(oh-ih)/2' for center)
+     * @param color - Padding color (default: 'black')
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Add black bars for 16:9 aspect ratio
+     * presets.pad('iw', 'iw*9/16');
+     *
+     * // Add 50px padding on all sides
+     * presets.pad('iw+100', 'ih+100');
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#pad | FFmpeg pad filter}
+     */
+    pad(width, height, x, y, color = 'black') {
+        let filter = `pad=${width}:${height}`;
+        if (x !== undefined)
+            filter += `:${x}`;
+        if (y !== undefined)
+            filter += `:${y}`;
+        filter += `:${color}`;
+        return filter;
+    }
+    /**
+     * Creates a trim filter string to cut a portion of the stream.
+     * Crucial for cutting segments from media.
+     *
+     * @param start - Start time in seconds
+     * @param end - End time in seconds (optional)
+     * @param duration - Duration in seconds (optional, alternative to end)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.trim(10, 30)  // Extract from 10s to 30s
+     * presets.trim(5, undefined, 10)  // Extract 10s starting at 5s
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#trim | FFmpeg trim filter}
+     */
+    trim(start, end, duration) {
+        let filter = `trim=start=${start}`;
+        if (end !== undefined)
+            filter += `:end=${end}`;
+        if (duration !== undefined)
+            filter += `:duration=${duration}`;
+        return filter;
+    }
+    /**
+     * Creates a setpts filter string to change presentation timestamps.
+     * Essential for speed changes and timestamp manipulation.
+     *
+     * @param expression - PTS expression (e.g., 'PTS*2' for half speed, 'PTS/2' for double speed)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * // Double speed
+     * presets.setpts('PTS/2');
+     *
+     * // Half speed
+     * presets.setpts('PTS*2');
+     *
+     * // Reset timestamps
+     * presets.setpts('PTS-STARTPTS');
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#setpts | FFmpeg setpts filter}
+     */
+    setpts(expression) {
+        return `setpts=${expression}`;
+    }
+    /**
+     * Creates an asetpts filter string for audio timestamp manipulation.
+     *
+     * @param expression - PTS expression
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.asetpts('PTS-STARTPTS')  // Reset timestamps to start from 0
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#asetpts | FFmpeg asetpts filter}
+     */
+    asetpts(expression) {
+        return `asetpts=${expression}`;
+    }
+    /**
+     * Creates a transpose filter string for rotation/flipping.
+     * More efficient than rotate for 90-degree rotations.
+     *
+     * @param mode - Transpose mode (0-3, or named constants)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.transpose(1)  // Rotate 90 degrees clockwise
+     * presets.transpose('cclock')  // Rotate 90 degrees counter-clockwise
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#transpose | FFmpeg transpose filter}
+     */
+    transpose(mode) {
+        return `transpose=${mode}`;
+    }
+    /**
+     * Creates a setsar filter string to set sample aspect ratio.
+     * Important for correcting aspect ratio issues.
+     *
+     * @param ratio - Aspect ratio (e.g., '1:1', '16:9', or number)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.setsar('1:1')  // Square pixels
+     * presets.setsar(1.333)  // 4:3 aspect ratio
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#setsar | FFmpeg setsar/setdar filter}
+     */
+    setsar(ratio) {
+        return `setsar=${ratio}`;
+    }
+    /**
+     * Creates a setdar filter string to set display aspect ratio.
+     *
+     * @param ratio - Aspect ratio (e.g., '16:9', '4:3')
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.setdar('16:9')  // Widescreen
+     * presets.setdar('4:3')  // Traditional TV aspect
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#setsar | FFmpeg setsar/setdar filter}
+     */
+    setdar(ratio) {
+        return `setdar=${ratio}`;
+    }
+    /**
+     * Creates an apad filter string to add audio padding.
+     * Useful for ensuring minimum audio duration.
+     *
+     * @param wholeDuration - Minimum duration in seconds (optional)
+     * @param padDuration - Amount of padding to add in seconds (optional)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.apad(30)  // Ensure at least 30 seconds total
+     * presets.apad(undefined, 5)  // Add 5 seconds of padding
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#apad | FFmpeg apad filter}
+     */
+    apad(wholeDuration, padDuration) {
+        if (!wholeDuration && !padDuration)
+            return 'apad';
+        let filter = 'apad';
+        if (wholeDuration)
+            filter += `=whole_dur=${wholeDuration}`;
+        if (padDuration)
+            filter += wholeDuration ? `:pad_dur=${padDuration}` : `=pad_dur=${padDuration}`;
+        return filter;
+    }
+    /**
+     * Creates a deinterlace filter string.
+     * Essential for processing interlaced content.
+     *
+     * @param mode - Deinterlace mode (default: 'yadif')
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.deinterlace('yadif')  // Standard deinterlacing
+     * presets.deinterlace('bwdif')  // Bob Weaver deinterlacing
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#yadif | FFmpeg yadif filter}
+     */
+    deinterlace(mode = 'yadif') {
+        return mode;
+    }
+    /**
+     * Creates a select filter string to select specific frames.
+     * Powerful for extracting keyframes, specific frame types, etc.
+     *
+     * @param expression - Selection expression
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.select('eq(pict_type,I)')  // Select only keyframes
+     * presets.select('not(mod(n,10))')  // Select every 10th frame
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#select | FFmpeg select filter}
+     */
+    select(expression) {
+        return `select='${expression}'`;
+    }
+    /**
+     * Creates an aselect filter string for audio selection.
+     *
+     * @param expression - Selection expression
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.aselect('between(t,10,20)')  // Select audio between 10-20 seconds
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#aselect | FFmpeg aselect filter}
+     */
+    aselect(expression) {
+        return `aselect='${expression}'`;
+    }
+    /**
+     * Creates a concat filter string to concatenate multiple inputs.
+     * Essential for joining multiple video/audio segments.
+     *
+     * @param n - Number of input segments
+     * @param v - Number of output video streams (0 or 1)
+     * @param a - Number of output audio streams (0 or 1)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.concat(3, 1, 1)  // Join 3 segments with video and audio
+     * presets.concat(2, 1, 0)  // Join 2 video-only segments
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#concat | FFmpeg concat filter}
+     */
+    concat(n, v = 1, a = 1) {
+        return `concat=n=${n}:v=${v}:a=${a}`;
+    }
+    /**
+     * Creates an amerge filter string to merge multiple audio streams into one.
+     * Different from amix - this creates multi-channel output.
+     *
+     * @param inputs - Number of input streams
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.amerge(2)  // Merge 2 mono streams to stereo
+     * presets.amerge(6)  // Merge 6 channels for 5.1 surround
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#amerge | FFmpeg amerge filter}
+     */
+    amerge(inputs = 2) {
+        return `amerge=inputs=${inputs}`;
+    }
+    /**
+     * Creates a channelmap filter string to remap audio channels.
+     * Critical for audio channel manipulation.
+     *
+     * @param map - Channel mapping (e.g., '0-0|1-1' or 'FL-FR|FR-FL' to swap stereo)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.channelmap('FL-FR|FR-FL')  // Swap left and right channels
+     * presets.channelmap('0-0|0-1')  // Duplicate mono to stereo
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#channelmap | FFmpeg channelmap filter}
+     */
+    channelmap(map) {
+        return `channelmap=${map}`;
+    }
+    /**
+     * Creates a channelsplit filter string to split audio channels.
+     *
+     * @param channelLayout - Channel layout to split (optional)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.channelsplit('stereo')  // Split stereo to 2 mono
+     * presets.channelsplit('5.1')  // Split 5.1 to individual channels
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#channelsplit | FFmpeg channelsplit filter}
+     */
+    channelsplit(channelLayout) {
+        return channelLayout ? `channelsplit=channel_layout=${channelLayout}` : 'channelsplit';
+    }
+    /**
+     * Creates a loudnorm filter string for loudness normalization.
+     * Essential for broadcast compliance and consistent audio levels.
+     *
+     * @param I - Integrated loudness target (default: -24 LUFS)
+     * @param TP - True peak (default: -2 dBTP)
+     * @param LRA - Loudness range (default: 7 LU)
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.loudnorm(-23, -1, 7)  // EBU R128 broadcast standard
+     * presets.loudnorm(-16, -1.5, 11)  // Streaming platforms standard
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#loudnorm | FFmpeg loudnorm filter}
+     */
+    loudnorm(I = -24, TP = -2, LRA = 7) {
+        return `loudnorm=I=${I}:TP=${TP}:LRA=${LRA}`;
+    }
+    /**
+     * Creates a compand filter string for audio compression/expansion.
+     * Important for dynamic range control.
+     *
+     * @param attacks - Attack times
+     * @param decays - Decay times
+     * @param points - Transfer function points
+     * @param gain - Output gain
+     * @returns Filter string or null if not supported
+     *
+     * @example
+     * ```typescript
+     * presets.compand('0.3|0.3', '1|1', '-90/-60|-60/-40|-40/-30|-20/-20', 6)
+     * ```
+     *
+     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#compand | FFmpeg compand filter}
+     */
+    compand(attacks, decays, points, gain) {
+        let filter = `compand=attacks=${attacks}:decays=${decays}:points=${points}`;
+        if (gain !== undefined)
+            filter += `:gain=${gain}`;
+        return filter;
+    }
 }
 /**
  * Filter chain builder for composing multiple filters.
@@ -263,6 +694,11 @@ export class FilterChain {
      *
      * @param filter - Filter string to add (ignored if null/undefined)
      * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.add('scale=1920:1080')
+     * ```
      */
     add(filter) {
         if (filter) {
@@ -275,6 +711,11 @@ export class FilterChain {
      *
      * @param filter - Custom filter string
      * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.custom('myfilter=param1:param2')
+     * ```
      */
     custom(filter) {
         return this.add(filter);
@@ -284,6 +725,11 @@ export class FilterChain {
      *
      * @param separator - Separator between filters (default: ',')
      * @returns Combined filter string
+     *
+     * @example
+     * ```typescript
+     * const filterString = chain.build()  // "scale=1920:1080,fps=30"
+     * ```
      */
     build(separator = ',') {
         return this.filters.join(separator);
@@ -292,6 +738,11 @@ export class FilterChain {
      * Returns the filters as an array.
      *
      * @returns Array of filter strings
+     *
+     * @example
+     * ```typescript
+     * const filters = chain.toArray()  // ["scale=1920:1080", "fps=30"]
+     * ```
      */
     toArray() {
         return [...this.filters];
@@ -328,22 +779,52 @@ export class ChainBuilderBase extends FilterChain {
      * @param width - Target width
      * @param height - Target height
      * @param options - Additional scaling options
+     *
      * @returns This instance for chaining
      *
-     * @see {@link FilterPresetBase.scale}
-     */
-    scale(width, height, options) {
-        return this.add(this.presets.scale(width, height, options));
-    }
-    /**
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .scale(1920, 1080)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .scale(1280, 720, { flags: 'lanczos' })
+     *   .build();
+     * ```
+     *
+     * @see {@link FilterPresetBase.scale}
+     */
+    scale(width, height, options) {
+        return this.add(this.presets.scale(width, height, options));
+    }
+    /**
      * 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
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .crop(640, 480)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .crop(1920, 1080, 100, 50)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.crop}
      */
     crop(width, height, x = 0, y = 0) {
@@ -353,8 +834,23 @@ export class ChainBuilderBase extends FilterChain {
      * Adds an FPS filter to the chain.
      *
      * @param fps - Target frame rate
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .fps(30)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .fps(23.976)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.fps}
      */
     fps(fps) {
@@ -364,8 +860,23 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a format filter to the chain.
      *
      * @param pixelFormat - Target pixel format(s)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .format('yuv420p')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .format(AV_PIX_FMT_RGB24)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.format}
      */
     format(pixelFormat) {
@@ -375,8 +886,23 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a rotate filter to the chain.
      *
      * @param angle - Rotation angle in degrees
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .rotate(45)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .rotate(-90)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.rotate}
      */
     rotate(angle) {
@@ -387,6 +913,13 @@ export class ChainBuilderBase extends FilterChain {
      *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .hflip()
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.hflip}
      */
     hflip() {
@@ -397,6 +930,13 @@ export class ChainBuilderBase extends FilterChain {
      *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .vflip()
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.vflip}
      */
     vflip() {
@@ -408,8 +948,23 @@ export class ChainBuilderBase extends FilterChain {
      * @param type - Fade type ('in' or 'out')
      * @param start - Start time in seconds
      * @param duration - Fade duration in seconds
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .fade('in', 0, 2)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .fade('out', 10, 1.5)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.fade}
      */
     fade(type, start, duration) {
@@ -421,8 +976,23 @@ export class ChainBuilderBase extends FilterChain {
      * @param x - X position (default: 0)
      * @param y - Y position (default: 0)
      * @param options - Additional overlay options
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .overlay(100, 50)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .overlay(10, 10, { enable: 'between(t,5,10)' })
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.overlay}
      */
     overlay(x = 0, y = 0, options) {
@@ -432,8 +1002,23 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a volume filter to the chain.
      *
      * @param factor - Volume factor
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .volume(0.5)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .volume(2.0)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.volume}
      */
     volume(factor) {
@@ -445,19 +1030,76 @@ export class ChainBuilderBase extends FilterChain {
      * @param sampleFormat - Target sample format
      * @param sampleRate - Target sample rate (optional)
      * @param channelLayout - Target channel layout (optional)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .aformat(AV_SAMPLE_FMT_FLT, 48000, 'stereo')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .aformat('s16', 44100)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.aformat}
      */
     aformat(sampleFormat, sampleRate, channelLayout) {
         return this.add(this.presets.aformat(sampleFormat, sampleRate, channelLayout));
     }
+    /**
+     * Adds an asetnsamples filter to the chain.
+     *
+     * @param samples - Number of samples per frame
+     * @param padding - Whether to pad or drop samples (default: true)
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .asetnsamples(960)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .asetnsamples(1024, false)
+     *   .build();
+     * ```
+     *
+     * @see {@link FilterPresetBase.asetnsamples}
+     */
+    asetnsamples(samples, padding = true) {
+        return this.add(this.presets.asetnsamples(samples, padding));
+    }
     /**
      * Adds an atempo filter to the chain.
      *
      * @param factor - Tempo factor (0.5 to 2.0)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .atempo(1.5)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .atempo(0.8)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.atempo}
      */
     atempo(factor) {
@@ -469,8 +1111,23 @@ export class ChainBuilderBase extends FilterChain {
      * @param type - Fade type ('in' or 'out')
      * @param start - Start time in seconds
      * @param duration - Fade duration in seconds
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .afade('in', 0, 3)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .afade('out', 25, 2)
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.afade}
      */
     afade(type, start, duration) {
@@ -481,24 +1138,323 @@ export class ChainBuilderBase extends FilterChain {
      *
      * @param inputs - Number of inputs (default: 2)
      * @param duration - Duration mode (default: 'longest')
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .amix(3, 'longest')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .amix(2, 'first')
+     *   .build();
+     * ```
+     *
      * @see {@link FilterPresetBase.amix}
      */
     amix(inputs = 2, duration = 'longest') {
         return this.add(this.presets.amix(inputs, duration));
     }
+    // ========== New Critical Filter Chain Methods ==========
+    /**
+     * Adds a pad filter to the chain.
+     *
+     * @param width - Target width
+     * @param height - Target height
+     * @param x - X position of input
+     * @param y - Y position of input
+     * @param color - Padding color
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.pad('iw*2', 'ih*2')  // Double the canvas size
+     * ```
+     *
+     * @see {@link FilterPresetBase.pad}
+     */
+    pad(width, height, x, y, color = 'black') {
+        return this.add(this.presets.pad(width, height, x, y, color));
+    }
+    /**
+     * Adds a trim filter to the chain.
+     *
+     * @param start - Start time in seconds
+     * @param end - End time in seconds
+     * @param duration - Duration in seconds
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.trim(10, 20)  // Extract 10 seconds from t=10 to t=20
+     * ```
+     *
+     * @see {@link FilterPresetBase.trim}
+     */
+    trim(start, end, duration) {
+        return this.add(this.presets.trim(start, end, duration));
+    }
+    /**
+     * Adds a setpts filter to the chain.
+     *
+     * @param expression - PTS expression
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.setpts('PTS/2')  // Double playback speed
+     * ```
+     *
+     * @see {@link FilterPresetBase.setpts}
+     */
+    setpts(expression) {
+        return this.add(this.presets.setpts(expression));
+    }
+    /**
+     * Adds an asetpts filter to the chain.
+     *
+     * @param expression - PTS expression
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.asetpts('PTS-STARTPTS')  // Reset audio timestamps
+     * ```
+     *
+     * @see {@link FilterPresetBase.asetpts}
+     */
+    asetpts(expression) {
+        return this.add(this.presets.asetpts(expression));
+    }
+    /**
+     * Adds a setsar filter to the chain.
+     *
+     * @param ratio - Sample aspect ratio
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.setsar('1:1')  // Square pixels
+     * ```
+     *
+     * @see {@link FilterPresetBase.setsar}
+     */
+    setsar(ratio) {
+        return this.add(this.presets.setsar(ratio));
+    }
+    /**
+     * Adds a setdar filter to the chain.
+     *
+     * @param ratio - Display aspect ratio
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.setdar('16:9')  // Set widescreen aspect
+     * ```
+     *
+     * @see {@link FilterPresetBase.setdar}
+     */
+    setdar(ratio) {
+        return this.add(this.presets.setdar(ratio));
+    }
+    /**
+     * Adds an apad filter to the chain.
+     *
+     * @param wholeDuration - Minimum total duration
+     * @param padDuration - Padding duration to add
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.apad(10)  // Ensure at least 10 seconds of audio
+     * ```
+     *
+     * @see {@link FilterPresetBase.apad}
+     */
+    apad(wholeDuration, padDuration) {
+        return this.add(this.presets.apad(wholeDuration, padDuration));
+    }
+    /**
+     * Adds a select filter to the chain.
+     *
+     * @param expression - Selection expression
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.select('eq(pict_type,I)')  // Select only I-frames
+     * ```
+     *
+     * @see {@link FilterPresetBase.select}
+     */
+    select(expression) {
+        return this.add(this.presets.select(expression));
+    }
+    /**
+     * Adds an aselect filter to the chain.
+     *
+     * @param expression - Selection expression
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.aselect('between(t,10,20)')  // Select audio between 10-20s
+     * ```
+     *
+     * @see {@link FilterPresetBase.aselect}
+     */
+    aselect(expression) {
+        return this.add(this.presets.aselect(expression));
+    }
+    /**
+     * Adds a concat filter to the chain.
+     *
+     * @param n - Number of input segments
+     * @param v - Number of video streams
+     * @param a - Number of audio streams
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.concat(3, 1, 1)  // Concatenate 3 segments with video and audio
+     * ```
+     *
+     * @see {@link FilterPresetBase.concat}
+     */
+    concat(n, v = 1, a = 1) {
+        return this.add(this.presets.concat(n, v, a));
+    }
+    /**
+     * Adds an amerge filter to the chain.
+     *
+     * @param inputs - Number of input streams
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.amerge(2)  // Merge 2 audio streams
+     * ```
+     *
+     * @see {@link FilterPresetBase.amerge}
+     */
+    amerge(inputs = 2) {
+        return this.add(this.presets.amerge(inputs));
+    }
+    /**
+     * Adds a channelmap filter to the chain.
+     *
+     * @param map - Channel mapping string
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.channelmap('FL-FR|FR-FL')  // Swap stereo channels
+     * ```
+     *
+     * @see {@link FilterPresetBase.channelmap}
+     */
+    channelmap(map) {
+        return this.add(this.presets.channelmap(map));
+    }
+    /**
+     * Adds a channelsplit filter to the chain.
+     *
+     * @param channelLayout - Channel layout to split
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.channelsplit('stereo')  // Split stereo into two mono streams
+     * ```
+     *
+     * @see {@link FilterPresetBase.channelsplit}
+     */
+    channelsplit(channelLayout) {
+        return this.add(this.presets.channelsplit(channelLayout));
+    }
+    /**
+     * Adds a loudnorm filter to the chain.
+     *
+     * @param I - Integrated loudness target (LUFS)
+     * @param TP - True peak (dBTP)
+     * @param LRA - Loudness range (LU)
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.loudnorm(-16, -1.5, 11)  // Streaming loudness standard
+     * ```
+     *
+     * @see {@link FilterPresetBase.loudnorm}
+     */
+    loudnorm(I = -24, TP = -2, LRA = 7) {
+        return this.add(this.presets.loudnorm(I, TP, LRA));
+    }
+    /**
+     * Adds a compand filter to the chain.
+     *
+     * @param attacks - Attack times
+     * @param decays - Decay times
+     * @param points - Transfer function points
+     * @param gain - Output gain
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain.compand('0.3|0.3', '1|1', '-90/-60|-60/-40|-40/-30|-20/-20', 6)
+     * ```
+     *
+     * @see {@link FilterPresetBase.compand}
+     */
+    compand(attacks, decays, points, gain) {
+        return this.add(this.presets.compand(attacks, decays, points, gain));
+    }
     /**
      * Adds a transpose filter to the chain (hardware-specific).
      * Only available for hardware presets that support transpose
      *
-     * @param dir - Transpose direction (default: 0)
+     * @param mode - Transpose mode (number or string)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .transpose('clock')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .transpose('cclock_flip')
+     *   .build();
+     * ```
      */
-    transpose(dir = 0) {
+    transpose(mode = 0) {
         if ('transpose' in this.presets) {
-            return this.add(this.presets.transpose(dir));
+            return this.add(this.presets.transpose(mode));
         }
         return this.add(null);
     }
@@ -507,8 +1463,22 @@ export class ChainBuilderBase extends FilterChain {
      * Only available for hardware presets that support tonemapping
      *
      * @param options - Tonemapping options
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .tonemap()
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .tonemap({ tonemap: 'hable', desat: '0' })
+     *   .build();
+     * ```
      */
     tonemap(options) {
         if ('tonemap' in this.presets) {
@@ -521,8 +1491,22 @@ export class ChainBuilderBase extends FilterChain {
      * Only available for hardware presets that support deinterlacing
      *
      * @param mode - Deinterlace mode (optional)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .deinterlace()
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .deinterlace('yadif')
+     *   .build();
+     * ```
      */
     deinterlace(mode) {
         if ('deinterlace' in this.presets) {
@@ -535,8 +1519,22 @@ export class ChainBuilderBase extends FilterChain {
      * Falls back to hflip/vflip if hardware flip not available
      *
      * @param direction - Flip direction ('h' or 'v')
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .flip('h')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .flip('v')
+     *   .build();
+     * ```
      */
     flip(direction) {
         if ('flip' in this.presets) {
@@ -551,8 +1549,22 @@ export class ChainBuilderBase extends FilterChain {
      *
      * @param type - Blur type (default: 'avg')
      * @param radius - Blur radius (optional)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .blur('gaussian', 5)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .blur('box')
+     *   .build();
+     * ```
      */
     blur(type = 'avg', radius) {
         if ('blur' in this.presets) {
@@ -565,8 +1577,22 @@ export class ChainBuilderBase extends FilterChain {
      * Only available for hardware presets that support sharpening
      *
      * @param amount - Sharpen amount (optional)
+     *
      * @returns This instance for chaining
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .sharpen(1.5)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .sharpen()
+     *   .build();
+     * ```
      */
     sharpen(amount) {
         if ('sharpen' in this.presets) {
@@ -580,8 +1606,22 @@ export class ChainBuilderBase extends FilterChain {
      *
      * @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
      *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .stack('h', 2)
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .stack('x', 4)
+     *   .build();
+     * ```
      */
     stack(type, inputs = 2) {
         if ('stack' in this.presets) {
@@ -593,6 +1633,14 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a hwupload filter to upload frames to hardware.
      *
      * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .hwupload()
+     *   .scale(1920, 1080)
+     *   .build();
+     * ```
      */
     hwupload() {
         if ('hwupload' in this.presets) {
@@ -604,6 +1652,14 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a hwdownload filter to download frames from hardware.
      *
      * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .scale(1920, 1080)
+     *   .hwdownload()
+     *   .build();
+     * ```
      */
     hwdownload() {
         if ('hwdownload' in this.presets) {
@@ -615,7 +1671,22 @@ export class ChainBuilderBase extends FilterChain {
      * Adds a hwmap filter to map frames between hardware devices.
      *
      * @param derive - Device to derive from (optional)
+     *
      * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .hwmap('cuda')
+     *   .build();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const chain = FilterPresets.chain()
+     *   .hwmap()
+     *   .build();
+     * ```
      */
     hwmap(derive) {
         if ('hwmap' in this.presets) {
@@ -683,7 +1754,18 @@ export class FilterPresets extends FilterPresetBase {
      * @param width - Target width
      * @param height - Target height
      * @param flags - Scaling algorithm flags (optional)
+     *
      * @returns Scale filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.scale(1920, 1080);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.scale(1280, 720, 'lanczos');
+     * ```
      */
     static scale(width, height, flags) {
         const result = FilterPresets.instance.scale(width, height, { flags });
@@ -696,7 +1778,18 @@ export class FilterPresets extends FilterPresetBase {
      * @param height - Crop height
      * @param x - X position (default: 0)
      * @param y - Y position (default: 0)
+     *
      * @returns Crop filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.crop(640, 480);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.crop(1920, 1080, 100, 50);
+     * ```
      */
     static crop(width, height, x = 0, y = 0) {
         const result = FilterPresets.instance.crop(width, height, x, y);
@@ -706,7 +1799,18 @@ export class FilterPresets extends FilterPresetBase {
      * Creates an FPS filter string.
      *
      * @param fps - Target frame rate
+     *
      * @returns FPS filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.fps(30);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.fps(23.976);
+     * ```
      */
     static fps(fps) {
         const result = FilterPresets.instance.fps(fps);
@@ -716,7 +1820,18 @@ export class FilterPresets extends FilterPresetBase {
      * Creates a format filter string.
      *
      * @param pixelFormat - Target pixel format(s)
+     *
      * @returns Format filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.format('yuv420p');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.format(AV_PIX_FMT_RGB24);
+     * ```
      */
     static format(pixelFormat) {
         const result = FilterPresets.instance.format(pixelFormat);
@@ -726,7 +1841,18 @@ export class FilterPresets extends FilterPresetBase {
      * Creates a rotate filter string.
      *
      * @param angle - Rotation angle in degrees
+     *
      * @returns Rotate filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.rotate(45);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.rotate(-90);
+     * ```
      */
     static rotate(angle) {
         const result = FilterPresets.instance.rotate(angle);
@@ -736,6 +1862,11 @@ export class FilterPresets extends FilterPresetBase {
      * Creates a horizontal flip filter string.
      *
      * @returns Horizontal flip filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.hflip();
+     * ```
      */
     static hflip() {
         const result = FilterPresets.instance.hflip();
@@ -745,6 +1876,11 @@ export class FilterPresets extends FilterPresetBase {
      * Creates a vertical flip filter string.
      *
      * @returns Vertical flip filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.vflip();
+     * ```
      */
     static vflip() {
         const result = FilterPresets.instance.vflip();
@@ -756,7 +1892,18 @@ export class FilterPresets extends FilterPresetBase {
      * @param type - Fade type ('in' or 'out')
      * @param start - Start time in seconds
      * @param duration - Fade duration in seconds
+     *
      * @returns Fade filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.fade('in', 0, 2);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.fade('out', 10, 1.5);
+     * ```
      */
     static fade(type, start, duration) {
         const result = FilterPresets.instance.fade(type, start, duration);
@@ -767,7 +1914,18 @@ export class FilterPresets extends FilterPresetBase {
      *
      * @param x - X position (default: 0)
      * @param y - Y position (default: 0)
+     *
      * @returns Overlay filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.overlay(100, 50);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.overlay();
+     * ```
      */
     static overlay(x = 0, y = 0) {
         const result = FilterPresets.instance.overlay(x, y);
@@ -777,7 +1935,18 @@ export class FilterPresets extends FilterPresetBase {
      * Creates a volume filter string.
      *
      * @param factor - Volume multiplication factor
+     *
      * @returns Volume filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.volume(0.5);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.volume(2.0);
+     * ```
      */
     static volume(factor) {
         const result = FilterPresets.instance.volume(factor);
@@ -789,17 +1958,61 @@ export class FilterPresets extends FilterPresetBase {
      * @param sampleFormat - Target sample format
      * @param sampleRate - Target sample rate (optional)
      * @param channelLayout - Target channel layout (optional)
+     *
      * @returns Audio format filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.aformat(AV_SAMPLE_FMT_FLT, 48000, 'stereo');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.aformat('s16', 44100);
+     * ```
      */
     static aformat(sampleFormat, sampleRate, channelLayout) {
         const result = FilterPresets.instance.aformat(sampleFormat, sampleRate, channelLayout);
         return result ?? '';
     }
+    /**
+     * Creates an asetnsamples filter string.
+     *
+     * @param samples - Number of samples per frame
+     * @param padding - Whether to pad or drop samples (default: true)
+     *
+     * @returns Asetnsamples filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.asetnsamples(960);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.asetnsamples(1024, false);
+     * ```
+     */
+    static asetnsamples(samples, padding = true) {
+        const result = FilterPresets.instance.asetnsamples(samples, padding);
+        return result ?? '';
+    }
     /**
      * Creates an atempo filter string.
      *
      * @param factor - Tempo factor (0.5 to 2.0)
+     *
      * @returns Atempo filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.atempo(1.5);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.atempo(0.8);
+     * ```
      */
     static atempo(factor) {
         const result = FilterPresets.instance.atempo(factor);
@@ -811,7 +2024,18 @@ export class FilterPresets extends FilterPresetBase {
      * @param type - Fade type ('in' or 'out')
      * @param start - Start time in seconds
      * @param duration - Fade duration in seconds
+     *
      * @returns Audio fade filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.afade('in', 0, 3);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.afade('out', 25, 2);
+     * ```
      */
     static afade(type, start, duration) {
         const result = FilterPresets.instance.afade(type, start, duration);
@@ -822,7 +2046,18 @@ export class FilterPresets extends FilterPresetBase {
      *
      * @param inputs - Number of inputs (default: 2)
      * @param duration - Duration mode (default: 'longest')
+     *
      * @returns Amix filter string
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.amix(3, 'longest');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = FilterPresets.amix(2, 'first');
+     * ```
      */
     static amix(inputs = 2, duration = 'longest') {
         const result = FilterPresets.instance.amix(inputs, duration);
@@ -837,7 +2072,7 @@ export class FilterPresets extends FilterPresetBase {
  * @example
  * ```typescript
  * // Create hardware presets for CUDA
- * const hw = new HardwareFilterPresets(AV_HWDEVICE_TYPE_CUDA, 'cuda');
+ * const hw = new HardwareFilterPresets(AV_HWDEVICE_TYPE_CUDA);
  *
  * // Check capabilities
  * if (hw.support.scale) {
@@ -859,12 +2094,12 @@ export class HardwareFilterPresets extends FilterPresetBase {
     support;
     /**
      * @param deviceType - Hardware device type enum
-     * @param deviceTypeName - Hardware device type name (e.g., 'cuda', 'vaapi')
+     * @param deviceTypeName - Optional hardware device type name (e.g., 'cuda', 'vaapi')
      */
     constructor(deviceType, deviceTypeName) {
         super();
         this.deviceType = deviceType;
-        this.deviceTypeName = deviceTypeName;
+        this.deviceTypeName = deviceTypeName ?? HardwareDeviceContext.getTypeName(deviceType);
         this.support = this.getSupport();
     }
     /**
@@ -918,8 +2153,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * @param width - Target width
      * @param height - Target height
      * @param options - Hardware-specific scaling options
+     *
      * @returns Hardware scale filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.scale(1920, 1080);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.scale(1280, 720, { npp: true });
+     * ```
      *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#scale_005fcuda | FFmpeg scale_cuda filter}
      */
@@ -958,8 +2203,19 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * @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
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.overlay(100, 50);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.overlay(0, 0, { eof_action: 'pass' });
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#overlay_005fcuda | FFmpeg overlay_cuda filter}
      */
     overlay(x = 0, y = 0, options) {
@@ -981,18 +2237,51 @@ export class HardwareFilterPresets extends FilterPresetBase {
      *
      * 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
+     * - 1 / 'clock': 90 degrees clockwise
+     * - 2 / 'cclock': 90 degrees counter-clockwise
+     * - 3 / 'clock_flip': 90 degrees clockwise and vertical flip
+     *
+     * @param mode - Transpose mode (number or string)
      *
-     * @param dir - Transpose direction (default: 0)
      * @returns Hardware transpose filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.transpose('clock');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.transpose(2);
+     * ```
      */
-    transpose(dir = 0) {
+    transpose(mode) {
         if (!this.support.transpose) {
             return null;
         }
+        // Convert string modes to numbers
+        let dir;
+        if (typeof mode === 'string') {
+            switch (mode) {
+                case 'clock':
+                    dir = 1;
+                    break;
+                case 'cclock':
+                    dir = 2;
+                    break;
+                case 'clock_flip':
+                    dir = 3;
+                    break;
+                case 'cclock_flip':
+                    dir = 0;
+                    break;
+                default:
+                    dir = 0;
+            }
+        }
+        else {
+            dir = mode;
+        }
         // Special handling for different hardware transpose implementations
         let filterName;
         if (this.deviceType === AV_HWDEVICE_TYPE_CUDA) {
@@ -1011,8 +2300,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * 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
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.tonemap();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.tonemap({ tonemap: 'hable', desat: '0' });
+     * ```
      */
     tonemap(options) {
         if (!this.support.tonemap) {
@@ -1040,8 +2339,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * - VideoToolbox: yadif_videotoolbox
      *
      * @param mode - Deinterlacing mode (optional)
+     *
      * @returns Hardware deinterlace filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.deinterlace();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.deinterlace('send_field');
+     * ```
      */
     deinterlace(mode) {
         if (!this.support.deinterlace) {
@@ -1067,8 +2376,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * 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
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.flip('h');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.flip('v');
+     * ```
      */
     flip(direction) {
         if (!this.support.flip) {
@@ -1089,8 +2408,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      *
      * @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
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.blur('gaussian', 5);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.blur('avg');
+     * ```
      */
     blur(type = 'avg', radius) {
         if (!this.support.blur) {
@@ -1116,8 +2445,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * - CUDA: sharpen_npp (NPP-based)
      *
      * @param amount - Sharpening amount (optional)
+     *
      * @returns Hardware sharpen filter string or null if not supported
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.sharpen(1.5);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.sharpen();
+     * ```
      */
     sharpen(amount) {
         if (!this.support.sharpen) {
@@ -1141,8 +2480,18 @@ export class HardwareFilterPresets extends FilterPresetBase {
      *
      * @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
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.stack('h', 2);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.stack('x', 4);
+     * ```
      */
     stack(type, inputs = 2) {
         if (!this.support.stack) {
@@ -1159,6 +2508,11 @@ export class HardwareFilterPresets extends FilterPresetBase {
      *
      * @returns Hardware upload filter string
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.hwupload();
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwupload | FFmpeg hwupload filter}
      */
     hwupload() {
@@ -1172,6 +2526,11 @@ export class HardwareFilterPresets extends FilterPresetBase {
      *
      * @returns Hardware download filter string
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.hwdownload();
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwdownload | FFmpeg hwdownload filter}
      */
     hwdownload() {
@@ -1181,8 +2540,19 @@ export class HardwareFilterPresets extends FilterPresetBase {
      * Creates a hwmap filter to map frames between hardware devices.
      *
      * @param derive - Device to derive from (optional)
+     *
      * @returns Hardware map filter string
      *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.hwmap('cuda');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const filter = hwPresets.hwmap();
+     * ```
+     *
      * @see {@link https://ffmpeg.org/ffmpeg-filters.html#hwmap | FFmpeg hwmap filter}
      */
     hwmap(derive) {