feat(nam): folder management — editable dir, rescan, models-folder on stage card (#245)

Author: OpenSauce

CLAUDE.md

@@ -0,0 +1,133 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Rustortion is a real-time guitar/bass amp simulator built in Rust. It runs as a standalone JACK app and as a VST3/CLAP plugin. The GUI is shared between both targets via the `rustortion-ui` crate.
+
+## Workspace Crates
+
+- **`rustortion-core`** — DSP engine, amp stages, IR cabinet, preset management. No GUI dependencies.
+- **`rustortion-ui`** — Shared GUI: stages, components, messages, handlers, i18n, `SharedApp<ParamBackend>`. Uses `iced = "0.14"`.
+- **`rustortion-standalone`** — Standalone JACK app. Thin shell wrapping `SharedApp<StandaloneBackend>` with MIDI, tuner, settings, recording.
+- **`rustortion-plugin`** — VST3/CLAP plugin via nih-plug. Editor uses `iced_baseview` + `SharedApp<PluginBackend>`.
+- **`xtask`** — Build automation.
+
+## Build & Development Commands
+
+```bash
+# Build and run standalone (requires JACK/PipeWire)
+cargo run --release
+
+# Build plugin
+cargo build -p rustortion-plugin --release
+
+# Lint (formatting + clippy) — this is what CI runs
+make lint
+
+# Run tests
+make test                    # all tests
+cargo test test_name         # single test
+
+# Benchmarks
+make bench
+
+# Coverage (requires cargo-tarpaulin)
+make cover
+```
+
+**System dependencies** (must be installed before building):
+```bash
+sudo apt-get install libjack-jackd2-dev libasound2-dev pkg-config
+```
+
+**Clippy flags** used in CI: `-D warnings -D clippy::all -D clippy::pedantic -D clippy::nursery`
+(`lib.rs` has `#![allow(...)]` overrides for specific pedantic/nursery lints)
+
+**Dev profile** uses `opt-level = 1` because IR cabinet processing is too slow in pure debug mode.
+
+## Architecture
+
+### Shared GUI Pattern
+
+Both standalone and plugin use `SharedApp<B: ParamBackend>` from `rustortion-ui`:
+
+```
+rustortion-standalone                    rustortion-plugin
+  AmplifierApp                             PluginApp (iced_baseview::Application)
+    └─ SharedApp<StandaloneBackend>          └─ SharedApp<PluginBackend>
+         └─ StandaloneBackend                     └─ PluginBackend
+              └─ Manager/Engine (JACK)                  └─ EngineHandle + GuiContext
+```
+
+`ParamBackend` trait (`rustortion-ui/src/backend.rs`) abstracts engine communication. `Capabilities` struct controls which UI sections render (e.g. plugin hides tuner, MIDI config, recording, settings).
+
+### Audio Signal Flow
+
+```
+Input → [Tuner bypass] → Input Filters (HP/LP) → [Upsample] → Amp Chain (stages) → [Downsample] → Pitch Shifter → IR Cabinet → Peak Meter → Recorder → Output
+```
+
+### Key Modules
+
+#### rustortion-core
+- **`src/amp/chain.rs`** — Ordered list of processing stages.
+- **`src/amp/stages/`** — 10 registered DSP stages: preamp, compressor, noise_gate, tonestack, poweramp, multiband_saturator, level, delay, reverb, eq. Plus utilities: `clipper`, `filter`, `common`.
+- **`src/audio/engine.rs`** — Core audio processing loop. Controlled via crossbeam channels.
+- **`src/ir/`** — IR cabinet, convolver (FIR/FFT), loader.
+- **`src/preset/`** — Preset save/load/delete, `StageConfig` enum, `InputFilterConfig`.
+
+#### rustortion-ui
+- **`src/app.rs`** — `SharedApp<B>` — shared state, update(), view(), subscription().
+- **`src/backend.rs`** — `ParamBackend` trait, `Capabilities`, `ExternalEvent`.
+- **`src/stages/mod.rs`** — `gui_stage_registry!` macro, `ParamUpdate`, all 10 stage view modules.
+- **`src/components/`** — Reusable UI components: widgets, dialogs, preset_bar, peak_meter, ir_cabinet_control, minimap, etc.
+- **`src/handlers/`** — Portable handlers: preset, hotkey.
+- **`src/messages/`** — Message enums for Iced event-driven updates.
+- **`src/i18n/`** — `tr!()` macro, EN + ZH_CN locales.
+- **`src/tabs.rs`** — Tab navigation: Amp, Effects, Cabinet, IO.
+
+#### rustortion-standalone
+- **`src/gui/app.rs`** — `AmplifierApp` wrapping `SharedApp<StandaloneBackend>` + standalone handlers (MIDI, tuner, settings, recording).
+- **`src/backend.rs`** — `StandaloneBackend` implementing `ParamBackend` via `Manager`/`Engine`.
+- **`src/audio/`** — JACK client, Manager, ports.
+- **`src/gui/handlers/`** — Standalone-only: midi, tuner, settings.
+- **`src/gui/components/dialogs/`** — Standalone-only dialogs: midi, settings, tuner.
+
+#### rustortion-plugin
+- **`src/lib.rs`** — nih-plug `Plugin` impl, audio processing, initialization.
+- **`src/editor.rs`** — `PluginEditor` (nih-plug `Editor` trait) + `PluginApp` (iced_baseview `Application`).
+- **`src/backend.rs`** — `PluginBackend` implementing `ParamBackend` via `EngineHandle` + `GuiContext`.
+- **`src/params.rs`** — Full nih-plug parameter set: global params + 8 slots × 10 stage types.
+
+### Stage Registration (`rustortion-ui/src/stages/mod.rs`)
+
+The `gui_stage_registry!` macro generates `StageType`, `StageConfig`, and `StageMessage` enums plus all boilerplate. Adding a new stage requires:
+1. Add one line to the macro invocation
+2. Create `rustortion-ui/src/stages/new_stage.rs` with config, message, and view implementations
+3. Create `rustortion-core/src/amp/stages/new_stage.rs` implementing the `Stage` trait
+4. Add i18n keys to EN and ZH_CN in `rustortion-ui/src/i18n/mod.rs`
+5. Add slot params to `rustortion-plugin/src/params.rs`
+
+### Thread Model
+
+The JACK process callback (standalone) or nih-plug `process()` (plugin) runs on a real-time thread. The GUI communicates with the engine via crossbeam channels. Shared state (tuner data, peak meter) uses `ArcSwap` for lock-free reads.
+
+## Common Pitfalls
+
+- **JACK/PipeWire must be running** before `cargo run --release`. If JACK is not available the app will panic on startup.
+- **Dev profile uses `opt-level = 1`** — benchmarks and performance comparisons must use `--release`.
+- **The `gui_stage_registry!` macro** in `rustortion-ui/src/stages/mod.rs` generates boilerplate. Do not hand-write — add one line to the macro invocation instead.
+- **Preset JSON format** — each preset is a JSON file in `~/.config/rustortion/presets/`. Structure: `{ "name": "...", "stages": [...], "ir_name": "...", "ir_gain": N, "pitch_shift_semitones": N, "input_filters": {...} }`.
+- **IR files** are in `impulse_responses/` and `~/.config/rustortion/impulse_responses/`. Loading is async (off RT thread).
+- **Clippy is strict** — CI runs `-D warnings -D clippy::all -D clippy::pedantic -D clippy::nursery`.
+- **iced_baseview** is a fork at `github.com/OpenSauce/iced_baseview`, upgraded to iced 0.14 crates.io.
+
+## Conventions
+
+- Rust edition 2024
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `chore:`, etc.
+- Changelog generated via `git-cliff`
+- Standalone entry point: `rustortion-standalone/src/bin/gui.rs`
+- Releases via `cargo-dist` (`.github/workflows/release.yml`, `dist-workspace.toml`)

presets/Clean_Eb.json

@@ -0,0 +1,94 @@
+{
+  "name": "Clean Eb",
+  "description": null,
+  "author": null,
+  "stages": [
+    {
+      "Compressor": {
+        "attack_ms": 1.0,
+        "release_ms": 100.0,
+        "threshold_db": -20.0,
+        "ratio": 4.0,
+        "makeup_db": 3.9000003
+      }
+    },
+    {
+      "Preamp": {
+        "gain": 1.1,
+        "bias": 1.4901161e-8,
+        "clipper_type": "Triode"
+      }
+    },
+    {
+      "ToneStack": {
+        "model": "British",
+        "bass": 1.0500001,
+        "mid": 1.4,
+        "treble": 1.25,
+        "presence": 1.45
+      }
+    },
+    {
+      "MultibandSaturator": {
+        "low_drive": 0.099999994,
+        "mid_drive": 0.17999999,
+        "high_drive": 0.11,
+        "low_level": 1.0,
+        "mid_level": 1.54,
+        "high_level": 1.0,
+        "low_freq": 325.0,
+        "high_freq": 2850.0
+      }
+    },
+    {
+      "Level": {
+        "gain": 0.90000004
+      }
+    },
+    {
+      "Eq": {
+        "gains": [
+          -8.6,
+          -7.0,
+          -3.3,
+          0.0,
+          0.0,
+          0.0,
+          0.0,
+          2.8000002,
+          3.6000001,
+          1.6000001,
+          3.1000001,
+          3.2000003,
+          -0.29999983,
+          -4.9,
+          -2.9999998,
+          -4.2999997
+        ]
+      }
+    },
+    {
+      "Reverb": {
+        "room_size": 0.24,
+        "damping": 0.96,
+        "mix": 0.06
+      }
+    },
+    {
+      "Delay": {
+        "delay_ms": 300.0,
+        "feedback": 0.3,
+        "mix": 0.26
+      }
+    }
+  ],
+  "ir_name": "Science Amplification/4x12/G12H-150/MD 421-U Brighter.wav",
+  "ir_gain": 0.34,
+  "pitch_shift_semitones": -1,
+  "input_filters": {
+    "hp_enabled": true,
+    "hp_cutoff": 117.0,
+    "lp_enabled": true,
+    "lp_cutoff": 7174.0
+  }
+}

presets/Djent_Eb.json

@@ -0,0 +1,103 @@
+{
+  "name": "Djent Eb",
+  "description": null,
+  "author": null,
+  "stages": [
+    {
+      "Preamp": {
+        "gain": 3.3,
+        "bias": 0.0,
+        "clipper_type": "ClassA"
+      }
+    },
+    {
+      "ToneStack": {
+        "model": "Modern",
+        "bass": 0.90000004,
+        "mid": 1.2,
+        "treble": 1.1,
+        "presence": 0.95
+      }
+    },
+    {
+      "NoiseGate": {
+        "threshold_db": -20.0,
+        "ratio": 10.0,
+        "attack_ms": 1.4,
+        "hold_ms": 10.0,
+        "release_ms": 100.0
+      }
+    },
+    {
+      "Compressor": {
+        "attack_ms": 1.0,
+        "release_ms": 80.0,
+        "threshold_db": -14.0,
+        "ratio": 4.0,
+        "makeup_db": 18.5
+      }
+    },
+    {
+      "Preamp": {
+        "gain": 6.5,
+        "bias": 0.70000005,
+        "clipper_type": "Triode"
+      }
+    },
+    {
+      "MultibandSaturator": {
+        "low_drive": 0.42,
+        "mid_drive": 0.59999996,
+        "high_drive": 0.64,
+        "low_level": 0.91999996,
+        "mid_level": 0.97999996,
+        "high_level": 0.97999996,
+        "low_freq": 413.0,
+        "high_freq": 2410.0
+      }
+    },
+    {
+      "Level": {
+        "gain": 0.25
+      }
+    },
+    {
+      "Eq": {
+        "gains": [
+          -9.2,
+          -8.6,
+          -5.7,
+          -3.4999998,
+          -0.29999983,
+          0.0,
+          0.0,
+          0.0,
+          0.0,
+          0.0,
+          0.0,
+          0.0,
+          -0.29999983,
+          -0.39999983,
+          -1.9999999,
+          -6.7
+        ]
+      }
+    },
+    {
+      "Reverb": {
+        "room_size": 0.32999998,
+        "damping": 0.39,
+        "mix": 0.089999996
+      }
+    }
+  ],
+  "ir_name": "Science Amplification/4x12/G12H-150/SM57 Brighter.wav",
+  "ir_gain": 0.42,
+  "pitch_shift_semitones": -1,
+  "input_filters": {
+    "hp_enabled": true,
+    "hp_cutoff": 133.0,
+    "lp_enabled": true,
+    "lp_cutoff": 7469.0
+  }
+}

rustortion-plugin/src/backend.rs

@@ -245,6 +245,17 @@ impl ParamBackend for PluginBackend {
         None
     }
 
+    fn nam_models_dir(&self) -> Option<std::path::PathBuf> {
+        Some(crate::user_nam_dir())
+    }
+
+    fn rescan_nam_models(&self) -> Result<usize, String> {
+        let dir = crate::user_nam_dir();
+        let loader = rustortion_core::nam::NamLoader::new(&dir).map_err(|e| e.to_string())?;
+        rustortion_core::nam::registry::init_from_loader(&loader);
+        Ok(loader.available_names().len())
+    }
+
     fn persist_chain_state(&self, stages: &[StageConfig]) {
         // Store in SharedState for editor close/reopen within same session
         self.shared_state.store_gui_stages(stages);

rustortion-plugin/src/lib.rs

@@ -13,6 +13,17 @@ pub mod params;
 
 use params::RustortionParams;
 
+/// Directory the plugin loads user-provided `.nam` models from:
+/// `~/.config/rustortion/nam`. Shared by the init-time loader and the backend's
+/// rescan so the two can never drift to different paths.
+#[must_use]
+pub fn user_nam_dir() -> std::path::PathBuf {
+    dirs::config_dir()
+        .unwrap_or_default()
+        .join("rustortion")
+        .join("nam")
+}
+
 enum PluginTask {
     LoadPreset(String),
     /// Combined task: create new samplers at the given factor, then reload the
@@ -376,10 +387,7 @@ impl Plugin for RustortionPlugin {
 
                 // Load user NAM models from ~/.config/rustortion/nam into the
                 // process-global registry so the NAM stage can resolve models.
-                let nam_dir = dirs::config_dir()
-                    .unwrap_or_default()
-                    .join("rustortion")
-                    .join("nam");
+                let nam_dir = user_nam_dir();
                 match rustortion_core::nam::NamLoader::new(&nam_dir) {
                     Ok(loader) => {
                         nih_log!("Loaded {} NAM model(s)", loader.available_names().len());