X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=hdmisdi.rst;h=c3028af503a97103fb347743756528823e94d173;hb=b4d515a6900619c64967a573a8bc8d26483adffc;hp=339e64c582f7232e625056e2af6ce6ad6c56fcc9;hpb=16be766b873f0a310f2d359a4097e06bc5ba29d2;p=nageru-docs

diff --git a/hdmisdi.rst b/hdmisdi.rst
index 339e64c..c3028af 100644
--- a/hdmisdi.rst
+++ b/hdmisdi.rst
@@ -17,7 +17,7 @@ Setting up HDMI/SDI output
 
 Turning on HDMI/SDI output is simple; just 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.) 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.
@@ -101,7 +101,72 @@ tradeoffs must be made. The most important sources of latency are:
    The 4K series in this context include everything that have “4K” in their
    names, plus the Mini Recorder, Duo 2 and Quad 2 devices.
 
-TODO: Write about queuing options. And latency measurements. And audio.
+Controlling latency
+...................
+
+Of the different sources of latency outlined in the previous section,
+the only one that is really under your control (short of buying faster
+or better hardware) is the input queue latency. By default, Nageru
+attempts to strike a balance between reducing latency and having to
+drop frames due to jitter; by looking at each queue's input length
+history, it attempts to find a “safe queue limit”, above which it
+can drop frames without risking underrun (which requires duplicating
+frames). However, if latency is more important to you than 100% smooth
+motion, you can override this by using the *--max-input-queue-frames=*
+flag; this is a hard limit on the number of frames that can be kept
+in the queue, on top of Nageru's own heuristics. It cannot be set lower
+than 1, or else all incoming frames would immediately get dropped
+on arrival.
+
+However, even though the other factors are largely outside your control,
+you still have to *account* for them. Nageru needs to know when to begin
+processing a frame, and it cannot do this adaptively; you need to give
+Nageru a latency budget for processing and output queueing, which tells it when
+to start processing a frame (by picking out the input frames available at that
+time). If a frame isn't processed in time for the output card to pick it up,
+it will be dropped, which means its effort was wasted. (Nageru will tell you
+on the terminal if this happens.) The latency budget is set by
+*--output-buffer-frames=*, where the default is a pretty generous 6.0,
+or 100 ms at 60 fps; if you want lower latency, this you probably want
+to adjust this value down to the point where Nageru starts complaining about
+dropped or late frames, and then a bit up again to get some margin.
+(But see the part about `audio latency <audio-latency>` below.) Note that
+the value can be fractional.
+
+As an exception to the above, Nageru also allows *slop*; if the frame is
+late but only a little (ie., less than the slop), it will give it on to the
+output card nevertheless and hope for forgiveness, which may or may not
+cause it to be displayed. The slop is set with *--output-slop-frames=*,
+where the default is 0.5 frames.
+
+
+.. _audio-latency:
+
+Audio latency
+.............
+
+Since Nageru does not require synchronized audio sources, neither to video
+nor to each other (which would require a common, locked reference clock for all
+capture and sound cards), it needs to *resample* incoming audio to match
+the rate of the master video clock. To avoid buffer underruns caused by
+uneven delivery of input audio, each card needs an audio input queue,
+just like the video input queue; by default, this is set to 100 ms, which then
+acts as a lower bound on your latency.
+
+If you want to reduce video latency, you will probably want to reduce audio
+latency correspondingly, or audio will arrive too late to be heard. You can
+adjust the audio latency with the *--audio-queue-length-ms=* flag, but notice
+that this value is in milliseconds, not in frames.
+
+Audio and video queue lengths do not need to match exactly; the two streams
+(audio and video) will be synchronized at playback, both for network streaming
+and for HDMI/SDI output.
+
+
+Measuring latency
+.................
+
+TODO: Write about latency measurements.
 
 TODO: Write something about time codes here.