behind-the-scenes and then runs the multichannel audio code.)
+.. _audio-meters:
+
Audio meters
------------
speaker suddenly coughing, or a very loud bass drum. This prevents
both clipping and blowing out the speakers' ears.
-(TODO: write more)
+At this point, the audio signal is *almost* where we'd like it
+to be, but the overall sound level might not be quite right.
+All the previous compressors have been working in the objective
+domain, but as explained in the :ref:`previous section <audio-meters>`,
+this does not necessarily correspond to the desired overall
+audio loudness. (Their default levels have been calibrated so
+that they end up around 0 LU for typical speech content,
+but they could easily miss by a few LU in many cases.)
+
+Thus, there's a final **makeup gain** at the end to compensate
+for these issues. When the “Auto” checkbox is ticked, which is
+by default, it will very slowly (filter constant of 30 seconds)
+adjust itself so that the overall level goes toward 0 LU,
+ie., the reference level. It is so slow because the R128 calculations
+inherently must go over a certain amount of time (what we want
+to change with this gain is the *overall* sound level,
+not the *immediate* one). In periods where the makeup gain is
+far off, such as when the stream is all silent, it doesn't update
+at all. As with the other knobs, you can uncheck the “Auto”
+checkbox and tune this yourself if you want to.
Multichannel mode
-----------------
+**Multichannel mode** expands on simple audio mode by allowing you
+to have multiple *buses* of audio. (In a sense, it could more accurately
+be called “multibus mode” instead, but the name would be too confusing.)
+A bus in Nageru is a pair of channels (left/right), sourced from
+a video capture or ALSA card. The channel mapping is flexible; my USB
+sound card has 18 channels, for instance, and you can use that to make
+several buses. Each bus has a name (for instance, something like
+“Blue microphone” or “Speaker PC”), which is just for convenience;
+Nageru doesn't care what you write here, but the labels are useful
+for the operator.
+
+Input mappings
+''''''''''''''
+
+.. image:: images/input-mapping.png
+
+The input mapping dialog should be pretty much self-explanatory;
+you can use the + button to add a new bus, and the - button to remove
+the currently selected one (you select by clicking on it). The up and
+down buttons rearrange the order by moving the currently selected bus
+up or down, if possible.
+
+Because mappings can be tedious to setup, you wouldn't want to set up
+a complicated one every time you started Nageru. Therefore, mappings
+can be saved and loaded from disk; the stored file is a
+`protocol buffer <https://developers.google.com/protocol-buffers/>`_
+in textual format. You can also load one at start with the
+“--input-mapping” parameter, which also implies multichannel mode
+(--multichannel).
+
+Nageru strives to keep the mapping consistent even
+in the face of a changed environment—for instance, if you unplug and
+replug a USB sound card, Nageru will attempt to keep your buses mapped to
+that card still mapped. (While the card unplugged, the main display will show
+the relevant buses as “(disconnected)”.) Similarly, if an ALSA device
+is taken by another program on startup and cannot be accessed by Nageru,
+it will mark it as “(busy)” and try again in the background. However,
+there are edge cases where Nageru simply cannot do the right thing,
+for instance if you unplug two identical cards and plug them back
+in the reverse order; USB cards don't carry any kind of serial number
+or other forms of unique identification.
+
+
+The audio views
+'''''''''''''''
+
+.. image:: images/audio-view-selector.png
+
+Once multichannel mode is active, a little selector shows up to the right,
+just below the level meters. The arrows (or equivalently, the PgUp/PgDown
+keys on the keyboard) allow you to select between two views:
+
+ * In the **compact audio view** (which is the default), each bus is
+ represented only by its label, its peak meter (see below) and its
+ fader. This takes up little screen estate, and allows the video channels
+ to be visible. This is the typical view you'd use once you've set up
+ everything and are actually doing live video editing; the controls
+ from the full audio view are still in effect, but you cannot see or
+ interact with them.
+
+ * The **full audio view** contains a lot more controls, but leaves no
+ room for the video channels. These are useful when you are doing initial
+ setup of your mix, or if you want to go back and tune something.
+ The full audio view will be described in detail in the following section;
+ the interpretation of the corresponding controls in the compact audio view
+ is the same.
+
+.. image:: images/audio-bus-controls.png
+
+There's one set each of these controls for every bus.
+
+(TODO: write more)
+
MIDI control
------------
projects / nageru-docs / commitdiff
