Write some more basic Futatabi docs.

[nageru-docs] / streaming.rst

diff --git a/streaming.rst b/streaming.rst
index 3f6e754903bdd88b4719b42dbfc493b2664f1776..e8c09ef313052636d52362ba146c23697f81ca2f 100644 (file)
--- a/streaming.rst
+++ b/streaming.rst
@@ -12,13 +12,15 @@ machines you may have available, you can choose two different
 approaches for streaming: **Transcoded** or **direct**.
 
 
 approaches for streaming: **Transcoded** or **direct**.
 
 

+.. _transcoded-streaming:
+

 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”
 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
+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
 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


@@ -43,12 +45,12 @@ most browsers in the \<video\> tag::
 
   while :; do
     vlc -I dummy -v --network-caching 3000 \
 
   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 '#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
+      --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
 
     sleep 1
   done
 


@@ -70,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
 
     -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
 ---------------
 
 Direct encoding
 ---------------


@@ -104,11 +110,14 @@ flag; e.g.::
     --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
     --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 <https://github.com/mstorsjo/fdk-aac>`_ encoder
+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.
 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.

 
 For speed control, you can use::
 
 
 For speed control, you can use::
 


@@ -117,7 +126,9 @@ For speed control, you can use::
 
 There are many more parameters, in particular “--x264-bitrate” to control
 the nominal bitrate (4500 kbit/sec per default, plus audio). Most of them
 
 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.
+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
 
 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


@@ -125,12 +136,50 @@ around with the default timebase Nageru is using. If so, please add the
 “--http-coarse-timebase” flag.
 
 
 “--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 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
 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


@@ -141,6 +190,20 @@ 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
 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.
 
 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
+