Merge commit '489e6add4478b0f5717dbf644234c6f3a3baf02c'
[ffmpeg.git] / doc / ffserver.texi
index 4d4b7a8..ad48f47 100644 (file)
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle ffserver Documentation
 @titlepage
@@ -42,6 +43,124 @@ For each feed you can have different output streams in various
 formats, each one specified by a @code{<Stream>} section in the
 configuration file.
 
+@chapter Detailed description
+
+@command{ffserver} works by forwarding streams encoded by
+@command{ffmpeg}, or pre-recorded streams which are read from disk.
+
+Precisely, @command{ffserver} acts as an HTTP server, accepting POST
+requests from @command{ffmpeg} to acquire the stream to publish, and
+serving RTSP clients or HTTP clients GET requests with the stream
+media content.
+
+A feed is an @ref{FFM} stream created by @command{ffmpeg}, and sent to
+a port where @command{ffserver} is listening.
+
+Each feed is identified by a unique name, corresponding to the name
+of the resource published on @command{ffserver}, and is configured by
+a dedicated @code{Feed} section in the configuration file.
+
+The feed publish URL is given by:
+@example
+http://@var{ffserver_ip_address}:@var{http_port}/@var{feed_name}
+@end example
+
+where @var{ffserver_ip_address} is the IP address of the machine where
+@command{ffserver} is installed, @var{http_port} is the port number of
+the HTTP server (configured through the @option{HTTPPort} option), and
+@var{feed_name} is the name of the corresponding feed defined in the
+configuration file.
+
+Each feed is associated to a file which is stored on disk. This stored
+file is used to send pre-recorded data to a player as fast as
+possible when new content is added in real-time to the stream.
+
+A "live-stream" or "stream" is a resource published by
+@command{ffserver}, and made accessible through the HTTP protocol to
+clients.
+
+A stream can be connected to a feed, or to a file. In the first case,
+the published stream is forwarded from the corresponding feed
+generated by a running instance of @command{ffmpeg}, in the second
+case the stream is read from a pre-recorded file.
+
+Each stream is identified by a unique name, corresponding to the name
+of the resource served by @command{ffserver}, and is configured by
+a dedicated @code{Stream} section in the configuration file.
+
+The stream access HTTP URL is given by:
+@example
+http://@var{ffserver_ip_address}:@var{http_port}/@var{stream_name}[@var{options}]
+@end example
+
+The stream access RTSP URL is given by:
+@example
+http://@var{ffserver_ip_address}:@var{rtsp_port}/@var{stream_name}[@var{options}]
+@end example
+
+@var{stream_name} is the name of the corresponding stream defined in
+the configuration file. @var{options} is a list of options specified
+after the URL which affects how the stream is served by
+@command{ffserver}. @var{http_port} and @var{rtsp_port} are the HTTP
+and RTSP ports configured with the options @var{HTTPPort} and
+@var{RTSPPort} respectively.
+
+In case the stream is associated to a feed, the encoding parameters
+must be configured in the stream configuration. They are sent to
+@command{ffmpeg} when setting up the encoding. This allows
+@command{ffserver} to define the encoding parameters used by
+the @command{ffmpeg} encoders.
+
+The @command{ffmpeg} @option{override_ffserver} commandline option
+allows one to override the encoding parameters set by the server.
+
+Multiple streams can be connected to the same feed.
+
+For example, you can have a situation described by the following
+graph:
+
+@verbatim
+               _________       __________
+              |         |     |          |
+ffmpeg 1 -----| feed 1  |-----| stream 1 |
+    \         |_________|\    |__________|
+     \                    \
+      \                    \   __________
+       \                    \ |          |
+        \                    \| stream 2 |
+         \                    |__________|
+          \
+           \   _________       __________
+            \ |         |     |          |
+             \| feed 2  |-----| stream 3 |
+              |_________|     |__________|
+
+               _________       __________
+              |         |     |          |
+ffmpeg 2 -----| feed 3  |-----| stream 4 |
+              |_________|     |__________|
+
+               _________       __________
+              |         |     |          |
+              | file 1  |-----| stream 5 |
+              |_________|     |__________|
+
+@end verbatim
+
+@anchor{FFM}
+@section FFM, FFM2 formats
+
+FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of
+video and audio streams and encoding options, and can store a moving time segment
+of an infinite movie or a whole movie.
+
+FFM is version specific, and there is limited compatibility of FFM files
+generated by one version of ffmpeg/ffserver and another version of
+ffmpeg/ffserver. It may work but it is not guaranteed to work.
+
+FFM2 is extensible while maintaining compatibility and should work between
+differing versions of tools. FFM2 is the default.
+
 @section Status stream
 
 @command{ffserver} supports an HTTP interface which exposes the
@@ -66,13 +185,6 @@ the special stream @file{status.html} is requested.
 
 @section How do I make it work?
 
-First, build the kit. It *really* helps to have installed LAME first. Then when
-you run the ffserver ./configure, make sure that you have the
-@code{--enable-libmp3lame} flag turned on.
-
-LAME is important as it allows for streaming audio to Windows Media Player.
-Don't ask why the other audio types do not work.
-
 As a simple test, just run the following two command lines where INPUTFILE
 is some file which you can decode with ffmpeg:
 
@@ -94,11 +206,9 @@ WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
 transfer the entire file before starting to play.
 The same is true of AVI files.
 
-@section What happens next?
-
-You should edit the ffserver.conf file to suit your needs (in terms of
-frame rates etc). Then install ffserver and ffmpeg, write a script to start
-them up, and off you go.
+You should edit the @file{ffserver.conf} file to suit your needs (in
+terms of frame rates etc). Then install @command{ffserver} and
+@command{ffmpeg}, write a script to start them up, and off you go.
 
 @section What else can it do?
 
@@ -172,19 +282,6 @@ You use this by adding the ?date= to the end of the URL for the stream.
 For example:   @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
 @c man end
 
-@section What is FFM, FFM2
-
-FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of
-video and audio streams and encoding options, and can store a moving time segment
-of an infinite movie or a whole movie.
-
-FFM is version specific, and there is limited compatibility of FFM files
-generated by one version of ffmpeg/ffserver and another version of
-ffmpeg/ffserver. It may work but it is not guaranteed to work.
-
-FFM2 is extensible while maintaining compatibility and should work between
-differing versions of tools. FFM2 is the default.
-
 @chapter Options
 @c man begin OPTIONS
 
@@ -258,20 +355,29 @@ allow everybody else.
 
 @section Global options
 @table @option
+@item HTTPPort @var{port_number}
 @item Port @var{port_number}
 @item RTSPPort @var{port_number}
 
-Set TCP port number on which the HTTP/RTSP server is listening. You
-must select a different port from your standard HTTP web server if it
-is running on the same computer.
+@var{HTTPPort} sets the HTTP server listening TCP port number,
+@var{RTSPPort} sets the RTSP server listening TCP port number.
+
+@var{Port} is the equivalent of @var{HTTPPort} and is deprecated.
+
+You must select a different port from your standard HTTP web server if
+it is running on the same computer.
 
 If not specified, no corresponding server will be created.
 
+@item HTTPBindAddress @var{ip_address}
 @item BindAddress @var{ip_address}
 @item RTSPBindAddress @var{ip_address}
 Set address on which the HTTP/RTSP server is bound. Only useful if you
 have several network interfaces.
 
+@var{BindAddress} is the equivalent of @var{HTTPBindAddress} and is
+deprecated.
+
 @item MaxHTTPConnections @var{n}
 Set number of simultaneous HTTP connections that can be handled. It
 has to be defined @emph{before} the @option{MaxClients} parameter,
@@ -303,8 +409,14 @@ ignored, and the log is written to standard output.
 
 @item NoDaemon
 Set no-daemon mode. This option is currently ignored since now
-@command{ffserver} will work in no-daemon mode, and is deprecated.
-
+@command{ffserver} will always work in no-daemon mode, and is
+deprecated.
+
+@item UseDefaults
+@item NoDefaults
+Control whether default codec options are used for the all streams or not.
+Each stream may overwrite this setting for its own. Default is @var{UseDefaults}.
+The lastest occurrence overrides previous if multiple definitions.
 @end table
 
 @section Feed section
@@ -342,8 +454,9 @@ Truncate the feed file, rather than appending to it. By default
 file size value is reached (see @option{FileMaxSize} option).
 
 @item FileMaxSize @var{size}
-Set maximum size of the feed. 0 means unlimited. The postfixes
-@code{K}, @code{M}, and @code{G} are recognized.
+Set maximum size of the feed file in bytes. 0 means unlimited. The
+postfixes @code{K} (2^10), @code{M} (2^20), and @code{G} (2^30) are
+recognized.
 
 Default value is 5M.
 
@@ -366,7 +479,7 @@ e.g. if you need to generate multiple FFM feeds with a single
 This option is ignored in case the commandline option @option{-n} is
 specified.
 
-@item ACL
+@item ACL @var{spec}
 Specify the list of IP address which are allowed or denied to write
 the feed. Multiple ACL options can be specified.
 @end table
@@ -443,7 +556,7 @@ Set ACL for the stream.
 
 @item DynamicACL @var{spec}
 
-@item RTSPOtion @var{option}
+@item RTSPOption @var{option}
 
 @item MulticastAddress @var{address}
 
@@ -461,7 +574,16 @@ for regular streams.
 @item Comment @var{value}
 @item Copyright @var{value}
 @item Title @var{value}
-Set metadata corresponding to the option.
+Set metadata corresponding to the option. All these options are
+deprecated in favor of @option{Metadata}.
+
+@item Metadata @var{key} @var{value}
+Set metadata value on the output stream.
+
+@item UseDefaults
+@item NoDefaults
+Control whether default codec options are used for the stream or not.
+Default is @var{UseDefaults} unless disabled globally.
 
 @item NoAudio
 @item NoVideo
@@ -481,8 +603,9 @@ Set sampling frequency for audio. When using low bitrates, you should
 lower this frequency to 22050 or 11025. The supported frequencies
 depend on the selected audio codec.
 
-@item AVOptionAudio @var{option} @var{value} (@emph{encoding,audio})
-Set generic option for audio stream.
+@item AVOptionAudio [@var{codec}:]@var{option} @var{value} (@emph{encoding,audio})
+Set generic or private option for audio stream.
+Private option must be prefixed with codec name or codec must be defined before.
 
 @item AVPresetAudio @var{preset} (@emph{encoding,audio})
 Set preset for audio stream.
@@ -559,8 +682,9 @@ Set video @option{qdiff} encoding option.
 @item DarkMask @var{float} (@emph{encoding,video})
 Set @option{lumi_mask}/@option{dark_mask} encoding options.
 
-@item AVOptionVideo @var{option} @var{value} (@emph{encoding,video})
-Set generic option for video stream.
+@item AVOptionVideo [@var{codec}:]@var{option} @var{value} (@emph{encoding,video})
+Set generic or private option for video stream.
+Private option must be prefixed with codec name or codec must be defined before.
 
 @item AVPresetVideo @var{preset} (@emph{encoding,video})
 Set preset for video stream.
@@ -664,11 +788,11 @@ NoVideo
 @end example
 
 @item
-Ogg Vorbis audio:
+Ogg Vorbis audio
 @example
 <Stream test.ogg>
 Feed feed1.ffm
-Title "Stream title"
+Metadata title "Stream title"
 AudioBitRate 64
 AudioChannels 2
 AudioSampleRate 44100
@@ -684,7 +808,6 @@ Feed feed1.ffm
 Format rm
 AudioBitRate 32
 NoVideo
-NoAudio
 </Stream>
 @end example
 
@@ -698,7 +821,6 @@ AudioBitRate 32
 VideoBitRate 128
 VideoFrameRate 25
 VideoGopSize 25
-NoAudio
 </Stream>
 @end example
 
@@ -717,10 +839,10 @@ NoAudio
 <Stream file.asf>
 File "/usr/local/httpd/htdocs/test.asf"
 NoAudio
-Author "Me"
-Copyright "Super MegaCorp"
-Title "Test stream from disk"
-Comment "Test comment"
+Metadata author "Me"
+Metadata copyright "Super MegaCorp"
+Metadata title "Test stream from disk"
+Metadata comment "Test comment"
 </Stream>
 @end example
 @end itemize