NAMFORUM Sysop: Created page

2026-09-01T06:00:40Z

Created page

New page

= 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.

See [[Capture Types]].

== Official specification ==

The authoritative technical specification for the NAM model file format is maintained in the official Neural Amp Modeler documentation:

https://neural-amp-modeler.readthedocs.io/en/latest/model-file.html

Because NAM is under active development, developers implementing NAM file support should consult the current specification rather than relying solely on secondary documentation.

== See also ==

* [[Neural Amp Modeler]]
* [[Training a NAM Model]]
* [[NAM A2 Architecture]]
* [[NAM Playback]]
* [[Gain Staging and Calibration]]
* [[Capture Types]]
* [[Troubleshooting Captures]]
* [[Glossary]]

'''[https://namforum.com/ Discuss NAM models and file compatibility on NAMFORUM]'''

[[Category:Neural Amp Modeler]]
[[Category:Model formats]]
[[Category:Capture technology]]

NAM Model File Format - Revision history

NAMFORUM Sysop: Created page