feat(patina): per-band compressor gain stage with Threshold, Ratio and Knee

Tester feedback asked for a threshold and a ratio. Each band now cuts like a
small compressor: Threshold (dB above the local floor) replaces Selectivity,
Ratio scales the cut per dB above it (inf:1 is the old behaviour), and a
Soft/Hard knee switch sets the curve. A small graph shows bump height in, cut
out. Mix and Output move to the slider panel so the detection panel fits.
common-ui gains rotary_text for knobs with custom value text.

plugins/patina/core/src/lib.rs

@@ -3,14 +3,10 @@ mod pitch;
 mod settings;
 use pitch::PitchProbe;
 use rustfft::{num_complex::Complex32, Fft, FftPlanner};
-pub use settings::{focus_offset, knee, Focus, Settings};
+pub use settings::{focus_offset, knee, Focus, Knee, Settings, RATIO_INFINITE};
 use std::{f32::consts::PI, sync::Arc};
 
 pub const GRID: usize = 512;
-/// dB of cut per dB of prominence above the threshold.
-const SLOPE: f32 = 1.5;
-/// Fixed soft-knee width, in dB of prominence.
-const KNEE: f32 = 3.;
 /// Neighboring peaks closer than this (Hz, or one octave) are joined by a
 /// straight line in dB, so harmonic gaps do not count as expected level.
 const JOIN_HZ: f32 = 800.;
@@ -463,7 +459,9 @@ impl Engine {
         let fall = 1. - (-frame_time / 0.04).exp();
         let awake = self.sample_power / self.hop as f32 > 1e-9;
         self.sample_power = 0.;
-        let threshold = self.settings.threshold();
+        let threshold = self.settings.threshold;
+        let slope = self.settings.slope();
+        let knee_width = self.settings.knee_width();
         self.target.fill(0.);
         self.frame.input.fill(-200.);
         self.frame.envelope.fill(-200.);
@@ -588,7 +586,8 @@ impl Engine {
                 // material is never cut.
                 let live = awake && content[i] && level > -130.;
                 let target = if live {
-                    (knee(excess, KNEE) * SLOPE).min(self.settings.depth) * (1. - self.tone[i])
+                    (knee(excess, knee_width) * slope).min(self.settings.depth)
+                        * (1. - self.tone[i])
                 } else {
                     0.
                 };
@@ -609,7 +608,7 @@ impl Engine {
         }
         let cut = self.target;
         smooth(&cut, &mut self.target, (self.envelope_radius / 2).max(1), 1);
-        let attack = (-(self.hop as f32) / (self.rate * self.settings.attack * 0.001)).exp();
+        let attack = (-(self.hop as f32) / (self.rate * self.settings.attack_time() * 0.001)).exp();
         let release = (-(self.hop as f32) / (self.rate * self.settings.release * 0.001)).exp();
         for i in 0..GRID {
             let target = self.target[i];

plugins/patina/core/src/settings.rs

@@ -19,15 +19,34 @@ impl Default for Focus {
         }
     }
 }
+/// Shape of each band's gain curve around the threshold.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum Knee {
+    /// Wide knee: cuts fade in gradually around the threshold.
+    #[default]
+    Soft,
+    /// Narrow knee and a faster attack: cuts start right at the threshold.
+    Hard,
+}
+/// Ratio at or above this value is treated as ∞:1.
+pub const RATIO_INFINITE: f32 = 20.;
+/// dB of cut per dB of detected prominence at ∞:1. The detector smooths a bump across
+/// frequency and reads it lower than it is; this restores the true height.
+const CALIBRATION: f32 = 1.5;
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
-#[serde(deny_unknown_fields)]
+#[serde(from = "Stored")]
 pub struct Settings {
-    /// Largest cut in dB. Prominent bumps are flattened toward the threshold, never deeper.
+    /// Largest cut in dB per band.
     pub depth: f32,
     /// 0 % follows broad tonal bumps, 100 % targets narrow rings.
     pub sharpness: f32,
-    /// 0 % treats any bump; 100 % treats only the most prominent bumps.
-    pub selectivity: f32,
+    /// How far (dB) a band must rise above its local floor before it is cut.
+    pub threshold: f32,
+    /// Cut per dB above the threshold: at n:1 a bump ends 1/n as far above the threshold.
+    /// `RATIO_INFINITE` and above flatten bumps to the threshold.
+    pub ratio: f32,
+    pub knee: Knee,
     pub attack: f32,
     pub release: f32,
     pub transient_guard: f32,
@@ -39,15 +58,68 @@ pub struct Settings {
     pub focus: [Focus; 4],
     /// 0 % cuts every bump. Higher values hold back cuts on bumps that follow the played note
     /// (a harmonic the sound is built on) while bumps fixed in Hz are still cut.
-    #[serde(default)]
     pub tone_guard: f32,
 }
+/// Stored form. Settings saved before 0.5 have Selectivity (%) instead of Threshold, and no
+/// Ratio, Knee or Tone guard.
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Stored {
+    depth: f32,
+    sharpness: f32,
+    #[serde(default)]
+    threshold: Option<f32>,
+    #[serde(default)]
+    selectivity: Option<f32>,
+    #[serde(default)]
+    ratio: Option<f32>,
+    #[serde(default)]
+    knee: Knee,
+    attack: f32,
+    release: f32,
+    transient_guard: f32,
+    low: f32,
+    high: f32,
+    mix: f32,
+    output: f32,
+    bypass: bool,
+    focus: [Focus; 4],
+    #[serde(default)]
+    tone_guard: f32,
+}
+impl From<Stored> for Settings {
+    fn from(s: Stored) -> Self {
+        let d = Settings::default();
+        Self {
+            depth: s.depth,
+            sharpness: s.sharpness,
+            threshold: s
+                .threshold
+                .or(s.selectivity.map(|v| 0.5 + v * 0.05))
+                .unwrap_or(d.threshold),
+            ratio: s.ratio.unwrap_or(d.ratio),
+            knee: s.knee,
+            attack: s.attack,
+            release: s.release,
+            transient_guard: s.transient_guard,
+            low: s.low,
+            high: s.high,
+            mix: s.mix,
+            output: s.output,
+            bypass: s.bypass,
+            focus: s.focus,
+            tone_guard: s.tone_guard,
+        }
+    }
+}
 impl Default for Settings {
     fn default() -> Self {
         Self {
             depth: 6.,
             sharpness: 40.,
-            selectivity: 50.,
+            threshold: 3.,
+            ratio: RATIO_INFINITE,
+            knee: Knee::Soft,
             attack: 5.,
             release: 80.,
             transient_guard: 30.,
@@ -66,7 +138,8 @@ impl Settings {
         for (v, low, high) in [
             (self.depth, 0., 20.),
             (self.sharpness, 0., 100.),
-            (self.selectivity, 0., 100.),
+            (self.threshold, 0., 18.),
+            (self.ratio, 1., RATIO_INFINITE),
             (self.attack, 1., 200.),
             (self.release, 10., 1000.),
             (self.transient_guard, 0., 100.),
@@ -104,9 +177,27 @@ impl Settings {
     pub fn reference_width(&self) -> f32 {
         (self.envelope_width() * 16.).clamp(2., 3.)
     }
-    /// Prominence threshold in dB above the local reference, from Selectivity.
-    pub fn threshold(&self) -> f32 {
-        0.5 + self.selectivity * 0.05
+    /// dB of cut per dB of detected prominence above the threshold.
+    pub fn slope(&self) -> f32 {
+        if self.ratio >= RATIO_INFINITE {
+            CALIBRATION
+        } else {
+            CALIBRATION * (1. - 1. / self.ratio)
+        }
+    }
+    /// Soft-knee width in dB of prominence.
+    pub fn knee_width(&self) -> f32 {
+        match self.knee {
+            Knee::Soft => 6.,
+            Knee::Hard => 1.,
+        }
+    }
+    /// Attack time actually used: the hard knee grips twice as fast.
+    pub fn attack_time(&self) -> f32 {
+        match self.knee {
+            Knee::Soft => self.attack,
+            Knee::Hard => (self.attack * 0.5).max(0.5),
+        }
     }
     pub const PRESETS: [&'static str; 5] = [
         "Gentle cleanup",
@@ -121,18 +212,21 @@ impl Settings {
             1 => {
                 s.low = 1500.;
                 s.high = 12000.;
-                s.depth = 8.;
+                s.depth = 10.;
                 s.sharpness = 55.;
-                s.selectivity = 40.;
+                s.threshold = 2.5;
+                s.ratio = 3.;
                 s.attack = 3.;
                 s.release = 60.;
             }
             2 => {
                 s.low = 250.;
                 s.high = 6000.;
-                s.depth = 8.;
+                s.depth = 12.;
                 s.sharpness = 75.;
-                s.selectivity = 35.;
+                s.threshold = 2.5;
+                s.ratio = 6.;
+                s.knee = Knee::Hard;
                 s.attack = 10.;
                 s.release = 150.;
                 s.transient_guard = 80.;
@@ -140,14 +234,18 @@ impl Settings {
             3 => {
                 s.low = 2000.;
                 s.high = 16000.;
+                s.depth = 9.;
                 s.sharpness = 25.;
-                s.selectivity = 45.;
+                s.threshold = 2.5;
+                s.ratio = 2.5;
             }
             4 => {
                 s.low = 150.;
                 s.high = 12000.;
+                s.depth = 8.;
                 s.sharpness = 50.;
-                s.selectivity = 45.;
+                s.threshold = 2.5;
+                s.ratio = 3.;
                 s.tone_guard = 80.;
             }
             _ => {}

plugins/patina/core/tests/dsp.rs

@@ -148,7 +148,7 @@ fn resonant_bump_is_cut_where_it_is_and_nowhere_else() {
     }
 }
 #[test]
-fn depth_selectivity_and_focus_each_do_one_thing() {
+fn depth_threshold_and_focus_each_do_one_thing() {
     let run = |s: Settings| {
         let mut bump = Peak::new(3000., 4., 12., 48000.);
         let frame = settle(s, |i| bump.tick(saw(220., i, 48000.)));
@@ -160,7 +160,7 @@ fn depth_selectivity_and_focus_each_do_one_thing() {
         ..Default::default()
     });
     let picky = run(Settings {
-        selectivity: 100.,
+        threshold: 5.5,
         ..Default::default()
     });
     let mut protect = Settings::default();
@@ -279,7 +279,7 @@ fn invalid_settings_do_not_mutate_and_numerical_inputs_stay_finite() {
 }
 #[test]
 fn soft_knee_and_presets_are_valid() {
-    for i in 0..4 {
+    for i in 0..Settings::PRESETS.len() {
         Settings::preset(i).validate().unwrap();
     }
     assert_eq!(knee(-2., 3.), 0.);
@@ -469,3 +469,103 @@ fn old_settings_without_tone_guard_still_load() {
     let s: Settings = serde_json::from_value(json).unwrap();
     assert_eq!(s.tone_guard, 0.);
 }
+
+/// Cut at the bump for a resonance of `gain` dB (Q 4 at 3 kHz) on a 220 Hz saw.
+fn bump_cut(s: Settings, gain: f32) -> f32 {
+    let mut bump = Peak::new(3000., 4., gain, 48000.);
+    let frame = settle(
+        Settings {
+            transient_guard: 0.,
+            ..s
+        },
+        |i| bump.tick(saw(220., i, 48000.)),
+    );
+    peak_reduction(&frame, 3000. / 1.26, 3000. * 1.26)
+}
+#[test]
+fn ratio_spares_small_peaks_and_still_cuts_big_ones() {
+    let at = |ratio: f32, gain: f32| {
+        bump_cut(
+            Settings {
+                depth: 20.,
+                ratio,
+                ..Default::default()
+            },
+            gain,
+        )
+    };
+    let (small_hard, big_hard) = (at(RATIO_INFINITE, 6.), at(RATIO_INFINITE, 18.));
+    let (small, big) = (at(2., 6.), at(2., 18.));
+    // At 2:1 each cut is about half the ∞:1 cut.
+    for (half, full) in [(small, small_hard), (big, big_hard)] {
+        assert!((half / full - 0.5).abs() < 0.15, "{half} vs {full}");
+    }
+    assert!(small < 1., "small bump cut by {small} dB at 2:1");
+    assert!(big > 4., "big bump cut only {big} dB at 2:1");
+    // Ratio between the two ends gives a cut between them.
+    let mid = at(4., 18.);
+    assert!(big < mid && mid < big_hard, "{big} < {mid} < {big_hard}");
+}
+#[test]
+fn cut_grows_with_the_bump_until_depth() {
+    let s = Settings {
+        depth: 20.,
+        ratio: 3.,
+        ..Default::default()
+    };
+    let cuts: Vec<f32> = [4., 8., 12., 18., 24.]
+        .iter()
+        .map(|g| bump_cut(s, *g))
+        .collect();
+    for w in cuts.windows(2) {
+        assert!(w[1] > w[0] + 0.5, "{cuts:?}");
+    }
+    let capped = bump_cut(Settings { depth: 4., ..s }, 24.);
+    assert!(capped <= 4.001 && capped > 3., "{capped}");
+}
+#[test]
+fn threshold_moves_where_cuts_start() {
+    let low = bump_cut(Settings::default(), 9.);
+    let high = bump_cut(
+        Settings {
+            threshold: 9.,
+            ..Default::default()
+        },
+        9.,
+    );
+    assert!(low > 2. && high < 0.5, "{low} / {high}");
+}
+#[test]
+fn hard_knee_starts_cutting_closer_to_the_threshold() {
+    // A bump just under the threshold: the soft knee already cuts a little, the hard knee not.
+    let s = Settings {
+        threshold: 4.,
+        ..Default::default()
+    };
+    let soft = bump_cut(s, 6.);
+    let hard = bump_cut(
+        Settings {
+            knee: Knee::Hard,
+            ..s
+        },
+        6.,
+    );
+    assert!(soft > hard + 0.2, "soft {soft} vs hard {hard}");
+    assert_eq!(knee(0.25, 1.), 0.28125);
+}
+#[test]
+fn settings_from_before_threshold_still_load() {
+    let mut json = serde_json::to_value(Settings::default()).unwrap();
+    let map = json.as_object_mut().unwrap();
+    for key in ["threshold", "ratio", "knee", "tone_guard"] {
+        map.remove(key);
+    }
+    map.insert("selectivity".into(), 100.into());
+    let s: Settings = serde_json::from_value(json).unwrap();
+    assert_eq!(s.threshold, 5.5);
+    assert_eq!(s.ratio, RATIO_INFINITE);
+    assert_eq!(s.knee, Knee::Soft);
+    assert!(serde_json::from_str::<Settings>(r#"{"oops":1}"#).is_err());
+    let back: Settings = serde_json::from_str(&serde_json::to_string(&s).unwrap()).unwrap();
+    assert_eq!(back, s);
+}