Write about audio latency.

[nageru-docs] / hdmisdi.rst

diff --git a/hdmisdi.rst b/hdmisdi.rst
index 7c8a0c6e6654b9efc4fe8a13ab480645edd9a0c1..c3028af503a97103fb347743756528823e94d173 100644 (file)
--- a/hdmisdi.rst
+++ b/hdmisdi.rst
@@ -118,7 +118,55 @@ 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.
 
-TODO: Write about output queuing options. And latency measurements. And audio.
+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.