Rewrite the streaming documentation; we no longer recommend VLC.

diff --git a/streaming.rst b/streaming.rst
index 6f5ee5903e3dbad73a9ac2e5e57669eee428b102..52d3664b07096d7b61dc383498b1b1fa9e9b1d1c 100644 (file)
--- a/streaming.rst
+++ b/streaming.rst
@@ -37,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 <http://www.videolan.org/>`_. Here's an example line
-transcoding to 1.5 Mbit/sec H.264 suitable for streaming to
-most browsers in the \<video\> 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 <http://www.videolan.org/>`_, 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 <direct-encoding>`, including x264 speed control
+and Metacube output (see the section on :ref:`Cubemap integration <cubemap>` 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 \<video\> 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 <kaeru>`, below.
+Or, of course, you can use FFmpeg to do the transcoding if you wish.
 
 
 .. _direct-encoding:
@@ -89,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);
@@ -106,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 <https://github.com/mstorsjo/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 <https://trac.ffmpeg.org/wiki/Encode/HighQualityAudio>`_
-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
@@ -129,46 +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: 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 <transcoded-streaming>`. However, since it reuses
-Nageru's decoding and encoding code, it can do almost everything you can do
-with :ref:`direct encoding <direct-encoding>`, including x264 speed control
-and Metacube output (see the section on :ref:`Cubemap integration <cubemap>` 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 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:
 
@@ -191,20 +134,6 @@ 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
 --------------------