nooise 1.9.2

//! The Kick voice: a pitch-glide FM body shared by all four kick
//! characters, plus their click, drive, and amp envelope.

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(
                kick_type_index(c.voice_type),
                c,
                self.sample_rate,
                &mut self.rng,
            ));
            self.telemetry.kick_pulse.fetch_add(1, Ordering::Relaxed);
        }

        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 every `kick.type` voice: 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 four 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 are all authored soft and textural for
/// ambient use: each takes a short onset fade-in and a scaled-down click via
/// `KickVoiceCore` so none of them reads as a drum-machine transient.
pub(crate) enum KickVoice {
    A(SubKickVoice),
    B(WarmKickVoice),
    C(WoodKickVoice),
    D(FeltKickVoice),
}

impl KickVoice {
    pub(crate) fn new(
        voice_type: usize,
        c: &KickControls,
        sample_rate: f32,
        rng: &mut StdRng,
    ) -> Self {
        match voice_type {
            0 => Self::A(SubKickVoice::new(c, sample_rate, rng)),
            1 => Self::B(WarmKickVoice::new(c, sample_rate, rng)),
            2 => Self::C(WoodKickVoice::new(c, sample_rate, rng)),
            _ => Self::D(FeltKickVoice::new(c, sample_rate, rng)),
        }
    }

    pub(crate) fn next<R: Rng>(&mut self, rng: &mut R) -> (f32, f32) {
        match self {
            Self::A(voice) => voice.next(rng),
            Self::B(voice) => voice.next(rng),
            Self::C(voice) => voice.next(rng),
            Self::D(voice) => voice.next(rng),
        }
    }

    pub(crate) fn is_done(&self) -> bool {
        match self {
            Self::A(voice) => voice.is_done(),
            Self::B(voice) => voice.is_done(),
            Self::C(voice) => voice.is_done(),
            Self::D(voice) => voice.is_done(),
        }
    }
}

/// Shared FM body behind every `kick.type` voice: 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;

/// One-pole lowpass mapped exponentially from `kick.filter`, shared by every
/// type that ends in a lowpass (Sub, Warm, Felt). `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
    }
}

/// Pitch drop: the body settles at 0.28x its starting frequency.
const KICK_SUB_PITCH_DROP_RATIO: f32 = 0.28;
/// Modulator-to-carrier ratio: 2x puts sidebands on the harmonic series, which
/// is what keeps this voice reading as one fused low body.
const KICK_SUB_FM_MOD_RATIO: f32 = 2.0;
/// FM depth, the deepest of the four types: this is the hard transient edge the
/// three ambient types deliberately back away from.
const KICK_SUB_FM_DEPTH: f32 = 3.5;
/// Lowpass mapping bias; the reference every other type's bias is stated
/// relative to.
const KICK_SUB_FILTER_BIAS: f32 = -2.5;

/// 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 one-pole lowpass mapped
/// from `kick.filter`. Drive runs later in the shared layer module chain.
pub(crate) struct SubKickVoice {
    pub(crate) core: KickVoiceCore,
    pub(crate) body: KickFmBody,
    pub(crate) lowpass: KickLowPass,
}

impl SubKickVoice {
    pub(crate) fn new(c: &KickControls, sample_rate: f32, rng: &mut StdRng) -> Self {
        Self {
            core: KickVoiceCore::new(c, sample_rate, rng, 0.0, 1.0),
            body: KickFmBody::new(
                c,
                sample_rate,
                KICK_SUB_PITCH_DROP_RATIO,
                KICK_SUB_FM_MOD_RATIO,
                KICK_SUB_FM_DEPTH,
                FmWave::Sine,
            ),
            lowpass: KickLowPass::new(c.filter, KICK_SUB_FILTER_BIAS),
        }
    }

    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));

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

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

/// Shallower pitch-drop ratio than Sub's fixed 0.28x, so the Warm voice's
/// body settles a little above Sub without reading as a second sub layer.
const KICK_WARM_PITCH_DROP_RATIO: f32 = 0.42;
/// Modulator-to-carrier ratio. Below Sub's fixed 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.
const KICK_WARM_FM_MOD_RATIO: f32 = 1.5;
/// FM depth, well below Sub's fixed 3.5, so the modulator rounds the body out
/// instead of adding a hard transient edge.
const KICK_WARM_FM_DEPTH: f32 = 1.2;
/// Lowpass mapping bias: 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 toward
/// Sub's so it stays dark rather than bright.
const KICK_WARM_FILTER_BIAS: f32 = -2.35;
/// Linear onset fade-in. Rounds off the transient snap so the hit reads as a
/// swell into a body rather than a drum-machine attack.
const KICK_WARM_ATTACK_MS: f32 = 6.0;
/// The broadband onset noise burst is the single most aggressive-sounding
/// element of a kick; scaled well down from the user's `kick.click`.
const KICK_WARM_CLICK_SCALE: f32 = 0.45;
/// Output trim: brings this 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.
const KICK_WARM_OUTPUT_GAIN: f32 = 1.11;

/// 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. Shares
/// Sub's click/one-pole-lowpass/pan machinery via `KickVoiceCore`.
pub(crate) struct WarmKickVoice {
    pub(crate) core: KickVoiceCore,
    pub(crate) body: KickFmBody,
    pub(crate) lowpass: KickLowPass,
}

impl WarmKickVoice {
    pub(crate) fn new(c: &KickControls, sample_rate: f32, rng: &mut StdRng) -> Self {
        Self {
            core: KickVoiceCore::new(
                c,
                sample_rate,
                rng,
                KICK_WARM_ATTACK_MS,
                KICK_WARM_CLICK_SCALE,
            ),
            body: KickFmBody::new(
                c,
                sample_rate,
                KICK_WARM_PITCH_DROP_RATIO,
                KICK_WARM_FM_MOD_RATIO,
                KICK_WARM_FM_DEPTH,
                FmWave::Sine,
            ),
            lowpass: KickLowPass::new(c.filter, KICK_WARM_FILTER_BIAS),
        }
    }

    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) * KICK_WARM_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()
    }
}

/// `kick.filter` maps to the Wood bandpass's center frequency across this
/// range instead of a lowpass cutoff — an exponential (perceptually even)
/// sweep across the low-mid range where a struck wooden body resonates.
/// Deliberately narrow and low: 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, and the only one of the four that cannot be a constant.
///
/// 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 therefore
/// sits right on the fundamental and passes nearly all of it, while a high
/// center passes a fraction — so Wood ran more than twice as loud dark as it
/// did bright, and *inverted* against the other three types, which all get
/// louder as `kick.filter` opens up. Sweeping the control changed the balance
/// of the mix rather than only its color.
///
/// The curve below is an empirical fit against measured output at four
/// filter positions, 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 at each of those positions,
/// 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) centered in the 110-400Hz range via `kick.filter`, 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 = c.filter.clamp(0.0, 1.0);
        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()
    }
}

/// Pitch-drop ratio, matching Sub's default so only the carrier waveform and
/// filter darkness change for this type.
const KICK_FELT_PITCH_DROP_RATIO: f32 = 0.28;
/// FM depth, well below Sub's fixed 3.5: the triangle carrier already brings
/// its own odd harmonics, so Sub's depth would push this into buzz.
const KICK_FELT_FM_DEPTH: f32 = 1.8;
/// Lowpass mapping bias: below Sub's `-2.5`, so the same `kick.filter` range
/// lands darker and duller — the felt-beater muffling.
const KICK_FELT_FILTER_BIAS: f32 = -2.9;
/// Linear onset fade-in, the longest of the three soft types: a felt mallet
/// compresses on contact rather than striking instantly.
const KICK_FELT_ATTACK_MS: f32 = 8.0;
/// Scales the user's `kick.click` furthest down; a felt beater has almost no
/// broadband contact noise.
const KICK_FELT_CLICK_SCALE: f32 = 0.25;
/// Output trim: brings this 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.
const KICK_FELT_OUTPUT_GAIN: f32 = 1.36;

/// 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.
/// Uses a darker lowpass mapping than Sub and keeps the same
/// pitch-envelope/click/pan structure. Optional Drive follows all kick types
/// through the shared layer chain.
pub(crate) struct FeltKickVoice {
    pub(crate) core: KickVoiceCore,
    pub(crate) body: KickFmBody,
    pub(crate) lowpass: KickLowPass,
}

impl FeltKickVoice {
    pub(crate) fn new(c: &KickControls, sample_rate: f32, rng: &mut StdRng) -> Self {
        Self {
            core: KickVoiceCore::new(
                c,
                sample_rate,
                rng,
                KICK_FELT_ATTACK_MS,
                KICK_FELT_CLICK_SCALE,
            ),
            body: KickFmBody::new(
                c,
                sample_rate,
                KICK_FELT_PITCH_DROP_RATIO,
                KICK_SUB_FM_MOD_RATIO,
                KICK_FELT_FM_DEPTH,
                FmWave::Triangle,
            ),
            lowpass: KickLowPass::new(c.filter, KICK_FELT_FILTER_BIAS),
        }
    }

    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) * KICK_FELT_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 four, leaving the
    /// voice's own character as the only difference between them.
    fn render_one_hit(voice_type: usize, filter: f32) -> Vec<f32> {
        const SAMPLE_RATE: f32 = 48_000.0;
        let controls = KickControls {
            level: 1.0,
            filter,
            ..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
    }

    /// Switching `kick.type` is a change of character, not of level: all four
    /// 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 these four 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 at a dark
    /// `kick.filter` without anyone noticing.
    #[test]
    fn kick_types_render_at_a_matched_level() {
        // Loudness is checked across the filter sweep, not just at the
        // default: Wood's bandpass center moves with `kick.filter`, so a
        // single-position check would pass while the sweep stayed unbalanced.
        for filter in [0.0, 0.35, 0.7, 1.0] {
            let reference = crate::synth::fm::rms(&render_one_hit(0, filter));

            for (voice_type, label) in KICK_TYPES.iter().enumerate().skip(1) {
                let level = crate::synth::fm::rms(&render_one_hit(voice_type, filter));
                let ratio = level / reference;
                assert!(
                    (ratio - 1.0).abs() <= MATCHED_LEVEL_TOLERANCE,
                    "kick type {voice_type} ({label}) renders at {ratio:.2}x Sub at \
                     filter {filter}; 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 filter in [0.0, 0.35, 0.7, 1.0] {
            for (voice_type, label) in KICK_TYPES.iter().enumerate() {
                let peak = render_one_hit(voice_type, filter)
                    .into_iter()
                    .fold(0.0f32, f32::max);
                assert!(
                    peak <= MAX_KICK_PEAK,
                    "kick type {voice_type} ({label}) peaks at {peak:.2} at filter {filter}",
                );
            }
        }
    }

    /// Deliberately wider than the ~5% the four types actually 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;
}