From aa1646eb5df4881e8f87f1a881ea18e47f54cc8e Mon Sep 17 00:00:00 2001
From: "Steinar H. Gunderson" <sgunderson@bigfoot.com>
Date: Wed, 29 Mar 2017 22:15:54 +0200
Subject: [PATCH] Start working on HDMI/SDI output text.

---
 hdmisdi.rst | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 index.rst   |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 hdmisdi.rst

diff --git a/hdmisdi.rst b/hdmisdi.rst
new file mode 100644
index 0000000..80a7a4c
--- /dev/null
+++ b/hdmisdi.rst
@@ -0,0 +1,78 @@
+HDMI/SDI output
+===============
+
+Sometimes, what you want from a video mixer isn't a stream, just another
+output that goes to e.g. a projector—or you might want the live stream,
+but also a monitor output on a separate display. You could of course play
+the stream on another PC, but for many uses, the end-to-end latency is
+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
+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
+select the output card. (Equivalently, you can access the same functionality
+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.
+
+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
+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.
+
+
+A note on latency
+-----------------
+
+For a regular stream, a few seconds of latency is usually acceptable
+(clients will typically buffer at least a few seconds), and thus,
+working hard to shave off single frames' worth of latency is not worth it.
+However, for a live output, every millisecond of latency counts;
+if you have a stage with a projector behind it, 500 ms latency on
+the projector looks distinctly out of sync with what's happening
+on stage. Thus, HDMI/SDI output typically has much stricter
+latency demands than usual streaming.
+
+Nageru is capable of low latency operation, but not extremely low latency;
+for instance, it waits for an entire frame to arrive before processing
+it. (This is a complexity and flexibility tradeoff; anything else would make
+e.g. scaling nearly impossible.) Well-designed hardware switcher setups can do
+**cut-through switching** to get latency down to as little as one frame [#]_ or
+less, ie. 16.7 ms at 60 fps; Nageru can get down to 2–3 frames (50 ms)
+given the right hardware, and in general, 100 ms isn't hard. 
+
+.. [#] Since almost all latency in a realtime video setup is caused by processing of various
+       forms and not by length of the cable, most forms of latency will be
+       proportional to the length of a frame. Thus, one will often see latency
+       calculated in terms of number of frames, not milliseconds, and video at
+       higher frame rates will often see less delay. Networking (and by extension
+       streaming) is different; there, jitter and delay is more often caused
+       by propagation and administrative delays, and latency is more often
+       independent of the frame rate.
+
+
+Typical sources of latency
+..........................
+
+This section aims to illuminate some of the sources of latency and how to deal
+with them. Note that often, latency is at odds with throughput, and so,
+tradeoffs must be made. The most important sources of latency are:
+
+- Jitter and queuing latency
+- Processing latency
+- Output latency
+- Audio latency
+
+TODO: Write something about them.
+
+(TODO: Write something about time codes here.)
diff --git a/index.rst b/index.rst
index c6b295c..458ac54 100644
--- a/index.rst
+++ b/index.rst
@@ -15,6 +15,7 @@ Contents:
    hardware
    audio
    streaming
+   hdmisdi
    theme
 
 :ref:`search`
-- 
2.39.2