NeuralAmpModeler-rs

NeuralAmpModeler-rs is a high-performance, real-time neural inference DSP engine written in pure Rust. It provides the core DSP library for loading, building, and executing Neural Amp Modeler (NAM) models — WaveNet (A1/A2), LSTM, ConvNet, and Linear FIR/FFT — as well as impulse response (.wav) cabinet convolution.

Designed for embedding in audio hosts, CLAP plugins, standalone audio hosts, offline renderers, and embedded DSP pipelines, it guarantees zero heap allocations, zero locks, and zero blocking system calls on the real-time audio processing thread.

NeuralAmpModeler-rs is an independent public library for the wider audio and Rust communities. Public APIs and policies remain strictly host-agnostic and generally reusable; integration-specific logic belongs in downstream crates (such as standalone audio hosts, CLAP plugins, and real-time processing applications).

❤️‍🔥 NeuralAmpModeler-rs is in beta stage. Feedback, bug reports, performance metrics, and patch contributions are very welcome!

Series note: the current release series is 0.x; the 3.x versions on crates.io/docs.rs are yanked leftovers of an earlier monolithic incarnation of this project.

⚡ Key Strengths & Architectural Highlights

• Pure Rust & Strict Zero-Allocation RT Safety: Engineered from the ground up for absolute real-time audio determinism — zero heap allocations, zero mutex locks, and zero blocking syscalls on the audio processing thread (verified via CountingAllocator in heap audit suites). Parameter updates and model swaps pass through lock-free SPSC channels, while a 3-tier GC cascade (SPSC queue → 16-slot thread-local parking lot → overwrite ring) guarantees safe off-RT resource disposal without audio glitches.
• Extremely Fast SIMD Inference & Zero-Vtable Dispatch: Mandatory x86-64-v3 (AVX2/FMA/BMI2) baseline vectorization. The SimdMath / dispatch_simd! engine is a static match with zero function pointers or vtables. Production inference is native f32 on the AVX2 kernels (sum0..sum3 ILP, tap-major tiling). AVX-512 / VL256 / BF16 / VNNI were evaluated against a $\ge 12%$ end-to-end process() N=64 gate and are not a production acceleration (2026-08 Sapphire Rapids receipt: all canonical SKUs failed; see docs/architecture.md §1.2). The dispatch engine is kept for a possible future backend (e.g. ARM/NEON); AVX-512 sources stay in-tree as test/research, not as a marketed feature.
• Uncompromising Dual-Oracle Audio Parity: Validated against two independent co-equal test oracles: canonical C++ NAMCore f32 (market interop) and double-precision f64 reference oracle (mathematical ideality). Grounded in docs/quality-contract.json, BossWN Standard measures 2.31e-14 ESR against NAMCore and 9.05e-15 against the f64 oracle (SNR 136.4 dB, MR-STFT 6.46e-6), with ConvNet reaching 4.23e-15 ESR (SNR 143.7 dB).
• Const-Generic Optimization & Dynamic Topology Fallback: 23 static model profiles leverage Rust const generics so kernel sizes, receptive fields, and channel counts (CH=16, 12, 8, 4, 3) are known at compile time, enabling aggressive LLVM loop unrolling and register allocation. Non-standard topologies gracefully fallback to zero-allocation dynamic engines (WaveNetModelDyn, LstmModelDyn, WaveNetA2Dyn, WaveNetA2Cascade).
• Complete Native DSP Stack (Zero External Audio Crates): Integrated native Minimum-Phase Polyphase FIR Sinc Resampler (256 phases × 64 taps, Kaiser $\beta=12$, >105 dB stopband, zero pre-ringing cepstrum, 0.7–1.3 µs latency, replacing external libraries like rubato), UPOLS Partitioned FFT CabSim IR convolution (1.3 µs), and multi-stage Half-Band FIR Anti-Aliasing Oversampling (2×/4×, >100 dB attenuation, Kahles et al. JAES 2019).
• Adaptive Compute FSM & Pre-Transposed .namb v2 Container: Dynamic CPU load monitoring with hysteresis FSM that gracefully degrades model complexity (Full → Reduced → Minimal) with 32 ms click-free linear crossfades to prevent audio xruns. Binary .namb v2 container (Gate-Major LSTM, Interleaved-4 WaveNet) reduces model hot-swap latency from ~50 ms to <1 ms with mandatory IEEE 802.3 CRC32 integrity validation.
• Denormal & Subnormal Armor: Injected symmetric −220 dBFS deterministic dither (1.0e-11) + SSE2 MXCSR FTZ/DAZ reassertion on every processing call, eliminating 10–100× CPU microcode penalties on digital silence with zero net DC drift.

🥊 Feature Showcase ("Roofshoot")

🧠 Supported Architectures

🛠️ System Prerequisites

MSRV policy: rust-version = "1.98.0" in Cargo.toml is the public MSRV promise. Development happens on stable (pinned by rust-toolchain.toml). The MSRV promise is verified as an isolated local check — never mixed with the dev toolchain: cargo +1.98.0 check --locked from the repository root.

Installation of System Build Dependencies (Debian / Ubuntu / Pop!_OS)

sudo apt update && sudo apt install -y build-essential pkg-config cmake

🚀 Quick Start — Installation & Usage

Add to Your Cargo.toml

[dependencies]
NeuralAmpModeler-rs = "x.y.z"

For off-RT testing utilities and audio signal generators:

[dependencies]
NeuralAmpModeler-rs = { version = "x.y.z", features = ["testing"] }

Feature Flags

⚠️ Note on dynamic-engine: This flag does not enable non-standard topology support — dynamic fallbacks (WaveNetModelDyn, LstmModelDyn, WaveNetA2Dyn) are always compiled and unconditionally active. This flag is used exclusively for internal coverage and regression testing to force dynamic execution paths even when optimized static profiles are applicable.

Code Examples

1. Minimal Model Loading & Audio Processing

use std::path::Path;
use neural_amp_modeler_rs::loader::{load_and_build_model, LoadOptions};
use neural_amp_modeler_rs::models::NamModel; // trait providing `process()`
use neural_amp_modeler_rs::SystemSnapshot;

fn main() {
    // 1. Capture system hardware capabilities (SIMD features, CPU topology)
    let sys = SystemSnapshot::capture();

    // 2. Load a .nam or .namb neural model file
    let mut model_pair = load_and_build_model(
        Path::new("models/BossWN-standard.nam"),
        &sys,
        false, // mono processing
        LoadOptions::default(),
    ).expect("Failed to load NAM model");

    // 3. Process audio in block quanta (e.g. 64 samples)
    let input_buffer = vec![0.0_f32; 64];
    let mut output_buffer = vec![0.0_f32; 64];

    if let Some(ref mut model) = model_pair.model_l {
        model.process(&input_buffer, &mut output_buffer);
    }
}

2. Full DSP Engine Pipeline (Model + Cab IR + Polyphase Oversampling)

For the complete pipeline — model, cabinet IR, and 4× polyphase oversampling — see the offline_render example (cargo run --example offline_render -- <path/to/model.nam>). The API surface used there is documented in the crate docs.

3. Executable Examples

NeuralAmpModeler-rs includes 6 runnable examples in examples/ demonstrating key features:

Rustdoc Module Map

Full API documentation:

• Local Generation (Standard): cargo doc --open

• Docs.rs Simulation (Preview feature badges):

  # Note: Requires nightly rustc only for rendering experimental doc_cfg feature badges locally.
  # Production builds, testing, and CI of NeuralAmpModeler-rs remain strictly on stable Rust.
  RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc \
    --no-default-features \
    --features "stereo,testing,heap-audit,long_bench,avx512" \
    --no-deps
  

• Online Documentation: docs.rs/NeuralAmpModeler-rs

Note on docs.rs Builds and AVX-512: NeuralAmpModeler-rs/build.rs detects DOCS_RS=1 to early-return before avx2+fma CPU target feature assertions. This allows docs.rs builders (running on baseline x86-64 without AVX2) to document the API successfully. While the AVX2 baseline already delivers ample headroom for real-time operation (and project benchmarks show AVX-512 yields marginal real-world difference), avx512 is enabled in [package.metadata.docs.rs].features so that the complete API surface remains accessible to users wishing to utilize it. For new crates.io releases or manual doc rebuild requests, use the docs.rs re-trigger queue at https://docs.rs/crate/NeuralAmpModeler-rs/latest/builds.

🏆 Quality & Performance

• Numerical Fidelity: The quality contract (docs/quality-contract.json) tracks NAMCore parity, independent f64-oracle error, SNR (110–144 dB), and MR-STFT (< 1e-5) across 584 lines of per-model baseline envelopes.

• Measured CPU Headroom (Contract SLA Baseline Snapshot):

  Contract Reference: Frozen snapshot from docs/quality-contract.json (captured 2026-08-12 on AMD Ryzen 7 5700U 8C/16T, Zen 2, base 1.8 GHz / boost up to 4.3 GHz, governor performance, rustc 1.97.1, buffer size $N=64$ @ 48 kHz, AVX2 baseline). These figures establish the formal quality and regression baseline envelopes. Ambient thermal conditions, system load, or compiler release shifts (e.g. rustc 1.98+ observing ~43 µs on WaveNet Std) can modulate raw execution times without representing algorithmic regressions.

  • WaveNet Standard CH16: 36.9 µs (2.8% of the 1.33 ms deadline)
  • WaveNet Feather CH8: 19.4 µs (1.5%)
  • WaveNet Lite CH12: 52.6 µs (3.9%)
  • WaveNet Nano CH4: 17.4 µs (1.3%)
  • WaveNet A2 Full CH8: 27.6 µs (2.1%)
  • WaveNet A2 Lite CH3: 18.4 µs (1.4%)
  • LSTM 1×16: 7.5 µs (0.6%)
  • LSTM 2×8: 7.6 µs (0.6%)
  • ConvNet: 10.2 µs (0.8%)
  • Linear RF=2048: 0.3 µs (0.02%)
  • Full DSP Pipeline Base (No OS): 37.2 µs (2.8%)
  • Full DSP Pipeline HQ (4× OS): 150.6 µs (11.3%)
  • DSP Resampler (44.1k→48k): 1.3 µs | CabSim IR Medium (512): 1.3 µs

• Stress Coverage: Soak, concurrency, heap-audit, deadline, and model-checking suites exercise long-running and real-time invariants; skipped coverage and failed audit phases must be reviewed separately from passing checks.

• SIMD Acceleration: Production math is the AVX2 (x86-64-v3) baseline. All production models execute native f32 (BF16/VNNI retired). The ≥12% process() N=64 ROI rule is a promotion policy, not a passed measurement: the 2026-08 remote receipt failed every canonical SKU, so AVX-512 is not advertised and default builds dispatch Avx2 (detect_best_simd() returns Avx2 in default builds, with AVX-512 kernels cfg-gated behind the opt-in avx512 feature; see docs/architecture.md §1.2). FastMath activations (tanh, sigmoid) via Padé/minimax, with exact-grade Standard mode as default.

🧰 Local Development Environment (engine maintainers)

Crate consumers only need a Rust toolchain and the published crate — no vendor trees.

Developers working on NeuralAmpModeler-rs itself (parity, golden regeneration, cabsim C++ cross-validation, optional community-model tests) should prepare a local third-party/ tree after clone. That directory is gitignored and is never part of the published package:

# From the NeuralAmpModeler-rs repository root:
./utils/setup-third-party.sh

# Optional: link a private non-distributable model archive
NAM_COMMUNITY_MODELS_SRC=/path/to/your/nam_models ./utils/setup-third-party.sh
# or: ln -s /path/to/your/nam_models third-party/community_models

Tests and scripts skip gracefully with a declared gap when these artifacts are missing: the quick suite records GAP: lines in target/logs/quick-receipt.txt, prints FIDELITY: INCOMPLETE / OVERALL: PASSED_WITH_GAPS (exit 0), and never emits a green fidelity seal for skipped oracles — NAM_QUICK_STRICT=1 promotes those gaps to FAIL (exit 1). The long suite requires the NAMcore mirror outright (hard abort if absent). Override locations with NAM_THIRD_PARTY_DIR, NAM_CORE_DIR, NAM_PLUGIN_DIR, or NAM_MODELS_DIR if needed. See docs/fixtures.md for the full model search order.

Rust dependency supply-chain updates remain separate: ./utils/mod-update.sh.

🧪 CI & QA Automation Suite (./utils/)

The ./utils/ directory contains maintainer tools and standard scripts for code quality, numerical verification, and continuous integration:

Exact QA commands:

# 1. Static analysis (fmt, SPDX, check, clippy)
./utils/lints.sh

# 2. Agile first line (AI tasks: at most once, as final validation)
./utils/tests-quick.sh

#    Release-gate mode: skipped oracles (missing fixtures/C++ toolchain) become FAIL
NAM_QUICK_STRICT=1 ./utils/tests-quick.sh

#    Receipt + per-phase logs of the last run
cat target/logs/quick-receipt.txt   # plus target/logs/quick-phase{1,2,3}.log
# 3. Nightly / pre-release audit — HUMAN OPERATOR ONLY (AI agents must never run it)

./utils/tests-long.sh
./utils/tests-long.sh --strict-pre-release

#    Human certification protocol (checklist + evidence record for both runners)
#    docs/functional-tests.md

📚 Architecture & Engineering Documentation

The following technical documents are maintained in the source repository. The public Rust API is documented on docs.rs.

🤝 Contributing & Feedback

• Testing, testing, testing! Go on, "cargo add NeuralAmpModeler-rs" into your own project and make NeuralAmpModeler-rs it live and evolve!
• Test Models: Try your favorite .nam models and IR files — share your feedback and performance metrics.
• Report Issues: Submit detailed bug reports or feature suggestions on GitHub.
• Code & Docs: Help me to make NeuralAmpModeler-rs more useful and correct for the community!

🙏 Credits & Acknowledgments

• Steven Atkinson — Creator of Neural Amp Modeler (NAM) for pioneering deep learning amplifier modeling and sharing the ecosystem with the community.
• Mike Oliphant — Author of NeuralAudio, whose codebase provided invaluable insight into WaveNet inference in the early stages.

⚖️ License & AI Transparency

AI Transparency Note

The system architecture, core DSP engineering decisions, mathematical verification framework, and project orchestration are intellectual work (and love) of the maintainer (Fábio Lima). The implementation was accelerated through pair programming (Vibe Coding) using artificial intelligence models (Gemini, Claude, Grok, DeepSeek and others) within Google Antigravity IDE and Kilo Code. IA is just a tool that make wonder in wise hands.

License

This project is licensed under the Apache License, Version 2.0. See LICENSE.txt for details.