commit 66c052b3e57169dc0e107e069f00cf987467db40
parent cb100787af4b16764ac94a2edf9bcf7dc5ae59a7
Author: Steven Atkinson <[email protected]>
Date: Sat, 6 Jul 2024 20:11:33 -0500
Documentation on the `.nam` file format (#439)
* Add doc page for model file change log
* More info
Diffstat:
2 files changed, 74 insertions(+), 0 deletions(-)
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,3 +15,4 @@ Contents
installation
tutorials/main
api
+ model-file
diff --git a/docs/source/model-file.rst b/docs/source/model-file.rst
@@ -0,0 +1,73 @@
+``.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``
+ `here <https://github.com/sdatkinson/neural-amp-modeler/blob/cb100787af4b16764ac94a2edf9bcf7dc5ae59a7/nam/models/wavenet.py#L428>`_
+ and ``LSTM``
+ `here <https://github.com/sdatkinson/neural-amp-modeler/blob/cb100787af4b16764ac94a2edf9bcf7dc5ae59a7/nam/models/recurrent.py#L317>`_.)
+
+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.*)
+
+
+Change log
+----------
+
+v0.5
+^^^^
+
+v0.5.3
+""""""
+
+Introduced in ``neural-amp-modeler`` `version 0.9.0 <https://github.com/sdatkinson/neural-amp-modeler/releases/tag/v0.9.0>`_.
+
+* Add ``"training"`` field under ``"metadata"`` whose contents follow the
+ ``TrainingMetadata``
+ `Pydantic model <https://github.com/sdatkinson/neural-amp-modeler/blob/cb100787af4b16764ac94a2edf9bcf7dc5ae59a7/nam/train/metadata.py#L84>`_. (`#420 <https://github.com/sdatkinson/neural-amp-modeler/pull/420>`_)
+
+v0.5.2
+""""""
+
+Version corresponding to ``neural-amp-modeler``
+`version 0.5.2 <https://github.com/sdatkinson/neural-amp-modeler/releases/tag/v0.5.2>`_.
+TODO more info.
