X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=streaming.rst;h=52d3664b07096d7b61dc383498b1b1fa9e9b1d1c;hb=HEAD;hp=da427124e5690db156cb2e62c4f7bdf367f6f732;hpb=ca8b32618cb0182937774367aebe599dba2d815b;p=nageru-docs diff --git a/streaming.rst b/streaming.rst index da42712..52d3664 100644 --- a/streaming.rst +++ b/streaming.rst @@ -17,8 +17,7 @@ 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 +Transcoded streaming is 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 @@ -38,41 +37,34 @@ 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://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-x264-keyint 50 --sout-x264-tune film --sout-x264-preset slow \ - --sout-mux-caching 3000 - 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. +The stream can be transcoded by a number of programs, such as +`VLC `_, but Nageru also has its own +transcoder called **Kaeru**, named after the +Japanese verb *kaeru* (換える), meaning roughly to replace or exchange. +Kaeru is a command-line tool that is designed to transcode Nageru's streams. +Since it reuses Nageru's decoding and encoding code, it can do almost everything you can do +with :ref:`direct encoding `, including x264 speed control +and Metacube output (see the section on :ref:`Cubemap integration ` below). + +Using Kaeru is similar to launching Nageru, e.g. to rescale a stream to 848x480 +and output it to a 1.5 Mbit/sec H.264 stream suitable for most browsers in a \ tag:: + + ./kaeru -w 848 -h 480 --http-mux mp4 --http-audio-codec aac --http-audio-bitrate 128 \ + --x264-bitrate 1500 http://yourserver.example.org:9095/stream.nut + 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:: +created by Kaeru 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 -See also the section on :ref:`Kaeru `, below. +Or, of course, you can use FFmpeg to do the transcoding if you wish. .. _direct-encoding: @@ -90,7 +82,7 @@ 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 +running an external transcoder 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); @@ -107,19 +99,9 @@ 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 -the 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. -FFmpeg `recommends `_ -their own native AAC encoder (simply called “aac”) in the absence of any -external libraries. + --http-mux mp4 --http-audio-codec aac --http-audio-bitrate 128 -For speed control, you can use:: +Note the use here of the MP4 mux and AAC audio. For speed control, you can use:: ./nageru --x264-speedcontrol --x264-tune film \ --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128 @@ -130,47 +112,6 @@ are usually fine at the default, though. Note that you can change the x264 bitrate on-the-fly from the video menu; this is primarily useful if your network conditions change abruptly. -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. - - -.. _kaeru: - -Transcoding with Kaeru ----------------------- - -There is a third option that combines elements from the two previous -approaches: Since version 1.6.1, Nageru includes **Kaeru**, named after the -Japanese verb *kaeru* (換える), meaning roughly to replace or exchange. -Kaeru is a command-line tool that is designed to transcode Nageru's streams. -In that aspect, it is similar to using VLC as described in the section on -:ref:`transcoded streaming `. However, since it reuses -Nageru's decoding and encoding code, it can do almost everything you can do -with :ref:`direct encoding `, including x264 speed control -and Metacube output (see the section on :ref:`Cubemap integration ` below). - -Using Kaeru is similar to launching Nageru, e.g. to rescale a stream to 848x480:: - - ./kaeru -w 848 -h 480 --http-mux mp4 --http-audio-codec libfdk_aac --http-audio-bitrate 128 \ - http://yourserver.example.org:9095/stream.nut - -Unlike the VLC option, Kaeru will automatically reconnect if the source goes -away, so you do not need a while loop. Note that if you want to keep the audio -unchanged (usually audio is more important than video, so it's not uncommon to -want to transcode video but not audio), you can do so with the flag -*--no-transcode-audio* flag. - -There are some things you should keep in mind about Kaeru: - - - Kaeru is currently quite experimental, and much less tested than Nageru itself. - - Kaeru does not use the GPU; it uses FFmpeg's code for scaling and colorspace - conversion. This yields somewhat lower scaling quality and uses more CPU power, - but means you can run it on a headless server. - - There is no support for encoding using Quick Sync Video, since this depends on the GPU. - - 10-bit output is currently not supported. - .. _cubemap: @@ -182,7 +123,7 @@ 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 +Cubemap's *Metacube2* transport encoding; to use it, 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 @@ -193,25 +134,11 @@ 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. -For transcoded Cubemap output from VLC you can take exactly the same line as -earlier, just adding “metacube” to the HTTP options:: - - 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,metacube},dst=:1994}' \ - --sout-avformat-options '{movflags=empty_moov+frag_keyframe+default_base_moof}' \ - --sout-x264-vbv-maxrate 1500 --sout-x264-vbv-bufsize 1500 \ - --sout-x264-keyint 50 --sout-x264-tune film --sout-x264-preset slow \ - --sout-mux-caching 3000 - sleep 1 - done - Single-camera stream -------------------- -In addition to the regular mixed stream, you can (since Nageru 1.9.2) +In addition to the regular mixed stream, you can siphon out MJPEG streams consisting of a single camera only. This is useful either for running a very cheap secondary stream (say, a static overview camera that you would like to show on a separate screen somewhere), or for simple