Document unsynchronized HDMI/SDI output.

[nageru-docs] / streaming.rst

diff --git a/streaming.rst b/streaming.rst
index 3f6e754903bdd88b4719b42dbfc493b2664f1776..52d3664b07096d7b61dc383498b1b1fa9e9b1d1c 100644 (file)
--- a/streaming.rst
+++ b/streaming.rst
@@ -12,13 +12,14 @@ 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
 --------------------
 

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


@@ -36,40 +37,37 @@ 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).
 
 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://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.
+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
 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
 
 
   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
 

+Or, of course, you can use FFmpeg to do the transcoding if you wish.
+
+
+.. _direct-encoding:

 
 Direct encoding
 ---------------
 
 Direct encoding
 ---------------


@@ -84,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
 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);
 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);


@@ -101,39 +99,31 @@ 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 \
 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 <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.
+    --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
 
 There are many more parameters, in particular “--x264-bitrate” to control
 the nominal bitrate (4500 kbit/sec per default, plus audio). Most of them
 
   ./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.
+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.

 
 

+.. _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
 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
 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


@@ -141,6 +131,23 @@ 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.
 

+
+Single-camera stream
+--------------------
+
+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
+monitoring during debugging.
+
+The URL for said stream is “http://yourserver.example.org:9095/feeds/N.mp4”,
+where N is the card index (starting from zero). The feed is in MJPEG format
+and MP4 mux, regardless of other settings, just like the multicamera mux
+for Futatabi. (You are allowed to use a card that is not part of the
+multicamera mux, if you have limited the number of such cards.) For
+more technical details, see :ref:`futatabiformat`. Kaeru can transcode such
+streams to a more manageable bitrate/format, if you wish.