feat(nam): bypass model on sample-rate mismatch and surface it in the UI (#244)

Author: OpenSauce

.gitignore

@@ -4,6 +4,16 @@
 
 /claude
 
+# Local working material (not part of the repo)
+/docs
+/dsp_reference
+/.superpowers
+/.claude
+
+# NAM model files are user-provided; only the placeholder is tracked
+/nam/*
+!/nam/.gitkeep
+
 impulse_responses/*
 !/impulse_responses/Misc
 !/impulse_responses/Jesterdyne

rustortion-core/src/amp/stages/nam.rs

@@ -36,6 +36,24 @@ impl NamStage {
             sample_rate_mismatch: false,
         }
     }
+
+    /// Passthrough used when the model's native rate mismatches the engine rate.
+    /// Carries the real native rate so the UI/params can report the bypass reason.
+    const fn bypassed_for_mismatch(
+        input_gain: f32,
+        output_gain: f32,
+        mix: f32,
+        native_sample_rate: f32,
+    ) -> Self {
+        Self {
+            wavenet: None,
+            input_gain,
+            output_gain,
+            mix,
+            native_sample_rate,
+            sample_rate_mismatch: true,
+        }
+    }
 }
 
 impl Stage for NamStage {
@@ -135,11 +153,18 @@ impl NamConfig {
         };
 
         let native_sample_rate = model.sample_rate() as f32;
-        let sample_rate_mismatch = (native_sample_rate - sample_rate).abs() > 1.0;
-        if sample_rate_mismatch {
+        if (native_sample_rate - sample_rate).abs() > 1.0 {
+            // Resampling is intentionally avoided (too expensive on the RT path), so a
+            // rate mismatch bypasses the model entirely: pass the dry signal through.
             warn!(
                 "NAM model '{name}' native rate {native_sample_rate} Hz differs from engine \
-                 rate {sample_rate} Hz; tone may be affected"
+                 rate {sample_rate} Hz; bypassing model (dry passthrough)"
+            );
+            return NamStage::bypassed_for_mismatch(
+                input_gain,
+                output_gain,
+                mix,
+                native_sample_rate,
             );
         }
 
@@ -150,7 +175,8 @@ impl NamConfig {
                 output_gain,
                 mix,
                 native_sample_rate,
-                sample_rate_mismatch,
+                // Rates match (mismatch returned early above).
+                sample_rate_mismatch: false,
             },
             Err(e) => {
                 warn!("Failed to build NAM model '{name}': {e}; using passthrough");
@@ -173,6 +199,25 @@ mod tests {
         }
     }
 
+    #[test]
+    fn mismatch_bypass_is_dry_passthrough() {
+        // A rate-mismatch stage is built without a WaveNet but records the real native
+        // rate and the mismatch flag. We construct it directly here because building a
+        // real `WaveNet` requires loading a `.nam` model into the registry, which unit
+        // tests can't do; this still verifies the RT-path passthrough contract and the
+        // params reported to the UI.
+        let mut stage =
+            NamStage::bypassed_for_mismatch(db_to_lin(6.0), db_to_lin(-3.0), 0.5, 44_100.0);
+
+        // No model runs: output is the dry input, with no gain or mix applied.
+        for x in [-1.0, 0.0, 0.25, 0.9] {
+            assert_eq!(stage.process(x), x);
+        }
+
+        assert!((stage.get_parameter("native_sample_rate").unwrap() - 44_100.0).abs() < 1e-3);
+        assert!((stage.get_parameter("sample_rate_mismatch").unwrap() - 1.0).abs() < 1e-6);
+    }
+
     #[test]
     fn gain_and_mix_round_trip() {
         let mut stage = NamConfig::default().to_stage(48_000.0);

rustortion-ui/src/app.rs

@@ -433,6 +433,10 @@ impl<B: ParamBackend> SharedApp<B> {
                     can_move_up,
                     can_move_down,
                     bypassed,
+                    // Effective rate (device × oversampling) — the rate stages are
+                    // built at, so NAM's mismatch check compares against the right value.
+                    engine_sample_rate: self.backend.sample_rate()
+                        * self.backend.oversampling_factor(),
                 },
             ));
         }

rustortion-ui/src/components/widgets/common.rs

@@ -104,6 +104,10 @@ pub struct StageViewState {
     pub can_move_up: bool,
     pub can_move_down: bool,
     pub bypassed: bool,
+    /// Effective engine sample rate in Hz — the device rate times the oversampling
+    /// factor, i.e. the rate stages are actually built and run at. Used by stages
+    /// (e.g. NAM) to detect rate mismatches, so it must match what `to_stage` sees.
+    pub engine_sample_rate: u32,
 }
 
 fn stage_header(stage_name: &str, idx: usize, state: StageViewState) -> Element<'_, Message> {

rustortion-ui/src/i18n/mod.rs

@@ -167,6 +167,7 @@ pub struct Translations {
     pub nam_model: &'static str,
     pub nam_no_model: &'static str,
     pub nam_native_rate: &'static str,
+    pub nam_rate_mismatch_bypassed: &'static str,
     pub nam_model_not_found: &'static str,
     pub nam_input_gain: &'static str,
     pub nam_output_gain: &'static str,
@@ -369,6 +370,7 @@ pub static EN: Translations = Translations {
     nam_model: "Model",
     nam_no_model: "Select a model…",
     nam_native_rate: "Native rate",
+    nam_rate_mismatch_bypassed: "Bypassed — model rate vs engine rate",
     nam_model_not_found: "Model not found",
     nam_input_gain: "Input",
     nam_output_gain: "Output",
@@ -562,6 +564,7 @@ pub static ZH_CN: Translations = Translations {
     nam_model: "模型",
     nam_no_model: "选择模型…",
     nam_native_rate: "原始采样率",
+    nam_rate_mismatch_bypassed: "已旁通 — 模型采样率 vs 引擎采样率",
     nam_model_not_found: "未找到模型",
     nam_input_gain: "输入",
     nam_output_gain: "输出",

rustortion-ui/src/stages/nam.rs

@@ -103,13 +103,21 @@ pub fn view(idx: usize, cfg: &NamConfig, state: StageViewState) -> Element<'_, M
         .align_y(Alignment::Center);
 
         // Read-only info: the selected model's native sample rate (or "not found").
-        // A mismatch against the engine rate is logged at build time; the engine rate
-        // isn't available in this view, so it isn't shown here.
+        // When the native rate mismatches the engine rate the model is bypassed (dry
+        // passthrough, no resampling) — surface that here using both rates.
+        let engine_rate = state.engine_sample_rate;
         let info_line: Element<'_, Message> = match model_name.as_deref() {
             Some(name) => match registry::get(name) {
                 Some(model) => {
-                    let rate = model.sample_rate() as u32;
-                    text(format!("{}: {rate} Hz", tr!(nam_native_rate)))
+                    let native_rate = model.sample_rate() as u32;
+                    if native_rate.abs_diff(engine_rate) > 1 {
+                        text(format!(
+                            "{}: {native_rate} Hz · {engine_rate} Hz",
+                            tr!(nam_rate_mismatch_bypassed)
+                        ))
+                    } else {
+                        text(format!("{}: {native_rate} Hz", tr!(nam_native_rate)))
+                    }
                 }
                 None => text(tr!(nam_model_not_found)),
             }