NAM-Plug

NAM-Plug is a high-performance, ultra-low latency CLAP (CLever Audio Plug-in) audio plugin for real-time Neural Amp Modeler (NAM) simulation on Linux DAWs.

It directly embeds NeuralAmpModeler-rs as its core neural DSP engine, inheriting all of its real-time guarantees: zero heap allocations, zero locks, and zero blocking system calls on the real-time audio thread, x86-64-v3 (AVX2/FMA) baseline SIMD vectorization, and exact numerical parity against canonical C++ NAMCore and double-precision f64 reference oracles.

Designed for seamless integration into modern Linux digital audio workstations (DAWs) such as Bitwig Studio and REAPER, NAM-Plug offers a declarative, hardware-accelerated Slint GUI (with native X11 XEmbed embedding into the host panel, plus Wayland and X11 floating fallbacks) for loading .nam neural amp models and .wav impulse responses (IRs), gain staging, noise gating, oversampling, anti-aliasing filter configuration, and real-time DSP performance telemetry.

❤️‍🔥 NAM-Plug is in active development. Feedback, bug reports, performance metrics, and DAW compatibility notes are very welcome!

🎨 Visual Overview & GUI Showcase

The declarative Slint graphical interface running inside a Linux host. The interface features model and cabinet IR selectors, rotary controls for Input/Output gain staging and Noise Gate threshold, toggle selectors for half-band anti-aliasing Oversampling (Off, 2x, 4x) and Activation precision math (Standard vs Fast), an active/bypass state indicator, high-resolution adaptive peak level meters with IEC 60268-10 ballistics, and a real-time DSP telemetry status bar.

⚡ Key Strengths & Architectural Highlights

Native CLAP 1.2+ Standard Integration: Built on top of the clack framework, exposing a clean, robust implementation of the CLever Audio Plug-in (CLAP) standard with zero translation overhead, sample-accurate parameter automation, and native host extension compliance (audio-ports, audio-ports-activation, params, state, state-context, latency, gui, track-info, remote-controls, param-indication, preset-discovery, render, tail, log).
Inherited Neural Engine Excellence: Powered by NeuralAmpModeler-rs, supporting WaveNet (A1/A2 standard & slimmable profiles), LSTM (1-layer and 2-layer topologies), ConvNet, Linear FIR, and partitioned FFT speaker cabinet impulse responses (.wav).
Strict Zero-Allocation RT Safety & 3-Tier GC Cascade: The audio callback thread runs with strict real-time determinism — no heap allocations, no mutex locks, and no blocking I/O on the hot path. Dropped models, IRs, and oversamplers cascade through lock-free SPSC channels (32 slots) → processor parking lot (16 slots) → atomic overflow ring buffer with poison-resilient rollback guards (ActivateRollbackGuard).
Branchless FMA-Optimized Bypass Crossfader: 32 ms equal-power crossfade blending during bypass transitions, executing branchlessly with FMA vectorization and adaptive handling of fractional phase discrepancies between dry capture and resampled wet streams.
Cold-Path Latency Caching & Dynamic PDC: Effective latency (resampler + oversample + cab-sim) is cached on the audio thread and recomputed strictly during cold asset swaps, driving instant DAW Plugin Delay Compensation (clap_plugin_latency) without per-block audio thread overhead.
Decoupled Gain Staging & Model Calibration: Embedded model loudness metadata calibration (input_mult_adj/output_mult_adj) is isolated from sample-accurate DAW user-gain automation (ParamSmoother), preventing automation sweeps from altering static model calibration multipliers.
Generation-Counter Fast Path (gui_param_generation): Eliminates redundant atomic float loads when parameters are stationary, reading parameter targets only upon modification.
Hardware-Accelerated Slint GUI with Native X11 Embedding & Wayland: Declarative UI built with Slint 1.17 (FemtoVG / OpenGL rendering via winit), with native X11 XEmbed embedding into the host's plugin panel (CLAP_WINDOW_API_X11, embedded) plus X11/Wayland floating fallbacks (CLAP_WINDOW_API_X11/CLAP_WINDOW_API_WAYLAND). Features 5-zone modular architecture, adaptive mono/stereo tricolor VU meters with IEC 60268-10 PPM ballistics, and dedicated 60 Hz lock-free telemetry polling via SlintViewModel.
Half-Band Anti-Aliasing Oversampling: Optional 2x and 4x polyphase oversampling centered around the neural inference stage to eliminate high-frequency aliasing foldover in high-gain amp models.
Selectable Activation Precision: Supports both Standard (exact-grade, default) and Fast (Padé polynomial minimax approximations) math modes to balance precision against CPU consumption on demanding setups.
Real-Time DSP Telemetry & Diagnostics: Live footer display reporting sample rate (SR), buffer latency (Lat), DSP CPU load percentage (DSP %), CPU cycles per block, block size (Last N), real-time thread priority (RT Prio), overload xrun count, and diagnostic status flags (Flags).
5-Phase Advanced Optimization Pipeline (PGO + LLVM-BOLT): Automated compilation suite (build-release.sh) leveraging synthetic neural DSP profiling, Profile-Guided Optimization (PGO), LLVM-BOLT machine code layout optimization, and 5 strict verification gates (SONAME/symbols, clap-validator, NAMCore float parity, CabSim IR, and nam_perf_guard performance certification).
Linker-Level Symbol Isolation: Scoped version script (hide-libm-shadow.map) ensuring libm symbols resolve dynamically to glibc without dangerous PLT/GOT self-referential loops in release builds.

🥊 Feature Showcase ("Roofshoot")

Feature / Attribute	Technical Implementation	Benefit & Impact
Inference Engine	Core `NeuralAmpModeler-rs` engine (WaveNet A1/A2, LSTM, ConvNet, Linear)	Full model compatibility with exact C++ f32 & f64 reference parity
Plugin Standard	Native CLAP API wrapper (`clack-plugin` & `clack-extensions`)	Sub-millisecond buffer sizes and sample-accurate DAW automation
RT Determinism	Strict Zero Heap Drop, Zero Locks, Zero Hot-Path Logging	Guaranteed audio stability without buffer underruns (xruns)
SIMD Hardware Acceleration	Engine `x86-64-v3` (AVX2/FMA) production backend	Ultra-low CPU usage (WaveNet Std ≪ 1.33 ms deadline)
Bypass Crossfader	32 ms equal-power crossfade with branchless FMA loop & phase compensation	Smooth, pop-free bypass transitions with zero phase cancellation
Dynamic Latency (PDC)	Cold-path cached effective latency with dynamic `clap_plugin_latency`	Instant host Plugin Delay Compensation with 0 per-block overhead
Cabinet IR Convolution	Partitioned FFT & Direct FIR convolution engine (.wav IRs)	Seamless, zero-latency speaker cabinet simulation
Graphical User Interface	Slint 1.17 declarative UI (FemtoVG/OpenGL backend via `winit`)	Native X11 XEmbed embedding + Wayland/X11 floating, high-DPI scaling, IEC 60268-10 ballistics
GUI Event Loop & Telemetry	Dedicated `"nam-slint-gui"` event loop thread with 60 Hz `SlintViewModel`	0% audio thread overhead, lock-free atomics, smooth 60 FPS metering
Oversampling	Half-band polyphase FIR filters (`Off`, `2x`, `4x`)	Eliminates aliasing distortion in high-gain amp models
Activation Precision	`Standard` (exact-grade, default) vs `Fast` (Padé approximations)	User-selectable trade-off between math precision and CPU latency
CLAP State Persistence	Lock-free atomic synchronization & JSON serialization	Full preset saving/loading and seamless DAW project restoration
Diagnostics & Telemetry	Atomic telemetry bitmask & `LogBuffer` ring buffer integration	Real-time CPU, latency, overload, and flag telemetry in GUI footer
Release Optimization	5-phase PGO + LLVM-BOLT pipeline with demangled assembly report	Minimized I-Cache misses and maximum instruction throughput

🛠️ System Prerequisites

Dependency	Minimum Version	Package / Command
Linux Kernel	≥ 5.10	`uname -r`
Rust Toolchain	≥ 1.99.0 (edition 2024)	`rustc --version`
CPU Architecture	`x86_64` with AVX2/FMA (`x86-64-v3` baseline)	`lscpu`
CLAP Host / DAW	Bitwig, REAPER, Studio Pro, etc.	Host application
Development Libraries	`build-essential`, `pkg-config`, `cmake`, GL	See apt command below

MSRV policy: rust-version = "1.99.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.99.0 check --locked from the repository root.

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

sudo apt update && sudo apt install -y build-essential pkg-config cmake libgl1-mesa-dev libx11-dev libxcursor-dev libxcb1-dev libxkbcommon-dev

🚀 Building & Installation

1. Direct Shared Library Build (`cargo build`)

For standard plugin compilation:

cargo build --release

The resulting shared library will be placed at target/release/libnam_plug.so.

To install the plugin into your user CLAP directory:

mkdir -p ~/.clap
cp target/release/libnam_plug.so ~/.clap/nam_plug.clap

For development and host-harness testing support:

cargo build --features testing

To run the standalone GUI preview tool (live Slint interface without a DAW host):

cargo run --bin ui_preview

2. Mega-Optimized Compiler Build (`./utils/build-release.sh`)

For maximum performance in live and studio DAW environments, NAM-Plug includes a 5-phase optimization pipeline leveraging Profile-Guided Optimization (PGO) and LLVM BOLT (Binary Optimization and Layout Tool).

./utils/build-release.sh

What `build-release.sh` does under the hood

Phase 1 — Environment Verification: Validates toolchain prerequisites (rustc, cargo, python3, tar, zstd, flatpak, llvm-profdata, llvm-bolt, and perf) and verifies target CPU flags from .cargo/config.toml.
Phase 2 — PGO Trace Generation: Compiles pgo_profiling_workload with -Cprofile-generate, executing synthetic neural DSP workloads to collect realistic CPU performance profiles (.profraw), merging them into merged.profdata.
Phase 3 — PGO-Optimized Compilation: Recompiles libnam_plug.so using -Cprofile-use=merged.profdata and relocation symbols (-Clink-arg=-Wl,-q), allowing LLVM to optimize hot loops, inline activation functions, and unroll vector SIMD loops.
Phase 4 — LLVM BOLT Machine Code Reordering: Reorders machine code instructions via llvm-bolt to minimize Instruction Cache (I-Cache) misses and TLB pressure during real-time processing.
Phase 4.5 — Assembly Hotspot Disassembly Report: Outputs an AI-ready demangled disassembly report at target/dsp_hotpath.asm.
Phase 5 — Automated Deployment & Strict Certification: Strips and installs the finalized, hyper-optimized plugin directly to ~/.clap/nam_plug.clap, executing 5 release certification gates:
- Gate 1: Exported symbols and SONAME validation (clap_entry, SONAME presence).
- Gate 2: External clap-validator test suite compliance.
- Gate 3: NAMCore C++ float parity oracle (test_clap_parity_multi_rate).
- Gate 4: CabSim IR artifact test against distributed .so (test_cabsim_ir_changes_audio_release_artifact).
- Gate 5: Distributed artifact performance certification gate (nam_perf_guard latency distributions and real-time deadline margins).
Phase 6 — Release Packaging (.tar.zst): Generates a release distribution archive at ~/nam-plug-vx.y.z-linux-x86_64-v3.tar.zst containing the plugin, documentation, license, and a 1-click installation script.
Phase 7 — Release Packaging (.flatpak): Builds and exports the standalone Flatpak plugin extension bundle (~/nam-plug-vx.y.z-linux-x86_64-v3.flatpak) with AppStream metadata for sandboxed DAWs (Bitwig, REAPER).

CLI Options

Option	Description
`--install`	Automatically installs the Flatpak extension locally (`flatpak install --user`) in addition to `~/.clap/`.
`--no-flatpak`	Skips Phase 7 (Flatpak bundle creation).
`--no-tarball`	Skips Phase 6 (.tar.zst archive creation).
`--no-pgo`	Skips Phase 2/3 (Profile-Guided Optimization) and compiles directly with the `dist` release profile.
`--no-bolt`	Skips Phase 4 (LLVM BOLT post-link optimization).
`-h, --help`	Displays command-line help screen and exits.

3. Flatpak Plugin Extension Distribution (`.flatpak`)

In addition to traditional shared library installation, NAM-Plug is distributed as a standalone Flatpak Audio Plugin Extension (org.freedesktop.LinuxAudio.Plugins.NAMPlug), targeting the standard org.freedesktop.LinuxAudio.BaseExtension runtime point (branch 25.08).

This format enables sandboxed Flatpak DAWs (including Bitwig Studio com.bitwig.BitwigStudio, REAPER fm.reaper.Reaper, and Studio One com.fender.studioapp8) to seamlessly discover and load NAM-Plug without requiring insecure filesystem sandbox holes (--filesystem=host or --filesystem=home).

End-User Installation

Install the .flatpak bundle directly into your local user Flatpak repository:

flatpak install --user --reinstall ~/nam-plug-v0.8.0-linux-x86_64-v3.flatpak

How DAW Discovery Works in Flatpak

When installed, the plugin binary is mounted inside the DAW container at /app/extensions/Plugins/clap/nam_plug.clap. Compatible Flatpak DAWs configured with the org.freedesktop.LinuxAudio.Plugins extension point automatically scan this directory on startup and expose NAM-Plug directly in their native CLAP plugin browser.

To verify the installed extension files on your system:

ls -la ~/.local/share/flatpak/runtime/org.freedesktop.LinuxAudio.Plugins.NAMPlug/x86_64/25.08/active/files/clap/

Note

AppStream Metadata in Local Bundles vs. Flathub Repositories: Single-file .flatpak bundles distribute exclusively the extension's runtime commit; they do not bundle repository-wide AppStream catalog branches (appstream/x86_64). Consequently, graphical Flatpak managers (such as Warehouse or GNOME Software) display bundles installed from a local origin (namplug-origin) with fallback labels ("Sem metadados" / "No metadata" and an empty Versão column in flatpak list). In production distributions via Flathub or remote OSTree repositories, the AppStream catalog is indexed automatically. See docs/architecture.md for architectural details.

Developer Workflow (Building & Testing Flatpak Locally)

You can build and package the Flatpak extension bundle locally using either the release pipeline or flatpak-builder:

Automated Pipeline Build & Install:
```
./utils/build-release.sh --install
```

Standalone Manifest Compilation via flatpak-builder:

# Build the release CLAP library first
cargo build --release

# Compile and install the extension manifest locally
flatpak-builder --user --install --force-clean \
  --state-dir=target/flatpak-builder \
  target/flatpak-build \
  packaging/flatpak/org.freedesktop.LinuxAudio.Plugins.NAMPlug.yml

Uninstallation

To remove the Flatpak plugin extension:

flatpak uninstall --user org.freedesktop.LinuxAudio.Plugins.NAMPlug

🎛️ DAW Usage & Workflow Guide

1. Host Scanning & Loading

Open your CLAP-compatible DAW.
Trigger a plugin rescan if required. NAM-Plug will appear under your CLAP plugin list as NAM-Plug (or Neural Amp Modeler).
Insert NAM-Plug into an audio or guitar track.

2. Loading Models & Cabinet IRs

Neural Model: Click Load Model in the left panel to select a .nam or .namb amplifier model file.
Cabinet Impulse Response: Click Load IR to load a speaker cabinet .wav impulse response.

3. Staging & Performance Tuning

Gain Staging: Use the INPUT and OUTPUT rotary knobs to balance signal levels (-20.0 dB to +20.0 dB, default 0.0 dB).
Noise Gate: Adjust the GATE knob (-90.0 dB to -40.0 dB, default -90.0 dB — off by default, i.e. parked at the most permissive end of the range) to eliminate hum and background noise when not playing.
Anti-Aliasing Oversampling: Select 2x or 4x polyphase oversampling when running high-gain amplifier models to eliminate aliasing foldover distortion.
Activation Math Mode: Switch between Standard (exact precision, default) and Fast (Padé polynomial approximations) to optimize CPU usage on large sessions.
Active / Bypass: Toggle the ACTIVE button to bypass or re-engage processing seamlessly with 32 ms equal-power crossfading.

4. Telemetry Footer Monitoring

The status bar at the bottom of the plugin GUI provides real-time telemetry:

SR: Host sample rate (e.g., 48.0 kHz).
Lat: Added latency in samples/ms (e.g., 0 ms when oversampling is Off).
DSP: Percentage of real-time audio block budget consumed (e.g., DSP: 8.2%).
Cycles: Exact CPU cycle count for the last processed block.
Last N: Quantum block size (e.g., 128 samples).
RT Prio: Operating system real-time thread priority (e.g., 85).
Overloads: Count of detected audio buffer overruns/underruns (xruns).
Flags: Atomic diagnostic bitmask status.

⚠️ Known Host Limitations & DAW Compatibility

DAW / Host Environment	Status	Compatibility Notes
Bitwig Studio (Linux)	✅ Full Support	Native X11 embedded GUI (default) with X11/Wayland floating fallback, sample-accurate automation, state save/restore, and offline bounce.
REAPER (Native Linux)	✅ Full Support	Native X11 embedded GUI (default) with X11/Wayland floating fallback, parameter automation, and ultra-low latency playback.
PreSonus Studio One / Fender Studio Pro (Linux)	⚠️ Known GUI Limitation	Known issue: the host cannot initialize a natively embedded X11 GUI surface. NAM-Plug serves X11 floating and Wayland floating (`CLAP_WINDOW_API_X11`/`CLAP_WINDOW_API_WAYLAND` with `is_floating = true`), opening its own top-level window with bounded teardown joins.

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

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

Script	Purpose & Execution Scope
`utils/lints.sh`	Static Analysis Gate: Runs `cargo fmt`, compilation checks (`cargo check`), strict `cargo clippy` across feature combinations (`--all-features`, `--no-default-features`), validates SPDX license headers, and checks anti-patterns.
`utils/tests-quick.sh`	Consolidated QA Suite: Executes unit tests, host-harness tests, CLAP compliance checks (debug + release), and the RT-safety heap-audit gate (`--features testing,heap-audit`).
`utils/build-release.sh`	Compiler Optimization Pipeline: Multi-stage release builder using PGO and LLVM BOLT, outputting assembly report `target/dsp_hotpath.asm`, binary `~/.clap/nam_plug.clap`, and release archive `~/nam-plug-vx.y.z-linux-x86_64-v3.tar.zst`.

📚 Architectural & Technical Documentation

The following technical documents are maintained in the source repository:

Document	Primary Focus & Topic Coverage
`docs/architecture.md`	CLAP plugin architecture, SPSC GC thread model, Slint declarative GUI integration, lock-free state synchronization
`docs/testing.md`	Test suite layout, host-harness verification phases, CLAP test policies, and test coverage matrix
`docs/functional-tests.md`	Plugin functional test checklist and verification matrices
`docs/postmortem-libm-symbol-interposition.md`	Technical postmortem on libm symbol interposition resolution on Linux dynamic linkers
`docs/rt-hardening-evaluation.md`	Formal architectural evaluation of `rt-hardening` for CLAP plugins (E.5 / S6-T5) — decision: not activated in plugin, delegated to host
`NeuralAmpModeler-rs: Audio Fidelity Map`	DSP decision quality trade-off matrix and frequency response analysis (NeuralAmpModeler-rs engine)

🙏 Credits & Acknowledgments

Steven Atkinson — Creator of Neural Amp Modeler (NAM) for pioneering deep learning guitar amplifier modeling.
Clack Framework & CLAP Community — For providing the Rust clack library and creating the open, modern CLever Audio Plug-in standard.
Slint Team & Community — For the declarative GUI framework and high-performance FemtoVG/OpenGL renderer.

⚖️ License & AI Transparency

AI Transparency Note

The system architecture, real-time safety guarantees, CLAP state management, DSP pipeline design, and GUI implementation are intellectual work (and love) of the maintainer (Fábio Lima). Implementation was accelerated through pair programming (Vibe Coding) using artificial intelligence models (Gemini, Claude, Grok, DeepSeek and others) within Google Antigravity IDE. IA is just a tool that make wonder in wise hands.

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE.txt for full license details.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
benches		benches
docs		docs
examples		examples
packaging/flatpak		packaging/flatpak
src		src
tests		tests
utils		utils
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE.txt		LICENSE.txt
README.md		README.md
build.rs		build.rs
rust-toolchain.toml		rust-toolchain.toml

Navigation Menu

Repository files navigation

NAM-Plug

🎨 Visual Overview & GUI Showcase

⚡ Key Strengths & Architectural Highlights

🥊 Feature Showcase ("Roofshoot")

🛠️ System Prerequisites

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

🚀 Building & Installation

1. Direct Shared Library Build (`cargo build`)

2. Mega-Optimized Compiler Build (`./utils/build-release.sh`)

What `build-release.sh` does under the hood

CLI Options

3. Flatpak Plugin Extension Distribution (`.flatpak`)

End-User Installation

How DAW Discovery Works in Flatpak

Developer Workflow (Building & Testing Flatpak Locally)

Uninstallation

🎛️ DAW Usage & Workflow Guide

1. Host Scanning & Loading

2. Loading Models & Cabinet IRs

3. Staging & Performance Tuning

4. Telemetry Footer Monitoring

⚠️ Known Host Limitations & DAW Compatibility

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

📚 Architectural & Technical Documentation

🙏 Credits & Acknowledgments

⚖️ License & AI Transparency

AI Transparency Note

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NAM-Plug

🎨 Visual Overview & GUI Showcase

⚡ Key Strengths & Architectural Highlights

🥊 Feature Showcase ("Roofshoot")

🛠️ System Prerequisites

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

🚀 Building & Installation

1. Direct Shared Library Build (cargo build)

2. Mega-Optimized Compiler Build (./utils/build-release.sh)

What build-release.sh does under the hood

CLI Options

3. Flatpak Plugin Extension Distribution (.flatpak)

End-User Installation

How DAW Discovery Works in Flatpak

Developer Workflow (Building & Testing Flatpak Locally)

Uninstallation

🎛️ DAW Usage & Workflow Guide

1. Host Scanning & Loading

2. Loading Models & Cabinet IRs

3. Staging & Performance Tuning

4. Telemetry Footer Monitoring

⚠️ Known Host Limitations & DAW Compatibility

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

📚 Architectural & Technical Documentation

🙏 Credits & Acknowledgments

⚖️ License & AI Transparency

AI Transparency Note

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

1. Direct Shared Library Build (`cargo build`)

2. Mega-Optimized Compiler Build (`./utils/build-release.sh`)

What `build-release.sh` does under the hood

3. Flatpak Plugin Extension Distribution (`.flatpak`)

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