nooise 2.7.0

//! The Kick voice: legacy FM characters and 909-style resonant characters
//! under one trigger grid and Type selector.

use super::*;

pub(crate) struct KickEngine {
    pub(crate) sample_rate: f32,
    pub(crate) trigger: GridTrigger,
    pub(crate) voices: Vec<KickVoice>,
    pub(crate) rng: StdRng,
    pub(crate) telemetry: Arc<FluidTelemetry>,
}

impl KickEngine {
    pub(crate) fn new(sample_rate: f32, telemetry: Arc<FluidTelemetry>) -> Self {
        Self {
            sample_rate,
            trigger: GridTrigger::new(),
            voices: Vec::with_capacity(4),
            rng: StdRng::from_entropy(),
            telemetry,
        }
    }

    pub(crate) fn next(&mut self, c: &KickControls, timing: TimingContext) -> (f32, f32) {
        if self
            .trigger
            .pop_swung(timing, c.interval_beats, c.offset_beats, c.swing)
        {
            self.voices.push(KickVoice::new(
                wrapped_index(c.voice_type, KICK_TYPES.len()),
                c,
                self.sample_rate,
                &mut self.rng,
            ));
            self.telemetry.publish_kick(c.level);
        }

        let rng = &mut self.rng;
        mix_and_retain(&mut self.voices, |v| v.next(rng), KickVoice::is_done)
    }
}

/// Shared click transient + amplitude envelope + soft-attack + pan
/// machinery behind the original four `kick.type` voices: a single exponential amplitude
/// decay (also gates voice life via `is_done`), an optional short noise click
/// layered in at onset, an optional linear fade-in that rounds off the onset
/// transient, and a fixed per-voice
/// stereo pan drawn once at construction. Each variant supplies its own
/// pitch/oscillator body and filter around this; `shape` only covers the
/// parts identical across all types. `shape` updates `amp` for the
/// *next* call after using today's value to build `s`, so moving it ahead of
/// a caller-applied filter stage never changes the sample actually returned
/// (the filter never reads `amp`).
///
/// Both softening parameters are per-variant and inert at their Sub values:
/// `attack_samples` 0 leaves the fade-in branch untaken, and `click_scale`
/// 1.0 is an exact f32 identity on `c.click`. Sub therefore stays
/// byte-identical to its pre-`kick.type` render (enforced by
/// `kick_type_zero_matches_legacy_sub_voice_exactly`).
pub(crate) struct KickVoiceCore {
    pub(crate) amp: f32,
    pub(crate) amp_decay: f32,
    pub(crate) click_remaining: u64,
    pub(crate) click_level: f32,
    pub(crate) attack_remaining: u64,
    pub(crate) attack_gain: f32,
    pub(crate) attack_inc: f32,
    pub(crate) pan_gains: (f32, f32),
}

impl KickVoiceCore {
    pub(crate) fn new(
        c: &KickControls,
        sample_rate: f32,
        rng: &mut StdRng,
        attack_ms: f32,
        click_scale: f32,
    ) -> Self {
        let amp_tau = (c.amp_decay_ms * 0.001 * sample_rate / 3.0).max(1.0);
        let attack_samples = (attack_ms * 0.001 * sample_rate).round().max(0.0) as u64;
        Self {
            amp: c.level,
            amp_decay: (-1.0 / amp_tau).exp(),
            click_remaining: (c.amp_decay_ms * 0.001 * sample_rate * 0.04).round() as u64,
            click_level: c.click * click_scale,
            attack_remaining: attack_samples,
            attack_gain: 0.0,
            attack_inc: if attack_samples == 0 {
                0.0
            } else {
                1.0 / attack_samples as f32
            },
            pan_gains: StereoPanner::gains(rng.gen_range(-0.15f32..0.15)),
        }
    }

    #[inline]
    pub(crate) fn shape<R: Rng>(&mut self, body: f32, rng: &mut R) -> f32 {
        let mut s = body * self.amp;
        if self.click_remaining > 0 {
            s += rng.gen_range(-1.0f32..1.0) * self.click_level * self.amp;
            self.click_remaining -= 1;
        }
        // Applied to the output sample, never to `amp`, so the decay envelope
        // math (and `is_done`) is identical with or without an attack ramp.
        if self.attack_remaining > 0 {
            s *= self.attack_gain;
            self.attack_gain = (self.attack_gain + self.attack_inc).min(1.0);
            self.attack_remaining -= 1;
        }
        self.amp *= self.amp_decay;
        s
    }

    pub(crate) fn is_done(&self) -> bool {
        self.amp < 0.0001
    }
}

/// `kick.type` selects the voice character used for every new kick hit.
/// Index 0 (`Sub`) is the legacy voice, unchanged and the default; switching
/// type never touches the shared trigger/scheduling path in
/// `KickEngine::next` above. Types 1-3 stay soft and textural. Types 4-6
/// use a 909-style resonant body with an onset impulse and longer bass ring.
pub(crate) enum KickVoice {
    Lowpass(LowpassKickVoice),
    Wood(WoodKickVoice),
    Analog(AnalogKickVoice),
}

impl KickVoice {
    pub(crate) fn new(
        voice_type: usize,
        c: &KickControls,
        sample_rate: f32,
        rng: &mut StdRng,
    ) -> Self {
        match voice_type {
            0 => Self::Lowpass(LowpassKickVoice::new(&KICK_SUB, c, sample_rate, rng)),
            1 => Self::Lowpass(LowpassKickVoice::new(&KICK_WARM, c, sample_rate, rng)),
            2 => Self::Wood(WoodKickVoice::new(c, sample_rate, rng)),
            3 => Self::Lowpass(LowpassKickVoice::new(&KICK_FELT, c, sample_rate, rng)),
            4 => Self::Analog(AnalogKickVoice::new(&KICK_909, c, sample_rate, rng)),
            5 => Self::Analog(AnalogKickVoice::new(&KICK_DEEP, c, sample_rate, rng)),
            _ => Self::Analog(AnalogKickVoice::new(&KICK_DUST, c, sample_rate, rng)),
        }
    }

    pub(crate) fn next<R: Rng>(&mut self, rng: &mut R) -> (f32, f32) {
        match self {
            Self::Lowpass(voice) => voice.next(rng),
            Self::Wood(voice) => voice.next(rng),
            Self::Analog(voice) => voice.next(rng),
        }
    }

    pub(crate) fn is_done(&self) -> bool {
        match self {
            Self::Lowpass(voice) => voice.is_done(),
            Self::Wood(voice) => voice.is_done(),
            Self::Analog(voice) => voice.is_done(),
        }
    }
}

/// Shared FM body behind the original four `kick.type` voices: an exponential pitch glide
/// from `start_freq` toward a per-type drop ratio, feeding a single
/// modulator→carrier `FmStack` pair whose modulation index decays ~3x faster
/// than the pitch, which is what makes the onset read as a tight thud. Each
/// variant supplies its own constants and carrier waveform, so carrier shape
/// and any post-body filter stay per-type.
///
/// The glide stays here rather than in `synth::fm` because it is a kick
/// gesture, not an FM one: the stack takes a base frequency per sample and
/// has no opinion about how the caller arrived at it.
pub(crate) struct KickFmBody {
    pub(crate) freq: f32,
    pub(crate) target_freq: f32,
    pub(crate) freq_glide: f32,
    pub(crate) stack: FmStack,
}

impl KickFmBody {
    pub(crate) fn new(
        c: &KickControls,
        sample_rate: f32,
        pitch_drop_ratio: f32,
        mod_ratio: f32,
        fm_depth: f32,
        carrier_wave: FmWave,
    ) -> Self {
        let tau = (c.pitch_decay_ms * 0.001 * sample_rate / 3.0).max(1.0);
        let fm_tau = (c.pitch_decay_ms * 0.001 * sample_rate / 9.0).max(1.0);
        Self {
            freq: c.start_freq,
            target_freq: c.start_freq * pitch_drop_ratio,
            freq_glide: 1.0 / tau,
            stack: FmStack::new(sample_rate).with_pair(
                FmPair::new(mod_ratio, KICK_CARRIER_RATIO, fm_depth)
                    .with_wave(carrier_wave)
                    .with_index_decay(fm_tau),
            ),
        }
    }

    /// Advances the glide and the FM pair by one sample and returns the
    /// shaped body sample.
    #[inline]
    pub(crate) fn next(&mut self) -> f32 {
        self.freq += (self.target_freq - self.freq) * self.freq_glide;
        self.stack.next(self.freq)
    }
}

/// Every kick carrier sounds at the glided pitch itself; the glide, not a
/// carrier ratio, is what moves this voice. Formant-style timbres are what
/// the carrier ratio exists for.
const KICK_CARRIER_RATIO: f32 = 1.0;

/// Where the original voices' local filters sit, now that the interactive
/// sweep is a Filter module in the kick's chain.
pub(crate) const KICK_CHARACTER_FILTER_POSITION: f32 = 0.7;

/// One-pole lowpass at the fixed character position, shared by every type
/// that ends in a lowpass. `bias` shifts the same mapping
/// darker or brighter per type.
pub(crate) struct KickLowPass {
    pub(crate) state: f32,
    pub(crate) coeff: f32,
}

impl KickLowPass {
    pub(crate) fn new(filter: f32, bias: f32) -> Self {
        Self {
            state: 0.0,
            coeff: 10_f32.powf(filter * 3.0 + bias).clamp(0.01, 0.99),
        }
    }

    #[inline]
    pub(crate) fn process(&mut self, s: f32) -> f32 {
        self.state += self.coeff * (s - self.state);
        self.state
    }
}

/// Everything that distinguishes one lowpass-filtered kick character from
/// another. Sub, Warm, and Felt use `KickVoiceCore` shaping a `KickFmBody`,
/// trimmed through `KickLowPass`. Wood has its own bandpass path.
pub(crate) struct LowpassKickRecipe {
    /// Linear onset fade-in; 0.0 leaves `KickVoiceCore`'s fade branch untaken.
    attack_ms: f32,
    /// Scale on the user's `kick.click`; 1.0 is an exact f32 identity.
    click_scale: f32,
    /// The body settles at this ratio of its starting frequency.
    pitch_drop_ratio: f32,
    fm_mod_ratio: f32,
    fm_depth: f32,
    wave: FmWave,
    /// `KickLowPass` mapping bias; Sub's is the reference the others are
    /// stated relative to.
    filter_bias: f32,
    /// Output trim: brings the voice to Sub's rendered level at the same
    /// `kick.level`. Measured, not chosen by ear —
    /// `kick_types_render_at_a_matched_level` pins it. Sub's is exactly 1.0,
    /// an f32 identity, so its render stays byte-for-byte the legacy voice.
    output_gain: f32,
}

/// Type 0 (default): the original kick voice, byte-for-byte unchanged. A
/// sine carrier phase-modulated by a 2x-ratio sine modulator with decaying
/// depth (a tight FM thud), an exponential pitch glide from `start_freq` down
/// to `start_freq * 0.28`, an onset noise click, and a fixed character
/// lowpass. The interactive Filter and Drive both run later in the shared
/// layer module chain.
pub(crate) const KICK_SUB: LowpassKickRecipe = LowpassKickRecipe {
    attack_ms: 0.0,
    click_scale: 1.0,
    pitch_drop_ratio: 0.28,
    // 2x puts sidebands on the harmonic series, which is what keeps this
    // voice reading as one fused low body.
    fm_mod_ratio: 2.0,
    // The original hard transient edge; the three soft types back away from it.
    fm_depth: 3.5,
    wave: FmWave::Sine,
    filter_bias: -2.5,
    output_gain: 1.0,
};

/// Type 1: a warm, round FM body. Same FM-thud/pitch-glide approach as Sub,
/// but with a shallow FM depth at a hollow, woody modulator ratio, a slightly
/// shallower pitch drop, a soft attack ramp, and a scaled-down click.
pub(crate) const KICK_WARM: LowpassKickRecipe = LowpassKickRecipe {
    // Rounds off the transient snap so the hit reads as a swell into a body
    // rather than a drum-machine attack.
    attack_ms: 6.0,
    // The broadband onset noise burst is the single most aggressive-sounding
    // element of a kick; scaled well down.
    click_scale: 0.45,
    // Shallower than Sub's 0.28x, so the body settles a little above Sub
    // without reading as a second sub layer.
    pitch_drop_ratio: 0.42,
    // Below Sub's 2x: a 1.5 ratio places sidebands at non-harmonic-series
    // intervals that read hollow and woody rather than bright. Ratios at or
    // above 3x produce the metallic clang this voice deliberately avoids.
    fm_mod_ratio: 1.5,
    // Well below Sub's 3.5, so the modulator rounds the body out instead of
    // adding a hard transient edge.
    fm_depth: 1.2,
    wave: FmWave::Sine,
    // Nudged up from Sub's -2.5 so this voice's slightly higher body isn't
    // over-attenuated, but kept most of the way back so it stays dark.
    filter_bias: -2.35,
    output_gain: 1.11,
};

/// Type 3: a soft mallet/felt character. Swaps Sub's sine carrier for a naive
/// (non-band-limited, consistent with this codebase's additive-approximation
/// approach elsewhere — see `bass.rs`'s Saw voice) triangle: odd harmonics
/// only, falling off as 1/n², so it thickens the body without adding edge,
/// under a darker lowpass mapping than Sub.
pub(crate) const KICK_FELT: LowpassKickRecipe = LowpassKickRecipe {
    // The longest of the three soft types: a felt mallet compresses on
    // contact rather than striking instantly.
    attack_ms: 8.0,
    // Furthest down; a felt beater has almost no broadband contact noise.
    click_scale: 0.25,
    // Matches Sub, so only the carrier waveform and filter darkness change.
    pitch_drop_ratio: 0.28,
    fm_mod_ratio: KICK_SUB.fm_mod_ratio,
    // Well below Sub's 3.5: the triangle carrier already brings its own odd
    // harmonics, so Sub's depth would push this into buzz.
    fm_depth: 1.8,
    wave: FmWave::Triangle,
    // Below Sub's -2.5, so the same character position lands darker and
    // duller — the felt-beater muffling.
    filter_bias: -2.9,
    output_gain: 1.36,
};

/// The lowpass-filtered FM signal path for Sub, Warm, and Felt:
/// `KickVoiceCore` shaping the FM body, the recipe's output trim, then the
/// one-pole `KickLowPass`.
pub(crate) struct LowpassKickVoice {
    pub(crate) core: KickVoiceCore,
    pub(crate) body: KickFmBody,
    pub(crate) lowpass: KickLowPass,
    pub(crate) output_gain: f32,
}

impl LowpassKickVoice {
    pub(crate) fn new(
        recipe: &LowpassKickRecipe,
        c: &KickControls,
        sample_rate: f32,
        rng: &mut StdRng,
    ) -> Self {
        Self {
            core: KickVoiceCore::new(c, sample_rate, rng, recipe.attack_ms, recipe.click_scale),
            body: KickFmBody::new(
                c,
                sample_rate,
                recipe.pitch_drop_ratio,
                recipe.fm_mod_ratio,
                recipe.fm_depth,
                recipe.wave,
            ),
            lowpass: KickLowPass::new(KICK_CHARACTER_FILTER_POSITION, recipe.filter_bias),
            output_gain: recipe.output_gain,
        }
    }

    pub(crate) fn next<R: Rng>(&mut self, rng: &mut R) -> (f32, f32) {
        if self.core.is_done() {
            return (0.0, 0.0);
        }

        let body = self.body.next();
        let s = self
            .lowpass
            .process(self.core.shape(body, rng) * self.output_gain);

        (s * self.core.pan_gains.0, s * self.core.pan_gains.1)
    }

    pub(crate) fn is_done(&self) -> bool {
        self.core.is_done()
    }
}

/// A 909-style resonant body. Pitch falls through the low mids in the first
/// few cycles, then one sine oscillator rings at the bass fundamental. Its
/// long amplitude decay is independent of that pitch sweep. An onset-only
/// noise burst supplies the short beater sound without a separate mid tone.
pub(crate) struct AnalogKickRecipe {
    start_ratio: f32,
    end_ratio: f32,
    pitch_tau_ratio: f32,
    amp_tau_ratio: f32,
    click_scale: f32,
    attack_harmonic: f32,
    excitation: f32,
    impact: f32,
    output_gain: f32,
}

pub(crate) const KICK_909: AnalogKickRecipe = AnalogKickRecipe {
    start_ratio: 1.3,
    end_ratio: 0.27,
    pitch_tau_ratio: 0.48,
    amp_tau_ratio: 1.2,
    click_scale: 5.0,
    attack_harmonic: 0.1,
    excitation: 0.75,
    impact: 2.0,
    output_gain: 0.72,
};

pub(crate) const KICK_DEEP: AnalogKickRecipe = AnalogKickRecipe {
    start_ratio: 1.15,
    end_ratio: 0.25,
    pitch_tau_ratio: 0.55,
    amp_tau_ratio: 1.25,
    click_scale: 2.5,
    attack_harmonic: 0.05,
    excitation: 0.35,
    impact: 1.4,
    output_gain: 0.75,
};

pub(crate) const KICK_DUST: AnalogKickRecipe = AnalogKickRecipe {
    start_ratio: 1.3,
    end_ratio: 0.27,
    pitch_tau_ratio: 0.48,
    amp_tau_ratio: 0.9,
    click_scale: 6.0,
    attack_harmonic: 0.25,
    excitation: 0.9,
    impact: 1.5,
    output_gain: 0.77,
};

pub(crate) struct AnalogKickVoice {
    sample_rate: f32,
    sample_index: u64,
    onset_samples: u64,
    attack_samples: f32,
    impact_center: f32,
    impact_half_width: f32,
    impact: f32,
    phase: f32,
    freq: f32,
    target_freq: f32,
    freq_glide: f32,
    amp: f32,
    amp_decay: f32,
    click: f32,
    click_remaining: u64,
    click_decay: f32,
    attack_harmonic: f32,
    harmonic_decay: f32,
    excitation: f32,
    excitation_decay: f32,
    output_gain: f32,
    pan_gains: (f32, f32),
}

impl AnalogKickVoice {
    pub(crate) fn new(
        recipe: &AnalogKickRecipe,
        c: &KickControls,
        sample_rate: f32,
        rng: &mut StdRng,
    ) -> Self {
        let pitch_tau = (c.pitch_decay_ms * 0.001 * sample_rate * recipe.pitch_tau_ratio).max(1.0);
        let amp_tau = (c.amp_decay_ms * 0.001 * sample_rate * recipe.amp_tau_ratio).max(1.0);
        Self {
            sample_rate,
            sample_index: 0,
            onset_samples: (0.0027 * sample_rate).round() as u64,
            attack_samples: 0.001 * sample_rate,
            impact_center: 0.0034 * sample_rate,
            impact_half_width: 0.00018 * sample_rate,
            impact: recipe.impact,
            phase: -1.3,
            freq: c.start_freq * recipe.start_ratio,
            target_freq: c.start_freq * recipe.end_ratio,
            freq_glide: 1.0 - (-1.0 / pitch_tau).exp(),
            amp: c.level,
            amp_decay: (-1.0 / amp_tau).exp(),
            click: c.click * recipe.click_scale * c.level,
            click_remaining: (0.015 * sample_rate).round() as u64,
            click_decay: (-1.0 / (0.003 * sample_rate)).exp(),
            attack_harmonic: recipe.attack_harmonic,
            harmonic_decay: (-1.0 / (0.018 * sample_rate)).exp(),
            excitation: recipe.excitation,
            excitation_decay: (-1.0 / (0.015 * sample_rate)).exp(),
            output_gain: recipe.output_gain,
            pan_gains: StereoPanner::gains(rng.gen_range(-0.15f32..0.15)),
        }
    }

    #[inline]
    pub(crate) fn next<R: Rng>(&mut self, rng: &mut R) -> (f32, f32) {
        if self.is_done() {
            return (0.0, 0.0);
        }
        self.freq += (self.target_freq - self.freq) * self.freq_glide;
        let body = if self.sample_index < self.onset_samples {
            0.0
        } else {
            self.phase += std::f32::consts::TAU * self.freq / self.sample_rate;
            if self.phase >= std::f32::consts::TAU {
                self.phase -= std::f32::consts::TAU;
            }
            let attack =
                ((self.sample_index - self.onset_samples) as f32 / self.attack_samples).min(1.0);
            let harmonic = if self.attack_harmonic > 0.0001 {
                self.attack_harmonic * (self.phase * 2.0).sin()
            } else {
                0.0
            };
            (self.phase.sin() + harmonic) * attack
        };
        let impact_distance = (self.sample_index as f32 - self.impact_center).abs();
        let impact = if impact_distance < self.impact_half_width {
            self.impact * (1.0 - impact_distance / self.impact_half_width)
        } else {
            0.0
        };
        let click = if self.click_remaining > 0 {
            self.click_remaining -= 1;
            rng.gen_range(-1.0f32..1.0) * self.click
        } else {
            0.0
        };
        let sample = (body * self.amp * (1.0 + self.excitation) + click - impact * self.amp)
            * self.output_gain;
        self.amp *= self.amp_decay;
        self.click *= self.click_decay;
        self.attack_harmonic *= self.harmonic_decay;
        self.excitation *= self.excitation_decay;
        self.sample_index += 1;
        (sample * self.pan_gains.0, sample * self.pan_gains.1)
    }

    pub(crate) fn is_done(&self) -> bool {
        self.amp < 0.001
    }
}

/// Bounds the Wood bandpass's center is placed within. The character
/// position picks one point on this exponential low-mid range, where a struck
/// wooden body resonates; higher centers read as a thin, hollow tom.
const KICK_WOOD_CENTER_MIN_HZ: f32 = 110.0;
const KICK_WOOD_CENTER_MAX_HZ: f32 = 400.0;
/// SVF damping factor (Chamberlin topology): lower = more resonant. Set high
/// enough that the band colors the body without the long "boingy" ring a
/// lightly-damped SVF produces.
const KICK_WOOD_DAMP: f32 = 0.9;
/// Pitch-drop ratio, slightly shallower than Sub's 0.28x so the resonant body
/// has a clearer starting pitch to color.
const KICK_WOOD_PITCH_DROP_RATIO: f32 = 0.35;
/// Bandpass/dry blend. The bandpass alone throws away the carrier's low end
/// and reads thin; blending the unfiltered dry signal back in keeps the
/// weight underneath the wooden coloration.
const KICK_WOOD_BANDPASS_MIX: f32 = 0.6;
/// Linear onset fade-in, rounding off the transient snap.
const KICK_WOOD_ATTACK_MS: f32 = 5.0;
/// Scales the user's `kick.click` down; the broadband burst fights the soft
/// wooden body.
const KICK_WOOD_CLICK_SCALE: f32 = 0.35;
/// Output trim.
///
/// How much energy the bandpass passes depends on how far its center sits
/// from where the body's energy actually is, and the body is low: it starts
/// at `start_freq` and glides down to a third of that. A low center sits on
/// the fundamental and passes nearly all of it while a high center passes a
/// fraction, so the trim has to follow the center to keep Wood level with the
/// other three types. The curve is an empirical fit against measured output,
/// not a derived law — there is no closed form for the overlap between the
/// bandpass and the glide's moving spectrum.
/// `kick_types_render_at_a_matched_level` pins it, so retuning the timbre
/// cannot silently drift the balance back.
const KICK_WOOD_OUTPUT_GAIN_AT_DARKEST: f32 = 0.78;
const KICK_WOOD_OUTPUT_GAIN_SPAN: f32 = 1.91;
const KICK_WOOD_OUTPUT_GAIN_CURVE: f32 = 0.7;

fn kick_wood_output_gain(filter: f32) -> f32 {
    KICK_WOOD_OUTPUT_GAIN_AT_DARKEST
        * (1.0 + KICK_WOOD_OUTPUT_GAIN_SPAN * filter.powf(KICK_WOOD_OUTPUT_GAIN_CURVE))
}

/// Type 2: a soft wooden body. Runs the dry voice signal through a
/// hand-rolled, heavily-damped 2-pole bandpass (Chamberlin state-variable
/// filter) at a fixed center in the 110-400Hz range, then blends that band
/// back against the dry signal so the struck-wood coloration sits on top of
/// the kick's own low end rather than replacing it. Keeps the same
/// trigger/pitch-envelope/click/pan structure as Sub.
pub(crate) struct WoodKickVoice {
    pub(crate) core: KickVoiceCore,
    pub(crate) body: KickFmBody,
    pub(crate) svf_low: f32,
    pub(crate) svf_band: f32,
    pub(crate) svf_f: f32,
    pub(crate) output_gain: f32,
}

impl WoodKickVoice {
    pub(crate) fn new(c: &KickControls, sample_rate: f32, rng: &mut StdRng) -> Self {
        let filter = KICK_CHARACTER_FILTER_POSITION;
        let center_hz = KICK_WOOD_CENTER_MIN_HZ
            * (KICK_WOOD_CENTER_MAX_HZ / KICK_WOOD_CENTER_MIN_HZ).powf(filter);
        // Chamberlin SVF frequency coefficient; clamped well below the
        // stability limit (2.0) since `center_hz` can reach 400Hz even at low
        // sample rates used in tests.
        let svf_f = (2.0 * (std::f32::consts::PI * center_hz / sample_rate).sin()).clamp(0.0, 1.9);
        Self {
            core: KickVoiceCore::new(
                c,
                sample_rate,
                rng,
                KICK_WOOD_ATTACK_MS,
                KICK_WOOD_CLICK_SCALE,
            ),
            body: KickFmBody::new(
                c,
                sample_rate,
                KICK_WOOD_PITCH_DROP_RATIO,
                KICK_SUB.fm_mod_ratio,
                KICK_SUB.fm_depth,
                FmWave::Sine,
            ),
            svf_low: 0.0,
            svf_band: 0.0,
            svf_f,
            output_gain: kick_wood_output_gain(filter),
        }
    }

    pub(crate) fn next<R: Rng>(&mut self, rng: &mut R) -> (f32, f32) {
        if self.core.is_done() {
            return (0.0, 0.0);
        }

        let body = self.body.next();
        let dry = self.core.shape(body, rng);

        // Chamberlin state-variable filter, bandpass output: two running
        // integrators (`svf_low`, `svf_band`) plus a feedback resonance term
        // gated by `KICK_WOOD_DAMP`.
        let high = dry - self.svf_low - KICK_WOOD_DAMP * self.svf_band;
        self.svf_band += self.svf_f * high;
        self.svf_low += self.svf_f * self.svf_band;
        let s = (self.svf_band * KICK_WOOD_BANDPASS_MIX + dry * (1.0 - KICK_WOOD_BANDPASS_MIX))
            * self.output_gain;

        (s * self.core.pan_gains.0, s * self.core.pan_gains.1)
    }

    pub(crate) fn is_done(&self) -> bool {
        self.core.is_done()
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::*;

    #[test]
    fn swing_delays_the_kicks_odd_subdivision() {
        let telemetry = Arc::new(FluidTelemetry::default());
        let mut kick = KickEngine::new(48_000.0, Arc::clone(&telemetry));
        let controls = KickControls {
            level: 1.0,
            interval_beats: 0.5,
            swing: 1.0,
            ..KickControls::default()
        };

        kick.next(&controls, TimingContext::new(48_000.0, 120.0, 0.0));
        kick.next(&controls, TimingContext::new(48_000.0, 120.0, 0.5));
        assert_eq!(telemetry.kick_pulse.load(Ordering::Relaxed), 1);

        kick.next(&controls, TimingContext::new(48_000.0, 120.0, 0.75));
        assert_eq!(telemetry.kick_pulse.load(Ordering::Relaxed), 2);
    }

    /// Renders one hit of a single kick type and returns its per-sample
    /// stereo magnitude. The RNG is reseeded identically per type so the pan
    /// position and click noise are the same draw for all types, leaving the
    /// voice's own character as the only difference between them.
    fn render_one_hit(voice_type: usize) -> Vec<f32> {
        const SAMPLE_RATE: f32 = 48_000.0;
        let controls = KickControls {
            level: 1.0,
            ..KickControls::default()
        };
        let mut rng = StdRng::seed_from_u64(42);
        let mut voice = KickVoice::new(voice_type, &controls, SAMPLE_RATE, &mut rng);

        let mut rendered = Vec::new();
        while !voice.is_done() && rendered.len() < SAMPLE_RATE as usize {
            let (left, right) = voice.next(&mut rng);
            rendered.push((left * left + right * right).sqrt());
        }
        rendered
    }

    fn render_mono_hit(voice_type: usize) -> Vec<f32> {
        const SAMPLE_RATE: f32 = 48_000.0;
        let controls = KickControls {
            level: 1.0,
            ..KickControls::default()
        };
        let mut rng = StdRng::seed_from_u64(42);
        let mut voice = KickVoice::new(voice_type, &controls, SAMPLE_RATE, &mut rng);
        let mut rendered = Vec::with_capacity(SAMPLE_RATE as usize / 2);
        for _ in 0..SAMPLE_RATE as usize / 2 {
            let (left, right) = voice.next(&mut rng);
            rendered.push((left + right) * 0.5);
        }
        rendered
    }

    fn window_rms(samples: &[f32], start_ms: usize, end_ms: usize) -> f32 {
        crate::synth::fm::rms(&samples[start_ms * 48..end_ms * 48])
    }

    fn band_rms(samples: &[f32], low_hz: f32, high_hz: f32, start_ms: usize, end_ms: usize) -> f32 {
        const SAMPLE_RATE: f32 = 48_000.0;
        let low_coeff = 1.0 - (-std::f32::consts::TAU * low_hz / SAMPLE_RATE).exp();
        let high_coeff = 1.0 - (-std::f32::consts::TAU * high_hz / SAMPLE_RATE).exp();
        let (mut low, mut high, mut energy) = (0.0f32, 0.0f32, 0.0f32);
        let start = start_ms * 48;
        let end = end_ms * 48;
        for (sample_index, &sample) in samples[..end].iter().enumerate() {
            low += low_coeff * (sample - low);
            high += high_coeff * (sample - high);
            if sample_index >= start {
                energy += (high - low).powi(2);
            }
        }
        (energy / (end - start) as f32).sqrt()
    }

    /// The Oramics Detroit TR-909 kick reference has a short audible attack
    /// and a bass ring: its 180-300 ms RMS is about 26% of its 10-40 ms RMS.
    /// The previous FM-mid versions inverted that shape, leaving a pitched
    /// low-mid tone without enough tail. Keep a broad tolerance so this
    /// protects the shape, not the exact recording or its mastering level.
    /// https://oramics.github.io/sampled/DM/TR-909/Detroit/
    #[test]
    fn kick_909_has_a_short_attack_and_audible_bass_tail() {
        let samples = render_mono_hit(4);
        let attack = window_rms(&samples, 10, 40);
        let middle = window_rms(&samples, 40, 100);
        let tail = window_rms(&samples, 180, 300);
        assert!(attack > middle * 1.3, "attack must lead the body");
        assert!(
            (0.18..=0.36).contains(&(tail / attack)),
            "bass tail is {:.2}x the attack, outside the reference shape",
            tail / attack
        );
    }

    #[test]
    fn kick_909_moves_from_low_mids_into_bass_instead_of_holding_a_second_tone() {
        let samples = render_mono_hit(4);
        let early_mid = band_rms(&samples, 160.0, 500.0, 10, 40);
        let late_mid = band_rms(&samples, 160.0, 500.0, 100, 180);
        let tail_bass = band_rms(&samples, 20.0, 90.0, 180, 300);
        let tail_mid = band_rms(&samples, 160.0, 500.0, 180, 300);
        assert!(
            early_mid > late_mid * 4.0,
            "midrange should be an attack: {:.1}x",
            early_mid / late_mid
        );
        assert!(
            tail_bass > tail_mid * 3.0,
            "tail should ring in the bass: {:.1}x",
            tail_bass / tail_mid
        );
    }

    /// Switching `kick.type` is a change of character, not of level: all types
    /// must land at the same rendered loudness for the same `kick.level`, or
    /// the selector doubles as a hidden volume control and every song needs
    /// its Level re-balanced after an audition.
    ///
    /// Matched on RMS rather than peak: peak is set by a single transient
    /// sample and the types deliberately differ in transient hardness,
    /// while RMS is what a listener balances against the rest of the mix.
    ///
    /// This test is what makes the per-type output trims maintainable. They
    /// were previously constants chosen by ear with nothing verifying them,
    /// which is how Wood came to run at more than twice Sub's level without
    /// anyone noticing.
    #[test]
    fn kick_types_render_at_a_matched_level() {
        let reference = crate::synth::fm::rms(&render_one_hit(0));

        for (voice_type, label) in KICK_TYPES.iter().enumerate().skip(1) {
            let level = crate::synth::fm::rms(&render_one_hit(voice_type));
            let ratio = level / reference;
            assert!(
                (ratio - 1.0).abs() <= MATCHED_LEVEL_TOLERANCE,
                "kick type {voice_type} ({label}) renders at {ratio:.2}x Sub; \
                 retune its output trim",
            );
        }
    }

    /// Matching on RMS lets a peakier type sit higher in absolute terms —
    /// Wood especially, since its bandpass concentrates energy into a
    /// narrower band. That is intended, but it must stay bounded: an
    /// unchecked peak eats the headroom the shared Drive and Master bus
    /// expect to have.
    #[test]
    fn no_kick_type_exceeds_the_headroom_budget() {
        for (voice_type, label) in KICK_TYPES.iter().enumerate() {
            let peak = render_one_hit(voice_type)
                .into_iter()
                .fold(0.0f32, f32::max);
            assert!(
                peak <= MAX_KICK_PEAK,
                "kick type {voice_type} ({label}) peaks at {peak:.2}",
            );
        }
    }

    /// Deliberately wider than the ~5% the original four types sit within, so
    /// the test pins the balance without failing on the last digit of a trim.
    /// Felt is the widest at 14% under Sub mid-sweep; its filter response has
    /// a different shape from Sub's and closing that would need a second
    /// empirical curve for a difference at the edge of audibility.
    const MATCHED_LEVEL_TOLERANCE: f32 = 0.15;
    /// Headroom ceiling at `kick.level` 1.0, above the loudest type's
    /// measured peak with room for the trims to move.
    const MAX_KICK_PEAK: f32 = 1.8;
}