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. There is currently no support for audio from video inputs;
  13 all videos are silent. (This may change in the future.) If a file contains
  14 multiple video streams, like different angles or resolutions, only the first
  15 will be used.
  16
  17
  18 Basic video inputs
  19 ------------------
  20
  21 Adding video to an existing chain happens in two phases; first, the video
  22 must be *loaded*, giving it an identifier, and then that video can be used
  23 as inputs in a chain, much like :ref:`images <images>` or regular live inputs.
  24 Anything FFmpeg accepts, including network streams, can be used (probably even
  25 V4L input cards, although this is untested).
  26
  27 When loading a video, you need to decide what format to use; Y'CbCr or BGRA.
  28 (Whatever you choose, if you get a mismatch with what the video actually is in,
  29 FFmpeg will convert it on the CPU with no warning.) Most video is Y'CbCr,
  30 so this should be your default unless you know the video is encoded as RGB/BGR,
  31 and/or it has an alpha channel you want to use. Getting the format right makes
  32 for better efficiency; you not only save a conversion step on the CPU, but
  33 sometimes also on the GPU.
  34
  35 Videos are loaded like this::
  36
  37   local video = VideoInput.new("filename.mp4", Nageru.VIDEO_FORMAT_YCBCR)
  38
  39 or, for a network stream, perhaps::
  40
  41   local video = VideoInput.new("http://localhost/file.nut", Nageru.VIDEO_FORMAT_BGRA)
  42
  43 It can then be added to any chain like this::
  44
  45   local input = chain:add_video_input(video, false)
  46
  47 The second parameter specifies no deinterlacing. Note that interlaced video
  48 is currently not supported, not even with deinterlacing, so this parameter
  49 must always be false.
  50
  51 You can use the same video object to create many different video inputs::
  52
  53   local input1 = chain1:add_video_input(video, false)
  54   local input2 = chain2:add_video_input(video, false)
  55
  56 Videos run in the correct frame rate and on their own timer (generally the
  57 system clock in the computer), and loop when they get to the end or whenever an
  58 error occurs. If a video is changed while you're running Nageru, it will be
  59 reloaded (just like images) when it's at its end—but be aware, unless you're
  60 moving the new file atomically into place, you could end up corrupting the file
  61 Nageru is playing from, causing it to automatically rewind before the end of
  62 the segment.
  63
  64 Videos are assigned an arbitrary signal number when loaded. Whenever you need
  65 to refer to this signal number (say, to get its width or height for display),
  66 you should use *video:get_signal_num()*. Like any other signal, videos have
  67 a width and height, an interlaced flag (currently always false), a frame rate
  68 (which can vary during playback) and has_signal/is_connected member functions.
  69 The former is always true, but the former will be false if the video isn't
  70 currently playing for whatever reason (e.g., the file is corrupted, or a network
  71 stream is broken and hasn't reconnected yet).
  72
  73
  74 Controlling video playback
  75 --------------------------
  76
  77 Themes have some programmatic control over video playback. In particular,
  78 if you want to make a video start from the beginning, you can do::
  79
  80   video:rewind()
  81
  82 which will instantly make it start from the first frame again. This can be
  83 useful if you e.g. want the video to start when you're switching to it,
  84 or if you're not really using it to loop (e.g. as a transition marker).
  85
  86 You can also change its rate, e.g. by::
  87
  88   video:change_rate(2.0)
  89
  90 This will make it play at twice its usual speed. Your rate should not be
  91 negative nor exactly zero. You can set a rate to e.g. 1e-6 if you want to
  92 in practice stop the video; once you change it back to normal speed,
  93 the next frame will resume playing.
  94
  95
  96 Integration with CasparCG
  97 -------------------------
  98
  99 `CasparCG <http://casparcg.com/>`_ is an open-source broadcast graphics system,
 100 originally written by SVT, the Swedish public TV broadcaster. (In this
 101 context, “graphics” refers mostly to synthetically generated content,
 102 such as the score box in a sporting match.) With some coaxing, it is possible
 103 to integrate CasparCG with Nageru, so that Nageru does the mixing of the video
 104 sources and CasparCG generates graphics—CasparCG can also work as a standalone
 105 mixer indepedently of Nageru, but this will not be covered here.
 106
 107 The most straightforward use of CasparCG is to use it to generate an overlay,
 108 which is then taken in as a video input in Nageru. To achieve this, the simplest
 109 solution is to send raw BGRA data over a UNIX domain socket [#rawvideo]_, which involves
 110 adding an FFmpeg output to your CasparCG configuration. This can either be done
 111 by modifying your casparcg.config to open up a socket in your home directory
 112 (you shouldn't use /tmp on a multi-user machine, or you may open up a security
 113 hole)::
 114
 115   <consumers>
 116     <ffmpeg>
 117       <device>1</device>
 118       <path>unix:///home/user/caspar.sock</path>
 119       <args>-c:v rawvideo -vf format=pix_fmts=bgra -f nut -listen 1</args>
 120     </ffmpeg>
 121     <system-audio></system-audio>
 122   </consumers>
 123
 124 or by setting it up on-the-fly through ACMP::
 125
 126   add 1 stream unix:///home/user/caspar.sock -c:v rawvideo -vf format=pix_fmts=bgra -f nut -listen 1
 127
 128 You can then use *unix:///home/user/caspar.sock* as a video input to Nageru on the
 129 same machine, and then use e.g. *OverlayEffect* to overlay it on your video chains.
 130 (Remember to set up the video as BGRA and not Y'CbCr, so that you get alpha.)
 131
 132 CasparCG and Nageru does not run with synchronized clocks, so you will not get
 133 frame-perfect synchronization between graphics and overlay; however, this is normal
 134 even in a hardware chain, and most overlay graphics does not need to be timed
 135 to the input more than through a few frames. However, note that it is possible
 136 that Nageru lags behind CasparCG's graphics production after a while (typically
 137 on the order of hours) due to such clock skew; the easiest solution to this is
 138 just to use *change_rate(2.0)* or similar on the input, so that Nageru will consume
 139 CasparCG's frames as quickly as they come in without waiting any further.
 140
 141 There's also one usability stumbling block: *CasparCG's FFmpeg
 142 streams are one-shot, and so are FFmpeg's UNIX domain sockets.* This means that,
 143 in practice, if Nageru ever disconnects from CasparCG for any reason, the socket
 144 is “used up”, and you will need to recreate it somehow (e.g., by restarting CasparCG).
 145 Also note that the old socket still lingers in place even after being useless,
 146 so you will _first_ need to remove it, and CasparCG does not do this for you.
 147 The simplest way to deal with this is probably to have a wrapper script of some
 148 sort that orchestrates Nageru, CasparCG and your client for you, so that everything
 149 is taken up and down in the right order; it may be cumbersome and require some
 150 tweaking for oyur specific case, but it's not a challenging problem per se.
 151
 152 Nageru does not have functionality to work as a CasparCG client in itself,
 153 nor can your theme present a very detailed UI to do so. However, do note that
 154 since the theme is written in unrestricted Lua, so you can use e.g.
 155 `lua-http <https://github.com/daurnimator/lua-http>`_ to send signals
 156 to your backend (assuming it speaks HTTP) on e.g. transition changes.
 157 With some creativity, this allows you to at least bring some loose coupling
 158 between the two.
 159
 160 In general, the integration between Nageru and CasparCG leaves a bit to be
 161 desired, and in general, the combination of CasparCG + Nageru will require
 162 a beefire machine than Nageru alone. However, it also provides a much richer
 163 environment for graphics, so for many use cases, it will be worth it.
 164
 165 .. [#rawvideo] Good video codecs that support alpha are rare, so as long as CasparCG
 166                and Nageru are running on the same machine, raw video is probably your
 167                best bet. Even so, note that FFmpeg's muxers are not really made for
 168                such large amounts of data that raw HD video produces, so there will
 169                be some performance overhead on both sides of the socket.