Add Region Gain documentation

diff --git a/include/region-gain-adjustment.html b/include/region-gain-adjustment.html
new file mode 100644 (file)
index 0000000..83b64a0
--- /dev/null
+++ b/include/region-gain-adjustment.html
@@ -0,0 +1,124 @@
+<p>
+  Ardour allows adjusting region gain by a constant amount as opposed to
+  adjusting gain envelope where it's possible to change it gradually over time.
+  Like everything in Ardour, this is a non-destructive change. The result can be
+  adjusted at any a later time or discarded altogether. Internally, region gain
+  is an inherent property of regions, it can be edited directly in the region
+  properties dialog.
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/region-properties-gain-adjusted.png" alt="Region Properties">
+  <figcaption>
+    Region Properties
+  </figcaption>
+</figure>
+
+<p>
+  There are two additional ways to adjust region gain: by boosting or cutting
+  gain with a 1dB step, or by normalizing audio.
+</p>
+
+<h2>Boosting and Cutting Gain</h2>
+
+<p>
+  The quickest way to increase or decrease gain of selected regions without
+  involving the gain envelope is to use <em>Boost Gain</em> and
+  <em>Cut Gain</em> commands respectively.
+</p>
+
+<p>
+  These commands can be accessed via the main <em>Region &gt; Gain</em> menu or
+  region's context menu. A much easier way is to use shortcuts:
+  <strong>Alt+6</strong> boosts gain by 1dB, <strong>Alt+7</strong> cuts gain
+  by 1dB.
+</p>
+
+<p>
+  When gain is boosted or cut, the region caption in the bottom of the affected
+  region specifies the amount in parentheses. In an example below, gain was cut
+  by 2dB.
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/gain-cut-example.png" alt="Gain cut">
+  <figcaption>
+    Gain cut
+  </figcaption>
+</figure>
+
+<h2>Normalizing Audio Regions</h2>
+
+<p>
+  Audio normalization is a way to bring the amplitude of a signal to a target
+  level by applying the same amount of gain to an entire piece of audio data.
+  Unlike other ways to treat perceived loudness, such as compression,
+  normalization retains the original dynamic range.
+</p>
+
+<p>
+  Normalization is a common step in exporting an entire project to an audio
+  file. However, with Ardour, it's also possible to normalize some of the
+  regions. This effectively changes the region gain setting, the same one that
+  the boost/cut gain commands change.
+</p>
+
+<p>
+  Region-level normalization in Ardour can be accessed via the <em>Region &gt;
+  Gain &gt; Normalize…</em> menu command
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/normalize-region-settings.png" alt="Normalize Region">
+  <figcaption>
+    Normalize Region
+  </figcaption>
+</figure>
+
+<p>
+  The normalization tool locates the part of the audio region that has the
+  largest amplitude and adjusts the whole region so that that part matches the
+  normalization target. In an example below, an audio region was normalized
+  to -3dBFS, which led to -2.5dB gain reduction, and this is the part with the
+  largest amplitude hitting the exact -3dBFS target:
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/peak-normalization-zoomed-in.png" alt="Normalized region, zoomed in">
+  <figcaption>
+    Normalized region, zoomed in
+  </figcaption>
+</figure>
+
+<p>
+  It's also possible to apply additional constraints by analyzing perceieved
+  loudness of the material. The first option is to constraint root mean square
+  (RMS) to a certain amplitude value. The second option is to constrain loudness
+  units (LUFS) to a certain value.
+</p>
+
+<p>
+  The normalization tool will use the peak amplitude value, but will also
+  correct the calculated gain adjustment when the constraint demands that.
+  In the example below the same region as in example above was normalized to the
+  same peak amplitude of -3dB but with an additional constraint of -21LUFS.
+  The normalization tool took the peak amplitude into account and made sure it
+  wouldn't exceed the target value of -3dBFS, then adjusted the region gain
+  further from -2.5dB to -3.3dB to meet the LUFS constraint demands. This
+  resulted in the peak amplitude hitting -4.2dBFS rather than the target -3dBFS.
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/peak-normalization-with-lufs-zoomed-in.png" alt="Normalization with LUFS constraint, zoomed in">
+  <figcaption>
+    Normalization with LUFS constraint, zoomed in
+  </figcaption>
+</figure>
+
+<h2>Resetting Gain</h2>
+
+<p>
+  To reset gain correction for a region entirely you can either set it to
+  <tt>0</tt> in the region properties dialog or use the
+  <em>Region &gt; Gain &gt; Reset Gain</em> menu command.
+</p>

diff --git a/master-doc.txt b/master-doc.txt
index d8d18a82d74eab90a07955d0ab74a8ca14fe133f..d2929e398417052683abd46ebe9429a4b75f96f8 100644 (file)
--- a/master-doc.txt
+++ b/master-doc.txt
@@ -1262,11 +1262,25 @@ uri: editing-and-arranging/create-region-fades-and-crossfades
 part: chapter
 ---
 
+---
+title: Adjusting Gain
+link: adjusting-gain
+uri: adjusting-gain
+part: chapter
+---
+
+---
+title: Region Gain
+include: region-gain-adjustment.html
+link: region-gain-adjustment
+part: subchapter
+---
+
 ---
 title: Gain Envelopes
 include: gain-envelopes.html
 link: gain-envelopes
-part: chapter
+part: subchapter
 ---
 
 ---

diff --git a/source/images/peak-normalization-with-lufs-zoomed-in.png b/source/images/peak-normalization-with-lufs-zoomed-in.png
new file mode 100644 (file)
index 0000000..4d27357
Binary files /dev/null and b/source/images/peak-normalization-with-lufs-zoomed-in.png differ

diff --git a/source/images/peak-normalization-zoomed-in.png b/source/images/peak-normalization-zoomed-in.png
new file mode 100644 (file)
index 0000000..1230237
Binary files /dev/null and b/source/images/peak-normalization-zoomed-in.png differ