NeuralAmpModeler-rs

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 packaging.

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!

⚡ 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::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: 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.

🧰 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

• 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.