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

   1 Streaming and recording
   2 =======================
   3
   4 One of the primary purposes of Nageru is to prepare a stream
   5 that is suitable for live broadcast. However, it is *not*
   6 suitable for serving end-users directly; other software is
   7 much more suitable.
   8
   9 Depending on the amount of CPU power and bandwidth in your
  10 production machine (the one you run Nageru on) and other
  11 machines you may have available, you can choose two different
  12 approaches for streaming: **Transcoded** or **direct**.
  13
  14
  15 .. _transcoded-streaming:
  16
  17 Transcoded streaming
  18 --------------------
  19
  20 Transcoded streaming is in many ways the conceptually simplest from Nageru's point of
  21 view. In this mode, Nageru outputs its “digital intermediate”
  22 H.264 stream (see :ref:`digital-intermediate`), and you are
  23 responsible for transcoding it into a format that is suitable
  24 for streaming to clients. Thus, you can run Nageru on a regular
  25 laptop and then use e.g. a short-term virtual machine in the cloud
  26 to do the heavy lifting for video compression.
  27
  28 Nageru has a built-in HTTP server that listens on port 9095.
  29 You can get the intermediate by using any filename; by default,
  30 the NUT mux is used, so e.g. “http://yourserver.example.org:9095/stream.nut”
  31 would be appropriate. The NUT mux is chosen because it is among
  32 the few that can carry uncompressed audio easily. It is private
  33 to FFmpeg, and thus understood by almost everything in the free
  34 software world, but perhaps not by all other services. You can
  35 change it with the “--http-mux” parameter, although you might
  36 then also want to change the audio codec to using “--http-audio-codec”
  37 and “--http-audio-bitrate” to something your mux can transport
  38 (see below for more information about audio transcoding).
  39
  40 The stream can be transcoded by a number of programs, such as
  41 `VLC <http://www.videolan.org/>`_, but Nageru also has its own
  42 transcoder called **Kaeru**, named after the
  43 Japanese verb *kaeru* (換える), meaning roughly to replace or exchange.
  44 Kaeru is a command-line tool that is designed to transcode Nageru's streams.
  45 Since it reuses Nageru's decoding and encoding code, it can do almost everything you can do
  46 with :ref:`direct encoding <direct-encoding>`, including x264 speed control
  47 and Metacube output (see the section on :ref:`Cubemap integration <cubemap>` below).
  48
  49 Using Kaeru is similar to launching Nageru, e.g. to rescale a stream to 848x480
  50 and output it to a 1.5 Mbit/sec H.264 stream suitable for most browsers in a \<video\> tag::
  51
  52   ./kaeru -w 848 -h 480 --http-mux mp4 --http-audio-codec aac --http-audio-bitrate 128 \
  53     --x264-bitrate 1500 http://yourserver.example.org:9095/stream.nut
  54
  55 1.5 Mbit/sec is in the lower end of the spectrum for good
  56 720p60 conference video (most TV channels use 12-15 Mbit/sec
  57 for the same format).
  58
  59 Another variation popular today is to stream using segmented HTTP;
  60 you can use e.g. the ffmpeg command-line tool to segment the HLS
  61 created by Kaeru into a stream that will be accepted by most smartphones::
  62
  63   ffmpeg -i http://127.0.0.1:1994/ -codec copy -f hls \
  64     -hls_time 2 -hls_wrap 100 -bsf:v h264_mp4toannexb \
  65     -hls_segment_filename $NAME-hls-%03d.ts stream.m3u8
  66
  67 Or, of course, you can use FFmpeg to do the transcoding if you wish.
  68
  69
  70 .. _direct-encoding:
  71
  72 Direct encoding
  73 ---------------
  74
  75 If you do not wish to run an external transcoder, Nageru can
  76 encode high-quality H.264 video directly using
  77 `x264 <http://www.videolan.org/developers/x264.html>`_.
  78 This requires much more CPU power (a fast quadcore is recommended
  79 for a 720p60 stream), since it does not have any assistance from
  80 the GPU, but produces significantly better quality per bit,
  81 and also has much better bitrate control. Even if you use x264,
  82 the stream stored to disk is still the full-quality QSV stream.
  83
  84 Using Nageru's built-in x264 support is strongly preferable to
  85 running an external transcoder on the same machine, since it saves one H.264 decoding
  86 step, and also uses *speed control*. Speed control automatically
  87 turns x264's quality setting up and down to use up all remaining
  88 CPU power after Nageru itself has taken what it needs (but no more);
  89 it can use a range of settings all the way from about x264's
  90 “superfast” preset all the way to about the equivalent of “veryslow”.
  91 Note that this comes at the cost of about one second of extra delay.
  92
  93 Built-in x264 is also useful if you don't have a lot of bandwidth
  94 to your external encoding or distribution machine. You can, however,
  95 still transcode externally to get e.g. a lower-resolution for low-bandwidth
  96 users or segmented HLS; see the previous section for examples.
  97
  98 The built-in x264 encoder is activated using the “--http-x264-video”
  99 flag; e.g.::
 100
 101   ./nageru --http-x264-video --x264-preset veryfast --x264-tune film \
 102     --http-mux mp4 --http-audio-codec aac --http-audio-bitrate 128
 103
 104 Note the use here of the MP4 mux and AAC audio. For speed control, you can use::
 105
 106   ./nageru --x264-speedcontrol --x264-tune film \
 107     --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128
 108
 109 There are many more parameters, in particular “--x264-bitrate” to control
 110 the nominal bitrate (4500 kbit/sec per default, plus audio). Most of them
 111 are usually fine at the default, though. Note that you can change the
 112 x264 bitrate on-the-fly from the video menu; this is primarily useful
 113 if your network conditions change abruptly.
 114
 115
 116 .. _cubemap:
 117
 118 Cubemap integration
 119 -------------------
 120
 121 Even with built-in x264 support, Nageru is not particularly efficient
 122 for delivering streams to end users. For this, a natural choice is
 123 `Cubemap <http://cubemap.sesse.net/>`__; Cubemap scales without problems
 124 to multiple 10 Gbit/sec NICs on a quite normal machine, and you can easily
 125 add multiple Cubemap servers if so needed. Nageru has native support for
 126 Cubemap's *Metacube2* transport encoding; to use it, add “.metacube” to
 127 to the end of the URL, e.g. with a cubemap.config fragment like this::
 128
 129   stream /stream.mp4 src=http://yourserver.example.org:9094/stream.mp4.metacube pacing_rate_kbit=3000 force_prebuffer=1500000
 130
 131 Note that you will want a pacing rate of about 2:1 to your real average
 132 bitrate, in order to provide some for temporary spikes (the default allows
 133 spikes of 2x the nominal bitrate, but only on a one-second basis) and
 134 TCP retransmits. See the Cubemap documentation for more information about
 135 how to set up pacing.
 136
 137
 138 Single-camera stream
 139 --------------------
 140
 141 In addition to the regular mixed stream, you can
 142 siphon out MJPEG streams consisting of a single camera only. This is useful
 143 either for running a very cheap secondary stream (say, a static overview camera
 144 that you would like to show on a separate screen somewhere), or for simple
 145 monitoring during debugging.
 146
 147 The URL for said stream is “http://yourserver.example.org:9095/feeds/N.mp4”,
 148 where N is the card index (starting from zero). The feed is in MJPEG format
 149 and MP4 mux, regardless of other settings, just like the multicamera mux
 150 for Futatabi. (You are allowed to use a card that is not part of the
 151 multicamera mux, if you have limited the number of such cards.) For
 152 more technical details, see :ref:`futatabiformat`. Kaeru can transcode such
 153 streams to a more manageable bitrate/format, if you wish.