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.
 
 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.
 
 
 TODO: Write something about time codes here.