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 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{Port} 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 allow 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 URL is given by:
+@example
+http://@var{ffserver_ip_address}:@var{http_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}.
+
+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 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:
+@example
+ _________ __________
+ | | | |
+ffmpeg 1 -----| feed 1 |-----| stream 1 |
+ \ |_________|\ |__________|
+ \ \
+ \ \ __________
+ \ \ | |
+ \ \| stream 2 |
+ \ |__________|
+ \
+ \ _________ __________
+ \ | | | |
+ \| feed 2 |-----| stream 3 |
+ |_________| |__________|
+
+ _________ __________
+ | | | |
+ffmpeg 2 -----| feed 3 |-----| stream 4 |
+ |_________| |__________|
+
+ _________ __________
+ | | | |
+ | file 1 |-----| stream 5 |
+ |_________| |__________|
+@end example
+
+@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
@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:
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
@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.
@end table
@section Feed section
@table @option
@item File @var{filename}
-Set the path where the file is stored on disk.
+@item ReadOnlyFile @var{filename}
+Set the path where the feed file is stored on disk.
+
+If not specified, the @file{/tmp/FEED.ffm} is assumed, where
+@var{FEED} is the feed name.
+
+If @option{ReadOnlyFile} is used the file is marked as read-only and
+it will not be deleted or updated.
+
+@item Truncate
+Truncate the feed file, rather than appending to it. By default
+@command{ffserver} will append data to the file, until the maximum
+file size value is reached (see @option{FileMaxSize} option).
@item FileMaxSize @var{size}
-Set maximum size of the feed. 0 means unlimited.
+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.
-@item ReadOnlyFile @var{filename}
-Mark the file as readonly and it will not be deleted or updated.
+Default value is 5M.
@item Launch @var{args}
Launch an @command{ffmpeg} command when creating @command{ffserver}.
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
The following options are recognized within a Stream section.
+Encoding options are marked with the @emph{encoding} tag, and they are
+used to set the encoding parameters, and are mapped to libavcodec
+encoding options. Not all encoding options are supported, in
+particular it is not possible to set encoder private options. In order
+to override the encoding options specified by @command{ffserver}, you
+can use the @command{ffmpeg} @option{override_ffserver} commandline
+option.
+
+Only one of the @option{Feed} and @option{File} options should be set.
+
@table @option
@item Feed @var{feed_name}
-Set the input feed.
+Set the input feed. @var{feed_name} must correspond to an existing
+feed defined in a @code{Feed} section.
+
+When this option is set, encoding options are used to setup the
+encoding operated by the remote @command{ffmpeg} process.
+
+@item File @var{filename}
+Set the filename of the pre-recorded input file to stream.
-Must be specified for regular streams.
+When this option is set, encoding options are ignored and the input
+file content is re-streamed as is.
@item Format @var{format_name}
Set the format of the output stream.
@item DynamicACL @var{spec}
-@item RTSPOtion @var{option}
+@item RTSPOption @var{option}
@item MulticastAddress @var{address}
@item NoVideo
Suppress audio/video.
-@item AudioBitRate @var{rate}
+@item AudioCodec @var{codec_name} (@emph{encoding,audio})
+Set audio codec.
+
+@item AudioBitRate @var{rate} (@emph{encoding,audio})
Set bitrate for the audio stream in kbits per second.
-@item AudioChannels @var{n}
+@item AudioChannels @var{n} (@emph{encoding,audio})
Set number of audio channels.
-@item AudioSampleRate @var{n}
+@item AudioSampleRate @var{n} (@emph{encoding,audio})
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 VideoBitRate @var{n}
+@item AVOptionAudio @var{option} @var{value} (@emph{encoding,audio})
+Set generic option for audio stream.
+
+@item AVPresetAudio @var{preset} (@emph{encoding,audio})
+Set preset for audio stream.
+
+@item VideoCodec @var{codec_name} (@emph{encoding,video})
+Set video codec.
+
+@item VideoBitRate @var{n} (@emph{encoding,video})
Set bitrate for the video stream in kbits per second.
-@item VideoBitRateRange @var{range}
+@item VideoBitRateRange @var{range} (@emph{encoding,video})
Set video bitrate range.
A range must be specified in the form @var{minrate}-@var{maxrate}, and
specifies the @option{minrate} and @option{maxrate} encoding options
expressed in kbits per second.
-@item VideoBitRateRangeTolerance @var{n}
+@item VideoBitRateRangeTolerance @var{n} (@emph{encoding,video})
Set video bitrate tolerance in kbits per second.
-@item PixelFormat @var{pixel_format}
+@item PixelFormat @var{pixel_format} (@emph{encoding,video})
Set video pixel format.
-@item Debug @var{integer}
+@item Debug @var{integer} (@emph{encoding,video})
Set video @option{debug} encoding option.
-@item Strict @var{integer}
+@item Strict @var{integer} (@emph{encoding,video})
Set video @option{strict} encoding option.
-@item VideoBufferSize @var{n}
+@item VideoBufferSize @var{n} (@emph{encoding,video})
Set ratecontrol buffer size, expressed in KB.
-@item VideoFrameRate @var{n}
+@item VideoFrameRate @var{n} (@emph{encoding,video})
Set number of video frames per second.
-@item VideoSize
+@item VideoSize (@emph{encoding,video})
Set size of the video frame, must be an abbreviation or in the form
@var{W}x@var{H}. See @ref{video size syntax,,the Video size section
in the ffmpeg-utils(1) manual,ffmpeg-utils}.
Default value is @code{160x128}.
-@item VideoIntraOnly
+@item VideoIntraOnly (@emph{encoding,video})
Transmit only intra frames (useful for low bitrates, but kills frame rate).
-@item VideoGopSize @var{n}
+@item VideoGopSize @var{n} (@emph{encoding,video})
If non-intra only, an intra frame is transmitted every VideoGopSize
frames. Video synchronization can only begin at an intra frame.
-@item VideoTag @var{tag}
+@item VideoTag @var{tag} (@emph{encoding,video})
Set video tag.
-@item VideoHighQuality
-@item Video4MotionVector
+@item VideoHighQuality (@emph{encoding,video})
+@item Video4MotionVector (@emph{encoding,video})
-@item BitExact
+@item BitExact (@emph{encoding,video})
Set bitexact encoding flag.
-@item IdctSimple
+@item IdctSimple (@emph{encoding,video})
Set simple IDCT algorithm.
-@item Qscale @var{n}
+@item Qscale @var{n} (@emph{encoding,video})
Enable constant quality encoding, and set video qscale (quantization
scale) value, expressed in @var{n} QP units.
-@item VideoQMin @var{n}
-@item VideoQMax @var{n}
+@item VideoQMin @var{n} (@emph{encoding,video})
+@item VideoQMax @var{n} (@emph{encoding,video})
Set video qmin/qmax.
-@item VideoQDiff @var{integer}
+@item VideoQDiff @var{integer} (@emph{encoding,video})
Set video @option{qdiff} encoding option.
-@item LumiMask @var{float}
-@item DarkMask @var{float}
+@item LumiMask @var{float} (@emph{encoding,video})
+@item DarkMask @var{float} (@emph{encoding,video})
Set @option{lumi_mask}/@option{dark_mask} encoding options.
-@item AudioCodec @var{codec_name}
-@item VideoCodec @var{codec_name}
-Set audio/video codec.
+@item AVOptionVideo @var{option} @var{value} (@emph{encoding,video})
+Set generic option for video stream.
-@item AVOptionAudio @var{option} @var{value}
-@item AVOptionVideo @var{option} @var{value}
-Set generic option for audio/video stream.
-
-@item AVPresetAudio @var{preset}
-@item AVOptionVideo @var{preset}
-Set preset for audio/video stream.
+@item AVPresetVideo @var{preset} (@emph{encoding,video})
+Set preset for video stream.
@var{preset} must be the path of a preset file.
@end table
Format jpeg
VideoFrameRate 2
VideoIntraOnly
-#VideoSize 352x240
+VideoSize 352x240
NoAudio
Strict -1
</Stream>
@end example
@item
-Ogg Vorbis audio:
+Ogg Vorbis audio
@example
<Stream test.ogg>
Feed feed1.ffm
Format rm
AudioBitRate 32
NoVideo
-NoAudio
</Stream>
@end example
VideoBitRate 128
VideoFrameRate 25
VideoGopSize 25
-NoAudio
</Stream>
@end example