commit 27667893d588d0021554e913b437c1039e901f28
parent 64eb2538dbf9e57d324448f224c66c7fac918efb
Author: Steven Atkinson <[email protected]>
Date: Sun, 6 Oct 2024 16:44:56 -0700
[DOCUMENTATION] How to determine calibration levels (#482)
* Start writing calibration documentation
* Finish calibration doc
* Proofreading
* Fix table
* Remove youtube-input-level.png
Diffstat:
10 files changed, 298 insertions(+), 2 deletions(-)
diff --git a/docs/source/model-file.rst b/docs/source/model-file.rst
@@ -1,3 +1,5 @@
+.. _nam-file-spec:
+
``.nam`` file specification and change log
==========================================
diff --git a/docs/source/tutorials/calibration.rst b/docs/source/tutorials/calibration.rst
@@ -0,0 +1,293 @@
+How to determine the calibration levels of your recording setup
+===============================================================
+
+Background
+----------
+
+With the arrival of highly-accurate modeling technologies like NAM, there's been
+an interest in ensuring that the gain staging of the signal entering and leaving
+models is accurate *in the digital realm* to what one would experience when
+plugging into the source analog gear.
+
+As of version 0.10.0, :ref:`the NAM file spec<nam-file-spec>` defines a pair of
+metadata fields, ``"input_level_dbu"`` and ``"output_level_dbu"``, that document
+the relationship between the *digital* and *analog* signal strengths.
+Specifically, these fields record the *analog* signal strength (in dBu) that
+corresponds to the loudest signal that can be represented *digitally*. With
+these two values recorded, one can calibrate the gain staging of the digital
+models to accurately reflect the behavior of the source in its native analog
+realm.
+
+This tutorial explains how to take the measurements to fill in these metadata.
+
+Notes
+-----
+
+A few things before we begin:
+
+* **As with all metadata, providing calibration levels is optional.** If you
+ don't want to do this, you can leave them blank. The models will still work in
+ any plug-in that supports playing NAMs, but the gain-staging may not be
+ accurate to the source gear.
+* **Pay attention to what's in front of your model.** If you are using a model
+ with a calibrated input level, that level will *only* be correct if either (A)
+ there are no effects in front of it, or (B) any preceding effects' *input and
+ output* calibration levels are known and accounted for. This is possible to do
+ automatically within a single plug-in, but if there is *another* plug-in in
+ front of your NAM whose calibration is not known, then all bets are off!
+* **You can still use your ears!** Before getting too deep into this, remember
+ that we're trying to make music. Don't let the "correct" answer get in the way
+ of making the music you *want* to make!
+
+Tools needed
+------------
+
+In addition to your reamping gear (interface, reamp box, DI box, load
+box/microphone, cables), you're going to need to know how loud things are. In
+the *digital* realm, the meters in your DAW tell you what you need to know; for
+the *analog* electrical signal, you will need a
+`multimeter <https://en.wikipedia.org/wiki/Multimeter>`_.
+
+Procedure
+---------
+
+First, set up your gear as you would normally for reamping:
+
+* Mute the inputs to your interface in your DAW.
+* Connect the output of your interface to the input of your gear via the reamp
+ box.
+* Connect the output from your gear (or load box, or microphone) to the input of
+ your interface.
+* Turn the output from your interface to its maximum value.
+* Begin reamping and set the gain on the return input to your interface so that
+ no clipping occurs.
+
+.. image:: media/calibration/reamp-setup.jpg
+ :scale: 15 %
+ :align: center
+
+*Figure: Example reamping setup. The output from the Focusrite Solo passes
+through the reamp box into the input of the amp. The (effects loop!) send from
+the amp is returned to the recording input of the interface.*
+
+.. note:: My advice is to **set the reamping send level as high as your gear
+ will allow.** If it's too low, then the model won't see any examples of the
+ gear distorting under a very hot signal and may not predict it accurately. You
+ don't need to worry if it's exactly accurate to how loud a guitar is--that's
+ the purpose of calibration--what's important is that the model has trained on
+ examples that are at least as loud as (preferably even louder than!) how the
+ model will be used in practice.
+
+Go ahead and reamp your gear to get the data for your model. **So long as you're
+happy with your send level and the return doesn't clip, you're good.**
+
+From this point onwards, **do not change any hardware gain levels**. You already
+recorded your data; if you make any changes, your calibration measurements won't
+correspond to your data.
+
+Next, measure the send level. To do this, play a sine wave with 1kHz frequency
+and 0dBFS peak amplitude. Some plug-ins can do tone generation, or else you can
+just loop this 1-second file:
+`sine 1k.wav <https://drive.google.com/file/d/18y53y4yi_QEUundLlBZsjdY_OeytC6y1/view?usp=drive_link>`_.
+Unplug your cable from the gear you are reamping and measure the RMS voltage
+across its tip and sleeve.
+
+.. image:: media/calibration/voltage.jpg
+ :scale: 15 %
+ :align: center
+
+*Figure: Measuring the level of the jack that was plugged into the input of the
+amp. I measure 6.40 Volts RMS.*
+
+Convert the RMS voltage to dBu using the formula:
+
+.. math::
+
+ \text{dBu} = 20 \times \log_{10}\left(\frac{V_{\text{RMS}}}{0.7746}\right)
+
+Alternatively, the bottom of this page has a table of pre-computed values you
+can reference.
+
+*Example: In the picture above, I measured 6.40 V. This corresponds to 18.3 dBu.*
+
+Next, measure the return level. To do this, start by connecting the send from
+your interface directly to the return you used for recording. Remember, **do not
+change any hardware gain levels** or else you're going to have a different
+calibration from how you recorded your data!
+
+.. image:: media/calibration/reamp-setup-no-amp.jpg
+ :scale: 15 %
+ :align: center
+
+*Figure: My reamping setup, with the send plugged directly back into the
+return.*
+
+Play the sine tone, and note the return level (in dBFS) in your DAW:
+
+.. image:: media/calibration/sine-tone.png
+ :scale: 30 %
+ :align: center
+
+*Figure: Monitoring the return level. The "send" track is outputting a 1 kHz
+sine tone at 0 dBFS. The return track is clipping.*
+
+You may find that your send signal is so loud that it clips the return, like
+above. *This is not a problem.* If this happens, reduce the level of the sine
+tone in the DAW until the return doesn't clip *(You should do not change the
+``input.wav`` file as well. In fact, hopefully you already reamped so that
+you're not tempted!)*
+
+.. image:: media/calibration/sine-tone-level-reduced.png
+ :scale: 30 %
+ :align: center
+
+*Figure: Monitoring the return level. The "send" track is outputting a 1 kHz
+sine tone at -6.50 dBFS. The return track is measuring -0.5 dBFS.*
+
+Note the return level (-0.5 dBFS above) and the amount by which you reduced the
+sine tone's level (-6.50 dB).
+
+To compute the return level, remember: what we are trying to do is figure out
+how loud an analog signal is (in dBu) that barely clips the return on our
+interface (i.e. achieves 0 dBFS). We know the analog level of the sine tone (at
+full volume, i.e. 0 dBFS) from above, so the formula to compute your return
+level calibration, in dBu, is:
+
+.. math::
+
+ \text{dBu}_{return} = \text{dBu}_{send} - \Delta + L,
+
+where Δ is the amount by which you reduced the sine tone's level, and *L* is the
+return level.
+
+For example, using the numbers above, I get *18.3 - 6.50 + 0.5 = 12.3 dBu*.
+
+Careful: The return level calibration may not be what you think it is
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of this writing (October 2024), some users are likely familiar with a
+manufacturer-provided calibration level for their interface's inputs. For
+example, the maximum input level for the instrument inputs on the 4th-generation
+Focusrite Scarlett 18i20 is listed in its manual as 12 dBu:
+
+.. image:: media/calibration/scarlett-instrument-input-doc.png
+ :align: center
+ :scale: 50 %
+
+*Figure: Instrument input specifications, from the manual for the*
+`Focusrite Scarlett 18i20 4th Generation <https://downloads.focusrite.com/focusrite/scarlett-4th-gen/scarlett-18i20-4th-gen>`_
+*.*
+
+This is specifically for when the interface is set to **minimum gain**; if you
+adjust (increase) the gain when recording to get a bigger waveform when
+recording, then this will *reduce* the dBu at which clipping happens. **If you
+record with your gain all the way down**, then you can use the manufacturer's
+specification; but if not, then you should calculate it as above. (You may also
+find that if you compute measure it yourself, the calibration for your own
+interface's inputs may be slightly different from the manufacturer's spec.)
+
+Providing the calibration in the metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once you've figure out the calibration levels for your recording, you can
+provide them as metadata when making your model. Using the numbers from above, I
+would write this:
+
+.. image:: media/calibration/metadata-gui.png
+ :align: center
+ :scale: 50 %
+
+*Figure: Metadata for the local GUI-based trainer.*
+
+A note on updating old model files
+----------------------------------
+
+If you know the levels from a model that you made previously, you can update
+old files to include this metadata. ``.nam`` files conform to the JSON file
+format and can be edited as plain text. If you want to do this, you can make a
+new model and use it as a reference for how to add the new metadata fields to
+your old files. Look for the fields ``"input_level_dbu"`` and
+``"output_level_dbu"`` in the new file and copy them to your old file in the
+corresponding location, changing the numbers as necessary. (If you only know
+one, then you can leave the other as `null`.) As always, it's recommended to
+save a backup of your file before you being editing it in case you make a
+mistake.
+
+Appendix: Conversion table between RMS voltage and dBu
+------------------------------------------------------
+
++-----------------+-----------------+
+| RMS Voltage (V) | dBu |
++=================+=================+
+| 0.8 | 0.0 |
++-----------------+-----------------+
+| 0.9 | 1.0 |
++-----------------+-----------------+
+| 1.0 | 2.0 |
++-----------------+-----------------+
+| 1.1 | 3.0 |
++-----------------+-----------------+
+| 1.2 | 4.0 |
++-----------------+-----------------+
+| 1.3 | 4.5 |
++-----------------+-----------------+
+| 1.4 | 5.0 |
++-----------------+-----------------+
+| 1.5 | 6.0 |
++-----------------+-----------------+
+| 1.6 | 6.5 |
++-----------------+-----------------+
+| 1.7 | 7.0 |
++-----------------+-----------------+
+| 1.8 | 7.5 |
++-----------------+-----------------+
+| 1.9 | 8.0 |
++-----------------+-----------------+
+| 2.1 | 8.5 |
++-----------------+-----------------+
+| 2.2 | 9.0 |
++-----------------+-----------------+
+| 2.3 | 9.5 |
++-----------------+-----------------+
+| 2.4 | 10.0 |
++-----------------+-----------------+
+| 2.6 | 10.5 |
++-----------------+-----------------+
+| 2.7 | 11.0 |
++-----------------+-----------------+
+| 2.9 | 11.5 |
++-----------------+-----------------+
+| 3.1 | 12.0 |
++-----------------+-----------------+
+| 3.3 | 12.5 |
++-----------------+-----------------+
+| 3.5 | 13.0 |
++-----------------+-----------------+
+| 3.7 | 13.5 |
++-----------------+-----------------+
+| 3.9 | 14.0 |
++-----------------+-----------------+
+| 4.1 | 14.5 |
++-----------------+-----------------+
+| 4.4 | 15.0 |
++-----------------+-----------------+
+| 4.6 | 15.5 |
++-----------------+-----------------+
+| 4.9 | 16.0 |
++-----------------+-----------------+
+| 5.2 | 16.5 |
++-----------------+-----------------+
+| 5.5 | 17.0 |
++-----------------+-----------------+
+| 5.8 | 17.5 |
++-----------------+-----------------+
+| 6.2 | 18.0 |
++-----------------+-----------------+
+| 6.5 | 18.5 |
++-----------------+-----------------+
+| 6.9 | 19.0 |
++-----------------+-----------------+
+| 7.3 | 19.5 |
++-----------------+-----------------+
+| 7.7 | 20.0 |
++-----------------+-----------------+
diff --git a/docs/source/tutorials/main.rst b/docs/source/tutorials/main.rst
@@ -6,4 +6,5 @@ Tutorials
colab
gui
- full
-\ No newline at end of file
+ full
+ calibration
+\ No newline at end of file
diff --git a/docs/source/tutorials/media/calibration/metadata-gui.png b/docs/source/tutorials/media/calibration/metadata-gui.png
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/reamp-setup-no-amp.jpg b/docs/source/tutorials/media/calibration/reamp-setup-no-amp.jpg
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/reamp-setup.jpg b/docs/source/tutorials/media/calibration/reamp-setup.jpg
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/scarlett-instrument-input-doc.png b/docs/source/tutorials/media/calibration/scarlett-instrument-input-doc.png
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/sine-tone-level-reduced.png b/docs/source/tutorials/media/calibration/sine-tone-level-reduced.png
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/sine-tone.png b/docs/source/tutorials/media/calibration/sine-tone.png
Binary files differ.
diff --git a/docs/source/tutorials/media/calibration/voltage.jpg b/docs/source/tutorials/media/calibration/voltage.jpg
Binary files differ.
