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 was the only option supported before 1.3.0,
  21 and in many ways the conceptually simplest from Nageru's point of
  22 view. In this mode, Nageru outputs its “digital intermediate”
  23 H.264 stream (see :ref:`digital-intermediate`), and you are
  24 responsible for transcoding it into a format that is suitable
  25 for streaming to clients. Thus, you can run Nageru on a regular
  26 laptop and then use e.g. a short-term virtual machine in the cloud
  27 to do the heavy lifting for video compression.
  28
  29 Nageru has a built-in HTTP server that listens on port 9095.
  30 You can get the intermediate by using any filename; by default,
  31 the NUT mux is used, so e.g. “http://yourserver.example.org:9095/stream.nut”
  32 would be appropriate. The NUT mux is chosen because it is among
  33 the few that can carry uncompressed audio easily. It is private
  34 to FFmpeg, and thus understood by almost everything in the free
  35 software world, but perhaps not by all other services. You can
  36 change it with the “--http-mux” parameter, although you might
  37 then also want to change the audio codec to using “--http-audio-codec”
  38 and “--http-audio-bitrate” to something your mux can transport
  39 (see below for more information about audio transcoding).
  40
  41 The stream be transcoded by a number of programs, most notably
  42 `VLC <http://www.videolan.org/>`_. Here's an example line
  43 transcoding to 1.5 Mbit/sec H.264 suitable for streaming to
  44 most browsers in the \<video\> tag::
  45
  46   while :; do
  47     vlc -I dummy -v --network-caching 3000 \
  48       http://http://yourserver.example.org:9095/stream.nut vlc://quit \
  49       --sout '#transcode{vcodec=h264,vb=1500,acodec=mp4a,aenc=fdkaac,ab=128}:std{mux=ffmpeg{mux=mp4},access=http{mime=video/mp4},dst=:1994}' \
  50       --sout-avformat-options '{movflags=empty_moov+frag_keyframe+default_base_moof}' \
  51       --sout-x264-vbv-maxrate 1500 --sout-x264-vbv-bufsize 1500 \
  52       --sout-x264-keyint 50 --sout-x264-tune film --sout-x264-preset slow \
  53       --sout-mux-caching 3000
  54     sleep 1
  55   done
  56
  57 (The for loop is to restart VLC if Nageru should be restarted.
  58 You can make similar loops around the other example scripts,
  59 or you can e.g. make systemd units for transcoding if you wish.)
  60
  61 Of course, you may need to adjust the bitrate (and then also
  62 the VBV settings) and preset for your content and CPU usage.
  63 1.5 Mbit/sec is in the lower end of the spectrum for good
  64 720p60 conference video (most TV channels use 12-15 Mbit/sec
  65 for the same format).
  66
  67 Another variation popular today is to stream using segmented HTTP;
  68 you can use e.g. the ffmpeg command-line tool to segment the HLS
  69 created by VLC into a stream that will be accepted by most smartphones::
  70
  71   ffmpeg -i http://127.0.0.1:1994/ -codec copy -f hls \
  72     -hls_time 2 -hls_wrap 100 -bsf:v h264_mp4toannexb \
  73     -hls_segment_filename $NAME-hls-%03d.ts stream.m3u8
  74
  75
  76 Direct encoding
  77 ---------------
  78
  79 If you do not wish to run an external transcoder, Nageru can
  80 encode high-quality H.264 video directly using
  81 `x264 <http://www.videolan.org/developers/x264.html>`_.
  82 This requires much more CPU power (a fast quadcore is recommended
  83 for a 720p60 stream), since it does not have any assistance from
  84 the GPU, but produces significantly better quality per bit,
  85 and also has much better bitrate control. Even if you use x264,
  86 the stream stored to disk is still the full-quality QSV stream.
  87
  88 Using Nageru's built-in x264 support is strongly preferable to
  89 running VLC on the same machine, since it saves one H.264 decoding
  90 step, and also uses *speed control*. Speed control automatically
  91 turns x264's quality setting up and down to use up all remaining
  92 CPU power after Nageru itself has taken what it needs (but no more);
  93 it can use a range of settings all the way from about x264's
  94 “superfast” preset all the way to about the equivalent of “veryslow”.
  95 Note that this comes at the cost of about one second of extra delay.
  96
  97 Built-in x264 is also useful if you don't have a lot of bandwidth
  98 to your external encoding or distribution machine. You can, however,
  99 still transcode externally to get e.g. a lower-resolution for low-bandwidth
 100 users or segmented HLS; see the previous section for examples.
 101
 102 The built-in x264 encoder is activated using the “--http-x264-video”
 103 flag; e.g.::
 104
 105   ./nageru --http-x264-video --x264-preset veryfast --x264-tune film \
 106     --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128
 107
 108 Note the use here of the MP4 mux and AAC audio. “libfdk_aac” signals
 109 the use of Franhofer's `FDK-AAC <https://github.com/mstorsjo/fdk-aac>`_ encoder
 110 from Android; it yields significantly better sound quality than e.g. FAAC,
 111 and it is open source, but under a somewhat cumbersome license. For this
 112 reason, most distributions do not compile FFmpeg with the FDK-AAC codec,
 113 so you will need to compile FFmpeg yourself, or use a worse codec.
 114 FFmpeg `recommends <https://trac.ffmpeg.org/wiki/Encode/HighQualityAudio>`_
 115 their own native AAC encoder (simply called “aac”) in the absence of any
 116 external libraries.
 117
 118 For speed control, you can use::
 119
 120   ./nageru --x264-speedcontrol --x264-tune film \
 121     --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128
 122
 123 There are many more parameters, in particular “--x264-bitrate” to control
 124 the nominal bitrate (4500 kbit/sec per default, plus audio). Most of them
 125 are usually fine at the default, though. Note that you can change the
 126 x264 bitrate on-the-fly from the video menu; this is primarily useful
 127 if your network conditions change abruptly.
 128
 129 A particular note about the MP4 mux: If you plan to stream for long periods
 130 continuously (more than about 12–24 hours), the 32-bit timestamps may wrap
 131 around with the default timebase Nageru is using. If so, please add the
 132 “--http-coarse-timebase” flag.
 133
 134
 135 Cubemap integration
 136 -------------------
 137
 138 Even with built-in x264 support, Nageru is not particularly efficient
 139 for delivering streams to end users. For this, a natural choice is
 140 `Cubemap <http://cubemap.sesse.net/>`_; Cubemap scales without problems
 141 to multiple 10 Gbit/sec NICs on a quite normal machine, and you can easily
 142 add multiple Cubemap servers if so needed. Nageru has native support for
 143 Cubemap's *Metacube2* transport encoding; simply add “.metacube” to
 144 to the end of the URL, e.g. with a cubemap.config fragment like this::
 145
 146   stream /stream.mp4 src=http://yourserver.example.org:9094/stream.mp4.metacube pacing_rate_kbit=3000 force_prebuffer=1500000
 147
 148 Note that you will want a pacing rate of about 2:1 to your real average
 149 bitrate, in order to provide some for temporary spikes (the default allows
 150 spikes of 2x the nominal bitrate, but only on a one-second basis) and
 151 TCP retransmits. See the cubemap documentation for more information about
 152 how to set up pacing.
 153
 154 For transcoded Cubemap output from VLC you can take exactly the same line as
 155 earlier, just adding “metacube” to the HTTP options::
 156
 157   while :; do
 158     vlc -I dummy -v --network-caching 3000 \
 159       http://http://yourserver.example.org:9095/stream.nut vlc://quit \
 160       --sout '#transcode{vcodec=h264,vb=1500,acodec=mp4a,aenc=fdkaac,ab=128}:std{mux=ffmpeg{mux=mp4},access=http{mime=video/mp4,metacube},dst=:1994}' \
 161       --sout-avformat-options '{movflags=empty_moov+frag_keyframe+default_base_moof}' \
 162       --sout-x264-vbv-maxrate 1500 --sout-x264-vbv-bufsize 1500 \
 163       --sout-x264-keyint 50 --sout-x264-tune film --sout-x264-preset slow \
 164       --sout-mux-caching 3000
 165     sleep 1
 166   done
 167