Start documenting videos.

diff --git a/index.rst b/index.rst
index 458ac54fea2d6f441e22abff2f6a9ee75d57a792..f33bfc959b8a5f186f4338e53a8a0e1ecd3e84fd 100644 (file)
--- a/index.rst
+++ b/index.rst
@@ -17,6 +17,7 @@ Contents:
    streaming
    hdmisdi
    theme
+   video
 
 :ref:`search`
 

diff --git a/theme.rst b/theme.rst
index 9028b6868256584fcbdff260239081bbbfbb9329..72da4bcfb65c549c023dd38eaf13afb48964d2fc 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -320,6 +320,8 @@ Transitions involving scenes tend to be the most complicated parts of the theme
 logic, but also make for the most distinct parts of your visual look.
 
 
+.. _images:
+
 Image inputs
 ------------
 

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