ff_filter/graph/

filter_step.rs

//! Internal filter step representation.

use std::time::Duration;

use super::FfmpegToken;
use super::builder::FilterGraphBuilder;
use super::types::{
    DrawTextOptions, EqBand, PitchAlgo, Rgb, ScaleAlgorithm, ToneMap, XfadeTransition, YadifMode,
};

use crate::animation::{AnimatedValue, AnimationEntry, AnimationTrack, Keyframe};
use crate::blend::BlendMode;
use crate::composite::CompositeOp;
use ff_format::{AlphaMode, ColorPrimaries, ColorRange, ColorSpace, ColorTransfer, PixelFormat};

/// Escapes a filesystem path for use as a value inside an `FFmpeg` filter
/// argument string (e.g. `lut3d`'s `file=` option).
///
/// `FFmpeg`'s filter-argument parser treats `:` as an option separator and `\`
/// as an escape character, so Windows paths like `D:\dir\file.cube` break the
/// parser. Normalising backslashes to forward slashes (accepted on Windows) and
/// escaping the drive colon as `\:` yields a value the parser accepts.
pub(crate) fn escape_filter_path(path: &str) -> String {
    path.replace('\\', "/").replace(':', "\\:")
}

// FilterStep

/// A single step in a filter chain.
///
/// Used by [`crate::FilterGraphBuilder`] to build pipeline filter graphs, and by
/// [`crate::AudioTrack::effects`] to attach per-track effects in a multi-track mix.
// Open catalog: new filter steps are added over time (e.g. `Raw`), so downstream
// matches must carry a `_` arm.
#[non_exhaustive]
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum FilterStep {
    /// Convert video to a suitable pixel format from the given options.
    Format {
        pix_fmts: Vec<PixelFormat>,
        color_spaces: Vec<ColorSpace>,
        color_ranges: Vec<ColorRange>,
    },

    /// Tag the stream's colour metadata via the `setparams` filter.
    ///
    /// Each field is emitted only when `Some` **and** its `FfmpegToken` is
    /// `Some` (e.g. `Unknown` → skipped), so an all-`None` step yields empty
    /// args. This is the consumer for `ColorPrimaries` / `ColorTransfer`, whose
    /// tokens the `format` filter has no option for.
    SetParams {
        color_space: Option<ColorSpace>,
        color_range: Option<ColorRange>,
        color_primaries: Option<ColorPrimaries>,
        color_trc: Option<ColorTransfer>,
    },

    /// Trim: keep only frames in `[start, end)` seconds. Either bound may be
    /// `None` for an open range (`start=None` keeps from 0; `end=None` keeps to
    /// end-of-stream).
    Trim {
        start: Option<f64>,
        end: Option<f64>,
    },
    /// Reset timestamps to start at zero (`setpts=PTS-STARTPTS`). Typically
    /// follows a [`Trim`](Self::Trim) so a placed clip's timeline offset is
    /// applied from zero.
    ResetPts,
    /// Shift every frame's presentation timestamp forward by `seconds`
    /// (`setpts=PTS+{seconds}/TB`). Places a layer later on the output timeline.
    OffsetPts { seconds: f64 },
    /// Scale to a new resolution using the given resampling algorithm.
    Scale {
        width: u32,
        height: u32,
        algorithm: ScaleAlgorithm,
    },
    /// Crop a rectangular region.
    Crop {
        x: u32,
        y: u32,
        width: u32,
        height: u32,
    },
    /// Overlay a second stream at position `(x, y)`.
    Overlay { x: i32, y: i32 },
    /// Fade-in from black starting at `start` seconds, over `duration` seconds.
    FadeIn { start: f64, duration: f64 },
    /// Fade-out to black starting at `start` seconds, over `duration` seconds.
    FadeOut { start: f64, duration: f64 },
    /// Audio fade-in from silence starting at `start` seconds, over `duration` seconds.
    AFadeIn { start: f64, duration: f64 },
    /// Audio fade-out to silence starting at `start` seconds, over `duration` seconds.
    AFadeOut { start: f64, duration: f64 },
    /// Fade-in from white starting at `start` seconds, over `duration` seconds.
    FadeInWhite { start: f64, duration: f64 },
    /// Fade-out to white starting at `start` seconds, over `duration` seconds.
    FadeOutWhite { start: f64, duration: f64 },
    /// Rotate clockwise by `angle_degrees`, filling exposed areas with `fill_color`.
    Rotate {
        angle_degrees: f64,
        fill_color: String,
    },
    /// HDR-to-SDR tone mapping.
    ToneMap(ToneMap),
    /// Adjust audio volume (in dB; negative = quieter).
    Volume(f64),
    /// Mix `n` audio inputs together (additive: the inputs are summed, not
    /// averaged, via `normalize=0`).
    Amix(usize),
    /// Multi-band parametric equalizer (low-shelf, high-shelf, or peak bands).
    ///
    /// Each band maps to its own `FFmpeg` filter node chained in sequence.
    /// The `bands` vec must not be empty.
    ParametricEq { bands: Vec<EqBand> },
    /// Apply a 3D LUT from a `.cube` or `.3dl` file.
    Lut3d { path: String },
    /// Brightness/contrast/saturation adjustment via `FFmpeg` `eq` filter.
    ///
    /// `temperature`/`tint` are carried for the derive-to-ff-render `ColorGradeNode`
    /// mapping (GPU-default path) and are **not** applied by the CPU `eq` filter, which
    /// has no such option; they are a GPU-only enrichment (like `MotionBlur.sub_frames`
    /// on the CPU `tblend`). Range −1.0..=1.0 each, neutral 0.0.
    Eq {
        brightness: f32,
        contrast: f32,
        saturation: f32,
        /// Colour temperature offset (−1.0 cool/blue, +1.0 warm/orange). GPU-only.
        temperature: f32,
        /// Colour tint offset (−1.0 magenta, +1.0 green). GPU-only.
        tint: f32,
    },
    /// Brightness / contrast / saturation / gamma via `FFmpeg` `eq` filter (optionally animated).
    ///
    /// Arguments are evaluated at [`Duration::ZERO`] for the initial graph build.
    /// Per-frame updates are applied via `avfilter_graph_send_command` in #363.
    ///
    /// `temperature`/`tint` are carried for the GPU `ColorGradeNode` mapping and are
    /// **not** applied by the CPU `eq` filter (a GPU-only enrichment; see [`Self::Eq`]).
    EqAnimated {
        /// Brightness offset. Range: −1.0 – 1.0 (neutral: 0.0).
        brightness: AnimatedValue<f64>,
        /// Contrast multiplier. Range: 0.0 – 3.0 (neutral: 1.0).
        contrast: AnimatedValue<f64>,
        /// Saturation multiplier. Range: 0.0 – 3.0 (neutral: 1.0; 0.0 = grayscale).
        saturation: AnimatedValue<f64>,
        /// Global gamma correction. Range: 0.1 – 10.0 (neutral: 1.0).
        gamma: AnimatedValue<f64>,
        /// Colour temperature offset (−1.0 – 1.0; neutral 0.0). GPU-only.
        temperature: AnimatedValue<f64>,
        /// Colour tint offset (−1.0 – 1.0; neutral 0.0). GPU-only.
        tint: AnimatedValue<f64>,
    },
    /// Three-way color balance (shadows / midtones / highlights) via `FFmpeg` `colorbalance` filter
    /// (optionally animated).
    ///
    /// Each tuple is `(R, G, B)`. Valid range per component: −1.0 – 1.0 (neutral: 0.0).
    ///
    /// Arguments are evaluated at [`Duration::ZERO`] for the initial graph build.
    /// Per-frame updates are applied via `avfilter_graph_send_command` in #363.
    ColorBalanceAnimated {
        /// Shadows (lift) correction per channel. `FFmpeg` params: `"rs"`, `"gs"`, `"bs"`.
        lift: AnimatedValue<(f64, f64, f64)>,
        /// Midtones (gamma) correction per channel. `FFmpeg` params: `"rm"`, `"gm"`, `"bm"`.
        gamma: AnimatedValue<(f64, f64, f64)>,
        /// Highlights (gain) correction per channel. `FFmpeg` params: `"rh"`, `"gh"`, `"bh"`.
        gain: AnimatedValue<(f64, f64, f64)>,
    },
    /// Per-channel RGB color curves adjustment.
    Curves {
        master: Vec<(f32, f32)>,
        r: Vec<(f32, f32)>,
        g: Vec<(f32, f32)>,
        b: Vec<(f32, f32)>,
    },
    /// White balance correction via `colorchannelmixer`.
    WhiteBalance { temperature_k: u32, tint: f32 },
    /// Hue rotation by an arbitrary angle.
    Hue { degrees: f32 },
    /// Per-channel gamma correction via `FFmpeg` `eq` filter.
    Gamma { r: f32, g: f32, b: f32 },
    /// Three-way colour corrector (lift / gamma / gain) via `FFmpeg` `curves` filter.
    ThreeWayCC {
        /// Affects shadows (blacks). Neutral: `Rgb::NEUTRAL`.
        lift: Rgb,
        /// Affects midtones. Neutral: `Rgb::NEUTRAL`. All components must be > 0.0.
        gamma: Rgb,
        /// Affects highlights (whites). Neutral: `Rgb::NEUTRAL`.
        gain: Rgb,
    },
    /// Three-way (lift/gamma/gain) colour corrector with optionally animated
    /// per-channel parameters.
    ///
    /// Parameters are evaluated at [`Duration::ZERO`] for the graph build. `curves`
    /// takes string curve options rather than scalars, so it is not driven by
    /// `send_command` here: the CPU (`libavfilter`) path renders the `Duration::ZERO`
    /// curves statically; the GPU path (`ff_render::ColorWheelsNode`) animates the
    /// parameters per frame. Each `[R, G, B]` array carries the per-channel tracks,
    /// with the same `Rgb::NEUTRAL` (1.0) convention as [`ThreeWayCC`](Self::ThreeWayCC).
    ThreeWayCCAnimated {
        /// Shadows (lift) per channel `[R, G, B]`. Neutral: 1.0.
        lift: [AnimatedValue<f64>; 3],
        /// Midtones (gamma) per channel `[R, G, B]`. Neutral: 1.0; must be > 0.0.
        gamma: [AnimatedValue<f64>; 3],
        /// Highlights (gain) per channel `[R, G, B]`. Neutral: 1.0.
        gain: [AnimatedValue<f64>; 3],
    },
    /// Vignette effect via `FFmpeg` `vignette` filter.
    Vignette {
        /// Radius angle in radians (valid range: 0.0 – π/2 ≈ 1.5708). Default: π/5 ≈ 0.628.
        angle: f32,
        /// Horizontal centre of the vignette. `0.0` maps to `w/2`.
        x0: f32,
        /// Vertical centre of the vignette. `0.0` maps to `h/2`.
        y0: f32,
    },
    /// Vignette with an optionally animated normalised amount.
    ///
    /// `amount` is a normalised darkening strength in `[0, 1]`; it maps to the
    /// `vignette` filter's `angle` (radians) as `amount * PI/2`. `vignette`
    /// re-evaluates `angle` per frame under `eval=frame`, so a `Track` self-animates
    /// via a `t`-expression (like [`RotateAnimated`](Self::RotateAnimated)); a
    /// `Static` renders a plain static vignette.
    VignetteAnimated {
        /// Normalised darkening amount, evaluated to `[0, 1]` at `Duration::ZERO`.
        amount: AnimatedValue<f64>,
        /// Horizontal centre. `0.0` maps to `w/2`.
        x0: f32,
        /// Vertical centre. `0.0` maps to `h/2`.
        y0: f32,
    },
    /// HSL adjustment via `FFmpeg` `hue` filter (`ff_render::HslNode` on the GPU).
    ///
    /// `hue` works in YUV (a chroma rotation for hue/saturation, a luma add for
    /// brightness), so it approximates the GPU node's HSL-space adjustment within a
    /// documented tolerance. `lightness` is scaled to the filter's `b` brightness.
    Hsl {
        /// Hue rotation in degrees.
        hue: f32,
        /// Saturation multiplier (neutral `1.0`).
        saturation: f32,
        /// Lightness offset in `[-1, 1]` (scaled to the `hue` filter's brightness).
        lightness: f32,
    },
    /// HSL adjustment with optionally animated parameters.
    ///
    /// The GPU animates per frame; the CPU (`libavfilter`) path renders the
    /// `Duration::ZERO` values (`hue`'s options accept `t`-expressions, but the CPU
    /// path is kept static so the GPU-default path is the single animated one).
    HslAnimated {
        /// Hue rotation in degrees, evaluated at `Duration::ZERO`.
        hue: AnimatedValue<f64>,
        /// Saturation multiplier, evaluated at `Duration::ZERO`.
        saturation: AnimatedValue<f64>,
        /// Lightness offset in `[-1, 1]`, evaluated at `Duration::ZERO`.
        lightness: AnimatedValue<f64>,
    },
    /// Horizontal flip (mirror left-right).
    HFlip,
    /// Vertical flip (mirror top-bottom).
    VFlip,
    /// Reverse video playback (buffers entire clip in memory — use only on short clips).
    Reverse,
    /// Reverse audio playback (buffers entire clip in memory — use only on short clips).
    AReverse,
    /// Pad to a target resolution with a fill color (letterbox / pillarbox).
    Pad {
        /// Target canvas width in pixels.
        width: u32,
        /// Target canvas height in pixels.
        height: u32,
        /// Horizontal offset of the source frame within the canvas.
        /// Negative values are replaced with `(ow-iw)/2` (centred).
        x: i32,
        /// Vertical offset of the source frame within the canvas.
        /// Negative values are replaced with `(oh-ih)/2` (centred).
        y: i32,
        /// Fill color (any `FFmpeg` color string, e.g. `"black"`, `"0x000000"`).
        color: String,
    },
    /// Scale (preserving aspect ratio) then centre-pad to fill target dimensions
    /// (letterbox or pillarbox as required).
    ///
    /// Implemented as a `scale` filter with `force_original_aspect_ratio=decrease`
    /// followed by a `pad` filter that centres the scaled frame on the canvas.
    FitToAspect {
        /// Target canvas width in pixels.
        width: u32,
        /// Target canvas height in pixels.
        height: u32,
        /// Fill color for the bars (any `FFmpeg` color string, e.g. `"black"`).
        color: String,
    },
    /// Scale (preserving aspect ratio) to *cover* the target dimensions, then
    /// centre-crop the overflow (no bars).
    ///
    /// Implemented as a `scale` filter with `force_original_aspect_ratio=increase`
    /// followed by a `crop` filter that centres the scaled frame on the canvas.
    /// The counterpart to [`FitToAspect`](Self::FitToAspect) (cover vs contain).
    FillToAspect {
        /// Target canvas width in pixels.
        width: u32,
        /// Target canvas height in pixels.
        height: u32,
    },
    /// Gaussian blur with configurable radius.
    ///
    /// `sigma` is the blur radius. Valid range: 0.0 – 10.0 (values near 0.0 are
    /// nearly a no-op; higher values produce a stronger blur).
    GBlur {
        /// Blur radius (standard deviation). Must be ≥ 0.0.
        sigma: f32,
    },
    /// Crop with optionally animated boundaries (pixels, `f64` for sub-pixel precision).
    ///
    /// Arguments are evaluated at [`Duration::ZERO`] for the initial graph build.
    /// Per-frame updates are applied via `avfilter_graph_send_command` in #363.
    CropAnimated {
        /// X offset of the top-left corner, in pixels.
        x: AnimatedValue<f64>,
        /// Y offset of the top-left corner, in pixels.
        y: AnimatedValue<f64>,
        /// Width of the cropped region. Must evaluate to > 0 at `Duration::ZERO`.
        width: AnimatedValue<f64>,
        /// Height of the cropped region. Must evaluate to > 0 at `Duration::ZERO`.
        height: AnimatedValue<f64>,
    },
    /// Gaussian blur with an optionally animated sigma (blur radius).
    ///
    /// Arguments are evaluated at [`Duration::ZERO`] for the initial graph build.
    /// Per-frame updates are applied via `avfilter_graph_send_command` in #363.
    GBlurAnimated {
        /// Blur radius (standard deviation). Must evaluate to ≥ 0.0 at `Duration::ZERO`.
        sigma: AnimatedValue<f64>,
    },
    /// Scale (resize / zoom) with optionally animated width/height, in pixels.
    ///
    /// Unlike `crop`, `scale` cannot be driven by `send_command` (its output size is
    /// fixed at init); instead this **self-animates** via `scale=eval=frame` with the
    /// width/height tracks compiled to `t`-expressions
    /// ([`AnimationTrack::to_ffmpeg_expr`](crate::animation::AnimationTrack::to_ffmpeg_expr)).
    /// The same expression is placed in both the preview and export graphs, so it
    /// animates identically. When both are `Static` it renders a plain static `scale`.
    ScaleAnimated {
        /// Target width in pixels (expression when a `Track`).
        width: AnimatedValue<f64>,
        /// Target height in pixels (expression when a `Track`).
        height: AnimatedValue<f64>,
        /// Resampling algorithm (`flags=`).
        algorithm: ScaleAlgorithm,
    },
    /// Rotate with an optionally animated angle (degrees), filling exposed corners
    /// with `fill_color`.
    ///
    /// `rotate`'s `angle` option is an expression re-evaluated every frame, so this
    /// **self-animates** via `rotate=angle=EXPR`: the angle track is compiled to a
    /// `t`-expression ([`AnimationTrack::to_ffmpeg_expr`](crate::animation::AnimationTrack::to_ffmpeg_expr))
    /// and converted degrees→radians. The same expression drives preview and export.
    /// Output size stays `iw`×`ih` (corners clipped / filled). `Static` → a plain
    /// rotate.
    RotateAnimated {
        /// Rotation angle in **degrees** (clockwise); an expression when a `Track`.
        angle: AnimatedValue<f64>,
        /// Colour for exposed corners (e.g. `"black"`, `"none"` for transparent).
        fill_color: String,
    },
    /// Sharpen or blur via unsharp mask (luma + chroma strength).
    ///
    /// Positive values sharpen; negative values blur. Valid range for each
    /// component: −1.5 – 1.5.
    Unsharp {
        /// Luma (brightness) sharpening/blurring amount. Range: −1.5 – 1.5.
        luma_strength: f32,
        /// Chroma (colour) sharpening/blurring amount. Range: −1.5 – 1.5.
        chroma_strength: f32,
    },
    /// Unsharp mask with an optionally animated luma/chroma amount.
    ///
    /// Arguments are evaluated at [`Duration::ZERO`] for the graph build. Unlike
    /// [`GBlurAnimated`](Self::GBlurAnimated), `FFmpeg`'s `unsharp` exposes **no
    /// runtime-settable parameter** (verified against the pinned 7.1/8.0 source),
    /// so it cannot be driven by `send_command` and it has no per-frame expression.
    /// On the CPU (`libavfilter`) path it therefore renders the `Duration::ZERO`
    /// value statically; the GPU path animates it by re-evaluating per frame.
    UnsharpAnimated {
        /// Luma amount. Evaluated to −1.5 – 1.5 at `Duration::ZERO`.
        luma_strength: AnimatedValue<f64>,
        /// Chroma amount. Evaluated to −1.5 – 1.5 at `Duration::ZERO`.
        chroma_strength: AnimatedValue<f64>,
    },
    /// High Quality 3D noise reduction (`hqdn3d`).
    ///
    /// Typical values: `luma_spatial=4.0`, `chroma_spatial=3.0`,
    /// `luma_tmp=6.0`, `chroma_tmp=4.5`. All values must be ≥ 0.0.
    Hqdn3d {
        /// Spatial luma noise reduction strength. Must be ≥ 0.0.
        luma_spatial: f32,
        /// Spatial chroma noise reduction strength. Must be ≥ 0.0.
        chroma_spatial: f32,
        /// Temporal luma noise reduction strength. Must be ≥ 0.0.
        luma_tmp: f32,
        /// Temporal chroma noise reduction strength. Must be ≥ 0.0.
        chroma_tmp: f32,
    },
    /// Non-local means noise reduction (`nlmeans`).
    ///
    /// `strength` controls the denoising intensity; range 1.0–30.0.
    /// Higher values remove more noise but are significantly more CPU-intensive.
    ///
    /// NOTE: nlmeans is CPU-intensive; avoid for real-time pipelines.
    Nlmeans {
        /// Denoising strength. Must be in the range [1.0, 30.0].
        strength: f32,
    },
    /// Deinterlace using the `yadif` filter.
    Yadif {
        /// Deinterlacing mode controlling output frame rate and spatial checks.
        mode: YadifMode,
    },
    /// Cross-dissolve transition between two video streams (`xfade`).
    ///
    /// Requires two input slots: slot 0 is clip A, slot 1 is clip B.
    /// `duration` is the overlap length in seconds; `offset` is the PTS
    /// offset (in seconds) at which clip B begins.
    XFade {
        /// Transition style.
        transition: XfadeTransition,
        /// Overlap duration in seconds. Must be > 0.0.
        duration: f64,
        /// PTS offset (seconds) where clip B starts.
        offset: f64,
    },
    /// Draw text onto the video using the `drawtext` filter.
    DrawText {
        /// Full set of drawtext parameters.
        opts: DrawTextOptions,
    },
    /// Burn-in SRT subtitles (hard subtitles) using the `subtitles` filter.
    SubtitlesSrt {
        /// Absolute or relative path to the `.srt` file.
        path: String,
        /// Optional ASS style override for the `subtitles` filter's `force_style`
        /// option, e.g. `"Fontsize=24,PrimaryColour=&H00FFFFFF&,Alignment=2"`.
        /// `None` uses the file's default styling. (The `ass` filter has no
        /// `force_style`; ASS files carry their own styles.)
        force_style: Option<String>,
    },
    /// Burn-in ASS/SSA styled subtitles using the `ass` filter.
    SubtitlesAss {
        /// Absolute or relative path to the `.ass` or `.ssa` file.
        path: String,
    },
    /// Playback speed change using `setpts` (video) and chained `atempo` (audio).
    ///
    /// `factor > 1.0` = fast motion; `factor < 1.0` = slow motion.
    /// Valid range: 0.1–100.0.
    ///
    /// Video path: `setpts=PTS/{factor}`.
    /// Audio path: the `atempo` filter only accepts [0.5, 2.0] per instance;
    /// `filter_inner` chains multiple instances to cover the full range.
    Speed {
        /// Speed multiplier. Must be in [0.1, 100.0].
        factor: f64,
    },
    /// EBU R128 two-pass loudness normalization.
    ///
    /// Pass 1 measures integrated loudness with `ebur128=peak=true:metadata=1`.
    /// Pass 2 applies a linear volume correction so the output reaches `target_lufs`.
    /// All audio frames are buffered in memory between the two passes — use only
    /// for clips that fit comfortably in RAM.
    LoudnessNormalize {
        /// Target integrated loudness in LUFS (e.g. −23.0). Must be < 0.0.
        target_lufs: f32,
        /// True-peak ceiling in dBTP (e.g. −1.0). Must be ≤ 0.0.
        true_peak_db: f32,
        /// Target loudness range in LU (e.g. 7.0). Must be > 0.0.
        lra: f32,
    },
    /// Peak-level two-pass normalization using `astats`.
    ///
    /// Pass 1 measures the true peak with `astats=metadata=1`.
    /// Pass 2 applies `volume={gain}dB` so the output peak reaches `target_db`.
    /// All audio frames are buffered in memory between passes — use only
    /// for clips that fit comfortably in RAM.
    NormalizePeak {
        /// Target peak level in dBFS (e.g. −1.0). Must be ≤ 0.0.
        target_db: f32,
    },
    /// Noise gate via `FFmpeg`'s `agate` filter.
    ///
    /// Audio below `threshold_db` is attenuated; audio above passes through.
    /// The threshold is converted from dBFS to the linear scale expected by
    /// `agate`'s `threshold` parameter (`linear = 10^(dB/20)`).
    ANoiseGate {
        /// Gate open/close threshold in dBFS (e.g. −40.0).
        threshold_db: f32,
        /// Attack time in milliseconds — how quickly the gate opens. Must be > 0.0.
        attack_ms: f32,
        /// Release time in milliseconds — how quickly the gate closes. Must be > 0.0.
        release_ms: f32,
    },
    /// Dynamic range compressor via `FFmpeg`'s `acompressor` filter.
    ///
    /// Reduces the dynamic range of the audio signal: peaks above
    /// `threshold_db` are attenuated by `ratio`:1.  `makeup_db` applies
    /// additional gain after compression to restore perceived loudness.
    ACompressor {
        /// Compression threshold in dBFS (e.g. −20.0).
        threshold_db: f32,
        /// Compression ratio (e.g. 4.0 = 4:1). Must be ≥ 1.0.
        ratio: f32,
        /// Attack time in milliseconds. Must be > 0.0.
        attack_ms: f32,
        /// Release time in milliseconds. Must be > 0.0.
        release_ms: f32,
        /// Make-up gain in dB applied after compression (e.g. 6.0).
        makeup_db: f32,
    },
    /// Downmix stereo to mono via `FFmpeg`'s `pan` filter.
    ///
    /// Both channels are mixed with equal weight:
    /// `mono|c0=0.5*c0+0.5*c1`.  The output has a single channel.
    StereoToMono,
    /// Remap audio channels using `FFmpeg`'s `channelmap` filter.
    ///
    /// `mapping` is a `|`-separated list of output channel names taken
    /// from input channels, e.g. `"FR|FL"` swaps left and right.
    /// Must not be empty.
    ChannelMap {
        /// `FFmpeg` channelmap mapping expression (e.g. `"FR|FL"`).
        mapping: String,
    },
    /// A/V sync correction via audio delay or advance.
    ///
    /// Positive `ms`: uses `FFmpeg`'s `adelay` filter to shift audio later.
    /// Negative `ms`: uses `FFmpeg`'s `atrim` filter to trim the audio start,
    /// effectively advancing audio by `|ms|` milliseconds.
    /// Zero `ms`: uses `adelay` with zero delay (no-op).
    AudioDelay {
        /// Delay in milliseconds. Positive = delay; negative = advance.
        ms: f64,
    },
    /// Audio trim: keep only samples in `[start, end)` seconds (`atrim`). Either
    /// bound may be `None` for an open range. The audio counterpart of
    /// [`Trim`](Self::Trim).
    ATrim {
        start: Option<f64>,
        end: Option<f64>,
    },
    /// Reset audio timestamps to start at zero (`asetpts=PTS-STARTPTS`). Typically
    /// follows an [`ATrim`](Self::ATrim) so a placed track's delay is applied from
    /// zero. The audio counterpart of [`ResetPts`](Self::ResetPts).
    AResetPts,
    /// Concatenate `n` sequential video input segments via `FFmpeg`'s `concat` filter.
    ///
    /// Requires `n` video input slots (0 through `n-1`). `n` must be ≥ 2.
    ConcatVideo {
        /// Number of video input segments to concatenate. Must be ≥ 2.
        n: u32,
    },
    /// Concatenate `n` sequential audio input segments via `FFmpeg`'s `concat` filter.
    ///
    /// Requires `n` audio input slots (0 through `n-1`). `n` must be ≥ 2.
    ConcatAudio {
        /// Number of audio input segments to concatenate. Must be ≥ 2.
        n: u32,
    },
    /// Freeze a single frame for a configurable duration using `FFmpeg`'s `loop` filter.
    ///
    /// The frame nearest to `pts` seconds is held for `duration` seconds, then
    /// playback resumes. Frame numbers are approximated using a 25 fps assumption;
    /// accuracy depends on the source stream's actual frame rate.
    FreezeFrame {
        /// Timestamp of the frame to freeze, in seconds. Must be >= 0.0.
        pts: f64,
        /// Duration to hold the frozen frame, in seconds. Must be > 0.0.
        duration: f64,
    },
    /// Scrolling text ticker (right-to-left) using the `drawtext` filter.
    ///
    /// The text starts off-screen to the right and scrolls left at
    /// `speed_px_per_sec` pixels per second using the expression
    /// `x = w - t * speed`.
    Ticker {
        /// Text to display. Special characters (`\`, `:`, `'`) are escaped.
        text: String,
        /// Y position as an `FFmpeg` expression, e.g. `"h-50"` or `"10"`.
        y: String,
        /// Horizontal scroll speed in pixels per second (must be > 0.0).
        speed_px_per_sec: f32,
        /// Font size in points.
        font_size: u32,
        /// Font color as an `FFmpeg` color string, e.g. `"white"` or `"0xFFFFFF"`.
        font_color: String,
    },
    /// Composite a PNG image (watermark / logo) over video with optional opacity.
    ///
    /// This is a compound step: internally it creates a `movie` source, an
    /// optional `scale` filter, a `lut` alpha-scaling filter, and an `overlay`
    /// compositing filter. The image file is loaded once at graph construction
    /// time.
    OverlayImage {
        /// Absolute or relative path to the `.png` file.
        path: String,
        /// Horizontal position as an `FFmpeg` expression, e.g. `"10"` or `"W-w-10"`.
        x: String,
        /// Vertical position as an `FFmpeg` expression, e.g. `"10"` or `"H-h-10"`.
        y: String,
        /// Opacity 0.0 (fully transparent) to 1.0 (fully opaque).
        opacity: f32,
        /// Optional overlay width as an `FFmpeg` `scale` expression, e.g. `"300"`
        /// or `"iw*0.15"` (`iw`/`ih` are the overlay's own dimensions). `-1`
        /// preserves aspect ratio. `None` keeps the image's native width.
        width: Option<String>,
        /// Optional overlay height as an `FFmpeg` `scale` expression. `-1`
        /// preserves aspect ratio. `None` keeps the image's native height.
        height: Option<String>,
    },

    /// Blend a `top` layer over the current stream (bottom) using the given mode.
    ///
    /// This is a compound step:
    /// - **Normal** mode: `[top]colorchannelmixer=aa=<opacity>[top_faded];
    ///   [bottom][top_faded]overlay=format=auto:shortest=1[out]`
    ///   (the `colorchannelmixer` step is omitted when `opacity == 1.0`).
    /// - All other modes return [`crate::FilterError::InvalidConfig`] from
    ///   [`crate::FilterGraphBuilder::build`] until implemented.
    ///
    /// The `top` builder's steps are applied to the second input slot (`in1`).
    /// `opacity` is clamped to `[0.0, 1.0]` by the builder method.
    ///
    /// `Box<FilterGraphBuilder>` is used to break the otherwise-recursive type:
    /// `FilterStep` → `FilterGraphBuilder` → `Vec<FilterStep>`.
    ///
    /// Not serialized: this compositor-internal variant carries a
    /// `FilterGraphBuilder` (which cannot round-trip serde), and it never appears
    /// in the editing model's persisted effect chains.
    #[cfg_attr(feature = "serde", serde(skip))]
    Blend {
        /// Filter pipeline for the top (foreground) layer.
        top: Box<FilterGraphBuilder>,
        /// How the two layers are combined.
        mode: BlendMode,
        /// Opacity of the top layer in `[0.0, 1.0]`; 1.0 = fully opaque.
        opacity: f32,
        /// How the top layer's alpha is interpreted by the `overlay` filter
        /// (`alpha=`). [`AlphaMode::Straight`] is the `FFmpeg` default.
        alpha: AlphaMode,
    },

    /// Composite a `top` layer over the current stream (bottom) using a
    /// Porter-Duff alpha-compositing [`CompositeOp`].
    ///
    /// This is a compound, two-input step (slot 0 = bottom, slot 1 = top with
    /// the `top` builder's steps applied). `Over`/`Under` are built with the
    /// `overlay` filter; the rest use `blend` with a per-channel expression.
    ///
    /// `Box<FilterGraphBuilder>` breaks the otherwise-recursive type, following
    /// the same pattern as [`FilterStep::Blend`].
    ///
    /// Not serialized (compositor-internal; see [`FilterStep::Blend`]).
    #[cfg_attr(feature = "serde", serde(skip))]
    Composite {
        /// The Porter-Duff operator combining the two layers.
        op: CompositeOp,
        /// Filter pipeline for the top (foreground) layer.
        top: Box<FilterGraphBuilder>,
        /// Opacity of the top layer in `[0.0, 1.0]`; 1.0 = fully opaque.
        /// Only affects `Over`/`Under` (the expression operators ignore it).
        opacity: f32,
        /// How the top layer's alpha is interpreted by the `overlay` filter
        /// (`alpha=`). [`AlphaMode::Straight`] is the `FFmpeg` default.
        alpha: AlphaMode,
    },

    /// Remove pixels matching `color` using `FFmpeg`'s `chromakey` filter,
    /// producing a `yuva420p` output with transparent areas where the key
    /// color was detected.
    ///
    /// Use this for YCbCr-encoded sources (most video).  For RGB sources
    /// use `colorkey` instead.
    ChromaKey {
        /// `FFmpeg` color string, e.g. `"green"`, `"0x00FF00"`, `"#00FF00"`.
        color: String,
        /// Match radius in `[0.0, 1.0]`; higher = more pixels removed.
        similarity: f32,
        /// Edge softness in `[0.0, 1.0]`; `0.0` = hard edge.
        blend: f32,
    },

    /// [`ChromaKey`](Self::ChromaKey) with optionally animated `similarity` /
    /// `blend`.
    ///
    /// The GPU animates per frame; the CPU (`libavfilter`) path renders the
    /// `Duration::ZERO` values (`chromakey`'s options are static, so the CPU path
    /// is kept static and the GPU-default path is the single animated one, matching
    /// [`HslAnimated`](Self::HslAnimated)).
    ChromaKeyAnimated {
        /// `FFmpeg` color string, e.g. `"0x00FF00"`.
        color: String,
        /// Match radius in `[0.0, 1.0]`, evaluated at `Duration::ZERO` on the CPU.
        similarity: AnimatedValue<f64>,
        /// Edge softness in `[0.0, 1.0]`, evaluated at `Duration::ZERO` on the CPU.
        blend: AnimatedValue<f64>,
    },

    /// Remove pixels matching `color` in RGB space using `FFmpeg`'s `colorkey`
    /// filter, producing an `rgba` output with transparent areas where the key
    /// color was detected.
    ///
    /// Use this for RGB-encoded sources.  For YCbCr-encoded video (most video)
    /// use `chromakey` instead.
    ColorKey {
        /// `FFmpeg` color string, e.g. `"green"`, `"0x00FF00"`, `"#00FF00"`.
        color: String,
        /// Match radius in `[0.0, 1.0]`; higher = more pixels removed.
        similarity: f32,
        /// Edge softness in `[0.0, 1.0]`; `0.0` = hard edge.
        blend: f32,
    },

    /// Reduce color spill from the key color on subject edges using `FFmpeg`'s
    /// `hue` filter to desaturate the spill hue region.
    ///
    /// Applies `hue=h=0:s=(1.0 - strength)`.  `strength=0.0` leaves the image
    /// unchanged; `strength=1.0` fully desaturates.
    ///
    /// `key_color` is stored for future use by a more targeted per-hue
    /// implementation.
    SpillSuppress {
        /// `FFmpeg` color string identifying the spill color, e.g. `"green"`.
        key_color: String,
        /// Suppression intensity in `[0.0, 1.0]`; `0.0` = no effect, `1.0` = full suppression.
        strength: f32,
    },

    /// Merge a grayscale `matte` as the alpha channel of the input video using
    /// `FFmpeg`'s `alphamerge` filter.
    ///
    /// White (luma=255) in the matte produces fully opaque output; black (luma=0)
    /// produces fully transparent output.
    ///
    /// This is a compound step: the `matte` builder's pipeline is applied to the
    /// second input slot (`in1`) before the `alphamerge` filter is linked.
    ///
    /// `Box<FilterGraphBuilder>` breaks the otherwise-recursive type, following
    /// the same pattern as [`FilterStep::Blend`].
    ///
    /// Not serialized (compositor-internal; see [`FilterStep::Blend`]).
    #[cfg_attr(feature = "serde", serde(skip))]
    AlphaMatte {
        /// Pipeline for the grayscale matte stream (slot 1).
        matte: Box<FilterGraphBuilder>,
    },

    /// Key out pixels by luminance value using `FFmpeg`'s `lumakey` filter.
    ///
    /// Pixels whose normalized luma is within `tolerance` of `threshold` are
    /// made transparent.  When `invert` is `true`, a `geq` filter is appended
    /// to negate the alpha channel, effectively swapping transparent and opaque
    /// regions.
    ///
    /// - `threshold`: luma cutoff in `[0.0, 1.0]`; `0.0` = black, `1.0` = white.
    /// - `tolerance`: match radius around the threshold in `[0.0, 1.0]`.
    /// - `softness`: edge feather width in `[0.0, 1.0]`; `0.0` = hard edge.
    /// - `invert`: when `false`, keys out bright regions (pixels matching the
    ///   threshold); when `true`, the alpha is negated after keying, making
    ///   the complementary region transparent instead.
    ///
    /// Output carries an alpha channel (`yuva420p`).
    LumaKey {
        /// Luma cutoff in `[0.0, 1.0]`.
        threshold: f32,
        /// Match radius around the threshold in `[0.0, 1.0]`.
        tolerance: f32,
        /// Edge feather width in `[0.0, 1.0]`; `0.0` = hard edge.
        softness: f32,
        /// When `true`, the alpha channel is negated after keying.
        invert: bool,
    },

    /// Apply a rectangular alpha mask using `FFmpeg`'s `geq` filter.
    ///
    /// Pixels inside the rectangle defined by (`x`, `y`, `width`, `height`)
    /// are made fully opaque (`alpha=255`); pixels outside are made fully
    /// transparent (`alpha=0`).  When `invert` is `true` the roles are swapped:
    /// inside becomes transparent and outside becomes opaque.
    ///
    /// - `x`, `y`: top-left corner of the rectangle (in pixels).
    /// - `width`, `height`: rectangle dimensions (must be > 0).
    /// - `invert`: when `false`, keeps the interior; when `true`, keeps the
    ///   exterior.
    ///
    /// `width` and `height` are validated in [`build`](FilterGraphBuilder::build);
    /// zero values return [`crate::FilterError::InvalidConfig`].
    ///
    /// The output carries an alpha channel (`rgba`).
    RectMask {
        /// Left edge of the rectangle (pixels from the left).
        x: u32,
        /// Top edge of the rectangle (pixels from the top).
        y: u32,
        /// Width of the rectangle in pixels (must be > 0).
        width: u32,
        /// Height of the rectangle in pixels (must be > 0).
        height: u32,
        /// When `true`, the mask is inverted: outside is opaque, inside is transparent.
        invert: bool,
    },

    /// [`RectMask`](Self::RectMask) with optionally animated `x` / `y` / `width` /
    /// `height`.
    ///
    /// The GPU animates the rectangle per frame; the CPU (`libavfilter`) path renders
    /// the `Duration::ZERO` values (the `geq` rectangle bounds are static, so the CPU
    /// path is kept static and the GPU-default path is the animated one, matching
    /// [`ChromaKeyAnimated`](Self::ChromaKeyAnimated)). `width` / `height` are clamped
    /// to at least `1` at render time so a zero-size frame never fails `geq` build.
    RectMaskAnimated {
        /// Left edge in pixels, evaluated at `Duration::ZERO` on the CPU.
        x: AnimatedValue<f64>,
        /// Top edge in pixels, evaluated at `Duration::ZERO` on the CPU.
        y: AnimatedValue<f64>,
        /// Width in pixels (clamped to `>= 1`), evaluated at `Duration::ZERO` on the CPU.
        width: AnimatedValue<f64>,
        /// Height in pixels (clamped to `>= 1`), evaluated at `Duration::ZERO` on the CPU.
        height: AnimatedValue<f64>,
        /// When `true`, the mask is inverted: outside is opaque, inside is transparent.
        invert: bool,
    },

    /// Set the alpha channel to the frame's own BT.709 luma using `FFmpeg`'s `geq`
    /// filter (a self-referential continuous luma mask).
    ///
    /// `alpha = luma`, where `luma = 0.2126·R + 0.7152·G + 0.0722·B` on the frame's
    /// own gamma-encoded RGB. Bright pixels stay opaque, dark pixels become
    /// transparent. When `invert` is `true`, `255 - luma` is used, so dark pixels
    /// stay opaque. This is the CPU pair of `ff_render::LumaMaskNode` (mask = the
    /// frame itself, which multiplies the existing alpha by `luma`); on an opaque
    /// source `alpha = luma` and `alpha *= luma` coincide, and the coefficients
    /// match exactly. (`geq` exposes no alpha-read function here, so the existing
    /// alpha is replaced rather than multiplied.)
    ///
    /// The output carries an alpha channel (`rgba`).
    LumaMask {
        /// When `true`, use `255 - luma` (dark pixels stay opaque).
        invert: bool,
    },

    /// Feather (soften) the alpha channel edges using a Gaussian blur.
    ///
    /// Splits the stream into a color copy and an alpha copy, blurs the alpha
    /// plane with `gblur=sigma=<radius>`, then re-merges:
    ///
    /// ```text
    /// [in]split=2[color][with_alpha];
    /// [with_alpha]alphaextract[alpha_only];
    /// [alpha_only]gblur=sigma=<radius>[alpha_blurred];
    /// [color][alpha_blurred]alphamerge[out]
    /// ```
    ///
    /// `radius` is the blur kernel half-size in pixels and must be > 0.
    /// Validated in [`build`](FilterGraphBuilder::build); `radius == 0` returns
    /// [`crate::FilterError::InvalidConfig`].
    ///
    /// Typically chained after a keying or masking step
    /// (e.g. [`FilterStep::ChromaKey`], [`FilterStep::RectMask`],
    /// [`FilterStep::PolygonMatte`]).  Applying this step to a fully-opaque
    /// video (no prior alpha) is a no-op because a uniform alpha of 255 blurs
    /// to 255 everywhere.
    FeatherMask {
        /// Gaussian blur kernel half-size in pixels (must be > 0).
        radius: u32,
    },

    /// Simulate motion blur by blending consecutive frames via `FFmpeg`'s `tblend` filter.
    ///
    /// `shutter_angle_degrees` controls the blend ratio; 360° equals a full
    /// frame-period exposure (maximum blur). `sub_frames` is the number of
    /// frames blended and must be in [2, 16]; it is validated by
    /// [`FilterGraph::motion_blur`](crate::FilterGraph::motion_blur).
    MotionBlur {
        /// Shutter angle in degrees (0° = no blur, 360° = full-period blur).
        shutter_angle_degrees: f32,
        /// Number of frames blended. Must be in [2, 16].
        sub_frames: u8,
    },

    /// Motion blur with an optionally animated shutter angle.
    ///
    /// `tblend`'s blend is written as an expression (`all_expr`), and `blend`
    /// re-evaluates that expression per frame with `T` bound to the frame's
    /// presentation time in seconds. So this **self-animates**: the shutter track is
    /// compiled to a `T`-expression
    /// ([`AnimationTrack::to_ffmpeg_expr`](crate::animation::AnimationTrack::to_ffmpeg_expr))
    /// and folded into the same `A`/`B` mix the constant form uses. The same
    /// expression drives preview and export.
    ///
    /// **`T`, not `t`.** `blend`'s expression variables are upper-case (`X Y W H SW
    /// SH T N A B TOP BOTTOM`); a lower-case `t` is not among them and would
    /// evaluate as an unknown.
    ///
    /// A `Static` shutter renders exactly what [`MotionBlur`](Self::MotionBlur)
    /// renders, so the two agree where they overlap.
    MotionBlurAnimated {
        /// Shutter angle in degrees (0° = no blur, 360° = full-period blur); an
        /// expression when a `Track`.
        shutter_angle: AnimatedValue<f64>,
        /// Number of frames blended. Must be in [2, 16].
        sub_frames: u8,
    },

    /// Correct radial lens distortion using two polynomial coefficients via
    /// `FFmpeg`'s `lenscorrection` filter.
    ///
    /// Negative values correct barrel distortion; positive values correct
    /// pincushion distortion. Both `k1` and `k2` must be in [−1.0, 1.0];
    /// validated by [`FilterGraph::lens_correction`](crate::FilterGraph::lens_correction).
    LensCorrection {
        /// First-order radial distortion coefficient. Range: [−1.0, 1.0].
        k1: f32,
        /// Second-order radial distortion coefficient. Range: [−1.0, 1.0].
        k2: f32,
    },

    /// Add synthetic per-frame random film grain to luma and chroma channels
    /// via `FFmpeg`'s `noise` filter.
    ///
    /// `luma_strength` and `chroma_strength` are clamped to [0.0, 100.0].
    /// The `allf=t` flag varies the seed each frame to simulate real film grain.
    FilmGrain {
        /// Grain strength applied to the luma (Y) plane. Clamped to [0.0, 100.0].
        luma_strength: f32,
        /// Grain strength applied to the Cb and Cr planes. Clamped to [0.0, 100.0].
        chroma_strength: f32,
    },
    /// Temporal film grain (the `noise` filter) with an optionally animated strength.
    ///
    /// Strengths are evaluated at [`Duration::ZERO`] for the graph build. Like
    /// [`UnsharpAnimated`](Self::UnsharpAnimated), `noise` exposes no
    /// runtime-settable parameter, so the CPU (`libavfilter`) path renders the
    /// `Duration::ZERO` strength statically; the GPU path animates it per frame. The
    /// grain *pattern* is temporal on both paths regardless (`allf=t` on the CPU, the
    /// per-frame seed on the GPU).
    FilmGrainAnimated {
        /// Luma-plane grain strength. Evaluated to [0.0, 100.0] at `Duration::ZERO`.
        luma_strength: AnimatedValue<f64>,
        /// Chroma-plane grain strength. Evaluated to [0.0, 100.0] at `Duration::ZERO`.
        chroma_strength: AnimatedValue<f64>,
    },

    /// Uniform scale by a fractional multiplier via `FFmpeg`'s `scale` filter.
    ///
    /// Both width and height are multiplied by `factor`. Used to hide warped
    /// border pixels left after lens distortion correction.
    ScaleMultiplier {
        /// Scale factor applied to both dimensions (e.g. `1.05` = 5 % zoom-in).
        factor: f32,
    },

    /// Reduce lateral chromatic aberration by independently shifting the R and B
    /// channels via `FFmpeg`'s `rgbashift` filter.
    ///
    /// `rh` and `bh` are the horizontal pixel shifts for the red and blue
    /// channels respectively. Derived from scale deviations by
    /// [`FilterGraph::fix_chromatic_aberration`](crate::FilterGraph::fix_chromatic_aberration).
    ChromaticAberration {
        /// Horizontal shift for the red channel in pixels (positive = right).
        rh: i32,
        /// Horizontal shift for the blue channel in pixels (positive = right).
        bh: i32,
    },

    /// Glow / bloom effect: blends blurred highlights back over the image via
    /// `split`, `curves`, `gblur`, and `blend` filters.
    ///
    /// This is a compound step — see
    /// [`FilterGraph::glow`](crate::FilterGraph::glow) for parameter semantics.
    Glow {
        /// Luminance threshold that triggers the glow (clamped to [0.0, 1.0]).
        threshold: f32,
        /// Gaussian blur radius in pixels (clamped to [0.5, 50.0]).
        radius: f32,
        /// Additive blend strength (clamped to [0.0, 2.0]).
        intensity: f32,
    },
    /// Glow / bloom (the compound `split`/`curves`/`gblur`/`blend` chain) with
    /// optionally animated parameters.
    ///
    /// Parameters are evaluated at [`Duration::ZERO`] for the graph build. None of
    /// the sub-filters expose a runtime-settable glow parameter, so the CPU path
    /// renders the `Duration::ZERO` values statically; the GPU path
    /// (`ff_render::GlowNode`) animates them per frame.
    GlowAnimated {
        /// Luminance threshold. Evaluated to [0.0, 1.0] at `Duration::ZERO`.
        threshold: AnimatedValue<f64>,
        /// Gaussian blur radius in pixels. Evaluated to [0.5, 50.0] at `Duration::ZERO`.
        radius: AnimatedValue<f64>,
        /// Additive blend strength. Evaluated to [0.0, 2.0] at `Duration::ZERO`.
        intensity: AnimatedValue<f64>,
    },

    /// Convolution reverb using an impulse response (IR) audio file.
    ///
    /// The IR is loaded via `FFmpeg`'s `amovie` filter, optionally delayed by
    /// `pre_delay_ms` via `adelay`, then convolved with the main audio stream
    /// via `FFmpeg`'s `afir` filter.
    ///
    /// This is a compound step — see
    /// [`FilterGraph::reverb_ir`](crate::FilterGraph::reverb_ir) for parameter
    /// semantics.
    ReverbIr {
        /// Absolute or relative path to the `.wav` or `.flac` IR file.
        ir_path: String,
        /// Wet (reverb) mix level in [0.0, 1.0].
        wet: f32,
        /// Dry (original) mix level in [0.0, 1.0].
        dry: f32,
        /// Pre-delay before the reverb tail in milliseconds (clamped to 0–500).
        pre_delay_ms: u32,
    },

    /// Algorithmic multi-tap echo/reverb via `FFmpeg`'s `aecho` filter.
    ///
    /// `in_gain` and `out_gain` are amplitude multipliers clamped to [0.0, 1.0].
    /// `delays` contains delay times in milliseconds (one per tap); `decays`
    /// contains the corresponding decay factors in [0.0, 1.0].  Both vecs must
    /// have equal length in the range 1–8; validated by
    /// [`FilterGraph::reverb_echo`](crate::FilterGraph::reverb_echo).
    ReverbEcho {
        /// Input gain (amplitude multiplier). Clamped to [0.0, 1.0].
        in_gain: f32,
        /// Output gain (amplitude multiplier). Clamped to [0.0, 1.0].
        out_gain: f32,
        /// Delay times in milliseconds (one per tap).
        delays: Vec<f32>,
        /// Decay factors per tap. Clamped to [0.0, 1.0].
        decays: Vec<f32>,
    },

    /// Pitch shift without tempo change.
    ///
    /// Shifts audio pitch by `semitones` semitones without altering playback
    /// duration.  Implemented as `asetrate` (changes the declared sample rate
    /// to shift pitch) followed by `atempo` (restores the original duration).
    ///
    /// Range: [−24.0, 24.0]; validated by
    /// [`FilterGraph::pitch_shift`](crate::FilterGraph::pitch_shift).
    ///
    /// This is a compound step — `filter_name()` returns `"asetrate"` for
    /// `validate_filter_steps`; the actual graph construction is handled by
    /// `filter_inner::build::build_audio_graph`.
    PitchShift {
        /// Pitch shift in semitones. Range: [−24.0, 24.0].
        semitones: f32,
        /// Backend algorithm. [`PitchAlgo::Rubberband`] uses the formant-preserving
        /// `rubberband` filter when available (else falls back to the signal path).
        algo: PitchAlgo,
    },

    /// Time-stretch audio without changing pitch via `FFmpeg`'s `atempo` filter.
    ///
    /// `factor < 1.0` = slower (longer duration); `factor > 1.0` = faster
    /// (shorter duration).  Range: [0.1, 10.0].  Values outside [0.5, 2.0]
    /// are realised by chaining multiple `atempo` instances (each in [0.5, 2.0]).
    ///
    /// Validated by [`FilterGraph::time_stretch`](crate::FilterGraph::time_stretch).
    TimeStretch {
        /// Speed / duration factor. 0.5 = 2× longer; 2.0 = 2× shorter. Range: [0.1, 10.0].
        factor: f32,
        /// Backend algorithm. [`PitchAlgo::Rubberband`] uses the higher-quality
        /// `rubberband` filter when available (else falls back to the signal path).
        algo: PitchAlgo,
    },

    /// Simultaneously change audio speed and pitch by the same factor.
    ///
    /// Equivalent to playing a tape at a different speed: `factor > 1.0` makes
    /// audio faster and higher; `factor < 1.0` makes it slower and lower.
    ///
    /// Uses `FFmpeg`'s `asetrate` to multiply the declared sample rate by
    /// `factor` without resampling.  Range: [0.1, 10.0]; validated by
    /// [`FilterGraph::speed_change`](crate::FilterGraph::speed_change).
    SpeedChange {
        /// Speed/pitch multiplier. Range: [0.1, 10.0].
        factor: f64,
    },

    /// Spectral noise reduction using a statistical noise-type model.
    ///
    /// Uses `FFmpeg`'s `afftdn` filter.  `noise_type_flag` is the single-letter
    /// `nt` parameter (`"w"` = white, `"p"` = pink, `"b"` = brown).
    /// `nr_level` is the reduction amount in dB, clamped to [0.0, 97.0].
    ///
    /// Created by [`FilterGraph::noise_reduce`](crate::FilterGraph::noise_reduce).
    NoiseReduce {
        /// `afftdn` `nt` flag: `"w"`, `"p"`, or `"b"`.
        noise_type_flag: String,
        /// Noise reduction amount in dB. Clamped to [0.0, 97.0].
        nr_level: f32,
    },

    /// Spectral noise reduction using a captured noise profile.
    ///
    /// Uses `FFmpeg`'s `afftdn` with the `pl` (profile length) option: the
    /// filter learns the noise profile from the first `profile_duration_secs`
    /// seconds, then subtracts it from the rest of the stream.
    /// `nr_level` is the reduction amount in dB, clamped to [0.0, 97.0].
    ///
    /// Created by
    /// [`FilterGraph::noise_reduce_profile`](crate::FilterGraph::noise_reduce_profile).
    NoiseReduceProfile {
        /// Duration in seconds from which to capture the noise profile. Minimum 0.1.
        profile_duration_secs: f32,
        /// Noise reduction amount in dB. Clamped to [0.0, 97.0].
        nr_level: f32,
    },

    /// Sidechain compression for audio ducking via `FFmpeg`'s `sidechaincompress` filter.
    ///
    /// Reduces the background audio level when the foreground (sidechain) signal
    /// exceeds the threshold.  Push background audio to slot 0 and foreground
    /// audio to slot 1.
    ///
    /// `threshold_linear` is the trigger level as a linear amplitude (pre-converted
    /// from dBFS by [`FilterGraph::duck`](crate::FilterGraph::duck)).
    /// `ratio`, `attack_ms`, and `release_ms` are validated by
    /// [`FilterGraph::duck`](crate::FilterGraph::duck).
    Duck {
        /// Compression threshold as a linear amplitude ratio in (0.0, 1.0].
        threshold_linear: f32,
        /// Compression ratio (e.g. 20.0 for near hard-limiting). Must be >= 1.0.
        ratio: f32,
        /// Attack time in milliseconds. Must be >= 0.0.
        attack_ms: f32,
        /// Release time in milliseconds. Must be >= 0.0.
        release_ms: f32,
    },

    /// Apply a polygon alpha mask using `FFmpeg`'s `geq` filter with a
    /// crossing-number point-in-polygon test.
    ///
    /// Pixels inside the polygon are fully opaque (`alpha=255`); pixels outside
    /// are fully transparent (`alpha=0`).  When `invert` is `true` the roles
    /// are swapped.
    ///
    /// - `vertices`: polygon corners as `(x, y)` in `[0.0, 1.0]` (normalised
    ///   to frame size).  Minimum 3, maximum 16.
    /// - `invert`: when `false`, inside = opaque; when `true`, outside = opaque.
    ///
    /// Vertex count and coordinates are validated in
    /// [`build`](FilterGraphBuilder::build); out-of-range values return
    /// [`crate::FilterError::InvalidConfig`].
    ///
    /// The `geq` expression is constructed from the vertex list at graph
    /// build time.  Degenerate polygons (zero area) produce a fully-transparent
    /// mask.  The output carries an alpha channel (`rgba`).
    PolygonMatte {
        /// Polygon corners in normalised `[0.0, 1.0]` frame coordinates.
        vertices: Vec<(f32, f32)>,
        /// When `true`, the mask is inverted: outside is opaque, inside is transparent.
        invert: bool,
    },

    /// Apply an arbitrary `FFmpeg` avfilter to the current stream — the escape
    /// hatch for filters not covered by the typed builder methods.
    ///
    /// `filter` is the avfilter name (e.g. `"selectivecolor"`, `"pseudocolor"`)
    /// and `args` its option string (e.g. `"reds=…:blues=…"`; empty when the
    /// filter takes no options). It is emitted as a single node `filter=args`
    /// and linked in chain order like any other step, so it accepts one input
    /// and produces one output.
    ///
    /// The filter name is checked for existence when the graph is built
    /// ([`build`](FilterGraphBuilder::build)); the `args` are validated by
    /// `FFmpeg` on the first [`push_video`](crate::FilterGraph::push_video) /
    /// [`push_audio`](crate::FilterGraph::push_audio), exactly as for the typed
    /// steps. Prefer the typed builder methods where they exist; use this for
    /// filters they do not cover.
    Raw {
        /// The avfilter name (e.g. `"selectivecolor"`).
        filter: String,
        /// The avfilter option string (e.g. `"reds=…"`); empty for none.
        args: String,
    },

    /// Splice a whole libavfilter *description* into the chain — the escape
    /// hatch for graph shapes the step list cannot express.
    ///
    /// `desc` takes the same syntax as `ffmpeg -vf`, so it may chain several
    /// filters (`"scale=64:48,hue=s=0"`) and may use labels to branch and
    /// rejoin (`"split[a][b];[a]hue=s=0[c];[b][c]overlay"`). It is parsed with
    /// `avfilter_graph_parse2` and spliced in as one step.
    ///
    /// Use [`Raw`](Self::Raw) for a *single* untyped filter; that is what it is
    /// for, and it needs no parser. This variant exists for the two things
    /// `Raw` cannot do: take a whole chain as one string, and describe a
    /// non-linear graph.
    ///
    /// The description must have exactly one open input and one open output, so
    /// it links into the chain like any other step. Sources (`"color=c=red"`,
    /// zero open inputs) and sinks are rejected.
    ///
    /// Video only, like [`Raw`](Self::Raw): the audio graph builds from an
    /// allow-list of audio steps, which neither variant is in.
    ParseDesc {
        /// The filter description (e.g. `"scale=64:48,hue=s=0"`).
        desc: String,
    },
}

/// Convert a color temperature in Kelvin to linear RGB multipliers using
/// Tanner Helland's algorithm.
///
/// Returns `(r, g, b)` each in `[0.0, 1.0]`.
/// Renders the three-way (lift/gamma/gain) colour corrector as `curves` `r/g/b`
/// options. Shared by [`FilterStep::ThreeWayCC`] and
/// [`FilterStep::ThreeWayCCAnimated`].
///
/// The formula maps each channel to a 3-point curve:
///   input 0.0 -> (lift - 1.0) * gain  (black point)
///   input 0.5 -> (0.5 * lift)^(1/gamma) * gain  (midtone)
///   input 1.0 -> gain  (white point)
/// All neutral (1.0) produces the identity curve `0/0 0.5/0.5 1/1`.
fn three_way_cc_args(lift: Rgb, gamma: Rgb, gain: Rgb) -> String {
    let curve = |l: f32, gm: f32, gn: f32| -> String {
        let l = f64::from(l);
        let gm = f64::from(gm);
        let gn = f64::from(gn);
        let black = ((l - 1.0) * gn).clamp(0.0, 1.0);
        let mid = ((0.5 * l).powf(1.0 / gm) * gn).clamp(0.0, 1.0);
        let white = gn.clamp(0.0, 1.0);
        format!("0/{black} 0.5/{mid} 1/{white}")
    };
    format!(
        "r='{}':g='{}':b='{}'",
        curve(lift.r, gamma.r, gain.r),
        curve(lift.g, gamma.g, gain.g),
        curve(lift.b, gamma.b, gain.b),
    )
}

/// Renders the compound glow filter chain (`split` -> `curves` -> `gblur` ->
/// `blend`) as a filtergraph string. Shared by [`FilterStep::Glow`] and
/// [`FilterStep::GlowAnimated`]. (The real build goes through `add_glow_step`; this
/// is for the `args()` completeness path.)
fn glow_compound_args(threshold: f32, radius: f32, intensity: f32) -> String {
    let t = threshold.clamp(0.0, 1.0);
    let r = radius.clamp(0.5, 50.0);
    let iv = intensity.clamp(0.0, 2.0);
    let hi_lo = format!("0/0 {t}/0 1/1");
    format!(
        "split=2[base][hl];[hl]curves=all='{hi_lo}'[glow_src];\
         [glow_src]gblur=sigma={r}[glow];\
         [base][glow]blend=all_mode=addition:all_opacity={iv}"
    )
}

/// Lightness offset `[-1, 1]` -> the `hue` filter's brightness `[-10, 10]`. The
/// filter adds `b * 25.5` to 8-bit luma, so `±1` lightness maps to `±10` b, a
/// roughly full-range luma shift. This YUV luma-add only approximates the GPU
/// node's HSL-space lightness, hence the wide parity tolerance.
const HSL_LIGHTNESS_TO_BRIGHTNESS: f32 = 10.0;

/// Renders the `hue` filter args for an HSL adjustment (hue degrees, saturation
/// multiplier, lightness scaled to the filter's brightness).
fn hsl_args(hue: f32, saturation: f32, lightness: f32) -> String {
    let b = lightness * HSL_LIGHTNESS_TO_BRIGHTNESS;
    format!("h={hue}:s={saturation}:b={b}")
}

fn kelvin_to_rgb(temp_k: u32) -> (f64, f64, f64) {
    let t = (f64::from(temp_k) / 100.0).clamp(10.0, 400.0);
    let r = if t <= 66.0 {
        1.0
    } else {
        (329.698_727_446_4 * (t - 60.0).powf(-0.133_204_759_2) / 255.0).clamp(0.0, 1.0)
    };
    let g = if t <= 66.0 {
        ((99.470_802_586_1 * t.ln() - 161.119_568_166_1) / 255.0).clamp(0.0, 1.0)
    } else {
        ((288.122_169_528_3 * (t - 60.0).powf(-0.075_514_849_2)) / 255.0).clamp(0.0, 1.0)
    };
    let b = if t >= 66.0 {
        1.0
    } else if t <= 19.0 {
        0.0
    } else {
        ((138.517_731_223_1 * (t - 10.0).ln() - 305.044_792_730_7) / 255.0).clamp(0.0, 1.0)
    };
    (r, g, b)
}

impl FilterStep {
    /// Returns the libavfilter filter name for this step.
    pub(crate) fn filter_name(&self) -> &str {
        match self {
            // Escape hatch: the runtime filter name is borrowed from `self`.
            // (The `&'static str` literals below coerce to the borrowed `&str`.)
            Self::Raw { filter, .. } => filter,
            // ParseDesc is a whole description, not one filter, so it has no
            // name to give. `add_and_link_step` dispatches it before the
            // single-filter path and `validate_filter_steps` skips it, so this
            // is never read; `null` (the identity filter) keeps a hypothetical
            // future fallback inert rather than wrong.
            Self::ParseDesc { .. } => "null",
            Self::Format { .. } => "format",
            Self::SetParams { .. } => "setparams",
            Self::Trim { .. } => "trim",
            // "setpts" is checked at build-time (see Speed's note below).
            Self::ResetPts | Self::OffsetPts { .. } => "setpts",
            Self::Scale { .. } => "scale",
            Self::Crop { .. } => "crop",
            Self::Overlay { .. } => "overlay",
            Self::FadeIn { .. }
            | Self::FadeOut { .. }
            | Self::FadeInWhite { .. }
            | Self::FadeOutWhite { .. } => "fade",
            Self::AFadeIn { .. } | Self::AFadeOut { .. } => "afade",
            Self::Rotate { .. } => "rotate",
            Self::ToneMap(_) => "tonemap",
            Self::Volume(_) => "volume",
            Self::Amix(_) => "amix",
            // ParametricEq is a compound step; "equalizer" is used only by
            // validate_filter_steps as a best-effort existence check.  The
            // actual nodes are built by `filter_inner::add_parametric_eq_chain`.
            Self::ParametricEq { .. } => "equalizer",
            Self::Lut3d { .. } => "lut3d",
            Self::Eq { .. } => "eq",
            Self::EqAnimated { .. } => "eq",
            Self::ColorBalanceAnimated { .. } => "colorbalance",
            Self::Curves { .. } => "curves",
            Self::WhiteBalance { .. } => "colorchannelmixer",
            Self::Hue { .. } => "hue",
            Self::Hsl { .. } => "hue",
            Self::HslAnimated { .. } => "hue",
            Self::Gamma { .. } => "eq",
            Self::ThreeWayCC { .. } => "curves",
            Self::ThreeWayCCAnimated { .. } => "curves",
            Self::Vignette { .. } => "vignette",
            Self::HFlip => "hflip",
            Self::VFlip => "vflip",
            Self::Reverse => "reverse",
            Self::AReverse => "areverse",
            Self::Pad { .. } => "pad",
            // FitToAspect is implemented as scale + pad; "scale" is validated at
            // build time.  The pad filter is inserted by filter_inner at graph
            // construction time.
            Self::FitToAspect { .. } => "scale",
            // FillToAspect is scale (cover) + crop; "scale" is validated at build
            // time.  The crop filter is inserted by filter_inner at graph
            // construction time.
            Self::FillToAspect { .. } => "scale",
            Self::GBlur { .. } => "gblur",
            Self::Unsharp { .. } => "unsharp",
            Self::Hqdn3d { .. } => "hqdn3d",
            Self::Nlmeans { .. } => "nlmeans",
            Self::Yadif { .. } => "yadif",
            Self::XFade { .. } => "xfade",
            Self::DrawText { .. } | Self::Ticker { .. } => "drawtext",
            // "setpts" is checked at build-time; the audio path uses "atempo"
            // which is verified at graph-construction time in filter_inner.
            Self::Speed { .. } => "setpts",
            Self::FreezeFrame { .. } => "loop",
            Self::LoudnessNormalize { .. } => "ebur128",
            Self::NormalizePeak { .. } => "astats",
            Self::ANoiseGate { .. } => "agate",
            Self::ACompressor { .. } => "acompressor",
            Self::StereoToMono => "pan",
            Self::ChannelMap { .. } => "channelmap",
            // AudioDelay dispatches to adelay (positive) or atrim (negative) at
            // build time; "adelay" is returned here for validate_filter_steps only.
            Self::AudioDelay { .. } => "adelay",
            Self::ATrim { .. } => "atrim",
            // "asetpts" is checked at build-time (audio counterpart of ResetPts).
            Self::AResetPts => "asetpts",
            Self::ConcatVideo { .. } | Self::ConcatAudio { .. } => "concat",
            Self::SubtitlesSrt { .. } => "subtitles",
            Self::SubtitlesAss { .. } => "ass",
            // OverlayImage is a compound step (movie → lut → overlay); "overlay"
            // is used only by validate_filter_steps as a best-effort existence
            // check.  The actual graph construction is handled by
            // `filter_inner::build::add_overlay_image_step`.
            Self::OverlayImage { .. } => "overlay",
            // Blend is a compound step; "overlay" is used as the primary filter
            // for validate_filter_steps.  Unimplemented modes are caught by
            // build() before validate_filter_steps is reached.
            Self::Blend { .. } => "overlay",
            // Composite shares the Blend construction: Over/Under use overlay,
            // the expression operators use blend. validate_filter_steps only
            // needs a real filter name to probe existence.
            Self::Composite { op, .. } => match op {
                CompositeOp::Over | CompositeOp::Under => "overlay",
                CompositeOp::In | CompositeOp::Out | CompositeOp::Atop | CompositeOp::Xor => {
                    "blend"
                }
            },
            Self::ChromaKey { .. } => "chromakey",
            Self::ChromaKeyAnimated { .. } => "chromakey",
            Self::ColorKey { .. } => "colorkey",
            Self::SpillSuppress { .. } => "hue",
            // AlphaMatte is a compound step (matte pipeline → alphamerge);
            // "alphamerge" is used by validate_filter_steps as the primary check.
            Self::AlphaMatte { .. } => "alphamerge",
            // LumaKey is a compound step when invert=true (lumakey + geq);
            // "lumakey" is used here for validate_filter_steps.
            Self::LumaKey { .. } => "lumakey",
            // RectMask uses geq to set alpha per-pixel based on rectangle bounds.
            Self::RectMask { .. } => "geq",
            Self::RectMaskAnimated { .. } => "geq",
            Self::LumaMask { .. } => "geq",
            // FeatherMask is a compound step (split → alphaextract → gblur → alphamerge);
            // "alphaextract" is used by validate_filter_steps as the primary check.
            Self::FeatherMask { .. } => "alphaextract",
            // PolygonMatte uses geq with a crossing-number point-in-polygon expression.
            Self::PolygonMatte { .. } => "geq",
            Self::CropAnimated { .. } => "crop",
            Self::GBlurAnimated { .. } => "gblur",
            Self::UnsharpAnimated { .. } => "unsharp",
            Self::ScaleAnimated { .. } => "scale",
            Self::RotateAnimated { .. } => "rotate",
            Self::VignetteAnimated { .. } => "vignette",
            Self::MotionBlur { .. } | Self::MotionBlurAnimated { .. } => "tblend",
            Self::LensCorrection { .. } => "lenscorrection",
            Self::FilmGrain { .. } => "noise",
            Self::FilmGrainAnimated { .. } => "noise",
            Self::ScaleMultiplier { .. } => "scale",
            Self::ChromaticAberration { .. } => "rgbashift",
            // Glow is a compound step (split → curves → gblur → blend);
            // "split" is used by validate_filter_steps as the primary check.
            Self::Glow { .. } => "split",
            Self::GlowAnimated { .. } => "split",
            // ReverbIr is a compound step (amovie[+adelay] → afir);
            // "afir" is used by validate_filter_steps as the primary check.
            Self::ReverbIr { .. } => "afir",
            Self::ReverbEcho { .. } => "aecho",
            // PitchShift is a compound step (asetrate → atempo);
            // "asetrate" is used by validate_filter_steps as the primary check.
            Self::PitchShift { .. } => "asetrate",
            // TimeStretch uses one or more chained atempo filters.
            Self::TimeStretch { .. } => "atempo",
            // SpeedChange uses asetrate to shift speed and pitch together.
            Self::SpeedChange { .. } => "asetrate",
            Self::NoiseReduce { .. } | Self::NoiseReduceProfile { .. } => "afftdn",
            // Duck is a two-input compound step; "sidechaincompress" is checked at
            // build time by validate_filter_steps.
            Self::Duck { .. } => "sidechaincompress",
        }
    }

    /// Returns the `args` string passed to `avfilter_graph_create_filter`.
    pub(crate) fn args(&self) -> String {
        match self {
            // Escape hatch: the option string is passed through verbatim.
            Self::Raw { args, .. } => args.clone(),
            // See `filter_name`: ParseDesc never reaches the single-filter path.
            Self::ParseDesc { .. } => String::new(),
            Self::Format {
                pix_fmts,
                color_spaces,
                color_ranges,
            } => {
                // Each option list uses the FFmpeg-canonical `FfmpegToken`, skipping values with no
                // FFmpeg equivalent (`None`); an option is emitted only when a token survives.
                fn render<T: FfmpegToken>(key: &str, values: &[T]) -> Option<String> {
                    let tokens: Vec<&str> = values
                        .iter()
                        .filter_map(FfmpegToken::ffmpeg_token)
                        .collect();
                    (!tokens.is_empty()).then(|| format!("{key}={}", tokens.join("|")))
                }
                [
                    render("pix_fmts", pix_fmts),
                    render("color_spaces", color_spaces),
                    render("color_ranges", color_ranges),
                ]
                .into_iter()
                .flatten()
                .collect::<Vec<_>>()
                .join(":")
            }
            Self::SetParams {
                color_space,
                color_range,
                color_primaries,
                color_trc,
            } => {
                // Each option is emitted from the FFmpeg-canonical `FfmpegToken`, only when the
                // value is `Some` and yields a token (`Unknown` → `None` → skipped). All-`None`
                // renders to the empty string.
                fn opt<T: FfmpegToken>(key: &str, v: Option<&T>) -> Option<String> {
                    v.and_then(FfmpegToken::ffmpeg_token)
                        .map(|tok| format!("{key}={tok}"))
                }
                [
                    opt("colorspace", color_space.as_ref()),
                    opt("range", color_range.as_ref()),
                    opt("color_primaries", color_primaries.as_ref()),
                    opt("color_trc", color_trc.as_ref()),
                ]
                .into_iter()
                .flatten()
                .collect::<Vec<_>>()
                .join(":")
            }
            Self::Trim { start, end } => match (start, end) {
                (Some(s), Some(e)) => format!("start={s}:end={e}"),
                (Some(s), None) => format!("start={s}"),
                (None, Some(e)) => format!("end={e}"),
                (None, None) => String::new(),
            },
            Self::ResetPts => "PTS-STARTPTS".to_string(),
            Self::OffsetPts { seconds } => format!("PTS+{seconds}/TB"),
            Self::Scale {
                width,
                height,
                algorithm,
            } => format!("w={width}:h={height}:flags={}", algorithm.as_flags_str()),
            Self::Crop {
                x,
                y,
                width,
                height,
            } => {
                format!("x={x}:y={y}:w={width}:h={height}")
            }
            Self::Overlay { x, y } => format!("x={x}:y={y}"),
            Self::FadeIn { start, duration } => {
                format!("type=in:start_time={start}:duration={duration}")
            }
            Self::FadeOut { start, duration } => {
                format!("type=out:start_time={start}:duration={duration}")
            }
            Self::FadeInWhite { start, duration } => {
                format!("type=in:start_time={start}:duration={duration}:color=white")
            }
            Self::FadeOutWhite { start, duration } => {
                format!("type=out:start_time={start}:duration={duration}:color=white")
            }
            Self::AFadeIn { start, duration } => {
                format!("type=in:start_time={start}:duration={duration}")
            }
            Self::AFadeOut { start, duration } => {
                format!("type=out:start_time={start}:duration={duration}")
            }
            Self::Rotate {
                angle_degrees,
                fill_color,
            } => {
                format!(
                    "angle={}:fillcolor={fill_color}",
                    angle_degrees.to_radians()
                )
            }
            Self::ToneMap(algorithm) => format!("tonemap={}", algorithm.as_str()),
            Self::Volume(db) => format!("volume={db}dB"),
            // `normalize=0` sums the inputs (additive) instead of averaging by the
            // active-input count, matching the multi-track mixer's convention so a
            // mix has the same level however it is built.
            Self::Amix(inputs) => format!("inputs={inputs}:normalize=0"),
            // args() for ParametricEq is not used by the build loop (which is
            // bypassed in favour of add_parametric_eq_chain); provided here for
            // completeness using the first band's args.
            Self::ParametricEq { bands } => bands.first().map(EqBand::args).unwrap_or_default(),
            Self::Lut3d { path } => {
                format!("file={}:interp=trilinear", escape_filter_path(path))
            }
            // `temperature`/`tint` are GPU-only (the CPU `eq` filter has no such option),
            // so they are intentionally not emitted into the argument string.
            Self::Eq {
                brightness,
                contrast,
                saturation,
                temperature: _,
                tint: _,
            } => format!("brightness={brightness}:contrast={contrast}:saturation={saturation}"),
            Self::EqAnimated {
                brightness,
                contrast,
                saturation,
                gamma,
                temperature: _,
                tint: _,
            } => {
                let b = brightness.value_at(Duration::ZERO);
                let c = contrast.value_at(Duration::ZERO);
                let s = saturation.value_at(Duration::ZERO);
                let g = gamma.value_at(Duration::ZERO);
                format!("brightness={b}:contrast={c}:saturation={s}:gamma={g}")
            }
            Self::ColorBalanceAnimated { lift, gamma, gain } => {
                let (rl, gl, bl) = lift.value_at(Duration::ZERO);
                let (rm, gm, bm) = gamma.value_at(Duration::ZERO);
                let (rh, gh, bh) = gain.value_at(Duration::ZERO);
                format!("rs={rl}:gs={gl}:bs={bl}:rm={rm}:gm={gm}:bm={bm}:rh={rh}:gh={gh}:bh={bh}")
            }
            Self::Curves { master, r, g, b } => {
                let fmt = |pts: &[(f32, f32)]| -> String {
                    pts.iter()
                        .map(|(x, y)| format!("{x}/{y}"))
                        .collect::<Vec<_>>()
                        .join(" ")
                };
                [("master", master.as_slice()), ("r", r), ("g", g), ("b", b)]
                    .iter()
                    .filter(|(_, pts)| !pts.is_empty())
                    .map(|(name, pts)| format!("{name}='{}'", fmt(pts)))
                    .collect::<Vec<_>>()
                    .join(":")
            }
            Self::WhiteBalance {
                temperature_k,
                tint,
            } => {
                let (r, g, b) = kelvin_to_rgb(*temperature_k);
                let g_adj = (g + f64::from(*tint)).clamp(0.0, 2.0);
                format!("rr={r}:gg={g_adj}:bb={b}")
            }
            Self::Hue { degrees } => format!("h={degrees}"),
            Self::Hsl {
                hue,
                saturation,
                lightness,
            } => hsl_args(*hue, *saturation, *lightness),
            Self::HslAnimated {
                hue,
                saturation,
                lightness,
            } => {
                // The CPU path is static (the GPU animates per frame): render the
                // `Duration::ZERO` values.
                #[allow(clippy::cast_possible_truncation)]
                hsl_args(
                    hue.value_at(Duration::ZERO) as f32,
                    saturation.value_at(Duration::ZERO) as f32,
                    lightness.value_at(Duration::ZERO) as f32,
                )
            }
            Self::Gamma { r, g, b } => format!("gamma_r={r}:gamma_g={g}:gamma_b={b}"),
            Self::Vignette { angle, x0, y0 } => {
                let cx = if *x0 == 0.0 {
                    "w/2".to_string()
                } else {
                    x0.to_string()
                };
                let cy = if *y0 == 0.0 {
                    "h/2".to_string()
                } else {
                    y0.to_string()
                };
                format!("angle={angle}:x0={cx}:y0={cy}")
            }
            Self::ThreeWayCC { lift, gamma, gain } => three_way_cc_args(*lift, *gamma, *gain),
            Self::ThreeWayCCAnimated { lift, gamma, gain } => {
                // The compound `curves` string is built from the `Duration::ZERO`
                // values (the CPU path is static; the GPU animates per frame).
                #[allow(clippy::cast_possible_truncation)]
                let at0 = |a: &[AnimatedValue<f64>; 3]| Rgb {
                    r: a[0].value_at(Duration::ZERO) as f32,
                    g: a[1].value_at(Duration::ZERO) as f32,
                    b: a[2].value_at(Duration::ZERO) as f32,
                };
                three_way_cc_args(at0(lift), at0(gamma), at0(gain))
            }
            Self::HFlip | Self::VFlip | Self::Reverse | Self::AReverse => String::new(),
            Self::GBlur { sigma } => format!("sigma={sigma}"),
            Self::Unsharp {
                luma_strength,
                chroma_strength,
            } => format!(
                "luma_msize_x=5:luma_msize_y=5:luma_amount={luma_strength}:\
                 chroma_msize_x=5:chroma_msize_y=5:chroma_amount={chroma_strength}"
            ),
            Self::Hqdn3d {
                luma_spatial,
                chroma_spatial,
                luma_tmp,
                chroma_tmp,
            } => format!("{luma_spatial}:{chroma_spatial}:{luma_tmp}:{chroma_tmp}"),
            Self::Nlmeans { strength } => format!("s={strength}"),
            Self::Yadif { mode } => format!("mode={}", *mode as i32),
            Self::XFade {
                transition,
                duration,
                offset,
            } => {
                let t = transition.as_str();
                format!("transition={t}:duration={duration}:offset={offset}")
            }
            Self::DrawText { opts } => {
                // Escape special characters recognised by the drawtext filter.
                let escaped = opts
                    .text
                    .replace('\\', "\\\\")
                    .replace(':', "\\:")
                    .replace('\'', "\\'");
                let mut parts = vec![
                    format!("text='{escaped}'"),
                    // The text is drawn literally; disable `%{...}` expansion so a
                    // user string cannot inject drawtext expansions (`%{gmtime}`, ...).
                    "expansion=none".to_string(),
                    format!("x={}", opts.x),
                    format!("y={}", opts.y),
                    format!("fontsize={}", opts.font_size),
                    format!("fontcolor={}@{:.2}", opts.font_color, opts.opacity),
                ];
                if let Some(ref ff) = opts.font_file {
                    // Escape like a filter path: an unescaped `:` (e.g. a Windows
                    // drive letter) would be read as an option separator and could
                    // inject drawtext options (`textfile=`, ...).
                    let ff_escaped = ff
                        .replace('\\', "/")
                        .replace(':', "\\:")
                        .replace('\'', "\\'");
                    parts.push(format!("fontfile={ff_escaped}"));
                }
                if let Some(ref bc) = opts.box_color {
                    parts.push("box=1".to_string());
                    parts.push(format!("boxcolor={bc}"));
                    parts.push(format!("boxborderw={}", opts.box_border_width));
                }
                parts.join(":")
            }
            Self::Ticker {
                text,
                y,
                speed_px_per_sec,
                font_size,
                font_color,
            } => {
                // Use the same escaping as DrawText.
                let escaped = text
                    .replace('\\', "\\\\")
                    .replace(':', "\\:")
                    .replace('\'', "\\'");
                // x = w - t * speed: at t=0 the text starts fully off the right
                // edge (x = w) and scrolls left by `speed` pixels per second.
                format!(
                    "text='{escaped}':x=w-t*{speed_px_per_sec}:y={y}:\
                     fontsize={font_size}:fontcolor={font_color}"
                )
            }
            // Video path: divide PTS by factor to change playback speed.
            // Audio path args are built by filter_inner (chained atempo).
            Self::Speed { factor } => format!("PTS/{factor}"),
            // args() is not used by the build loop for LoudnessNormalize (two-pass
            // is handled entirely in filter_inner); provided here for completeness.
            Self::LoudnessNormalize { .. } => "peak=true:metadata=1".to_string(),
            // args() is not used by the build loop for NormalizePeak (two-pass
            // is handled entirely in filter_inner); provided here for completeness.
            Self::NormalizePeak { .. } => "metadata=1".to_string(),
            Self::FreezeFrame { pts, duration } => {
                // The `loop` filter needs a frame index and a loop count, not PTS or
                // wall-clock duration.  We approximate both using 25 fps; accuracy
                // depends on the source stream's actual frame rate.
                #[allow(clippy::cast_possible_truncation)]
                let start = (*pts * 25.0) as i64;
                #[allow(clippy::cast_possible_truncation)]
                let loop_count = (*duration * 25.0) as i64;
                format!("loop={loop_count}:size=1:start={start}")
            }
            Self::SubtitlesSrt { path, force_style } => {
                // Escape for the filter's `:`-separated option parser: normalise
                // backslashes to `/` and escape the drive colon, else an absolute
                // Windows path (`C:\subs.srt`) breaks parsing at the colon.
                let escaped = path.replace('\\', "/").replace(':', "\\:");
                match force_style {
                    Some(fs) if !fs.is_empty() => {
                        // Single-quote the style value so its `,`/`=` are read as
                        // one option value by the parser.
                        format!("filename={escaped}:force_style='{fs}'")
                    }
                    _ => format!("filename={escaped}"),
                }
            }
            Self::SubtitlesAss { path } => {
                let escaped = path.replace('\\', "/").replace(':', "\\:");
                format!("filename={escaped}")
            }
            // args() for OverlayImage returns the overlay positional args (x:y).
            // These are not consumed by add_and_link_step (which is bypassed for
            // this compound step); they exist here only for completeness.
            Self::OverlayImage { x, y, .. } => format!("{x}:{y}"),
            // args() for Blend is not consumed by add_and_link_step (which is
            // bypassed in favour of add_blend_normal_step).  Provided for
            // completeness using the Normal-mode overlay args.
            Self::Blend { .. } => "format=auto:shortest=1".to_string(),
            // args() for Composite is not consumed by add_and_link_step (bypassed
            // for this compound two-input step); provided here only to satisfy the
            // exhaustive match.
            Self::Composite { .. } => String::new(),
            Self::ChromaKey {
                color,
                similarity,
                blend,
            } => format!("color={color}:similarity={similarity}:blend={blend}"),
            Self::ChromaKeyAnimated {
                color,
                similarity,
                blend,
            } => {
                // The CPU path is static (the GPU animates per frame): render the
                // `Duration::ZERO` values.
                #[allow(clippy::cast_possible_truncation)]
                let (s, b) = (
                    similarity.value_at(Duration::ZERO) as f32,
                    blend.value_at(Duration::ZERO) as f32,
                );
                format!("color={color}:similarity={s}:blend={b}")
            }
            Self::ColorKey {
                color,
                similarity,
                blend,
            } => format!("color={color}:similarity={similarity}:blend={blend}"),
            Self::SpillSuppress { strength, .. } => format!("h=0:s={}", 1.0 - strength),
            // args() is not consumed by add_and_link_step (which is bypassed for
            // this compound step); provided here for completeness.
            Self::AlphaMatte { .. } => String::new(),
            Self::LumaKey {
                threshold,
                tolerance,
                softness,
                ..
            } => format!("threshold={threshold}:tolerance={tolerance}:softness={softness}"),
            // args() is not consumed by add_and_link_step (which is bypassed for
            // this compound step); provided here for completeness.
            Self::FeatherMask { .. } => String::new(),
            Self::RectMask {
                x,
                y,
                width,
                height,
                invert,
            } => {
                let xw = x + width - 1;
                let yh = y + height - 1;
                let (inside, outside) = if *invert { (0, 255) } else { (255, 0) };
                format!(
                    "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
                     a='if(between(X,{x},{xw})*between(Y,{y},{yh}),{inside},{outside})'"
                )
            }
            Self::RectMaskAnimated {
                x,
                y,
                width,
                height,
                invert,
            } => {
                // The CPU path is static (the GPU animates per frame): render the
                // `Duration::ZERO` rectangle. width/height are clamped to >= 1 so a
                // degenerate frame never fails `geq` build.
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let px = |v: &AnimatedValue<f64>, min: f64| {
                    v.value_at(Duration::ZERO).max(min).round() as u32
                };
                let (x, y) = (px(x, 0.0), px(y, 0.0));
                let (width, height) = (px(width, 1.0), px(height, 1.0));
                let xw = x + width - 1;
                let yh = y + height - 1;
                let (inside, outside) = if *invert { (0, 255) } else { (255, 0) };
                format!(
                    "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
                     a='if(between(X,{x},{xw})*between(Y,{y},{yh}),{inside},{outside})'"
                )
            }
            Self::LumaMask { invert } => {
                // BT.709 luma of the frame's own RGB (0..255) becomes the alpha.
                // Matches `ff_render::LumaMaskNode` on an opaque source. `invert`
                // uses `255 - luma` so dark pixels stay opaque.
                let luma = "0.2126*r(X,Y)+0.7152*g(X,Y)+0.0722*b(X,Y)";
                let alpha = if *invert {
                    format!("255-({luma})")
                } else {
                    luma.to_string()
                };
                format!("r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':a='{alpha}'")
            }
            Self::PolygonMatte { vertices, invert } => {
                // Build a crossing-number point-in-polygon expression.
                // For each edge (ax,ay)→(bx,by), a horizontal ray from (X,Y) going
                // right crosses the edge when Y is in [min(ay,by), max(ay,by)) and
                // the intersection x > X.  Exact horizontal edges (dy==0) are skipped.
                let n = vertices.len();
                let mut edge_exprs = Vec::new();
                for i in 0..n {
                    let (ax, ay) = vertices[i];
                    let (bx, by) = vertices[(i + 1) % n];
                    let dy = by - ay;
                    if dy == 0.0 {
                        // Horizontal edge — never crosses a horizontal ray; skip.
                        continue;
                    }
                    let min_y = ay.min(by);
                    let max_y = ay.max(by);
                    let dx = bx - ax;
                    // x_intersect = ax*W + (Y - ay*H) * dx*W / (dy*H)
                    // NOTE: the `geq` filter's dimension constants are `W`/`H` (plane
                    // width/height) — it has no `iw`/`ih` (those belong to scale/overlay),
                    // so using them makes `geq` fail with "Undefined constant".
                    // `dx`/`dy` can be negative; parenthesise them so the expression
                    // never contains a bare `*-`/`/-`.
                    edge_exprs.push(format!(
                        "if(gte(Y,{min_y}*H)*lt(Y,{max_y}*H)*gt({ax}*W+(Y-{ay}*H)*({dx})*W/(({dy})*H),X),1,0)"
                    ));
                }
                let sum = if edge_exprs.is_empty() {
                    "0".to_string()
                } else {
                    edge_exprs.join("+")
                };
                let (inside, outside) = if *invert { (0, 255) } else { (255, 0) };
                format!(
                    "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
                     a='if(gt(mod({sum},2),0),{inside},{outside})'"
                )
            }
            Self::FitToAspect { width, height, .. } => {
                // Scale to fit within the target dimensions, preserving the source
                // aspect ratio.  The accompanying pad filter (inserted by
                // filter_inner after this scale filter) centres the result on the
                // target canvas.
                format!("w={width}:h={height}:force_original_aspect_ratio=decrease")
            }
            Self::FillToAspect { width, height } => {
                // Scale to cover the target dimensions, preserving the source
                // aspect ratio.  The accompanying crop filter (inserted by
                // filter_inner after this scale filter) centres the result on the
                // target canvas.
                format!("w={width}:h={height}:force_original_aspect_ratio=increase")
            }
            Self::Pad {
                width,
                height,
                x,
                y,
                color,
            } => {
                let px = if *x < 0 {
                    "(ow-iw)/2".to_string()
                } else {
                    x.to_string()
                };
                let py = if *y < 0 {
                    "(oh-ih)/2".to_string()
                } else {
                    y.to_string()
                };
                format!("width={width}:height={height}:x={px}:y={py}:color={color}")
            }
            Self::ANoiseGate {
                threshold_db,
                attack_ms,
                release_ms,
            } => {
                // `agate` expects threshold as a linear amplitude ratio (0.0–1.0).
                let threshold_linear = 10f32.powf(threshold_db / 20.0);
                format!("threshold={threshold_linear:.6}:attack={attack_ms}:release={release_ms}")
            }
            Self::ACompressor {
                threshold_db,
                ratio,
                attack_ms,
                release_ms,
                makeup_db,
            } => {
                format!(
                    "threshold={threshold_db}dB:ratio={ratio}:attack={attack_ms}:\
                     release={release_ms}:makeup={makeup_db}dB"
                )
            }
            Self::StereoToMono => "mono|c0=0.5*c0+0.5*c1".to_string(),
            Self::ChannelMap { mapping } => format!("map={mapping}"),
            // args() is not used directly for AudioDelay — the audio build loop
            // dispatches to add_raw_filter_step with the correct filter name and
            // args based on the sign of ms.  These are provided for completeness.
            Self::AudioDelay { ms } => {
                if *ms >= 0.0 {
                    format!("delays={ms}:all=1")
                } else {
                    format!("start={}", -ms / 1000.0)
                }
            }
            Self::ATrim { start, end } => match (start, end) {
                (Some(s), Some(e)) => format!("start={s:.6}:end={e:.6}"),
                (Some(s), None) => format!("start={s:.6}"),
                (None, Some(e)) => format!("end={e:.6}"),
                (None, None) => String::new(),
            },
            Self::AResetPts => "PTS-STARTPTS".to_string(),
            Self::ConcatVideo { n } => format!("n={n}:v=1:a=0"),
            Self::ConcatAudio { n } => format!("n={n}:v=0:a=1"),
            Self::CropAnimated {
                x,
                y,
                width,
                height,
            } => {
                let x0 = x.value_at(Duration::ZERO);
                let y0 = y.value_at(Duration::ZERO);
                let w0 = width.value_at(Duration::ZERO);
                let h0 = height.value_at(Duration::ZERO);
                // No `eval=frame`: this FFmpeg's `crop` has no `eval` option and already
                // re-evaluates the x/y position expressions per frame, so `send_command`
                // updates to x/y take effect. (w/h are fixed at init — animate pan, not
                // zoom, via crop; zoom is done by scaling.)
                format!("x={x0}:y={y0}:w={w0}:h={h0}")
            }
            Self::GBlurAnimated { sigma } => {
                let s0 = sigma.value_at(Duration::ZERO);
                format!("sigma={s0}")
            }
            Self::UnsharpAnimated {
                luma_strength,
                chroma_strength,
            } => {
                // No `eval=frame` / `send_command`: `unsharp` has no runtime param,
                // so the CPU path renders the `Duration::ZERO` value statically.
                let l0 = luma_strength.value_at(Duration::ZERO);
                let c0 = chroma_strength.value_at(Duration::ZERO);
                format!(
                    "luma_msize_x=5:luma_msize_y=5:luma_amount={l0}:\
                     chroma_msize_x=5:chroma_msize_y=5:chroma_amount={c0}"
                )
            }
            Self::ScaleAnimated {
                width,
                height,
                algorithm,
            } => {
                let flags = algorithm.as_flags_str();
                let animated = matches!(width, AnimatedValue::Track(_))
                    || matches!(height, AnimatedValue::Track(_));
                if animated {
                    // Self-animate via per-frame expressions. A Static side is a
                    // constant expression; a Track side compiles to a `t`-expression.
                    let expr = |v: &AnimatedValue<f64>| match v {
                        AnimatedValue::Track(t) => t.to_ffmpeg_expr("t"),
                        AnimatedValue::Static(s) => format!("{s:.6}"),
                    };
                    format!(
                        "w={}:h={}:flags={flags}:eval=frame",
                        expr(width),
                        expr(height)
                    )
                } else {
                    let w0 = width.value_at(Duration::ZERO);
                    let h0 = height.value_at(Duration::ZERO);
                    format!("w={w0}:h={h0}:flags={flags}")
                }
            }
            Self::RotateAnimated { angle, fill_color } => match angle {
                // `rotate` re-evaluates `angle` per frame, so a Track self-animates.
                // Compile the degrees track to a `t`-expression, converted to radians.
                AnimatedValue::Track(track) => {
                    let deg = track.to_ffmpeg_expr("t");
                    format!("angle=({deg})*PI/180:fillcolor={fill_color}")
                }
                AnimatedValue::Static(deg) => {
                    format!("angle={}:fillcolor={fill_color}", deg.to_radians())
                }
            },
            Self::VignetteAnimated { amount, x0, y0 } => {
                let cx = if *x0 == 0.0 {
                    "w/2".to_string()
                } else {
                    x0.to_string()
                };
                let cy = if *y0 == 0.0 {
                    "h/2".to_string()
                } else {
                    y0.to_string()
                };
                match amount {
                    // `vignette` re-evaluates `angle` per frame under `eval=frame`, so a
                    // Track self-animates. The normalised amount is scaled to the angle
                    // (radians) in the expression: `amount * PI/2`.
                    AnimatedValue::Track(track) => {
                        let a = track.to_ffmpeg_expr("t");
                        format!("angle=({a})*PI/2:x0={cx}:y0={cy}:eval=frame")
                    }
                    AnimatedValue::Static(a) => {
                        format!("angle={}:x0={cx}:y0={cy}", a * std::f64::consts::FRAC_PI_2)
                    }
                }
            }
            Self::MotionBlur {
                shutter_angle_degrees,
                ..
            } => {
                let alpha = f64::from(*shutter_angle_degrees / 360.0).clamp(0.0, 1.0);
                let keep = 1.0 - alpha;
                let blend = alpha;
                format!("all_expr='A*{keep}+B*{blend}'")
            }
            Self::MotionBlurAnimated { shutter_angle, .. } => match shutter_angle {
                // Same mix as the constant form with the two constants replaced by
                // one clamped sub-expression in `T`. `clip` is FFmpeg's own
                // three-argument clamp, so the shutter stays in `[0, 360]` however
                // the track is authored.
                //
                // `A` is the **current** frame and `B` the previous one, so `alpha`
                // weights the previous: a shutter of 0 renders the current frame
                // untouched and 360 holds the previous one. Measured through the
                // real filter, because the direction is not obvious from `tblend`'s
                // documentation and getting it backwards inverts the effect.
                AnimatedValue::Track(track) => {
                    let deg = track.to_ffmpeg_expr("T");
                    let alpha = format!("clip(({deg})/360,0,1)");
                    format!("all_expr='A*(1-({alpha}))+B*({alpha})'")
                }
                AnimatedValue::Static(deg) => {
                    // Deliberately the *same arithmetic* as `MotionBlur`: an f32
                    // divide widened to f64. Dividing in f64 here would render a
                    // different string for any angle that is not exact in f32 (137
                    // gives 0.3805555555555556 against 0.3805555701255798), so the
                    // two forms would silently disagree where they should overlap.
                    #[allow(clippy::cast_possible_truncation)]
                    let alpha = f64::from((*deg as f32) / 360.0).clamp(0.0, 1.0);
                    let keep = 1.0 - alpha;
                    format!("all_expr='A*{keep}+B*{alpha}'")
                }
            },
            Self::LensCorrection { k1, k2 } => format!("k1={k1}:k2={k2}"),
            Self::FilmGrain {
                luma_strength,
                chroma_strength,
            } => {
                #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
                let ls = luma_strength.clamp(0.0, 100.0) as u32;
                #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
                let cs = chroma_strength.clamp(0.0, 100.0) as u32;
                format!("alls={ls}:c0s={cs}:c1s={cs}:allf=t")
            }
            Self::FilmGrainAnimated {
                luma_strength,
                chroma_strength,
            } => {
                // No `eval=frame` / `send_command`: `noise` has no runtime parameter,
                // so the CPU path renders the `Duration::ZERO` strength statically. The
                // pattern is still temporal via `allf=t`.
                #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
                let ls = luma_strength.value_at(Duration::ZERO).clamp(0.0, 100.0) as u32;
                #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
                let cs = chroma_strength.value_at(Duration::ZERO).clamp(0.0, 100.0) as u32;
                format!("alls={ls}:c0s={cs}:c1s={cs}:allf=t")
            }
            Self::ScaleMultiplier { factor } => {
                format!("w=iw*{factor}:h=ih*{factor}")
            }
            Self::ChromaticAberration { rh, bh } => {
                format!("rh={rh}:bh={bh}:edge=smear")
            }
            // args() is not consumed by add_and_link_step (which is bypassed for
            // this compound step); provided here for completeness.
            Self::Glow {
                threshold,
                radius,
                intensity,
            } => glow_compound_args(*threshold, *radius, *intensity),
            // The compound step is built by `add_glow_step`, not from this string;
            // the args are provided for completeness (rendered at `Duration::ZERO`).
            Self::GlowAnimated {
                threshold,
                radius,
                intensity,
            } => {
                #[allow(clippy::cast_possible_truncation)]
                let out = glow_compound_args(
                    threshold.value_at(Duration::ZERO) as f32,
                    radius.value_at(Duration::ZERO) as f32,
                    intensity.value_at(Duration::ZERO) as f32,
                );
                out
            }
            Self::ReverbEcho {
                in_gain,
                out_gain,
                delays,
                decays,
            } => {
                let delay_str = delays
                    .iter()
                    .map(|d| d.to_string())
                    .collect::<Vec<_>>()
                    .join("|");
                let decay_str = decays
                    .iter()
                    .map(|d| d.to_string())
                    .collect::<Vec<_>>()
                    .join("|");
                format!(
                    "in_gain={ig}:out_gain={og}:delays={ds}:decays={dec}",
                    ig = in_gain,
                    og = out_gain,
                    ds = delay_str,
                    dec = decay_str,
                )
            }
            // args() is not consumed by add_and_link_step (which is bypassed for
            // this compound step); provided here for completeness.
            Self::ReverbIr {
                ir_path,
                wet,
                dry,
                pre_delay_ms,
            } => {
                let delay = pre_delay_ms.min(&500);
                let delay_part = if *delay > 0 {
                    format!(",adelay={delay}:all=1")
                } else {
                    String::new()
                };
                format!("amovie={ir_path}{delay_part}[ir];[0:a][ir]afir=dry={dry}:wet={wet}")
            }
            // args() is not consumed by add_and_link_step (which is bypassed for
            // this compound step); provided here for completeness.
            Self::PitchShift { semitones, .. } => {
                let rate = 2f64.powf(f64::from(*semitones) / 12.0);
                let atempo = 1.0 / rate;
                format!("asetrate=sr*{rate:.6},atempo={atempo:.6}")
            }
            // args() is not consumed by add_and_link_step (bypassed in favour of
            // add_atempo_chain); provided here for single-instance completeness.
            Self::TimeStretch { factor, .. } => format!("{factor:.6}"),
            // args() is not consumed by add_and_link_step (bypassed; sample rate
            // is resolved from buffersrc_args at build time); provided for completeness.
            Self::SpeedChange { factor } => format!("asetrate=sr*{factor:.6}"),
            Self::NoiseReduce {
                noise_type_flag,
                nr_level,
            } => format!("nt={noise_type_flag}:nr={nr_level}"),
            Self::NoiseReduceProfile {
                profile_duration_secs,
                nr_level,
            } => format!("nr={nr_level}:nf=-25:nt=w:pl={profile_duration_secs}"),
            // args() is not consumed by add_and_link_step (bypassed for this
            // compound two-input step); provided for completeness.
            Self::Duck {
                threshold_linear,
                ratio,
                attack_ms,
                release_ms,
            } => format!(
                "threshold={threshold_linear}:ratio={ratio}:attack={attack_ms}:release={release_ms}"
            ),
        }
    }

    /// Animation entries this step contributes for per-frame `send_command`, when it
    /// is an animated variant with `Track` params.
    ///
    /// `node_name` must equal the filter instance name created for this step (the
    /// `send_command` target). Returns empty for non-animated steps and for `Static`
    /// params. Used by [`crate::filter_inner::add_and_link_step`] to surface effect
    /// animations to the composition builders; the standalone [`FilterGraphBuilder`]
    /// registers the equivalent entries in its own builder methods.
    pub(crate) fn animation_entries(&self, node_name: &str) -> Vec<AnimationEntry> {
        let mut entries = Vec::new();
        match self {
            Self::CropAnimated {
                x,
                y,
                width,
                height,
            } => {
                push_scalar_entry(&mut entries, node_name, "x", x);
                push_scalar_entry(&mut entries, node_name, "y", y);
                push_scalar_entry(&mut entries, node_name, "w", width);
                push_scalar_entry(&mut entries, node_name, "h", height);
            }
            Self::GBlurAnimated { sigma } => {
                push_scalar_entry(&mut entries, node_name, "sigma", sigma);
            }
            // `temperature`/`tint` are GPU-only; the `eq` filter has no such runtime
            // command, so they are not pushed here.
            Self::EqAnimated {
                brightness,
                contrast,
                saturation,
                gamma,
                temperature: _,
                tint: _,
            } => {
                push_scalar_entry(&mut entries, node_name, "brightness", brightness);
                push_scalar_entry(&mut entries, node_name, "contrast", contrast);
                push_scalar_entry(&mut entries, node_name, "saturation", saturation);
                push_scalar_entry(&mut entries, node_name, "gamma", gamma);
            }
            Self::ColorBalanceAnimated { lift, gamma, gain } => {
                push_tuple_entries(&mut entries, node_name, ["rs", "gs", "bs"], lift);
                push_tuple_entries(&mut entries, node_name, ["rm", "gm", "bm"], gamma);
                push_tuple_entries(&mut entries, node_name, ["rh", "gh", "bh"], gain);
            }
            _ => {}
        }
        entries
    }
}

/// Pushes an [`AnimationEntry`] for a scalar animated param when it is a `Track`.
fn push_scalar_entry(
    entries: &mut Vec<AnimationEntry>,
    node_name: &str,
    param: &'static str,
    av: &AnimatedValue<f64>,
) {
    if let AnimatedValue::Track(track) = av {
        entries.push(AnimationEntry {
            node_name: node_name.to_owned(),
            param,
            track: track.clone(),
            suffix: "",
        });
    }
}

/// Pushes three per-channel [`AnimationEntry`]s for a `(R, G, B)` tuple animated param
/// when it is a `Track`, splitting the tuple track into one scalar track per channel.
fn push_tuple_entries(
    entries: &mut Vec<AnimationEntry>,
    node_name: &str,
    params: [&'static str; 3],
    av: &AnimatedValue<(f64, f64, f64)>,
) {
    let AnimatedValue::Track(track) = av else {
        return;
    };
    for (i, param) in params.into_iter().enumerate() {
        let scalar = track
            .keyframes()
            .iter()
            .fold(AnimationTrack::new(), |t, kf| {
                let v = match i {
                    0 => kf.value.0,
                    1 => kf.value.1,
                    _ => kf.value.2,
                };
                t.push(Keyframe {
                    timestamp: kf.timestamp,
                    value: v,
                    easing: kf.easing.clone(),
                })
            });
        entries.push(AnimationEntry {
            node_name: node_name.to_owned(),
            param,
            track: scalar,
            suffix: "",
        });
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::animation::{AnimationTrack, Easing, Keyframe};

    #[test]
    fn escape_filter_path_should_escape_windows_drive_path() {
        // Backslashes → forward slashes; the drive colon is escaped as `\:` so
        // FFmpeg's filter-arg parser does not treat it as an option separator.
        assert_eq!(
            escape_filter_path(r"D:\dir\look.cube"),
            "D\\:/dir/look.cube"
        );
    }

    #[test]
    fn escape_filter_path_should_leave_unix_path_unchanged() {
        assert_eq!(escape_filter_path("/home/u/look.cube"), "/home/u/look.cube");
    }

    /// The animated form checked against the linked `FFmpeg`, not against a string.
    ///
    /// The animated shutter leans on one fact about `blend`: its expression is
    /// re-evaluated per frame with `T` bound to the frame's presentation time
    /// (`vf_blend.c`, `values[VAR_T] = pts * time_base`). A string-equality test
    /// cannot tell whether the linked build agrees, so these push frames through the
    /// real filter (RK-005). They live here rather than in `tests/` because `args()`
    /// is `pub(crate)` and widening it for a test would be the wrong trade.
    mod ffmpeg_reference {
        use super::*;
        use crate::FilterGraph;
        use ff_format::{PixelFormat, PooledBuffer, Rational, Timestamp, VideoFrame};

        const W: u32 = 8;
        const H: u32 = 8;
        const FPS: u32 = 30;

        /// A solid-luma frame at `frame_index / FPS` seconds.
        fn frame_at(luma: u8, frame_index: u32) -> VideoFrame {
            VideoFrame::new(
                vec![
                    PooledBuffer::standalone(vec![luma; (W * H) as usize]),
                    PooledBuffer::standalone(vec![128u8; ((W / 2) * (H / 2)) as usize]),
                    PooledBuffer::standalone(vec![128u8; ((W / 2) * (H / 2)) as usize]),
                ],
                vec![W as usize, (W / 2) as usize, (W / 2) as usize],
                W,
                H,
                PixelFormat::Yuv420p,
                // PTS in 1/FPS units, so `blend`'s `T` (pts * time_base) is the
                // frame's time in seconds, which is what the expression reads.
                Timestamp::new(i64::from(frame_index), Rational::new(1, FPS as i32)),
                true,
            )
            .unwrap()
        }

        /// Pushes `count` frames alternating white/black through `tblend=<args>` and
        /// returns the red channel of every frame that came out.
        ///
        /// Alternating matters: `tblend` mixes *consecutive inputs*, not an
        /// accumulating output, so a single seed is washed out after one step and
        /// every later frame would read the same whatever the shutter is. With
        /// alternating input there is contrast at every step, so the mix ratio is
        /// visible at any time.
        ///
        /// `None` means this build could not run the graph, which the callers treat
        /// as a skip (RK-002).
        fn run_tblend(args: &str, count: u32) -> Option<Vec<u8>> {
            let desc = format!("format=rgba,tblend={args},format=rgba");
            let mut graph = FilterGraph::parse_desc(&desc).ok()?;
            let mut out = Vec::new();
            for i in 0..count {
                let luma = if i % 2 == 0 { 235 } else { 16 };
                graph.push_video(0, &frame_at(luma, i)).ok()?;
                while let Ok(Some(frame)) = graph.pull_video() {
                    out.push(frame.plane(0).map(|p| p[0])?);
                }
            }
            Some(out)
        }

        fn constant_args(degrees: f32) -> String {
            FilterStep::MotionBlur {
                shutter_angle_degrees: degrees,
                sub_frames: 4,
            }
            .args()
        }

        fn ramp_args(from: f64, to: f64) -> String {
            let track = AnimationTrack::new()
                .push(Keyframe::new(Duration::ZERO, from, Easing::Linear))
                .push(Keyframe::new(Duration::from_secs(1), to, Easing::Linear));
            FilterStep::MotionBlurAnimated {
                shutter_angle: AnimatedValue::Track(track),
                sub_frames: 4,
            }
            .args()
        }

        #[test]
        fn ffmpeg_should_accept_the_animated_shutter_expression() {
            let Some(_) = run_tblend(&constant_args(180.0), 3) else {
                println!("skipping: this FFmpeg build cannot run tblend");
                return;
            };
            assert!(
                run_tblend(&ramp_args(360.0, 0.0), 3).is_some(),
                "FFmpeg rejected the animated shutter expression: {}",
                ramp_args(360.0, 0.0)
            );
        }

        #[test]
        fn an_animated_shutter_should_vary_across_frames_where_a_constant_one_does_not() {
            // The point of the animated form: with the same alternating input, a
            // constant shutter gives the same mix at every step, while a ramp gives a
            // different one as `T` advances. A build that ignored `T` would produce
            // the constant's flat answer for both.
            let Some(flat) = run_tblend(&constant_args(180.0), FPS) else {
                println!("skipping: this FFmpeg build cannot run tblend");
                return;
            };
            let Some(ramped) = run_tblend(&ramp_args(0.0, 360.0), FPS) else {
                return;
            };
            // `tblend` emits from the second input on, so output `k` is input frame
            // `k + 1`. Both indices below are odd, so both outputs come from an even
            // input frame and share the same pair (current white, previous black);
            // only the shutter differs. Mixing parities compares a white-over-black
            // step against a black-over-white one, where the two effects cancel and
            // the swing reads as small.
            //
            // Measured, and matching the algebra exactly: output 3 is input frame 4
            // (T = 0.133 s, shutter 48, alpha 0.133) -> 255*0.867 = 221, and output
            // 27 is frame 28 (alpha 0.933) -> 255*0.067 = 17.
            let (early, late) = (3usize, 27usize);
            assert_eq!(early % 2, late % 2, "the two samples must share a parity");
            println!(
                "tblend same-parity frames {early} / {late}: constant180={:?} ramp0to360={:?}",
                (flat.get(early), flat.get(late)),
                (ramped.get(early), ramped.get(late))
            );
            let (fe, fl) = (flat[early], flat[late]);
            let (re, rl) = (ramped[early], ramped[late]);
            assert!(
                fe.abs_diff(fl) <= 2,
                "a constant shutter must give the same mix at both frames: {fe} vs {fl}"
            );
            assert!(
                re.abs_diff(rl) > 32,
                "a ramped shutter must give a different mix as T advances: {re} vs {rl}"
            );
        }
    }

    #[test]
    fn motion_blur_animated_static_should_render_what_the_constant_form_renders() {
        // The two forms overlap at a constant shutter, and 137 is chosen precisely
        // because it is not exact in f32: an f64 divide here would render
        // 0.3805555555555556 where the constant form renders 0.3805555701255798,
        // and the paths would disagree for every ordinary angle.
        let constant = FilterStep::MotionBlur {
            shutter_angle_degrees: 137.0,
            sub_frames: 4,
        };
        let animated = FilterStep::MotionBlurAnimated {
            shutter_angle: AnimatedValue::Static(137.0),
            sub_frames: 4,
        };
        assert_eq!(constant.args(), animated.args());
        assert_eq!(constant.filter_name(), animated.filter_name());
    }

    #[test]
    fn motion_blur_animated_track_should_render_an_uppercase_t_expression() {
        // `blend`'s expression variables are upper-case (`X Y W H SW SH T N A B TOP
        // BOTTOM`). A lower-case `t` is not among them and would evaluate as an
        // unknown, so the case is part of the contract, not a style choice.
        let track = AnimationTrack::new()
            .push(Keyframe::new(Duration::ZERO, 0.0, Easing::Linear))
            .push(Keyframe::new(Duration::from_secs(1), 360.0, Easing::Linear));
        let step = FilterStep::MotionBlurAnimated {
            shutter_angle: AnimatedValue::Track(track),
            sub_frames: 4,
        };
        let args = step.args();
        assert!(
            args.contains('T'),
            "the expression must reference T: {args}"
        );
        assert!(
            !args.contains(" t") && !args.contains("(t"),
            "a lower-case t is not a blend variable: {args}"
        );
        assert!(
            args.contains("clip("),
            "the shutter must stay clamped to [0, 360]: {args}"
        );
        assert!(
            args.starts_with("all_expr='A*(1-(") && args.ends_with("'"),
            "the mix must keep the A/B form the constant version uses: {args}"
        );
    }

    #[test]
    fn motion_blur_animated_should_be_a_tblend_step() {
        let step = FilterStep::MotionBlurAnimated {
            shutter_angle: AnimatedValue::Static(180.0),
            sub_frames: 4,
        };
        assert_eq!(step.filter_name(), "tblend");
    }

    #[test]
    fn lut3d_args_should_escape_path() {
        let step = FilterStep::Lut3d {
            path: r"D:\luts\look.cube".to_string(),
        };
        let args = step.args();
        assert!(
            !args.contains(r"D:\"),
            "raw Windows path must not appear unescaped in args: {args}"
        );
        assert!(args.contains("D\\:/luts/look.cube"), "got: {args}");
        assert!(args.ends_with(":interp=trilinear"));
    }

    #[test]
    fn setparams_filter_name_should_be_setparams() {
        let step = FilterStep::SetParams {
            color_space: None,
            color_range: None,
            color_primaries: None,
            color_trc: None,
        };
        assert_eq!(step.filter_name(), "setparams");
    }

    #[test]
    fn raw_filter_name_should_be_the_given_filter() {
        let step = FilterStep::Raw {
            filter: "selectivecolor".to_string(),
            args: "reds=0.1 0 0".to_string(),
        };
        assert_eq!(step.filter_name(), "selectivecolor");
    }

    #[test]
    fn fill_to_aspect_args_should_cover_with_increase() {
        let step = FilterStep::FillToAspect {
            width: 1920,
            height: 1080,
        };
        assert_eq!(
            step.args(),
            "w=1920:h=1080:force_original_aspect_ratio=increase"
        );
    }

    #[test]
    fn fill_to_aspect_filter_name_should_be_scale() {
        let step = FilterStep::FillToAspect {
            width: 1920,
            height: 1080,
        };
        assert_eq!(step.filter_name(), "scale");
    }

    #[test]
    fn raw_args_should_pass_through_verbatim() {
        let step = FilterStep::Raw {
            filter: "selectivecolor".to_string(),
            args: "reds=0.1 0 0:blues=0 0 0.2".to_string(),
        };
        assert_eq!(step.args(), "reds=0.1 0 0:blues=0 0 0.2");
    }

    #[test]
    fn raw_with_empty_args_should_render_empty_args() {
        let step = FilterStep::Raw {
            filter: "hflip".to_string(),
            args: String::new(),
        };
        assert_eq!(step.filter_name(), "hflip");
        assert_eq!(step.args(), "");
    }

    #[test]
    fn setparams_args_should_emit_all_canonical_tokens() {
        let step = FilterStep::SetParams {
            color_space: Some(ColorSpace::Bt2020Ncl),
            color_range: Some(ColorRange::Limited),
            color_primaries: Some(ColorPrimaries::Bt2020),
            color_trc: Some(ColorTransfer::Hlg),
        };
        assert_eq!(
            step.args(),
            "colorspace=bt2020nc:range=tv:color_primaries=bt2020:color_trc=arib-std-b67"
        );
    }

    #[test]
    fn setparams_args_should_emit_only_provided_options() {
        // HDR tagging often sets just primaries + transfer.
        let step = FilterStep::SetParams {
            color_space: None,
            color_range: None,
            color_primaries: Some(ColorPrimaries::Bt2020),
            color_trc: Some(ColorTransfer::Pq),
        };
        assert_eq!(step.args(), "color_primaries=bt2020:color_trc=smpte2084");
    }

    #[test]
    fn setparams_args_should_skip_values_without_ffmpeg_token() {
        // `Unknown` renders to no token and must be skipped, not emitted as an invalid arg.
        let step = FilterStep::SetParams {
            color_space: Some(ColorSpace::Unknown),
            color_range: Some(ColorRange::Full),
            color_primaries: Some(ColorPrimaries::Unknown),
            color_trc: Some(ColorTransfer::Bt709),
        };
        assert_eq!(step.args(), "range=pc:color_trc=bt709");
    }

    #[test]
    fn setparams_args_should_be_empty_when_all_none() {
        let step = FilterStep::SetParams {
            color_space: None,
            color_range: None,
            color_primaries: None,
            color_trc: None,
        };
        assert_eq!(step.args(), "");
    }

    #[test]
    fn chroma_key_animated_should_render_static_zero_values_via_chromakey() {
        // The CPU path is static: args() renders the Duration::ZERO values through
        // the same `chromakey` filter as the const variant.
        let step = FilterStep::ChromaKeyAnimated {
            color: "0x00FF00".to_string(),
            similarity: AnimatedValue::Static(0.3),
            blend: AnimatedValue::Static(0.1),
        };
        assert_eq!(step.filter_name(), "chromakey");
        assert_eq!(step.args(), "color=0x00FF00:similarity=0.3:blend=0.1");
    }

    #[test]
    fn rect_mask_animated_should_render_static_zero_bounds_via_geq() {
        // The CPU path is static: args() renders the Duration::ZERO rectangle through
        // the same geq expression as the const RectMask variant.
        let step = FilterStep::RectMaskAnimated {
            x: AnimatedValue::Static(10.0),
            y: AnimatedValue::Static(20.0),
            width: AnimatedValue::Static(30.0),
            height: AnimatedValue::Static(40.0),
            invert: false,
        };
        assert_eq!(step.filter_name(), "geq");
        // xw = 10 + 30 - 1 = 39, yh = 20 + 40 - 1 = 59.
        assert_eq!(
            step.args(),
            "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
             a='if(between(X,10,39)*between(Y,20,59),255,0)'"
        );
    }

    #[test]
    fn rect_mask_animated_invert_should_swap_inside_outside() {
        let step = FilterStep::RectMaskAnimated {
            x: AnimatedValue::Static(0.0),
            y: AnimatedValue::Static(0.0),
            width: AnimatedValue::Static(8.0),
            height: AnimatedValue::Static(8.0),
            invert: true,
        };
        assert_eq!(
            step.args(),
            "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
             a='if(between(X,0,7)*between(Y,0,7),0,255)'"
        );
    }

    #[test]
    fn luma_mask_should_render_bt709_self_luma_geq() {
        // Non-invert: alpha becomes the frame's own BT.709 luma via geq. (geq exposes
        // no alpha-read function here, so alpha is set to the luma rather than
        // multiplied; on the opaque source this equals LumaMaskNode's alpha *= luma.)
        let step = FilterStep::LumaMask { invert: false };
        assert_eq!(step.filter_name(), "geq");
        assert_eq!(
            step.args(),
            "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
             a='0.2126*r(X,Y)+0.7152*g(X,Y)+0.0722*b(X,Y)'"
        );
    }

    #[test]
    fn luma_mask_invert_should_use_one_minus_luma() {
        // Invert: `255 - luma`, so dark pixels stay opaque.
        let step = FilterStep::LumaMask { invert: true };
        assert_eq!(
            step.args(),
            "r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':\
             a='255-(0.2126*r(X,Y)+0.7152*g(X,Y)+0.0722*b(X,Y))'"
        );
    }

    #[test]
    fn animation_entries_maps_only_track_params_to_the_node() {
        use crate::animation::{AnimatedValue, AnimationTrack, Easing, Keyframe};
        let ramp = || {
            AnimationTrack::new()
                .push(Keyframe::new(Duration::ZERO, 0.0, Easing::Linear))
                .push(Keyframe::new(Duration::from_secs(1), 10.0, Easing::Linear))
        };
        // Only x and h are Track → exactly two entries, both on the given node.
        let step = FilterStep::CropAnimated {
            x: AnimatedValue::Track(ramp()),
            y: AnimatedValue::Static(0.0),
            width: AnimatedValue::Static(4.0),
            height: AnimatedValue::Track(ramp()),
        };
        let entries = step.animation_entries("veff0");
        assert_eq!(entries.len(), 2);
        assert!(entries.iter().all(|e| e.node_name == "veff0"));
        let params: Vec<&str> = entries.iter().map(|e| e.param).collect();
        assert!(params.contains(&"x") && params.contains(&"h"));

        // A fully static animated step registers nothing.
        let static_step = FilterStep::CropAnimated {
            x: AnimatedValue::Static(0.0),
            y: AnimatedValue::Static(0.0),
            width: AnimatedValue::Static(4.0),
            height: AnimatedValue::Static(8.0),
        };
        assert!(static_step.animation_entries("veff0").is_empty());

        // A non-animated step never contributes entries.
        assert!(
            FilterStep::Crop {
                x: 0,
                y: 0,
                width: 4,
                height: 8,
            }
            .animation_entries("veff0")
            .is_empty()
        );
    }
}