node-av 5.2.4 → 6.0.0-beta.11

package/dist/api/filter-presets.js

@@ -1,6 +1,15 @@
 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 { avGetPixFmtName, avGetSampleFmtName } from '../lib/utilities.js';
+// Escape a filter option value for the filtergraph string. Bare tokens (numbers,
+// simple identifiers, expressions) are emitted as-is; anything with special
+// characters is single-quoted, with embedded quotes escaped FFmpeg-style.
+const escapeFilterValue = (value) => {
+    const s = String(value);
+    if (s !== '' && /^[A-Za-z0-9_.+\-/*]+$/.test(s))
+        return s;
+    return `'${s.replace(/'/g, "'\\''")}'`;
+};
 /**
  * Filter preset builder for composing filter chains.
  * Supports both software and hardware-accelerated filters.
@@ -12,8 +21,8 @@ import { avGetPixFmtName, avGetSampleFmtName } from '../lib/utilities.js';
  * // Software filter chain
  * const filter = FilterPreset.chain()
  *   .scale(1920, 1080)
- *   .fps(30)
- *   .fade('in', 0, 2)
+ *   .filter('fps', { fps: 30 })
+ *   .filter('fade', { type: 'in', start_time: 0, duration: 2 })
  *   .build();
  *
  * // Hardware-accelerated filter chain
@@ -65,7 +74,7 @@ export class FilterPreset {
      * // Software filter chain
      * const filter = FilterPreset.chain()
      *   .scale(1280, 720)
-     *   .fps(30)
+     *   .filter('fps', { fps: 30 })
      *   .build();
      * ```
      *
@@ -101,6 +110,39 @@ export class FilterPreset {
         }
         return this.add(filter);
     }
+    /**
+     * Adds any FFmpeg filter to the chain with type-safe options.
+     *
+     * Provides autocomplete for every available filter name and its options
+     * (generated from FFmpeg's AVOption metadata). Prefer the dedicated methods
+     * (e.g. {@link scale}) when hardware-aware selection or automatic mapping is
+     * needed; use {@link custom} for raw filter strings.
+     *
+     * @param name - Filter name (autocompleted from all available filters)
+     *
+     * @param options - Filter-specific options, typed to the chosen filter
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * chain
+     *   .filter('drawtext', { text: 'hello', fontsize: 24 })
+     *   .filter('hue', { s: 0 });
+     * // "drawtext=text=hello:fontsize=24,hue=s=0"
+     * ```
+     */
+    filter(name, options) {
+        if (!options) {
+            return this.add(name);
+        }
+        const entries = Object.entries(options);
+        const args = entries
+            .filter((e) => e[1] != null)
+            .map(([k, v]) => `${k}=${escapeFilterValue(v)}`)
+            .join(':');
+        return this.add(args ? `${name}=${args}` : name);
+    }
     /**
      * Builds the final filter string.
      *
@@ -470,28 +512,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * Adds an FPS filter to change frame rate.
-     *
-     * @param fps - Target frames per second
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.fps(30)  // Convert to 30 FPS
-     * chain.fps(23.976)  // Film frame rate
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#fps | FFmpeg fps filter}
-     */
-    fps(fps) {
-        if (fps <= 0) {
-            return this;
-        }
-        this.add(`fps=fps=${fps}`);
-        return this;
-    }
     /**
      * Adds a format filter to convert pixel format.
      *
@@ -528,25 +548,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * Adds a rotate filter to the chain.
-     *
-     * @param angle - Rotation angle in degrees
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.rotate(90)  // Rotate 90 degrees clockwise
-     * chain.rotate(-45)  // Rotate 45 degrees counter-clockwise
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#rotate | FFmpeg rotate filter}
-     */
-    rotate(angle) {
-        this.add(`rotate=${angle}*PI/180`);
-        return this;
-    }
     /**
      * Adds a flip filter to the chain (hardware-specific).
      * Falls back to hflip/vflip if hardware flip not available
@@ -704,29 +705,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * 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
-     *
-     * @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) {
-        this.add(`fade=t=${type}:st=${start}:d=${duration}`);
-        return this;
-    }
     /**
      * Creates an overlay filter string to composite two video streams.
      *
@@ -775,25 +753,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * 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
-     *
-     * @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) {
-        this.add(`volume=${factor}`);
-        return this;
-    }
     /**
      * Creates an audio format filter string.
      *
@@ -833,130 +792,6 @@ export class FilterPreset {
         this.add(filter);
         return this;
     }
-    /**
-     * Adds an asetnsamples filter 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 This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * // For Opus encoder (requires 960 samples)
-     * chain.asetnsamples(960);
-     *
-     * // Drop samples instead of padding
-     * chain.asetnsamples(1024, false);
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#asetnsamples | FFmpeg asetnsamples filter}
-     */
-    asetnsamples(samples, padding = true) {
-        const p = padding ? 1 : 0;
-        this.add(`asetnsamples=n=${samples}:p=${p}`);
-        return this;
-    }
-    /**
-     * Adds an aresample filter to change audio sample rate, format, and channel layout.
-     *
-     * Uses libswresample for high-quality audio resampling and format conversion.
-     * Can also perform timestamp compensation (stretch/squeeze/fill/trim).
-     *
-     * @param rate - Target sample rate in Hz
-     *
-     * @param format - Optional target sample format (e.g., 's16', 'flt', 'fltp')
-     *
-     * @param channelLayout - Optional target channel layout (e.g., 'mono', 'stereo')
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.aresample(44100)  // Convert to 44.1 kHz only
-     * chain.aresample(48000, 's16', 'stereo')  // Full conversion
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#aresample | FFmpeg aresample filter}
-     */
-    aresample(rate, format, channelLayout) {
-        const params = [`${rate}`];
-        if (format !== undefined) {
-            const formatStr = typeof format === 'number' ? `${format}` : format;
-            params.push(`osf=${formatStr}`);
-        }
-        if (channelLayout !== undefined) {
-            params.push(`ochl=${channelLayout}`);
-        }
-        this.add(`aresample=${params.join(':')}`);
-        return this;
-    }
-    /**
-     * Adds an atempo filter 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 This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.atempo(1.5)  // 1.5x speed
-     * chain.atempo(0.8)  // Slow down to 80% speed
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#atempo | FFmpeg atempo filter}
-     */
-    atempo(factor) {
-        this.add(`atempo=${factor}`);
-        return this;
-    }
-    /**
-     * Adds an audio fade filter.
-     *
-     * @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
-     * chain.afade('in', 0, 3)  // 3-second audio fade in
-     * chain.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) {
-        this.add(`afade=t=${type}:st=${start}:d=${duration}`);
-        return this;
-    }
-    /**
-     * Adds an amix filter 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 This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.amix(3, 'longest')  // Mix 3 audio streams
-     * chain.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') {
-        this.add(`amix=inputs=${inputs}:duration=${duration}`);
-        return this;
-    }
     /**
      * Adds a pad filter to add padding to video.
      * Essential for aspect ratio adjustments and letterboxing.
@@ -1006,79 +841,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * Adds a trim filter 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 This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.trim(10, 30)  // Extract from 10s to 30s
-     * chain.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}`;
-        this.add(filter);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`setpts=${expression}`);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`asetpts=${expression}`);
-        return this;
-    }
     /**
      * Creates a transpose filter string for rotation/flipping.
      * More efficient than rotate for 90-degree rotations.
@@ -1145,74 +907,6 @@ export class FilterPreset {
         }
         return this;
     }
-    /**
-     * 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) {
-        this.add(`setsar=${ratio}`);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`setdar=${ratio}`);
-        return this;
-    }
-    /**
-     * Adds an apad filter 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 This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.apad(30)  // Ensure at least 30 seconds total
-     * chain.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 this;
-        let filter = 'apad';
-        if (wholeDuration)
-            filter += `=whole_dur=${wholeDuration}`;
-        if (padDuration)
-            filter += wholeDuration ? `:pad_dur=${padDuration}` : `=pad_dur=${padDuration}`;
-        this.add(filter);
-        return this;
-    }
     /**
      * Creates a deinterlace filter string.
      * Essential for processing interlaced content.
@@ -1283,503 +977,41 @@ export class FilterPreset {
         return this;
     }
     /**
-     * Creates a select filter string to select specific frames.
-     * Powerful for extracting keyframes, specific frame types, etc.
+     * Adds a whisper filter for audio transcription using whisper.cpp.
+     * Transcribes audio and adds metadata to frames (lavfi.whisper.text, lavfi.whisper.duration).
      *
-     * @param expression - Selection expression
+     * @param options - Whisper transcription options
      *
-     * @returns Filter string or null if not supported
+     * @param options.model - Path to whisper.cpp model file
      *
-     * @example
-     * ```typescript
-     * presets.select('eq(pict_type,I)')  // Select only keyframes
-     * presets.select('not(mod(n,10))')  // Select every 10th frame
-     * ```
+     * @param options.language - Language for transcription (default: 'auto')
      *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#select | FFmpeg select filter}
-     */
-    select(expression) {
-        this.add(`select='${expression}'`);
-        return this;
-    }
-    /**
-     * Creates an aselect filter string for audio selection.
+     * @param options.queue - Audio queue size in seconds (default: 3)
      *
-     * @param expression - Selection expression
+     * @param options.useGpu - Use GPU for processing (default: true)
      *
-     * @returns Filter string or null if not supported
+     * @param options.gpuDevice - GPU device to use (default: 0)
      *
-     * @example
-     * ```typescript
-     * presets.aselect('between(t,10,20)')  // Select audio between 10-20 seconds
-     * ```
+     * @param options.destination - Output destination for transcripts
      *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#aselect | FFmpeg aselect filter}
-     */
-    aselect(expression) {
-        this.add(`aselect='${expression}'`);
-        return this;
-    }
-    /**
-     * Creates a concat filter string to concatenate multiple inputs.
-     * Essential for joining multiple video/audio segments.
+     * @param options.format - Output format: text|srt|json (default: 'text')
      *
-     * @param n - Number of input segments
+     * @param options.vadModel - Path to VAD model file (optional)
      *
-     * @param v - Number of output video streams (0 or 1)
+     * @param options.vadThreshold - VAD threshold 0.0-1.0 (default: 0.5)
      *
-     * @param a - Number of output audio streams (0 or 1)
+     * @param options.vadMinSpeechDuration - Minimum speech duration for VAD in seconds (default: 0.1)
      *
-     * @returns Filter string or null if not supported
+     * @param options.vadMinSilenceDuration - Minimum silence duration for VAD in seconds (default: 0.5)
+     *
+     * @returns This instance for chaining
      *
      * @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) {
-        this.add(`concat=n=${n}:v=${v}:a=${a}`);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`amerge=inputs=${inputs}`);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`channelmap=${map}`);
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(channelLayout ? `channelsplit=channel_layout=${channelLayout}` : 'channelsplit');
-        return this;
-    }
-    /**
-     * 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) {
-        this.add(`loudnorm=I=${I}:TP=${TP}:LRA=${LRA}`);
-        return this;
-    }
-    /**
-     * 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}`;
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a drawtext filter to overlay text on video.
-     *
-     * @param text - Text to display
-     *
-     * @param options - Text rendering options
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.drawtext('Hello World', { x: 10, y: 10, fontsize: 24 })
-     * chain.drawtext('Timestamp', {
-     *   x: 10,
-     *   y: 10,
-     *   fontsize: 24,
-     *   fontcolor: 'white',
-     *   fontfile: '/path/to/font.ttf'
-     * })
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#drawtext | FFmpeg drawtext filter}
-     */
-    drawtext(text, options) {
-        let filter = `drawtext=text='${text.replace(/'/g, "\\'").replace(/"/g, '\\"')}'`;
-        for (const [key, value] of Object.entries(options)) {
-            if (key === 'fontfile' && typeof value === 'string') {
-                filter += `:${key}='${value}'`;
-            }
-            else {
-                filter += `:${key}=${value}`;
-            }
-        }
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a split filter to duplicate a video stream.
-     *
-     * @param outputs - Number of output streams (default: 2)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.split()    // Split into 2 outputs
-     * chain.split(3)   // Split into 3 outputs
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#split | FFmpeg split filter}
-     */
-    split(outputs = 2) {
-        this.add(`split=${outputs}`);
-        return this;
-    }
-    /**
-     * Adds an asplit filter to duplicate an audio stream.
-     *
-     * @param outputs - Number of output streams (default: 2)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.asplit()   // Split into 2 outputs
-     * chain.asplit(3)  // Split into 3 outputs
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#asplit | FFmpeg asplit filter}
-     */
-    asplit(outputs = 2) {
-        this.add(`asplit=${outputs}`);
-        return this;
-    }
-    /**
-     * Adds an adelay filter to delay audio by specified milliseconds.
-     *
-     * @param delays - Delay in milliseconds (single value or array for multiple channels)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.adelay(100)        // Delay all channels by 100ms
-     * chain.adelay([100, 200]) // Delay first channel by 100ms, second by 200ms
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#adelay | FFmpeg adelay filter}
-     */
-    adelay(delays) {
-        const delayStr = Array.isArray(delays) ? delays.join('|') : delays.toString();
-        this.add(`adelay=${delayStr}`);
-        return this;
-    }
-    /**
-     * Adds an aecho filter for audio echo effect.
-     *
-     * @param in_gain - Input gain (0-1)
-     *
-     * @param out_gain - Output gain (0-1)
-     *
-     * @param delays - Delay in milliseconds
-     *
-     * @param decays - Decay factor (0-1)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.aecho(0.8, 0.9, 1000, 0.3)  // Echo with 1 second delay
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#aecho | FFmpeg aecho filter}
-     */
-    aecho(in_gain, out_gain, delays, decays) {
-        this.add(`aecho=${in_gain}:${out_gain}:${delays}:${decays}`);
-        return this;
-    }
-    /**
-     * Adds a highpass filter to remove low frequencies.
-     *
-     * @param frequency - Cutoff frequency in Hz
-     *
-     * @param options - Additional filter options
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.highpass(200)  // Remove frequencies below 200Hz
-     * chain.highpass(200, { width_type: 'q', width: 1 })
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#highpass | FFmpeg highpass filter}
-     */
-    highpass(frequency, options) {
-        let filter = `highpass=f=${frequency}`;
-        if (options) {
-            for (const [key, value] of Object.entries(options)) {
-                filter += `:${key}=${value}`;
-            }
-        }
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a lowpass filter to remove high frequencies.
-     *
-     * @param frequency - Cutoff frequency in Hz
-     *
-     * @param options - Additional filter options
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.lowpass(5000)  // Remove frequencies above 5000Hz
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#lowpass | FFmpeg lowpass filter}
-     */
-    lowpass(frequency, options) {
-        let filter = `lowpass=f=${frequency}`;
-        if (options) {
-            for (const [key, value] of Object.entries(options)) {
-                filter += `:${key}=${value}`;
-            }
-        }
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a bandpass filter to keep only a frequency band.
-     *
-     * @param frequency - Center frequency in Hz
-     *
-     * @param options - Additional filter options
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.bandpass(1000)  // Keep frequencies around 1000Hz
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#bandpass | FFmpeg bandpass filter}
-     */
-    bandpass(frequency, options) {
-        let filter = `bandpass=f=${frequency}`;
-        if (options) {
-            for (const [key, value] of Object.entries(options)) {
-                filter += `:${key}=${value}`;
-            }
-        }
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds an equalizer filter for frequency band adjustment.
-     *
-     * @param frequency - Center frequency in Hz
-     *
-     * @param width - Band width
-     *
-     * @param gain - Gain in dB
-     *
-     * @param width_type - Width type (optional)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.equalizer(1000, 2, 5)        // Boost 1000Hz by 5dB
-     * chain.equalizer(1000, 2, 5, 'q')   // Use Q factor for width
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#equalizer | FFmpeg equalizer filter}
-     */
-    equalizer(frequency, width, gain, width_type) {
-        let filter = `equalizer=f=${frequency}`;
-        if (width_type) {
-            filter += `:width_type=${width_type}`;
-        }
-        filter += `:width=${width}:gain=${gain}`;
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a compressor filter for dynamic range compression.
-     *
-     * @param options - Compressor parameters
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.compressor()  // Default compression
-     * chain.compressor({
-     *   threshold: 0.5,
-     *   ratio: 4,
-     *   attack: 5,
-     *   release: 50
-     * })
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#acompressor | FFmpeg acompressor filter}
-     */
-    compressor(options) {
-        if (!options || Object.keys(options).length === 0) {
-            this.add('acompressor');
-        }
-        else {
-            let filter = 'acompressor';
-            const params = [];
-            for (const [key, value] of Object.entries(options)) {
-                params.push(`${key}=${value}`);
-            }
-            filter += '=' + params.join(':');
-            this.add(filter);
-        }
-        return this;
-    }
-    /**
-     * Adds an atrim filter to trim audio.
-     *
-     * @param start - Start time in seconds
-     *
-     * @param end - End time in seconds (optional)
-     *
-     * @param duration - Duration in seconds (optional)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * chain.atrim(10, 20)  // Extract audio from 10s to 20s
-     * ```
-     *
-     * @see {@link https://ffmpeg.org/ffmpeg-filters.html#atrim | FFmpeg atrim filter}
-     */
-    atrim(start, end, duration) {
-        let filter = `atrim=start=${start}`;
-        if (end !== undefined)
-            filter += `:end=${end}`;
-        if (duration !== undefined)
-            filter += `:duration=${duration}`;
-        this.add(filter);
-        return this;
-    }
-    /**
-     * Adds a whisper filter for audio transcription using whisper.cpp.
-     * Transcribes audio and adds metadata to frames (lavfi.whisper.text, lavfi.whisper.duration).
-     *
-     * @param options - Whisper transcription options
-     *
-     * @param options.model - Path to whisper.cpp model file
-     *
-     * @param options.language - Language for transcription (default: 'auto')
-     *
-     * @param options.queue - Audio queue size in seconds (default: 3)
-     *
-     * @param options.useGpu - Use GPU for processing (default: true)
-     *
-     * @param options.gpuDevice - GPU device to use (default: 0)
-     *
-     * @param options.destination - Output destination for transcripts
-     *
-     * @param options.format - Output format: text|srt|json (default: 'text')
-     *
-     * @param options.vadModel - Path to VAD model file (optional)
-     *
-     * @param options.vadThreshold - VAD threshold 0.0-1.0 (default: 0.5)
-     *
-     * @param options.vadMinSpeechDuration - Minimum speech duration for VAD in seconds (default: 0.1)
-     *
-     * @param options.vadMinSilenceDuration - Minimum silence duration for VAD in seconds (default: 0.5)
-     *
-     * @returns This instance for chaining
-     *
-     * @example
-     * ```typescript
-     * // Basic transcription
-     * chain.whisper({
-     *   model: '/path/to/ggml-base.bin'
-     * });
+     * // Basic transcription
+     * chain.whisper({
+     *   model: '/path/to/ggml-base.bin'
+     * });
      *
      * // With language and output
      * chain.whisper({
@@ -1887,31 +1119,6 @@ export class FilterPreset {
         this.add('hwdownload');
         return this;
     }
-    /**
-     * 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) {
-        this.add(derive ? `hwmap=derive_device=${derive}` : 'hwmap');
-        return this;
-    }
     /**
      * Adds a filter to the chain.
      *
@@ -2149,4 +1356,119 @@ export class FilterPreset {
         }
     }
 }
+/**
+ * Type-safe builder for `filter_complex` graph strings.
+ *
+ * Composes one or more labeled filter chains - each with optional input/output
+ * pad labels and a sequence of type-safe {@link FilterPreset.filter} calls - and
+ * renders them to the description string consumed by
+ * {@link FilterComplexAPI.create}. Provides the same autocomplete and enum
+ * validation as {@link FilterPreset}, but for multi-input/output graphs.
+ *
+ * @example
+ * ```typescript
+ * const graph = FilterComplexGraph.create()
+ *   .chain({ inputs: ['0:v', '1:v'], outputs: 'tmp' }, (c) => c.filter('overlay', { x: 100, y: 50 }))
+ *   .chain({ inputs: 'tmp', outputs: 'out' }, (c) => c.filter('hue', { s: 0 }))
+ *   .build();
+ * // "[0:v][1:v]overlay=x=100:y=50[tmp];[tmp]hue=s=0[out]"
+ *
+ * using complex = FilterComplexAPI.create(graph, {
+ *   inputs: [{ label: '0:v' }, { label: '1:v' }],
+ *   outputs: [{ label: 'out' }],
+ * });
+ * ```
+ */
+export class FilterComplexGraph {
+    chains = [];
+    /**
+     * Create a new filter-complex graph builder.
+     *
+     * @returns A new builder instance
+     *
+     * @example
+     * ```typescript
+     * const graph = FilterComplexGraph.create();
+     * ```
+     */
+    static create() {
+        return new FilterComplexGraph();
+    }
+    /**
+     * Add a labeled filter chain to the graph.
+     *
+     * The chain's filters are built via a callback that receives a
+     * {@link FilterPreset} for type-safe `filter()` composition.
+     *
+     * @param labels - Optional input and output pad labels
+     *
+     * @param labels.inputs - Input pad label(s) prepended to the chain
+     *
+     * @param labels.outputs - Output pad label(s) appended to the chain
+     *
+     * @param build - Callback composing the chain's filters
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * graph.chain({ inputs: ['0:v', '1:v'], outputs: 'out' }, (c) =>
+     *   c.filter('overlay', { x: 0, y: 0 }).filter('hue', { s: 0 }),
+     * );
+     * ```
+     */
+    chain(labels, build) {
+        const preset = FilterPreset.chain();
+        const filterString = build(preset).build();
+        this.chains.push(`${this.renderLabels(labels.inputs)}${filterString}${this.renderLabels(labels.outputs)}`);
+        return this;
+    }
+    /**
+     * Add a raw chain segment to the graph.
+     *
+     * Escape hatch for graph syntax not expressible through {@link chain}.
+     *
+     * @param segment - Raw chain string (e.g. `'[0:v]split[a][b]'`)
+     *
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * graph.custom('[0:v]split[a][b]');
+     * ```
+     */
+    custom(segment) {
+        this.chains.push(segment);
+        return this;
+    }
+    /**
+     * Build the final filter-complex description string.
+     *
+     * @returns The graph description (chains joined by `;`)
+     *
+     * @example
+     * ```typescript
+     * const description = graph.build();
+     * ```
+     */
+    build() {
+        return this.chains.join(';');
+    }
+    /**
+     * Wrap pad labels in `[...]`.
+     *
+     * @param labels - A single label, an array of labels, or undefined
+     *
+     * @returns The bracketed label string (empty when no labels)
+     *
+     * @internal
+     */
+    renderLabels(labels) {
+        if (!labels) {
+            return '';
+        }
+        const list = Array.isArray(labels) ? labels : [labels];
+        return list.map((label) => `[${label}]`).join('');
+    }
+}
 //# sourceMappingURL=filter-presets.js.map