[FFmpeg-devel] [PATCH] doc/ffserver: document configuration syntax

Wed Nov 27 12:09:56 CET 2013

---
 doc/ffserver.texi | 361 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 361 insertions(+)

diff --git a/doc/ffserver.texi b/doc/ffserver.texi
index 14443e6..dbe5fb0 100644
--- a/doc/ffserver.texi
+++ b/doc/ffserver.texi
@@ -244,6 +244,367 @@ any ffmpeg instances, you will have to launch them manually.
 Enable debug mode. This option increases log verbosity, directs log
 messages to stdout.
 @end table
+
+ at chapter Configuration file syntax
+
+ at command{ffserver} reads a configuration file containing global
+options and settings for each stream.
+
+A line starting with @code{#} is ignored and treated as a comment.
+
+ at section Global options
+ at table @option
+ at item Port @var{port_number}
+ at 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.
+
+If not specified, no corresponding server will be created.
+
+ at item BindAddress @var{ip_address}
+ at item RTSPBindAddress @var{ip_address}
+Set address on which the HTTP/RTPS server is bound. Only useful if you
+have several network interfaces.
+
+ at 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,
+since it defines the @option{MaxClients} maximum limit.
+
+Default value is 2000.
+
+ at item MaxClients @var{n}
+Set number of simultaneous requests that can be handled. Since
+ at command{ffserver} is very fast, it is more likely that you will want
+to leave this high and use @option{MaxBandwidth}.
+
+Default value is 5.
+
+ at item MaxBandwidth @var{kbps}
+Set the maximum amount of kbit/sec that you are prepared to consume
+when streaming to clients.
+
+Default value is 1000.
+
+ at item CustomLog @var{filename}
+Set access log file (uses standard Apache log file format).
+
+'-' is the standard output.
+ at end table
+
+ at section ACL syntax
+An ACL (Access Control List) specifies the address which are allowed
+to access a given stream, or to write a given feed.
+
+It accepts the folling forms
+ at itemize
+ at item
+Allow/deny access to @var{address}.
+ at example
+ACL ALLOW <address>
+ACL DENY <address>
+ at end example
+
+ at item
+Allow/deny access to ranges of addresses from @var{first_address} to
+ at var{last_address}.
+ at example
+ACL ALLOW <first_address> <last_address>
+ACL DENY <first_address> <last_address>
+ at end example
+ at end itemize
+
+You can repeat the ACL allow/deny as often as you like. It is on a per
+stream basis. The first match defines the action. If there are no matches,
+then the default is the inverse of the last ACL statement.
+
+Thus 'ACL allow localhost' only allows access from localhost.
+'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and
+allow everybody else.
+
+ at section Feed section
+
+A Feed section defines a feed provided to @command{ffserver}.
+
+Each live feed contains one video and/or audio sequence coming from an
+ at command{ffmpeg} encoder or another @command{ffserver}. This sequence
+may be encoded simultaneously with several codecs at several
+resolutions.
+
+A feed instance specification is introduced by a line in the form:
+ at example
+<Feed FEED_FILENAME>
+ at end example
+
+where @var{FEED_FILENAME} specifies the unique name of the FFM stream.
+
+It must be followed by a list of options for the feed, and must be
+terminated by the line:
+ at example
+</Feed>
+ at end example
+
+The following options are recognized:
+ at table @option
+ at item File @var{filename}
+Set the path where the file is stored on disk.
+
+ at item FileMaxSize @var{size}
+Set maximum size of the feed. 0 means unlimited.
+
+ at item ReadOnlyFile @var{filename}
+Mark the file as readonly and it will not be deleted or updated.
+
+ at item Launch
+
+ at item ACL
+Specify the list of IP address which are allowed or denied to write
+the feed. Multiple ACL options can be specified.
+ at end table
+
+ at section Stream section
+
+A Stream section defines a stream provided by @command{ffserver}, and
+identified by a single name.
+
+The stream is sent when answering a request containing the stream
+name.
+
+A stream section must be introduced by the line:
+ at example
+<Stream STREAM_NAME>
+ at end example
+
+where @var{STREAM_NAME} specifies the unique name of the stream.
+
+It must be followed by a list of options for the stream, and must be
+terminated by the line
+ at example
+</Stream>
+ at end example
+
+The following options are recognized:
+ at table @option
+ at item Feed @var{feed_name}
+Set the input feed.
+
+Must be specified.
+
+ at item Format @var{format_name}
+Set the format of the stream.
+
+Must be the name of a format recognized by FFmpeg.
+
+ at item AudioBitRate @var{rate}
+Set bitrate for the audio stream. Codecs usually support only a few
+different bitrates.
+
+ at item AudioChannels @var{n}
+Set number of audio channels.
+
+ at item AudioSampleRate @var{n}
+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.
+
+ at item VideoBitRate @var{n}
+Set bitrate for the video stream.
+
+ at item VideoBufferSize @var{n}
+Set ratecontrol buffer size.
+
+ at item VideoFrameRate @var{n}
+Set number of video frames per second.
+
+ at item VideoSize
+Set size of the video frame, must be an abbreviation or in the form
+ at var{W}x at var{H}.  See @ref{video size syntax,,the Video size section
+in the ffmpeg-utils(1) manual,ffmpeg-utils}.
+
+Default value is 160x128.
+
+ at item VideoIntraOnly
+Transmit only intra frames (useful for low bitrates, but kills frame rate).
+
+ at item VideoGopSize @var{n}
+If non-intra only, an intra frame is transmitted every VideoGopSize
+frames. Video synchronization can only begin at an intra frame.
+
+ at item AudioCodec @var{codec_name}
+ at item VideoCodec @var{codec_name}
+Set audio/video codec.
+
+ at item NoAudio
+ at item NoVideo
+Suppress audio/video.
+
+ at item VideoQMin @var{n}
+ at item VideoQMax @var{n}
+Set video qmin/qmax.
+
+ at item Preroll @var{n}
+Set this to the number of seconds backwards in time to start. Note that
+most players will buffer 5-10 seconds of video, and also you need to allow
+for a keyframe to appear in the data stream.
+
+ at item ACL @var{spec}
+Set ACL for the stream.
+
+ at item Author @var{value}
+ at item Comment @var{value}
+ at item Copyright @var{value}
+ at item Title @var{value}
+Set metadata corresponding to the option.
+
+ at item FaviconURL @var{url}
+Set favicon (favourite icon) for the server status page (is ignored
+for regular streams).
+ at end table
+
+ at section Server status stream
+
+A server status stream is a special stream which is used to show
+statistics about the @command{ffserver} operations.
+
+It must be specified setting the option @option{Format} to
+ at code{status}.
+
+ at chapter Stream examples
+
+ at itemize
+ at item
+Multipart JPEG
+ at example
+<Stream test.mjpg>
+Feed feed1.ffm
+Format mpjpeg
+VideoFrameRate 2
+VideoIntraOnly
+NoAudio
+Strict -1
+</Stream>
+ at end example
+
+ at item
+Single JPEG
+ at example
+<Stream test.jpg>
+Feed feed1.ffm
+Format jpeg
+VideoFrameRate 2
+VideoIntraOnly
+#VideoSize 352x240
+NoAudio
+Strict -1
+</Stream>
+ at end example
+
+ at item
+Flash
+ at example
+<Stream test.swf>
+Feed feed1.ffm
+Format swf
+VideoFrameRate 2
+VideoIntraOnly
+NoAudio
+</Stream>
+ at end example
+
+ at item
+ASF compatible
+ at example
+<Stream test.asf>
+Feed feed1.ffm
+Format asf
+VideoFrameRate 15
+VideoSize 352x240
+VideoBitRate 256
+VideoBufferSize 40
+VideoGopSize 30
+AudioBitRate 64
+StartSendOnKey
+</Stream>
+ at end example
+
+ at item
+MP3 audio
+ at example
+<Stream test.mp3>
+Feed feed1.ffm
+Format mp2
+AudioCodec mp3
+AudioBitRate 64
+AudioChannels 1
+AudioSampleRate 44100
+NoVideo
+</Stream>
+ at end example
+
+ at item
+Ogg Vorbis audio:
+ at example
+<Stream test.ogg>
+Feed feed1.ffm
+Title "Stream title"
+AudioBitRate 64
+AudioChannels 2
+AudioSampleRate 44100
+NoVideo
+</Stream>
+ at end example
+
+ at item
+Real with audio only at 32 kbits
+ at example
+<Stream test.ra>
+Feed feed1.ffm
+Format rm
+AudioBitRate 32
+NoVideo
+NoAudio
+</Stream>
+ at end example
+
+ at item
+Real with audio and video at 64 kbits
+ at example
+<Stream test.rm>
+Feed feed1.ffm
+Format rm
+AudioBitRate 32
+VideoBitRate 128
+VideoFrameRate 25
+VideoGopSize 25
+NoAudio
+</Stream>
+ at end example
+
+ at item
+For stream coming from a file: you only need to set the input filename
+and optionally a new format.
+
+ at example
+<Stream file.rm>
+File "/usr/local/httpd/htdocs/tlive.rm"
+NoAudio
+</Stream>
+ at end example
+
+ at example
+<Stream file.asf>
+File "/usr/local/httpd/htdocs/test.asf"
+NoAudio
+Author "Me"
+Copyright "Super MegaCorp"
+Title "Test stream from disk"
+Comment "Test comment"
+</Stream>
+ at end example
+ at end itemize
+
 @c man end
 
 @include config.texi
-- 
1.8.1.2

