Document the imperative 1.9.0 functions.

[nageru-docs] / video.rst

diff --git a/video.rst b/video.rst
index cdef8f194674cc3343258fe2cd95ca5e73eed7b7..12e32e3fc8dbe8448ae8c88dd667e780335b5cf2 100644 (file)
--- a/video.rst
+++ b/video.rst
@@ -9,10 +9,14 @@ 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
 
 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.
+Nageru 1.6.0 onwards, and from Nageru 1.7.2, you can get audio from video inputs
+like any other input. (Be advised, though, that making a general video player
+that can maintain A/V sync on all kinds of video files is a hard problem,
+so there may still be bugs in this support.)
+
+If a file contains multiple video streams, like different
+angles or resolutions, only the first will be used. Similarly, only the first
+audio stream is used, and it's always converted to 48 kHz stereo.

 
 
 Basic video inputs
 
 
 Basic video inputs


@@ -61,13 +65,68 @@ 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.
 
 Nageru is playing from, causing it to automatically rewind before the end of
 the segment.
 

+Videos are assigned an arbitrary signal number when loaded. Whenever you need
+to refer to this signal number (say, to get its width or height for display),
+you should use *video:get_signal_num()*. Like any other signal, videos have
+a width and height, an interlaced flag (currently always false), a frame rate
+(which can vary during playback) and has_signal/is_connected member functions.
+The former is always true, but the former will be false if the video isn't
+currently playing for whatever reason (e.g., the file is corrupted, or a network
+stream is broken and hasn't reconnected yet).
+

 
 Controlling video playback
 --------------------------
 
 
 Controlling video playback
 --------------------------
 

-TODO
+Themes have some programmatic control over video playback. In particular,
+if you want to make a video start from the beginning, you can do::
+
+  video:rewind()
+
+which will instantly make it start from the first frame again. This can be
+useful if you e.g. want the video to start when you're switching to it,
+or if you're not really using it to loop (e.g. as a transition marker).
+
+You can also change its rate, e.g. by::
+
+  video:change_rate(2.0)
+
+This will make it play at twice its usual speed. Your rate should not be
+negative nor exactly zero. You can set a rate to e.g. 1e-6 if you want to
+in practice stop the video; once you change it back to normal speed,
+the next frame will resume playing. Be aware that changing the rate may
+make the audio behave unpredictably; there are no attempts to do time
+stretching or change the pitch accordingly.
+
+Finally, if you want to forcibly abort the playing of a video,
+even one that is blocking on I/O, you can use (since Nageru 1.7.2)::
+
+  video:disconnect()
+
+This is particularly useful when dealing with network streams, as FFmpeg does not
+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
 -------------------------
 
 
 Integration with CasparCG
 -------------------------
 

-TODO
+This section has been removed, as since 1.7.0, Nageru has :doc:`native support for HTML5 inputs <html>`,
+obsoleting CasparCG integration.