From: Steinar H. Gunderson Date: Mon, 7 Nov 2016 17:51:21 +0000 (+0100) Subject: Add a new node about streaming. X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=70e5848af3a67e5465f30698cbdce3375162b143;p=nageru-docs Add a new node about streaming. --- diff --git a/hardware.rst b/hardware.rst index 2a2db48..069240d 100644 --- a/hardware.rst +++ b/hardware.rst @@ -27,6 +27,8 @@ the stack trace pointing into libGL.so, your first intuition should be to check that you have the latest drivers for your GPU. +.. _digital-intermediate: + VA-API H.264 encoding --------------------- diff --git a/index.rst b/index.rst index c6772f8..a53411b 100644 --- a/index.rst +++ b/index.rst @@ -11,6 +11,7 @@ Contents: meintro hardware + streaming Indices and tables diff --git a/streaming.rst b/streaming.rst new file mode 100644 index 0000000..3f6e754 --- /dev/null +++ b/streaming.rst @@ -0,0 +1,146 @@ +Streaming and recording +======================= + +One of the primary purposes of Nageru is to prepare a stream +that is suitable for live broadcast. However, it is *not* +suitable for serving end-users directly; other software is +much more suitable. + +Depending on the amount of CPU power and bandwidth in your +production machine (the one you run Nageru on) and other +machines you may have available, you can choose two different +approaches for streaming: **Transcoded** or **direct**. + + +Transcoded streaming +-------------------- + +Transcoded streaming was the only option supported before 1.3.0, +and in many ways the conceptually simplest from Nageru's point of +view. In this mode, Nageru outputs its “digital intermediate” +H.264 stream (see `:ref:digital-intermediate`), and you are +responsible for transcoding it into a format that is suitable +for streaming to clients. Thus, you can run Nageru on a regular +laptop and then use e.g. a short-term virtual machine in the cloud +to do the heavy lifting for video compression. + +Nageru has a built-in HTTP server that listens on port 9095. +You can get the intermediate by using any filename; by default, +the NUT mux is used, so e.g. “http://yourserver.example.org:9095/stream.nut” +would be appropriate. The NUT mux is chosen because it is among +the few that can carry uncompressed audio easily. It is private +to FFmpeg, and thus understood by almost everything in the free +software world, but perhaps not by all other services. You can +change it with the “--http-mux” parameter, although you might +then also want to change the audio codec to using “--http-audio-codec” +and “--http-audio-bitrate” to something your mux can transport +(see below for more information about audio transcoding). + +The stream be transcoded by a number of programs, most notably +`VLC `_. Here's an example line +transcoding to 1.5 Mbit/sec H.264 suitable for streaming to +most browsers in the \ tag:: + + while :; do + vlc -I dummy -v --network-caching 3000 \ + http://http://yourserver.example.org:9095/stream.nut vlc://quit \ + --sout '#transcode{vcodec=h264,vb=1500,acodec=mp4a,aenc=fdkaac,ab=128}:std{mux=ffmpeg{mux=mp4},access=http{mime=video/mp4},dst=:1994}' \ + --sout-avformat-options '{movflags=empty_moov+frag_keyframe+default_base_moof}' \ + --sout-x264-vbv-maxrate 1500 --sout-x264-vbv-bufsize 1500 --sout-mux-caching 3000 \ + --sout-x264-keyint 50 --sout-mux-caching 3000 \ + --sout-x264-tune film --sout-x264-preset slow + sleep 1 + done + +(The for loop is to restart VLC if Nageru should be restarted. +You can make similar loops around the other example scripts, +or you can e.g. make systemd units for transcoding if you wish.) + +Of course, you may need to adjust the bitrate (and then also +the VBV settings) and preset for your content and CPU usage. +1.5 Mbit/sec is in the lower end of the spectrum for good +720p60 conference video (most TV channels use 12-15 Mbit/sec +for the same format). + +Another variation popular today is to stream using segmented HTTP; +you can use e.g. the ffmpeg command-line tool to segment the HLS +created by VLC into a stream that will be accepted by most smartphones:: + + ffmpeg -i http://127.0.0.1:1994/ -codec copy -f hls \ + -hls_time 2 -hls_wrap 100 -bsf:v h264_mp4toannexb \ + -hls_segment_filename $NAME-hls-%03d.ts stream.m3u8 + + +Direct encoding +--------------- + +If you do not wish to run an external transcoder, Nageru can +encode high-quality H.264 video directly using +`x264 `_. +This requires much more CPU power (a fast quadcore is recommended +for a 720p60 stream), since it does not have any assistance from +the GPU, but produces significantly better quality per bit, +and also has much better bitrate control. Even if you use x264, +the stream stored to disk is still the full-quality QSV stream. + +Using Nageru's built-in x264 support is strongly preferable to +running VLC on the same machine, since it saves one H.264 decoding +step, and also uses *speed control*. Speed control automatically +turns x264's quality setting up and down to use up all remaining +CPU power after Nageru itself has taken what it needs (but no more); +it can use a range of settings all the way from about x264's +“superfast” preset all the way to about the equivalent of “veryslow”. +Note that this comes at the cost of about one second of extra delay. + +Built-in x264 is also useful if you don't have a lot of bandwidth +to your external encoding or distribution machine. You can, however, +still transcode externally to get e.g. a lower-resolution for low-bandwidth +users or segmented HLS; see the previous section for examples. + +The built-in x264 encoder is activated using the “--http-x264-video” +flag; e.g.:: + + ./nageru --http-x264-video --x264-preset veryfast --x264-tune film \ + --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128 + +Note the use here of the MP4 mux and AAC audio. “libfdk_aac” signals +te use of Franhofer's `FDK-AAC `_ encoder +from Android; it yields significantly better sound quality than e.g. FAAC, +and it is open source, but under a somewhat cumbersome license. For this +reason, most distributions do not compile FFmpeg with the FDK-AAC codec, +so you will need to compile FFmpeg yourself, or use a worse codec. + +For speed control, you can use:: + + ./nageru --x264-speedcontrol --x264-tune film \ + --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128 + +There are many more parameters, in particular “--x264-bitrate” to control +the nominal bitrate (4500 kbit/sec per default, plus audio). Most of them +are usually fine at the default, though. + +A particular note about the MP4 mux: If you plan to stream for long periods +continuously (more than about 12–24 hours), the 32-bit timestamps may wrap +around with the default timebase Nageru is using. If so, please add the +“--http-coarse-timebase” flag. + + +Cubemap integration +------------------- + +Even with built-in x264 support, Nageru is not particularly efficient +for delivering streams to end users. For this, a natural choice is +`Cubemap `_; Cubemap scales without problems +to multiple 10 Gbit/sec NICs on a quite normal machine, and you can easily +add multiple Cubemap servers if so needed. Nageru has native support for +Cubemap's *Metacube2* transport encoding; simply add “.metacube” to +to the end of the URL, e.g. with a cubemap.config fragment like this:: + + stream /stream.mp4 src=http://yourserver.example.org:9094/stream.mp4.metacube pacing_rate_kbit=3000 force_prebuffer=1500000 + +Note that you will want a pacing rate of about 2:1 to your real average +bitrate, in order to provide some for temporary spikes (the default allows +spikes of 2x the nominal bitrate, but only on a one-second basis) and +TCP retransmits. See the cubemap documentation for more information about +how to set up pacing. +