--- /dev/null
+Streaming and recording
+=======================
+
+One of the primary purposes of Nageru is to prepare a stream
+that is suitable for live broadcast. However, it is *not*
+suitable for serving end-users directly; other software is
+much more suitable.
+
+Depending on the amount of CPU power and bandwidth in your
+production machine (the one you run Nageru on) and other
+machines you may have available, you can choose two different
+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
+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
+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
+to do the heavy lifting for video compression.
+
+Nageru has a built-in HTTP server that listens on port 9095.
+You can get the intermediate by using any filename; by default,
+the NUT mux is used, so e.g. “http://yourserver.example.org:9095/stream.nut”
+would be appropriate. The NUT mux is chosen because it is among
+the few that can carry uncompressed audio easily. It is private
+to FFmpeg, and thus understood by almost everything in the free
+software world, but perhaps not by all other services. You can
+change it with the “--http-mux” parameter, although you might
+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://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.
+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::
+
+ 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
+
+
+Direct encoding
+---------------
+
+If you do not wish to run an external transcoder, Nageru can
+encode high-quality H.264 video directly using
+`x264 <http://www.videolan.org/developers/x264.html>`_.
+This requires much more CPU power (a fast quadcore is recommended
+for a 720p60 stream), since it does not have any assistance from
+the GPU, but produces significantly better quality per bit,
+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
+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);
+it can use a range of settings all the way from about x264's
+“superfast” preset all the way to about the equivalent of “veryslow”.
+Note that this comes at the cost of about one second of extra delay.
+
+Built-in x264 is also useful if you don't have a lot of bandwidth
+to your external encoding or distribution machine. You can, however,
+still transcode externally to get e.g. a lower-resolution for low-bandwidth
+users or segmented HLS; see the previous section for examples.
+
+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
+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.
+
+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
+are usually fine at the default, though.
+
+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 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
+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 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
+
+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
+how to set up pacing.
+
projects / nageru-docs / commitdiff