too high, and you might not want to involve a full extra PC just for this
anyway.
-Thus, since 1.5.0, Nageru supports using a spare output card for HDMI/SDI
+Thus, Nageru supports using a spare output card for HDMI/SDI
output, turning it into a simple, reasonably low-latency audio/video switcher.
Setting up HDMI/SDI output
--------------------------
-Turning on HDMI/SDI output is simple; just right-click on the live view and
+To turn on HDMI/SDI output, right-click on the live view and
select the output card. (Equivalently, you can access the same functionality
-from the *Video* menu in the regular menu bar.) Currently, this is supported
+from the *Video* menu in the regular menu bar, or you can give the
+*--output-card=* parameter on the command line.) Currently, this is supported
for DeckLink cards only (PCI/Thunderbolt), as the precise output protocol for
the Intensity Shuttle cards is still unknown. The stream and recording will
keep running just as before.
A video mode will automatically be picked for you, favoring 59.94 fps if possible,
but you can change the mode on-the-fly to something else if you'd like,
as long as the resolution matches with what you've set up at program start.
-Note that whenever HDMI/SDI output is active, the output card will be the
+
+
+Unsynchronized HDMI/SDI output
+------------------------------
+
+By default, whenever HDMI/SDI output is active, the output card will be the
master clock; you cannot change it to any of the input cards. This also means
that the frame rate you choose here will determine the frame rate for the
stream.
+In Nageru 2.1.0 or newer, you can use the flag --output-card-unsynchronized
+to counteract this (there is currently no way to do it from the GUI).
+This is for if you want just a monitor output without synchronizing
+your entire stream chain to the output card (ie., you want to keep
+some other camera as the master). Sound support is untested, and is
+probably going to crackle a fair bit.
+
A note on latency
-----------------
and for HDMI/SDI output.
+.. _measuring-latency:
+
Measuring latency
.................
-TODO: Write about latency measurements.
-
-TODO: Write something about time codes here.
-
+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
+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.
+
+For more precise measurements, you can use Prometheus metrics to get percentiles
+for all of these points, which will measure over all frames (over a one-minute
+window). This yields more precise information than sampling every 100 frames,
+but setting up Prometheus and a graphic tool is a bit more work, and usually not
+worth it for simple measurement. For more information, see :doc:`monitoring`.
+
+Another trick that can be useful in some situations is *looping* your signal,
+ie., connecting your output back into your input. This allows you to measure
+delays that don't happen within Nageru itself, like any external converters,
+delays in the input driver, etc.. (It can also act as a sanity check to make
+sure your A/V chain passes the signal through without quality degradation,
+if you first set up a static picture as a signal and then switch to the loop
+input to verify that the signal stays stable without color e.g. shifts [#]_.
+See the section on :doc:`the frame analyzer <analyzer>` for other ways of
+debugging signal integrity.)
+
+For this, the *timecode output* is useful; you can turn it on from the Video
+menu, or through the command-line flag *--timecode-stream*. (You can also
+output it to standard output with the flag *--timecode-stdout*.) It contains
+some information about frame numbers and current time of day; if you activate
+it, switch to the loop input and then deactivate it while still holding the
+loop input active, the timecode will start repeating with roughly the
+same length as your latency. (It can't be an exact measurement, as delay is
+frequently fractional, and a loop length cannot be.) The easiest way to find
+the actual length is to look at the recorded video file by e.g. dumping each
+frame to an image file and looking at the sequence.
+
+In general, using Nageru's own latency measurement is both the simplest and
+the most precise. However, the timecode is a useful supplement, since it
+can also test external factors, such as network stream latency.
+
+.. [#] If you actually try this with Nageru, you will see some
+ dark “specks” slowly appear in the image. This is a consequence of
+ small roundoff errors accumulating over time, combined with Nageru's
+ static dither pattern that causes rounding to happen in the same
+ direction each time. The dithering used by Nageru is a tradeoff between
+ many factors, and overall helps image quality much more than it
+ hurts, but in the specific case of an ever-looping signal, it will
+ cause such artifacts.
projects / nageru-docs / blobdiff