NAM Model File Format

The NAM model file format is the file format used to store trained Neural Amp Modeler models.

NAM model files normally use the:

.nam

file extension.

A .nam file contains the information required by compatible NAM software or hardware to reconstruct and run the trained neural-network model. It can also contain metadata describing the model, the equipment that was modeled, training information, and capture calibration.

File structure

The current NAM file format can be parsed as JSON.

At the highest level, a NAM file contains a dictionary of fields describing the model.

Core fields include:

version
architecture
config
weights

Optional fields include:

sample_rate
metadata

The exact contents of some fields depend on the architecture of the model.

Version

The version field identifies the version of the NAM file specification.

The version follows semantic versioning.

This allows playback implementations to determine how the contents of a NAM file should be interpreted as the format evolves.

Architecture

The architecture field identifies the high-level neural-network architecture used by the model.

Historically, common values have included architectures such as:

WaveNet
LSTM

Other architectures supported by the NAM code can also be represented.

The architecture is important because the configuration and weights must be interpreted according to the model architecture that created them.

See NAM A2 Architecture.

Config

The config field contains architecture-specific configuration information.

Depending on the architecture, this can describe characteristics such as:

Layer configuration
Channel configuration
Receptive-field structure
Other parameters required to reconstruct the model

The meaning of the configuration data therefore depends on the architecture specified in the file.

Weights

The weights field contains the trained numerical parameters of the neural network.

These values are the result of the training process.

During playback, the NAM implementation reconstructs the appropriate model architecture and loads these trained parameters into it.

The relationship between individual weights and the model depends on the architecture.

Sample rate

A NAM file can contain a sample_rate field specifying the sample rate expected by the model.

The value is expressed in samples per second (Hz).

If the field is absent, the NAM specification states that implementations should generally assume 48 kHz.

Playback software or hardware must account appropriately for the sample rate expected by the model.

Metadata

NAM files can contain a metadata dictionary with descriptive information about the model.

Metadata is not merely cosmetic. Good metadata can make large model libraries substantially easier to identify, organize, search, and use correctly.

Supported metadata can include information about:

Model name
Creator
Modeled equipment
Tone
Training
Calibration
Export date

Not every NAM file contains all available metadata.

Model name

The metadata field:

name

can contain the name of the model.

Compatible playback software may use this as the model's displayed name rather than relying entirely on the filename.

Model creator

The:

modeled_by

field identifies the person or organization that created the model.

This can be useful when models are redistributed or downloaded independently of the collection in which they were originally published.

Equipment metadata

NAM supports several fields describing the equipment represented by the model.

These include:

gear_make

The manufacturer or make of the equipment.

gear_model

The model of the equipment.

gear_type

The type of equipment or signal chain represented by the NAM.

The current specification defines gear-type values including:

amp
pedal
pedal_amp
amp_cab
amp_pedal_cab
preamp
studio

These fields help answer an important playback question:

What is actually contained in this model?

See Capture Types.

Tone type

The metadata field:

tone_type

can classify the general character of the model.

The current NAM specification defines values including:

clean
overdrive
crunch
hi_gain
fuzz

This provides a standardized way for model-management systems to organize captures according to their general sound.

Training metadata

Models created with the simplified NAM trainers can contain a:

training

metadata dictionary.

This allows information about the training process to travel with the resulting model rather than being stored only in an external description.

The exact training metadata may evolve as NAM development continues.

Calibration metadata

NAM supports two particularly important calibration fields:

input_level_dbu

and:

output_level_dbu

These allow the model file to describe the analog level relationships used during capture.

input_level_dbu

input_level_dbu represents the analog level, expressed in dBu, presented to the modeled equipment when a 1 kHz digital sine wave has a peak level of 0 dBFS.

This provides a reference between the digital signal and the electrical input level used during the capture.

output_level_dbu

output_level_dbu represents the analog level, expressed in dBu, of a 1 kHz sine wave that produces a 0 dBFS peak when fed into the recording interface used for the output of the modeled equipment.

Together, these values can allow compatible systems to preserve meaningful gain relationships between capture and playback.

See Gain Staging and Calibration.

Why calibration metadata matters

Consider two people using different audio interfaces.

The same digital signal might produce different analog voltages from the two interfaces.

Without calibration information, both users can load the same NAM model but drive it at different effective analog-equivalent levels.

With appropriate calibration metadata and compatible playback equipment, the intended gain relationship can be reproduced more accurately.

This is particularly important with nonlinear equipment because changing the effective input level can change:

Distortion
Saturation
Compression
Attack
Dynamic response

Calibration therefore affects behavior, not merely volume.

Metadata is optional

A NAM model does not need complete metadata in order to function.

Many existing NAM files contain little descriptive information beyond the data required to run the model.

However, models intended for public distribution are considerably more useful when they include or are accompanied by meaningful documentation.

Useful information includes:

Equipment modeled
Equipment settings
Cabinet status
Capture method
Creator
Calibration
Model architecture
Training information

A filename alone is rarely sufficient documentation for a long-lived public model library.

Sequential models

The NAM specification also supports Sequential models.

A Sequential model combines complete child NAM models in processing order.

Each child model contains its own:

Architecture
Configuration
Weights

The wrapper itself contains the ordered collection of child models.

This makes it possible for the NAM format to describe a processing chain composed of multiple NAM-compatible model elements rather than only a single model.

The sample rates of the top-level Sequential model and its child models must agree.

Portability

One of the important characteristics of the NAM ecosystem is that the model file is separate from the system that created it.

A .nam file can potentially be:

Trained by one system
Stored by another service
Distributed through a model library
Loaded into multiple software players
Loaded into compatible hardware

The model is therefore not inherently tied to the computer or service that performed the training.

Actual compatibility still depends on whether the playback implementation supports the architecture and file-format version used by the model.

Forward compatibility

NAM continues to develop.

New architectures, metadata fields, and file-format capabilities can be introduced over time.

A NAM player that predates a particular architecture may be able to recognize the file but still be unable to execute the model.

For this reason, when a model fails to load, check:

Model architecture
NAM file version
Playback software version
Hardware firmware version

before assuming the file itself is corrupt.

Editing NAM files

Because the current NAM format is JSON-parsable, portions of a NAM file can technically be inspected using tools capable of reading JSON.

However, users should not casually modify model configuration or weight data.

Changing architecture-specific data without understanding its meaning can make the model invalid or alter its behavior.

Metadata is a more appropriate area for tools specifically designed to manage or update descriptive information.

Always preserve an original copy before manually modifying a model file.

File extension and filenames

The .nam extension identifies the file as a Neural Amp Modeler model.

The filename itself is not a reliable description of what the model contains.

For example, a file named after an amplifier could represent:

Amplifier only
Amplifier and cabinet
Pedal and amplifier
Amplifier, cabinet, and microphone
A larger signal chain

Consult metadata and creator documentation whenever possible.