Crate nam_rs 

nam-rs

Pure-Rust, real-time-safe inference for Neural Amp Modeler (NAM) .nam models.

This crate loads a .nam model file and runs its neural network forward pass — a whole buffer at a time (WaveNet uses a cache-friendly block kernel), or one sample at a time — with no heap allocation on the audio (hot) path. It is a from-scratch Rust port of NAM’s inference, written against the reference implementations below and validated for bit-level parity against them.

Both NAM architectures are supported — WaveNet and LSTM — and run through the architecture-agnostic Model enum, which dispatches on the .nam’s declared architecture so you never have to branch on it yourself.

Design contract

1. Parity with the reference. The forward pass must produce output equal (within float tolerance) to the canonical Python/C++ NAM implementations for the same .nam file and input. This is enforced by tests/parity.rs.
2. Real-time safety. The runtime’s process_buffer (on both WaveNet and Lstm, reached via Model) performs zero heap allocations, locks, or system calls. All scratch buffers are pre-allocated at construction. This is enforced by tests/rt_safety.rs.

Example

use nam_rs::{NamModel, Model};

// From disk you'd use `NamModel::from_file("model.nam")?`.
// Here we use a tiny in-line model for illustration.
let json = r#"{
    "version": "0.5.4", "architecture": "WaveNet",
    "config": {
        "layers": [{
            "input_size": 1, "condition_size": 1, "channels": 1, "head_size": 1,
            "kernel_size": 1, "dilations": [1], "activation": "ReLU",
            "gated": false, "head_bias": false
        }],
        "head": null, "head_scale": 1.0
    },
    "weights": [1.0, 2.0, 0.0, 0.0, 1.0, 0.0, 1.0, 1.0]
}"#;

let model = NamModel::from_json_str(json)?;
let mut amp = Model::from_nam(&model)?;   // picks WaveNet or Lstm from the file

// On the audio thread: process in place, no allocation.
let mut buffer = [0.1_f32, 0.2, 0.3, 0.4];
amp.process_buffer(&mut buffer);

Attribution

This is a derivative work. The algorithm and weight layout are ported from the following projects (see NOTICE for license texts):

• neural-amp-modeler — Steven Atkinson’s reference trainer + .nam exporter (Python, MIT). The source of truth for export_weights / export_config.
• NeuralAmpModelerCore — the canonical C++ inference library (MIT).
• NeuralAudio — Mike Oliphant’s high-performance C++ NAM/RTNeural runtime, designed to match NAM Core exactly (MIT). Primary porting reference.
• waveny — a Go port of NAM (Apache-2.0). Used as a conceptual cross-check only.

Structs

LayerArrayConfig

Configuration for a single WaveNet layer-array (a stack of dilated layers sharing channel/kernel parameters).

Lstm

A ready-to-run LSTM, all scratch pre-allocated in Lstm::new.

LstmConfig

LSTM configuration (NAM _export_config).

Metadata

Loudness/level-calibration fields NAM may write into metadata. All optional; older or minimal files omit them. Unknown metadata keys are ignored.

NamModel

A parsed .nam model file.

WaveNet

A ready-to-run WaveNet, with all scratch buffers pre-allocated.

WaveNetConfig

WaveNet configuration: a sequence of layer-arrays plus a final output scale.

Enums

Error

Errors produced when loading or building a NAM model.

Model

A runnable NAM model of any supported architecture.

ModelConfig

Architecture-specific configuration, tagged by NamModel.architecture.

Constants

DEFAULT_SAMPLE_RATE

Sample rate assumed when a .nam file omits the sample_rate field.