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 NAM-Audio-Pipe and NAM-Plug).

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

⚡ Key Strengths & Architectural Highlights

• Pure Rust & Zero-Allocation RT Safety: Engineered from the ground up for absolute real-time audio determinism — zero heap allocations, zero mutex locks, and zero blocking I/O on the hot path. Parameter updates and control-plane commands pass through lock-free SPSC channels.
• Extremely Fast SIMD Inference: Hand-crafted AVX2 (x86-64-v3) baseline vectorization and optional AVX-512 multiversioning (BF16/VNNI) protected by statistical performance gates and real-time deadline tests.
• Uncompromising Audio Parity: Validated against three independent test oracles (canonical C++ NAMCore f32, double-precision f64 reference oracle, and cross-ISA parity). In quality audits, BossWN Standard measured 2.31e-14 ESR against NAMCore and BossLSTM 1x16 measured 8.50e-12; paired f64-oracle ESR measured 9.05e-15 and 8.90e-13, respectively.
• Const-Generic Optimization: Static WaveNet and LSTM profiles leverage Rust const generics so kernel sizes, receptive fields, and channel counts are known at compile time, enabling aggressive LLVM compiler optimization, register allocation, and SIMD loop unrolling.
• Cabinet IR & DSP Pipeline: Integrated partitioned FFT and direct FIR convolution engine for speaker cabinet impulse responses (.wav), paired with polyphase half-band anti-aliasing oversampling and Padé FastMath activations.
• Flexible Host Integration: Exposes a clean, host-agnostic API for model loading, DSP pipeline construction, dynamic quality switching (.namb bundles), and diagnostics. Designed to be embedded as an rlib dependency in any Rust application.

🥊 Feature Showcase ("Roofshoot")

🧠 Supported Architectures

🛠️ System Prerequisites

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

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::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 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 + Cabinet IR + Polyphase Oversampling)

use std::path::Path;
use neural_amp_modeler_rs::dsp::{DspPipeline, OversampleMode};
use neural_amp_modeler_rs::loader::{load_and_build_model, LoadOptions};
use neural_amp_modeler_rs::SystemSnapshot;

fn main() {
    let sys = SystemSnapshot::capture();

    // Load neural model
    let model_pair = load_and_build_model(
        Path::new("models/BossWN-standard.nam"),
        &sys,
        false,
        LoadOptions::default(),
    ).unwrap();

    // Create DSP pipeline with 4x oversampling
    let mut pipeline = DspPipeline::new(
        model_pair.model_l,
        OversampleMode::FourTimes,
    );

    // Process real-time audio block
    let input = vec![0.1_f32; 128];
    let mut output = vec![0.0_f32; 128];
    pipeline.process(&input, &mut output);
}

3. Executable Examples

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

Rustdoc Module Map

Full API documentation:

• Local Generation: cargo doc --open
• Docs.rs Environment Simulation: DOCS_RS=1 cargo doc --features "stereo,testing" --no-deps
• Online Documentation: docs.rs/NeuralAmpModeler-rs

Note on docs.rs Builds: 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. 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 tracks NAMCore parity, independent f64-oracle error, SNR, and MR-STFT instead of relying on a single metric.
• Measured CPU Headroom: On the logged AMD Ryzen 7 5700U run, WaveNet Standard CH16 processed a 64-sample block in 37.5 µs (2.8% of the 1.33 ms deadline), while LSTM 1x16 used 7.4 µs (0.6%).
• 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: AVX2 baseline (x86-64-v3), AVX-512 multiversioning with BF16/VNNI on supported hardware (Intel Sapphire Rapids+, AMD Zen 4+). FastMath activations (tanh, sigmoid) via Padé/minimax polynomial approximations.

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

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

📚 Architecture & Engineering Documentation

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

🤝 Contributing & Feedback

• 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: Pull requests for SIMD optimizations, bug fixes, or documentation enhancements are very welcome.

🙏 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 the intellectual work of the maintainer (Fábio Henrique de Lima Silva). The implementation was accelerated through pair programming (Vibe Coding) using artificial intelligence models (Gemini, Claude, DeepSeek) within Google Antigravity IDE and Kilo Code.

License

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