Document the return value of choose() and how it is useful.

[nageru-docs] / video.rst

diff --git a/video.rst b/video.rst
index ed565f8d746b6ff82bbf17527e391d39073c56ba..ee2c1b59a85f73e7d66153fe7cde8443a984ce30 100644 (file)
--- a/video.rst
+++ b/video.rst
@@ -44,18 +44,13 @@ 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::
+It can then be display on an input like usual::
 
-  local input = chain:add_video_input(video, false)
+  input:display(video)
 
-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)
+Note that interlaced video is currently not supported, not even with deinterlacing.
+(Before Nageru 1.9.0, video inputs were distinct from live inputs, and had to
+be created differently, but this is no longer the case.)
 
 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
@@ -107,6 +102,23 @@ This is particularly useful when dealing with network streams, as FFmpeg does no
 always properly detect if the connection has been lost. See :ref:`menus`
 for a way to expose such functionality to the operator.
 
+.. _subtitle-ingest:
+
+Ingesting subtitles
+-------------------
+
+Video streams can contain separate subtitle tracks. Since Nageru 1.8.1,
+you can read these streams. This is particularly useful when using Nageru
+and Futatabi together (see :ref:`talkback`).
+
+To get the last subtitle given before the current video frame, call
+“signals:get_last_subtitle(n)” from get_chain, where n is the signal number
+of your video signal. It will either contain nil, if there hasn't been
+a subtitle, or else the raw subtitle. Note that if the video frame and
+the subtitle occur on the exact same timestamp, and the video frame
+is muxed before the subtitle packet, the subtitle will not make it in time.
+(Futatabi puts the subtitle slightly ahead of the video frame to avoid this.)
+
 
 Integration with CasparCG
 -------------------------