git.sesse.net Git - nageru-docs/blob - video.rst

   1 Video inputs
   2 ============
   3
   4 This section deals with video inputs from other sources than regular
   5 capture cards (which are typically known as “live inputs”, although
   6 they also carry video). The most obvious example would be a video file on disk
   7 (say, to play in a loop during pauses), but video inputs are quite
   8 flexible and can be used also for other things.
   9
  10 Before reading trying to use video inputs, you should read and understand how
  11 themes work in general (see :doc:`theme`). Video inputs are available from
  12 Nageru 1.6.0 onwards, and from Nageru 1.7.2, you can get audio from video inputs
  13 like any other input. (Be advised, though, that making a general video player
  14 that can maintain A/V sync on all kinds of video files is a hard problem,
  15 so there may still be bugs in this support.)
  16
  17 If a file contains multiple video streams, like different
  18 angles or resolutions, only the first will be used. Similarly, only the first
  19 audio stream is used, and it's always converted to 48 kHz stereo.
  20
  21
  22 Basic video inputs
  23 ------------------
  24
  25 Adding video to an existing chain happens in two phases; first, the video
  26 must be *loaded*, giving it an identifier, and then that video can be used
  27 as inputs in a chain, much like :ref:`images <images>` or regular live inputs.
  28 Anything FFmpeg accepts, including network streams, can be used (probably even
  29 V4L input cards, although this is untested).
  30
  31 When loading a video, you need to decide what format to use; Y'CbCr or BGRA.
  32 (Whatever you choose, if you get a mismatch with what the video actually is in,
  33 FFmpeg will convert it on the CPU with no warning.) Most video is Y'CbCr,
  34 so this should be your default unless you know the video is encoded as RGB/BGR,
  35 and/or it has an alpha channel you want to use. Getting the format right makes
  36 for better efficiency; you not only save a conversion step on the CPU, but
  37 sometimes also on the GPU.
  38
  39 Videos are loaded like this::
  40
  41   local video = VideoInput.new("filename.mp4", Nageru.VIDEO_FORMAT_YCBCR)
  42
  43 or, for a network stream, perhaps::
  44
  45   local video = VideoInput.new("http://localhost/file.nut", Nageru.VIDEO_FORMAT_BGRA)
  46
  47 It can then be display on an input like usual::
  48
  49   input:display(video)
  50
  51 Note that interlaced video is currently not supported, not even with deinterlacing.
  52 (Before Nageru 1.9.0, video inputs were distinct from live inputs, and had to
  53 be created differently, but this is no longer the case.)
  54
  55 Videos run in the correct frame rate and on their own timer (generally the
  56 system clock in the computer), and loop when they get to the end or whenever an
  57 error occurs. If a video is changed while you're running Nageru, it will be
  58 reloaded (just like images) when it's at its end—but be aware, unless you're
  59 moving the new file atomically into place, you could end up corrupting the file
  60 Nageru is playing from, causing it to automatically rewind before the end of
  61 the segment.
  62
  63 Videos are assigned an arbitrary signal number when loaded. Whenever you need
  64 to refer to this signal number (say, to get its width or height for display),
  65 you should use *video:get_signal_num()*. Like any other signal, videos have
  66 a width and height, an interlaced flag (currently always false), a frame rate
  67 (which can vary during playback) and has_signal/is_connected member functions.
  68 The former is always true, but the former will be false if the video isn't
  69 currently playing for whatever reason (e.g., the file is corrupted, or a network
  70 stream is broken and hasn't reconnected yet).
  71
  72
  73 Controlling video playback
  74 --------------------------
  75
  76 Themes have some programmatic control over video playback. In particular,
  77 if you want to make a video start from the beginning, you can do::
  78
  79   video:rewind()
  80
  81 which will instantly make it start from the first frame again. This can be
  82 useful if you e.g. want the video to start when you're switching to it,
  83 or if you're not really using it to loop (e.g. as a transition marker).
  84
  85 You can also change its rate, e.g. by::
  86
  87   video:change_rate(2.0)
  88
  89 This will make it play at twice its usual speed. Your rate should not be
  90 negative nor exactly zero. You can set a rate to e.g. 1e-6 if you want to
  91 in practice stop the video; once you change it back to normal speed,
  92 the next frame will resume playing. Be aware that changing the rate may
  93 make the audio behave unpredictably; there are no attempts to do time
  94 stretching or change the pitch accordingly.
  95
  96 Finally, if you want to forcibly abort the playing of a video,
  97 even one that is blocking on I/O, you can use (since Nageru 1.7.2)::
  98
  99   video:disconnect()
 100
 101 This is particularly useful when dealing with network streams, as FFmpeg does not
 102 always properly detect if the connection has been lost. See :ref:`menus`
 103 for a way to expose such functionality to the operator.
 104
 105 .. _subtitle-ingest:
 106
 107 Ingesting subtitles
 108 -------------------
 109
 110 Video streams can contain separate subtitle tracks. Since Nageru 1.8.1,
 111 you can read these streams. This is particularly useful when using Nageru
 112 and Futatabi together (see :ref:`talkback`).
 113
 114 To get the last subtitle given before the current video frame, call
 115 “signals:get_last_subtitle(n)” from get_chain, where n is the signal number
 116 of your video signal. It will either contain nil, if there hasn't been
 117 a subtitle, or else the raw subtitle. Note that if the video frame and
 118 the subtitle occur on the exact same timestamp, and the video frame
 119 is muxed before the subtitle packet, the subtitle will not make it in time.
 120 (Futatabi puts the subtitle slightly ahead of the video frame to avoid this.)
 121
 122
 123 Integration with CasparCG
 124 -------------------------
 125
 126 This section has been removed, as since 1.7.0, Nageru has :doc:`native support for HTML5 inputs <html>`,
 127 obsoleting CasparCG integration.