# Room acoustics and neural models

> Prepare room responses and use the toolkit’s bounded NAM inference components.

Canonical: https://maru.audio/docs/dsp-acoustics-and-models
Documentation index: https://maru.audio/llms.txt

The toolkit also includes room-response construction and bounded neural amp
inference. These use more preparation than a simple sample tick. Keep model
inspection, geometry, asset loading and preparation separate from the work
that must meet each audio deadline.

## Build and play a room response

The room pipeline starts with dimensions, source/microphone placement,
materials and directivity. The image-source and ray-energy stages construct
early/late response data; octave weighting and response assembly prepare an IR.
The room convolver plays that prepared IR while the next response is built.

`shoebox-ism`, `ray-tracer`, `rir-assembly`, `rt-tail` and `rir-analysis` expose
bounded or resumable work. Schedule that work with the caller’s budget instead
of running a full rebuild in a single audio callback. `room-convolver` uses
prepared two-stage convolution and a 50 ms equal-power IR transition; its
response capacity is three seconds and two microphone channels.

Use material/physics helpers to keep units consistent. `rt60` offers both
theory and measured-decay fitting; an estimated decay from room parameters
is different from a fit to the resulting impulse response. Analytic directivity
is available; measured SOFA directivity is outside the listed helper contract.

## Prepare a neural amp model

`neural/nam-a2` supports standard A2 Lite (3 channels) and Full (8 channels)
causal networks. `nam-a2-spec` describes those topologies and weight counts;
`nam-a2-resource-spec` describes the numeric prepared-resource layout.
Model JSON inspection/packing belongs to the NAM resource tooling, outside the
DSP tick. Prepare and validate a candidate before replacing the active state.

Construction validates weights and the zero-input preparation path. An explicit
prewarm feeds the receptive field; reset clears histories while retaining the
prepared weights. Run inference at the model’s rate: this leaf does not resample.
The fixed A2 topology is a useful precise contract, rather than a promise of
arbitrary NAM architecture support. Qualify the full model, controls and host
for the product’s audio and realtime requirements.

## Toolkit reference

Import paths below are suffixes of `maruaudio/dsp/`. Use the exported types
and setters in your installed version for complete signatures and defaults.

### Acoustics

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `acoustics/vec3` | Caller-owned stride-3 vector arithmetic, normals, distances and normalization. | `vec3Set`, `vec3Copy` |
| `acoustics/rounding` | Half-to-even rounding and truncation toward zero for response construction. | `roundHalfEven`, `truncToward0` |
| `acoustics/geometry` | Bounded point, segment, plane and polygon operations for room geometry. | `clampLibroom`, `ccw3p` |
| `acoustics/physics` | Temperature/humidity-dependent sound speed, seven-band air absorption and explicit simulation constants. | `initPhysics`, `calculateSpeedOfSound` |
| `acoustics/rt60` | Sabine/Eyring decay estimates, inverse absorption targets and Schroeder-integral RT60 measurement over caller scratch. | `createRt60Measurement`, `rt60Sabine` |
| `acoustics/wall` | Prepared 3D polygon walls, normals, reflection and intersection queries. | `createWall`, `initWall3d` |
| `acoustics/directivity` | Analytic cardioid-family directivity, direction/angle conversion and Fibonacci-sphere sampling. Measured/SOFA patterns are outside this API. | `directivityParameter`, `directionVectorUnit` |
| `acoustics/materials` | Material lookup and octave-band interpolation of absorption/scattering coefficients; unknown names are rejected. | `createMaterialAbsorptionEntry`, `materialAbsorptionIndex` |
| `acoustics/materials-table` | Read-only absorption/scattering names, categories and octave-band coefficients used by material lookup. | `ACOUSTICS_MATERIALS_JSON_SHA256`, `ACOUSTICS_MATERIALS_CENTER_FREQS` |
| `acoustics/rir-builder` | Resumable fractional-delay impulse accumulation, windowed-sinc tables and zero-phase RIR high-pass filtering. | `initRirSincLut`, `rirBuilderAccumulate` |
| `acoustics/shoebox-ism` | Bounded, resumable shoebox image-source model with per-band attenuation and microphone directions. | `createShoeboxIsm`, `numberImageSources3` |
| `acoustics/octave-bands` | Antoni octave-band windows, spectral weighting/analysis/synthesis and truncated FIR application by overlap-add FFT. | `createOctaveBandLayout`, `octaveBandCount` |
| `acoustics/room-convolver` | Prepared stereo room-IR playback up to three seconds, two-stage convolution, budgeted IR swap and smoothed dry/wet. | `initRoomConvolver`, `processRoomConvolverBlock` |
| `acoustics/rir-assembly` | Budgeted restartable room-response assembly from image sources, fractional delays, octave weighting and high-pass filtering. | `createRirAssemblyParams`, `createRirAssembly` |
| `acoustics/ray-tracer` | Budgeted shoebox ray-energy histograms with absorption, scattering and receiver directivity. | `createRayTracerParams`, `createRayTracer` |
| `acoustics/rt-tail` | Seeded late-response generation from ray-energy histograms and octave-band weighting. | `createRtTail`, `beginRtTail` |
| `acoustics/rir-analysis` | Budgeted response display, Schroeder decay curve and broadband/per-band T30 measurements. | `createRirAnalysis`, `beginRirAnalysis` |

### Neural amp inference

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `neural/nam-a2` | Bounded standard NAM A2 Lite/Full causal WaveNet inference using the original learned weight stream. | `initNamA2`, `namA2Tick` |
| `neural/nam-a2-spec` | Lightweight standard NAM A2 topology, constants and weight-count contract for import validation. | `namA2WeightCount` |
| `neural/nam-a2-resource-spec` | Lightweight numerical prepared standard A2 resource layout shared by NAM pack writers and portable Processor readers. | `NAM_PACK_MAGIC`, `NAM_PACK_ABSENT` |

Return to [DSP fundamentals](https://maru.audio/docs/dsp-fundamentals.md) for I/O, lifecycle,
units and the category map.