Write about latency measurement.

[nageru-docs] / hdmisdi.rst

diff --git a/hdmisdi.rst b/hdmisdi.rst
index c3028af503a97103fb347743756528823e94d173..64fc924675b93bb31dc4c04a5d95c89fc7ad3958 100644 (file)
--- a/hdmisdi.rst
+++ b/hdmisdi.rst
@@ -166,7 +166,32 @@ and for HDMI/SDI output.
 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.