Start documenting videos.

[nageru-docs] / video.rst

diff --git a/video.rst b/video.rst
new file mode 100644 (file)
index 0000000..e1f1eb5
--- /dev/null
+++ b/video.rst
@@ -0,0 +1,73 @@
+Video inputs
+============
+
+This section deals with video inputs from other sources than regular
+capture cards (which are typically known as “live inputs”, although
+they also carry video). The most obvious example would be a video file on disk
+(say, to play in a loop during pauses), but video inputs are quite
+flexible and can be used also for other things.
+
+Before reading trying to use video inputs, you should read and understand how
+themes work in general (see :doc:`theme`). Video inputs are available from
+Nageru 1.6.0 onwards. There is currently no support for audio from video inputs;
+all videos are silent. (This may change in the future.) If a file contains
+multiple video streams, like different angles or resolutions, only the first
+will be used.
+
+
+Basic video inputs
+------------------
+
+Adding video to an existing chain happens in two phases; first, the video
+must be *loaded*, giving it an identifier, and then that video can be used
+as inputs in a chain, much like :ref:`images <images>` or regular live inputs.
+Anything FFmpeg accepts, including network streams, can be used (probably even
+V4L input cards, although this is untested).
+
+When loading a video, you need to decide what format to use; Y'CbCr or BGRA.
+(Whatever you choose, if you get a mismatch with what the video actually is in,
+FFmpeg will convert it on the CPU with no warning.) Most video is Y'CbCr,
+so this should be your default unless you know the video is encoded as RGB/BGR,
+and/or it has an alpha channel you want to use. Getting the format right makes
+for better efficiency; you not only save a conversion step on the CPU, but
+sometimes also on the GPU.
+
+Videos are loaded like this:
+
+  local video = VideoInput.new("filename.mp4", Nageru.VIDEO_FORMAT_YCBCR)
+
+or, for a network stream, perhaps:
+
+  local video = VideoInput.new("http://localhost/file.nut", Nageru.VIDEO_FORMAT_BGRA)
+
+It can then be added to any chain like this:
+
+  local input = chain:add_video_input(video, false)
+
+The second parameter specifies no deinterlacing. Note that interlaced video
+is currently not supported, not even with deinterlacing, so this parameter
+must always be false.
+
+You can use the same video object to create many different video inputs:
+  
+  local input1 = chain1:add_video_input(video, false)
+  local input2 = chain2:add_video_input(video, false)
+
+Videos run in the correct frame rate and on their own timer (generally the
+system clock in the computer), and loop when they get to the end or whenever an
+error occurs. If a video is changed while you're running Nageru, it will be
+reloaded (just like images) when it's at its end—but be aware, unless you're
+moving the new file atomically into place, you could end up corrupting the file
+Nageru is playing from, causing it to automatically rewind before the end of
+the segment.
+
+
+Controlling video playback
+--------------------------
+
+TODO
+
+Integration with CasparCG
+-------------------------
+
+TODO