Write a section on Kaeru.

diff --git a/streaming.rst b/streaming.rst
index d6c44560b0ce5b882a7eaeb677510d77443f350a..e8c09ef313052636d52362ba146c23697f81ca2f 100644 (file)
--- a/streaming.rst
+++ b/streaming.rst
@@ -45,7 +45,7 @@ most browsers in the \<video\> tag::
 
   while :; do
     vlc -I dummy -v --network-caching 3000 \
-      http://http://yourserver.example.org:9095/stream.nut vlc://quit \
+      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 \
@@ -72,6 +72,10 @@ created by VLC into a stream that will be accepted by most smartphones::
     -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.
+
+
+.. _direct-encoding:
 
 Direct encoding
 ---------------
@@ -132,12 +136,50 @@ 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 <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 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:
+
 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 <http://cubemap.sesse.net/>`_; Cubemap scales without problems
+`Cubemap <http://cubemap.sesse.net/>`__; 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
@@ -148,7 +190,7 @@ to the end of the URL, e.g. with a cubemap.config fragment like this::
 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
+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