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
    streaming
    hdmisdi
    theme

+   video

 
 :ref:`search`
 
 
 :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.
 
 
 logic, but also make for the most distinct parts of your visual look.
 
 

+.. _images:
+

 Image inputs
 ------------
 
 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