.nam file specification and change log

The current specification

.nam files are currently able to be parsed as JSON files. The outermost data structure is a dictionary.

There are a few keys you should expect to find with the following values:

• "version": A string stating the version of the file. It follows semantic versioning.

• "architecture": The high-level architecture of the model (usually either “WaveNet” or “LSTM”, though any string corresponding to a model class name defined in the nam package is valid. Also, if you’ve made a new architecture, you would give it a new name here. The convention is to use the class name.)

• "config": A dictionary architecture-specific details (e.g. number of layers, etc).

• "weights": a list of float-type numbers that are the weights (parameters) of the model. How they map into the model is architecture-specific. Looking at ._export_weights() will usually tell you what you need to know (e.g. for WaveNet at wavenet.py and LSTM at recurrent.py.)

There are also some optional keys that nam may use:

• "sample_rate": The (possibly non-integer) sample rate of the data that the model expects to see, in samples/sec (Hz) If not present, one should generally assume the sample rate was 48kHz.

• "metadata": A dictionary with key-value pairs of information about the model. The following may be used by this package:

  • "date": a dictionary with the "year", "month", "day", "hour", "minute", and "second" at which the model was exported (all integer-type).

  • "name": The name of the model (could be used as the display name by plugins.)

  • "modeled_by": Who made the model

  • "gear_make": Make of the gear (E.g. Fender)

  • "gear_model": Model of the gear (E.g. Deluxe Reverb)

  • "gear_type": What kind of gear this is a model of. Options are "amp", "pedal", "pedal_amp", "amp_cab", "amp_pedal_cab", "preamp", and "studio".

  • "tone_type": How the model sounds. Options are "clean", "overdrive", "crunch", "hi_gain", and "fuzz".

  • "training": A dictionary containing information about training (Only when the simplified trainers are used.)

  • "input_level_dbu": The level being input to the gear, in dBu, corresponding to a 1kHz sine wave with 0dBFS peak.

  • "output_level_dbu": The level, in dBu, of a 1kHz sine wave that achieves 0dBFS peak when input to the interface that’s recording the output of the gear being modeled.

Sequential models

"Sequential" models compose complete child NAM models in processing order. They use the existing file version and top-level envelope. The wrapper has an empty "weights" array because its parameters belong to its children:

{
  "version": "0.7.0",
  "architecture": "Sequential",
  "config": {
    "models": [
      {"version": "0.7.0", "architecture": "WaveNet", "config": {}, "weights": [], "sample_rate": 48000},
      {"version": "0.7.0", "architecture": "Linear", "config": {}, "weights": [], "sample_rate": 48000}
    ]
  },
  "weights": [],
  "sample_rate": 48000
}

Every entry in config.models is a complete NAM model with its own architecture, configuration, and weights. The top-level and child sample rates must agree.

Sequential files exported before Core support was completed used bare child configs and concatenated top-level weights. Because those files omitted the child architectures, they cannot be interpreted reliably and are not supported by this canonical format.

Change log

v0.5

v0.5.4

Introduced in neural-amp-modeler version 0.10.0.

• Add "input_level_dbu" and "output_level_dbu" fields under "metadata".

v0.5.3

Introduced in neural-amp-modeler version 0.9.0.

• Add "training" field under "metadata" whose contents follow the TrainingMetadata Pydantic model. (#420)

v0.5.2

Version corresponding to neural-amp-modeler version 0.5.2. TODO more info.