[FFmpeg-devel] [PATCH] Document the SAP muxer

[Stefano Sabatini]

On date Saturday 2010-10-09 17:40:19 +0300, Martin Storsjo encoded:
> ---
>  doc/protocols.texi |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 48 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/protocols.texi b/doc/protocols.texi
> index 88aedb9..05a7feb 100644
> --- a/doc/protocols.texi
> +++ b/doc/protocols.texi
> @@ -287,6 +287,54 @@ To send a stream in realtime to a RTSP server, for others to watch:
>  ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
>  @end example
>  
> + at section sap
> +
> +Session Announcement Protocol. This is not technically a protocol handler
> +in libavformat, it is a muxer.

Maybe it may be a good idea to mention the RFC number, e.g. Session
Announcement Protocol (RFC...).

And BTW maybe this should be placed into a muxdemuxers.texi file, or
even in two distinct files like for indevs/outdevs (not sure is a good
idea in this case), but this can be done in a further patch.

> +It is used for signalling of RTP streams, by announcing the SDP for the
> +streams regularly on a separate port.
> +
> +The syntax for a SAP url given to the muxer is:
> + at example
> +sap://@var{destination}[:@var{port}][?@var{options}]
> + at end example
> +
> +The RTP packets are sent to @var{destination} on port @var{port},
> +or to port 5004 if no port is specified.
> + at var{options} is a @code{&}-separated list. The following options
> +are supported:
> +
> + at table @option
> +
> + at item announce_addr=@var{address}
> +Specify the destination IP address for sending the announcements to.
> +If omitted, the announcements are sent to the commonly used SAP
> +announcement multicast address 224.2.127.254 (sap.mcast.net), or
> +ff0e::2:7ffe if @var{destination} is an IPv6 address.
> +
> + at item announce_port=@var{port}
> +Specify the port to send the announcements on, defaults to
> +9875 if not specified.
> +
> + at item ttl=@var{ttl}
> +Specify the time to live value for the announcements and RTP packets,
> +defaults to 255.
> +
> + at item same_port=@var{0|1}
> +If set to 1, send all RTP streams on the same port pair. If zero (the
> +default), all streams are sent on unique ports, with each stream on a
> +port 2 numbers higher than the previous.
> +VLC/Live555 requires this to be set to 1, to be able to receive the stream.
> + at end table
> +

> +Example command lines:

I'd prefer:
Example command lines follow.

as the incomplete sentence "Example command lines:" followed by
"To broadcast a stream on the local subnet, for watching in VLC:"
looks a little weird.

> +
> +To broadcast a stream on the local subnet, for watching in VLC:
> +
> + at example
> +ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
> + at end example
> +
>  @section tcp

Rest of the patch looks good, thanks.
-- 
FFmpeg = Funny Furious Murdering Picky Ecstatic Geek