[FFmpeg-devel] [PATCH] Add protocol documentation on RTSP

[Stefano Sabatini]

On date Saturday 2010-10-02 20:38:27 +0300, Martin Storsj? encoded:
> On Sat, 2 Oct 2010, Ronald S. Bultje wrote:
> 
> > On Sat, Oct 2, 2010 at 1:12 PM, Martin Storsj? <martin at martin.st> wrote:
> > > Even though RTSP isn't a protocol handler but a demuxer/muxer, having
> > > documentation on it (including some examples) in protocols.texi may still
> > > be useful.
> > >
> > > Ronald, can you check that the references to Real-RTSP and MS-RTSP are
> > > right, or should it be formulated in some other way?
> > 
> > Real is good to mention separately, I'd include MS in the main RTSP,
> > i.e. "RTSP (with data transferred over RTP; this is used by e.g. Apple
> > and Microsoft) as well as Real-RTSP (...", becuase MS is surprisingly
> > (although not completely) standards-compliant so it's good to give
> > them credit for that.
> 
> Ok, updated.
> 
> > > + at item http
> > > +Use HTTP tunneling as lower transport protocol
> > > + at end table
> > 
> > Include a note that this is useful for passing proxies.
> 
> Done.
> 
> > Can you also include a note on stream selection (-as <num>, -vs <num>,
> > I believe, or pressing a/n while running in ffplay) if the server
> > supports multi-bitrate.
> 
> Sure - I'm not all that familiar with that piece of code, but I wrote 
> something up that shouldn't be too far from the truth :-)
> 
> > Thanks for this patch, documentation is highly appreciated and
> > currently often missing!
> 
> Thanks to Stefano for pioneering this piece of documentation in the first 
> place. :-)
> 
> // Martin

> From 35d88a2c0aa8b6bfb7c2722d17170f565fd78cc2 Mon Sep 17 00:00:00 2001
> From: Martin Storsjo <martin at martin.st>
> Date: Sat, 2 Oct 2010 20:09:44 +0300
> Subject: [PATCH] Add protocol documentation on RTSP
> 
> ---
>  doc/protocols.texi |   70 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 70 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/protocols.texi b/doc/protocols.texi
> index 4f7b42e..c1ff310 100644
> --- a/doc/protocols.texi
> +++ b/doc/protocols.texi
> @@ -217,6 +217,76 @@ ffplay "rtmp://myserver/live/mystream live=1"
>  
>  Real-Time Protocol.
>  
> + at section rtsp
> +
> +RTSP isn't technically a protocol handler in libavformat, it's a demuxer
> +and muxer. The demuxer supports both normal RTSP (with data transferred

Please avoid abbreviations in official docs, that is isn't => is not

> +over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
> +data transferred over RDT).
> +
> +The muxer can be used to send a stream using RTSP ANNOUNCE to a server
> +supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's
> +RTSP server, http://github.com/revmischa/rtsp-server).

@url{http://github.com/revmischa/rtsp-server}

> +
> +The required syntax for a RTSP url is:
> + at example
> +rtsp://@var{hostname}[:@var{port}]/@var{path}[?@var{options}]
> + at end example

Specify that @var{options} are a &-separated list of options of the
form...

> +
> +The following options are supported:
> +
> + at table @option
> +
> + at item udp
> +Use UDP as lower transport protocol
> +
> + at item tcp
> +Use TCP (interleaving within the RTSP control channel) as lower
> +transport protocol
> +
> + at item multicast
> +Use UDP multicast as lower transport protocol
> +
> + at item http
> +Use HTTP tunneling as lower transport protocol, which is useful for
> +passing proxies.

Consistency nit: always use a final dot.

> + at end table
> +
> +Multiple lower transport protocols may be specified, in that case they are
> +tried one at a time (if the setup of one fails, the next one is tried).
> +For the muxer, only the @var{tcp} and @var{udp} options are supported.
> +
> +When receiving data over UDP, the demuxer tries to reorder received packets
> +(since they may arrive out of order, or packets may get lost totally). In
> +order for this to be enabled, a maximum delay must be specified in the
> + at var{max_delay} field of AVFormatContext.
> +

> +With multi-bitrate streams in Real-RTSP, the streams to receive are chosen
> +according to the @var{discard} field in AVStream. When watching such streams

This needs more explanation. How it is possible to see which streams
are received? What @var{discard} does represent? How can it be set
via-commandline?

> +with @file{ffplay}, the streams to display can be chosen with -vst @var{n}
> +and -ast @var{n} for audio and video respectively, and can be switched

> +on the fly by pressing @var{v} and @var{a}.

@code{v} and @code{a} are maybe more appropriate.

> +
> +Example command lines:
> +
> +To watch a stream over UDP, with a max reordering delay of 0.5 seconds:
> +
> + at example
> +ffplay -max_delay 500000 rtsp://server/video.mp4?udp
> + at end example
> +
> +To watch a stream tunneled over HTTP:
> +
> + at example
> +ffplay rtsp://server/video.mp4?http
> + at end example
> +
> +To send a stream in realtime to a RTSP server, for others to watch:
> +
> + at example
> +ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
> + at end example
> +
>  @section tcp

Much thank for the patch.
-- 
FFmpeg = Freak and Frenzy Miracolous Perennial Eager Geisha