Module implementation

How the built-in modules are implemented: DSP character and sources, real-time behavior, latency and tails. For controls, ranges and starting settings see the module guide; for the parameter contract see development.md.

Controls and state

Enabled uses a parameter-bound circle in the editor header, sharing the grid node's automation identity. Every module uses the same eight-position dial editor (see Shape a module). Each control is a host parameter per slot, described in EffectParameters.h; its editor position and per-module label are in EffectPresentation.h, whose layout rule (controls packed from the left, Output before Mix, modes in the header) is checked for every module by EffectPresentationTests.h. Starting settings live in SlotDefaults.h.

Modules of one family share their controls within a slot: the delays share Time, Feedback, High cut, Character, Modulation, Mix and Output; the classic modulation effects share Rate, Depth, Feedback, Character and Mix; Room, Dense Plate, Cloud and Hall share the reverb controls. Copy/Move/Swap transfers these values; the destination gets its own processor history.

DSP character and sources

• Delays (SlotTimeEffects.h) are original MIT implementations: fractional delay with bounded filtered feedback (0–82%), 5–4000 ms with a quadratic dial and 800–12000 Hz High cut. Time changes are smoothed and bend pitch. Analog Echo adds two-pole darkening and soft feedback saturation; Tape Echo adds saturation and wow/flutter; Digital Delay's Ducking lowers repeats beneath playing. Multi-head Tape feeds back only from the last head. Diffused Delay sends repeats through rotating allpasses.
• Reverbs: Room and Hall use Signalsmith-derived multistage diffusion and Householder networks with exact per-band decay; Dense Plate uses the Mutable Instruments Clouds Dattorro/Griesinger tank; Cloud is a rotating stereo allpass loop. Decay is nominal RT60, 0.15–30 s; Size 25–200%; Damping 800–12000 Hz; Pre-delay 0–200 ms; Low cut filters only the wet input. See reverb core adaptations.
• Cosmic Echo uses David Braun's MIT Faust reconstruction of the Valhalla Supermassive algorithms; see Cosmic Echo below and the player guide.
• Shimmer is an eight-line reverb with granular pitched feedback (±24 semitones); Freeze holds the tail and stops new input. Polyphonic pitch shifting and a harmonizer are not implemented.
• Juno Chorus is an original rate-scaled implementation informed by the Juno-60 BBD measurements of the MIT Junologue project: fixed 0.513/0.863 Hz triangle LFOs and a 1.66–5.35 ms delay. Frequency Shifter is a Bode-style single-sideband shifter (±2000 Hz) in a 0.05–1000 ms feedback delay with soft-saturated, bounded feedback.
• Distortion offers six original waveshapers with ±100% Bias, a 5 Hz DC blocker and 20 ms style crossfades. Tube Boost is an original biased soft saturator with Boost's Tilt/Low cut voicing. Neither oversamples, so bright, high-drive settings can alias.
• Pedal Drive (SlotPedalDrive.h, DSP) is an original set of voiced drives informed by documented pedal designs. It uses 4x FIR oversampling with 64 host samples of latency, aligned dry/bypass and local clean-low returns, independent stereo histories and 20 ms style crossfades. Its centered character parameter changes function/label by style; derived bias normalization is cached on the 16-sample control schedule. The FIR loops share input loads across interpolation phases and use independent decimation accumulators for portable vectorization. Settled styles use a single-voice path; only participating styles run during transitions; an inactive style starts with cleared filter history. See voices, signal flow and design references.
• EQs and Filter use the MIT AudioDSPTools coefficients and a scalar implementation of the RBJ/W3C equations. Dynamics were written independently, using AudioDSPTools and LEAF as MIT algorithm references.
• Spring Reverb has three dispersive tanks with driven excitation, after Gamper, Parker and Välimäki and the DAFx overview; no source implementation or calibration was copied.
• Wah follows Simper's trapezoidal SVF equations for its band-pass and body voicing, without third-party code.
• Airwindows modules (Tape, kPlate140, kGuitarHall2, Galactic3, CStrip2, BussColors4, ButterComp2, DigitalBlack) are native ports of MIT Airwindows source reviewed at b79c7a3f9053f408f38f740bef56ca3291a09ad4, with licenses beside the code and in shipped notices. Changes remove the VST2 SDK, use an explicit sample rate, seed random state deterministically and add smoothed wrapper Mix/Output controls. Native intensity and size controls are not presented as calibrated units. See Airwindows outboard and dynamics.

Timing scales with the host rate; nothing is forced to 44.1 kHz. Pedal Drive oversamples its driven path; the other built-in effects run at the host rate. Built-in effects keep independent left/right histories. A mono NAM stage downmixes once and broadcasts its result, so stereo effects belong after the last mono capture.

Noise Gate (Smart)

The spectral gate learns a per-band noise print during Learn and applies stereo-linked band gains, so the image does not wobble. A confidence guard relaxes suppression on strong notes and returns to the learned profile for quiet playing. Learning transitions to dry over 5 ms and opens the final gate; digital silence and captures shorter than about 300 ms do not replace an existing valid print, and during a new capture the last completed print remains the recallable snapshot. Very large or invalid samples are bounded so they cannot poison the filter histories.

The optional final broadband gate works independently of the spectral profile, also without learning. It detects the original input's maximum L/R peak (so either channel, including anti-phase input, can open it), applies one linked gain after the spectral mix, and closes linearly to exact zero over Release after a 20 ms hold, with a fixed 0.5 ms opening ramp, 5 ms peak-detector decay and 3 dB hysteresis. An enabled gate starts closed after reset or recall to avoid an initial noise burst; turning it Off reopens it over 0.5 ms. The GR readout estimates band gain plus gate attenuation, capped at 120 dB.

With Gate Off, untrained, settled Mix 0 and Reduction 0 pass the exact finite input. Completed snapshots survive project recall, rig-preset save/load and Copy/Move/Swap; Learn is saved off, suppressed on rig-preset load and excluded from scenes. Reset preserves the completed print but clears envelopes and histories. Profiles from older builds that this version cannot read are rejected without affecting the current sound.

LoFi Tape Machine

An original transport and degradation effect, not a measured cassette/deck emulation or a magnetic-hysteresis model; no Dusk/CHOWTape DSP is copied. The transport is a 10 ms wet delay modulated by up to 5 ms of wow and 0.35 ms of flutter. Both channels share the transport and dropout envelope; their audio histories and hiss are independent. With Noise off, a centered mono input stays mono with no crossfeed. Slower Speed changes bandwidth and modulation rate rather than performing a lasting playback-speed pitch shift.

The transport display derives pitch from changes in each read-head delay, so automation and the irregular wow component are represented. History is captured at 100 Hz into fixed storage on the audio thread and delivered through the meter queue; no UI timer invents movement when audio is stopped. The two components are shown separately, before Mix.

Cosmic Echo

Style	Topology
Gemini	Sixteen scattering delays
Sagittarius	Eight serial stereo allpasses
Virgo	Sparse delays with both cuts inside the feedback loop
Centaurus	Four serial four-channel allpasses
Great Annihilator	A delay stage and three matrix allpasses in global feedback
Lyra	Four scattering delays, filters at the output

Warp, Density, Feedback and modulation keep the source model's per-topology interactions. Time uses a quadratic dial; Time/Warp automation moves allpass-interpolated reads and can bend the sounding tail. Style changes fade and clear the old tail. The display is rendered by a private copy of the DSP whenever a setting changes: a measured impulse response, not an RT60 estimate. See the Faust reference.

Capture effects

Freeze's Capture is the source window. It repeats every Capture minus the effective Crossfade, bounded to a quarter of the window: 500 ms Capture and 20 ms Crossfade repeat every 480 ms. Stutter keeps the requested Window period and fades through zero even at 100% Gate length. Reverse Delay replaces its window each period with a short transition. Captured audio is transient and never saved in presets.

Cabinet IR

A mono WAV loads through NAM's IR loader and the adaptive convolver, which switches between direct and FFT convolution with zero added latency. Output 0 dB gives unity gain for a unit impulse at the IR's native rate; the -18 dB default is the upstream NAM cabinet headroom convention. IRs are not normalized. WAV parsing, resampling, history allocation and prewarming happen off the audio thread; an invalid load keeps the current selection, and a missing file keeps its path for relinking while the slot passes audio.

A2 Full / Lite

Captures that Core reports as slimmable offer A2 Lite. Changing the size reloads and prepares the model outside the audio thread and switches through the slot's normal fade, as the Core size API is not real-time safe. Every slot's Full Quality parameter stores the choice; requests from the editor or host automation apply on the idle thread and may coalesce. Fixed-size captures have no Lite mode.

Real-time behavior, latency and tails

Preparation, allocation and destruction happen outside the audio callback through the prepared-slot exchange. Audio uses fixed storage, smoothed controls and bounded feedback. 5 ms fades cover bypass and replacement. Delay, reverb and modulation histories drain with silence after bypass and then suspend: a muted delay stops writing feedback and clears its 8.1-second buffer in about nine seconds, reverbs drain for 30 seconds, modulation for 70 ms. No callback clears a whole delay ring at once.

Built-in effects have no block buffering. Pedal Drive reports 64 host samples for its oversampling filters and aligns its dry, clean-low and bypass paths; other built-in effects report zero host compensation latency. Delay, reverb and vibrato (8 ms center delay) delay the effected signal on purpose; that effect time is not compensated. NAM sample-rate conversion reports its own latency, and parallel lanes are aligned to the longer one. Host tail reporting follows serial and parallel placement but caps the automatic tail at 60 seconds for the whole plugin; very long synced echoes at high feedback can ring past it, so render a longer range for those.

Tests cover 44.1–192 kHz, variable blocks down to one frame, parameter extremes, finite output, block-size independence, zero audio-thread allocation, echo timing, reverb decay, bypass draining and reset, and project recall and editor gestures for every module in the native editor. See build.md for the commands. Listening and host validation are tracked in the release checklist.

Audition renders

The nam-fx-audition target renders one .ngrid preset and paired WAVs per effect style, plus measurements.csv, for example:

cmake --build build-grid --config Release --target nam-grid-clap nam-fx-audition
& .\build-grid\NeuralAmpModeler\nam-fx-audition.exe .\build-grid\out\nam-grid.clap .\tmp\cosmic-audition cosmic

Output goes to the directory passed to the exporter; tmp/ is gitignored. These renders are generated developer artifacts: they are not checked in or copied into release archives.