# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = [
+ 'sphinx.ext.autosectionlabel',
+]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Measuring latency
.................
-TODO: Write about latency measurements.
+In order to optimize latency, it can be useful to measure it, but for most
+people, it's hard to measure delays precisely enough to distinguish reliably
+between e.g. 70 and 80 milliseconds by eye alone. Nageru gives you some simple
+tools that will help.
+
+The most direct is the flag *--print-video-latency*. This samples, for every
+100th frame, the latency of that frame through Nageru. More precisely,
+it measures the wall clock time from the point where the frame is received from
+the input card driver (and put into the input queue) to up to four different
+points:
+
+ * **Mixer latency:** The frame is done processing on the GPU.
+ * **Quick Sync latency:** The frame is through :ref:`VA-API H.264 encoding <digital-intermediate>`
+ and ready to be muxed to disk. (Note that the mux might still be waiting
+ for audio before actually outputting the frame.)
+ * **x264 latency:** The frame is through :ref:`x264 encoding <transcoded-streaming>`
+ and ready to be muxed to disk and/or the network. (Same caveat about the
+ mux as the previous point.)
+ * **DeckLink output latency:** The HDMI/SDI output card reports that it has
+ shown the frame.
+
+As every output frame can depend on multiple input frames, each with different
+input queue latencies, latencies will be measured for each of them, and the
+lowest and highest will be printed. Do note that the measurement is still done
+over a single *output* frame; it is *not* a measurement over the last 100
+output frames, even though the statistics are only printed every 100th.
TODO: Write something about time codes here.