[FFmpeg-devel] [PATCH] doc/ffserver: add "Detailed description" chapter

[Timothy Gu]

On Fri, Nov 29, 2013 at 7:38 AM, Stefano Sabatini <stefasab at gmail.com> wrote:
> Also move FFM section up in the file, and rename it.
> ---
>  doc/ffserver.texi | 121 ++++++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 108 insertions(+), 13 deletions(-)
>
> diff --git a/doc/ffserver.texi b/doc/ffserver.texi
> index b6ee717..bcaf0b9 100644
> --- a/doc/ffserver.texi
> +++ b/doc/ffserver.texi
> @@ -42,6 +42,114 @@ For each feed you can have different output streams in various
>  formats, each one specified by a @code{<Stream>} section in the
>  configuration file.
>
> + at chapter Detailed description
> +
> + at command{ffserver} works by forwarding streams encoded by
> + at command{ffmpeg}, or pre-recorded streams which are read from disk.
> +

> +Exactly, @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.

I found "exactly" a little weird being used here. I think "precisely"
is a better wording. Here and below.

> +
> +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.
> +
> +Exactly, the feed publish URL is given by:
> + at example
> +http://@var{ffserver_ip_address}:@var{http_port}/@var{feed_name}
> + at end example
> +
> +where @var{ffserver_ip_address} is the IP address of the machine where
> + at command{ffserver} is installed, @var{http_port} is the port number of
> +the HTTP server (configured through the @option{Port} option), and
> + at 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
> + at command{ffserver}, and make 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.
> +
> +Exactly, the stream access URL is given by:
> + at example
> +http://@var{ffserver_ip_address}:@var{http_port}/@var{stream_name}[@var{options}]
> + at end example
> +
> + at 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
> + at 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
> + at command{ffmpeg} when setting up the encoding. This allows
> + at command{ffserver} to define the encoding parameters used for the
> +encoder.
> +
> +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.
> +
> +So you can have for example a situation described by the following
> +graph:
> + at example
> +               _________       __________
> +              |         |     |          |
> +ffmpeg 1 -----| feed 1  |-----| stream 1 |
> +    \         |_________|\    |__________|
> +     \                    \
> +      \                    \   __________
> +       \                    \ |          |
> +        \                    \| stream 2 |
> +         \                    |__________|
> +          \
> +           \   _________       __________
> +            \ |         |     |          |
> +             \| feed 2  |-----| stream 3 |
> +              |_________|     |__________|
> +
> +               _________       __________
> +              |         |     |          |
> +ffmpeg 2 -----| feed 3  |-----| stream 4 |
> +              |_________|     |__________|
> +
> +               _________       __________
> +              |         |     |          |
> +              | file 1  |-----| stream 5 |
> +              |_________|     |__________|
> + at end example
> +
> + at anchor{FFM}
> + at 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
> @@ -165,19 +273,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
>
> - at 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
>
> --
> 1.8.1.2
>
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel at ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel