Commit 8c8c3ca9 authored by Stefano Sabatini's avatar Stefano Sabatini

doc/protocols/rtsp, lavf/rtsp: fix/extend options documentation

parent 704c217f
...@@ -661,6 +661,8 @@ set to the the local RTP port value plus 1. ...@@ -661,6 +661,8 @@ set to the the local RTP port value plus 1.
@section rtsp @section rtsp
Real-Time Streaming Protocol.
RTSP is not technically a protocol handler in libavformat, it is a demuxer RTSP is not technically a protocol handler in libavformat, it is a demuxer
and muxer. The demuxer supports both normal RTSP (with data transferred and muxer. The demuxer supports both normal RTSP (with data transferred
over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
...@@ -675,14 +677,22 @@ The required syntax for a RTSP url is: ...@@ -675,14 +677,22 @@ The required syntax for a RTSP url is:
rtsp://@var{hostname}[:@var{port}]/@var{path} rtsp://@var{hostname}[:@var{port}]/@var{path}
@end example @end example
The following options (set on the @command{ffmpeg}/@command{ffplay} command Options can be set on the @command{ffmpeg}/@command{ffplay} command
line, or set in code via @code{AVOption}s or in @code{avformat_open_input}), line, or set in code via @code{AVOption}s or in
are supported: @code{avformat_open_input}.
Flags for @code{rtsp_transport}: The following options are supported.
@table @option @table @option
@item initial_pause
Do not start playing the stream immediately if set to 1. Default value
is 0.
@item rtsp_transport
Set RTSP trasport protocols.
It accepts the following values:
@table @samp
@item udp @item udp
Use UDP as lower transport protocol. Use UDP as lower transport protocol.
...@@ -700,17 +710,56 @@ passing proxies. ...@@ -700,17 +710,56 @@ passing proxies.
Multiple lower transport protocols may be specified, in that case they are 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). tried one at a time (if the setup of one fails, the next one is tried).
For the muxer, only the @code{tcp} and @code{udp} options are supported. For the muxer, only the @samp{tcp} and @samp{udp} options are supported.
Flags for @code{rtsp_flags}: @item rtsp_flags
Set RTSP flags.
@table @option The following values are accepted:
@table @samp
@item filter_src @item filter_src
Accept packets only from negotiated peer address and port. Accept packets only from negotiated peer address and port.
@item listen @item listen
Act as a server, listening for an incoming connection. Act as a server, listening for an incoming connection.
@end table @end table
Default value is @samp{none}.
@item allowed_media_types
Set media types to accept from the server.
The following flags are accepted:
@table @samp
@item video
@item audio
@item data
@end table
By default it accepts all media types.
@item min_port
Set minimum local UDP port. Default value is 5000.
@item max_port
Set maximum local UDP port. Default value is 65000.
@item timeout
Set maximum timeout (in seconds) to wait for incoming connections.
A value of -1 mean infinite (default). This option implies the
@option{rtsp_flags} set to @samp{listen}.
@item reorder_queue_size
Set number of packets to buffer for handling of reordered packets.
@item stimeout
Set socket TCP I/O timeout in micro seconds.
@item user-agent
Override User-Agent header. If not specified, it default to the
libavformat identifier string.
@end table
When receiving data over UDP, the demuxer tries to reorder received packets 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). This (since they may arrive out of order, or packets may get lost totally). This
can be disabled by setting the maximum demuxing delay to zero (via can be disabled by setting the maximum demuxing delay to zero (via
...@@ -721,36 +770,36 @@ streams to display can be chosen with @code{-vst} @var{n} and ...@@ -721,36 +770,36 @@ streams to display can be chosen with @code{-vst} @var{n} and
@code{-ast} @var{n} for video and audio respectively, and can be switched @code{-ast} @var{n} for video and audio respectively, and can be switched
on the fly by pressing @code{v} and @code{a}. on the fly by pressing @code{v} and @code{a}.
Example command lines: @subsection Examples
To watch a stream over UDP, with a max reordering delay of 0.5 seconds: The following examples all make use of the @command{ffplay} and
@command{ffmpeg} tools.
@itemize
@item
Watch a stream over UDP, with a max reordering delay of 0.5 seconds:
@example @example
ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4 ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
@end example @end example
To watch a stream tunneled over HTTP: @item
Watch a stream tunneled over HTTP:
@example @example
ffplay -rtsp_transport http rtsp://server/video.mp4 ffplay -rtsp_transport http rtsp://server/video.mp4
@end example @end example
To send a stream in realtime to a RTSP server, for others to watch: @item
Send a stream in realtime to a RTSP server, for others to watch:
@example @example
ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
@end example @end example
To receive a stream in realtime: @item
Receive a stream in realtime:
@example @example
ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output} ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
@end example @end example
@end itemize
@table @option
@item stimeout
Socket IO timeout in micro seconds.
@end table
@section sap @section sap
......
...@@ -65,7 +65,7 @@ ...@@ -65,7 +65,7 @@
#define RTSP_FLAG_OPTS(name, longname) \ #define RTSP_FLAG_OPTS(name, longname) \
{ name, longname, OFFSET(rtsp_flags), AV_OPT_TYPE_FLAGS, {.i64 = 0}, INT_MIN, INT_MAX, DEC, "rtsp_flags" }, \ { name, longname, OFFSET(rtsp_flags), AV_OPT_TYPE_FLAGS, {.i64 = 0}, INT_MIN, INT_MAX, DEC, "rtsp_flags" }, \
{ "filter_src", "Only receive packets from the negotiated peer IP", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_FILTER_SRC}, 0, 0, DEC, "rtsp_flags" } { "filter_src", "only receive packets from the negotiated peer IP", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_FILTER_SRC}, 0, 0, DEC, "rtsp_flags" }
#define RTSP_MEDIATYPE_OPTS(name, longname) \ #define RTSP_MEDIATYPE_OPTS(name, longname) \
{ name, longname, OFFSET(media_type_mask), AV_OPT_TYPE_FLAGS, { .i64 = (1 << (AVMEDIA_TYPE_DATA+1)) - 1 }, INT_MIN, INT_MAX, DEC, "allowed_media_types" }, \ { name, longname, OFFSET(media_type_mask), AV_OPT_TYPE_FLAGS, { .i64 = (1 << (AVMEDIA_TYPE_DATA+1)) - 1 }, INT_MIN, INT_MAX, DEC, "allowed_media_types" }, \
...@@ -74,23 +74,23 @@ ...@@ -74,23 +74,23 @@
{ "data", "Data", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << AVMEDIA_TYPE_DATA}, 0, 0, DEC, "allowed_media_types" } { "data", "Data", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << AVMEDIA_TYPE_DATA}, 0, 0, DEC, "allowed_media_types" }
#define RTSP_REORDERING_OPTS() \ #define RTSP_REORDERING_OPTS() \
{ "reorder_queue_size", "Number of packets to buffer for handling of reordered packets", OFFSET(reordering_queue_size), AV_OPT_TYPE_INT, { .i64 = -1 }, -1, INT_MAX, DEC } { "reorder_queue_size", "set number of packets to buffer for handling of reordered packets", OFFSET(reordering_queue_size), AV_OPT_TYPE_INT, { .i64 = -1 }, -1, INT_MAX, DEC }
const AVOption ff_rtsp_options[] = { const AVOption ff_rtsp_options[] = {
{ "initial_pause", "Don't start playing the stream immediately", OFFSET(initial_pause), AV_OPT_TYPE_INT, {.i64 = 0}, 0, 1, DEC }, { "initial_pause", "do not start playing the stream immediately", OFFSET(initial_pause), AV_OPT_TYPE_INT, {.i64 = 0}, 0, 1, DEC },
FF_RTP_FLAG_OPTS(RTSPState, rtp_muxer_flags), FF_RTP_FLAG_OPTS(RTSPState, rtp_muxer_flags),
{ "rtsp_transport", "RTSP transport protocols", OFFSET(lower_transport_mask), AV_OPT_TYPE_FLAGS, {.i64 = 0}, INT_MIN, INT_MAX, DEC|ENC, "rtsp_transport" }, \ { "rtsp_transport", "set RTSP transport protocols", OFFSET(lower_transport_mask), AV_OPT_TYPE_FLAGS, {.i64 = 0}, INT_MIN, INT_MAX, DEC|ENC, "rtsp_transport" }, \
{ "udp", "UDP", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_UDP}, 0, 0, DEC|ENC, "rtsp_transport" }, \ { "udp", "UDP", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_UDP}, 0, 0, DEC|ENC, "rtsp_transport" }, \
{ "tcp", "TCP", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_TCP}, 0, 0, DEC|ENC, "rtsp_transport" }, \ { "tcp", "TCP", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_TCP}, 0, 0, DEC|ENC, "rtsp_transport" }, \
{ "udp_multicast", "UDP multicast", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_UDP_MULTICAST}, 0, 0, DEC, "rtsp_transport" }, { "udp_multicast", "UDP multicast", 0, AV_OPT_TYPE_CONST, {.i64 = 1 << RTSP_LOWER_TRANSPORT_UDP_MULTICAST}, 0, 0, DEC, "rtsp_transport" },
{ "http", "HTTP tunneling", 0, AV_OPT_TYPE_CONST, {.i64 = (1 << RTSP_LOWER_TRANSPORT_HTTP)}, 0, 0, DEC, "rtsp_transport" }, { "http", "HTTP tunneling", 0, AV_OPT_TYPE_CONST, {.i64 = (1 << RTSP_LOWER_TRANSPORT_HTTP)}, 0, 0, DEC, "rtsp_transport" },
RTSP_FLAG_OPTS("rtsp_flags", "RTSP flags"), RTSP_FLAG_OPTS("rtsp_flags", "set RTSP flags"),
{ "listen", "Wait for incoming connections", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_LISTEN}, 0, 0, DEC, "rtsp_flags" }, { "listen", "wait for incoming connections", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_LISTEN}, 0, 0, DEC, "rtsp_flags" },
RTSP_MEDIATYPE_OPTS("allowed_media_types", "Media types to accept from the server"), RTSP_MEDIATYPE_OPTS("allowed_media_types", "set media types to accept from the server"),
{ "min_port", "Minimum local UDP port", OFFSET(rtp_port_min), AV_OPT_TYPE_INT, {.i64 = RTSP_RTP_PORT_MIN}, 0, 65535, DEC|ENC }, { "min_port", "set minimum local UDP port", OFFSET(rtp_port_min), AV_OPT_TYPE_INT, {.i64 = RTSP_RTP_PORT_MIN}, 0, 65535, DEC|ENC },
{ "max_port", "Maximum local UDP port", OFFSET(rtp_port_max), AV_OPT_TYPE_INT, {.i64 = RTSP_RTP_PORT_MAX}, 0, 65535, DEC|ENC }, { "max_port", "set maximum local UDP port", OFFSET(rtp_port_max), AV_OPT_TYPE_INT, {.i64 = RTSP_RTP_PORT_MAX}, 0, 65535, DEC|ENC },
{ "timeout", "Maximum timeout (in seconds) to wait for incoming connections. -1 is infinite. Implies flag listen", OFFSET(initial_timeout), AV_OPT_TYPE_INT, {.i64 = -1}, INT_MIN, INT_MAX, DEC }, { "timeout", "set maximum timeout (in seconds) to wait for incoming connections (-1 is infinite, imply flag listen)", OFFSET(initial_timeout), AV_OPT_TYPE_INT, {.i64 = -1}, INT_MIN, INT_MAX, DEC },
{ "stimeout", "timeout (in micro seconds) of socket i/o operations.", OFFSET(stimeout), AV_OPT_TYPE_INT, {.i64 = 0}, INT_MIN, INT_MAX, DEC }, { "stimeout", "set timeout (in micro seconds) of socket TCP I/O operations", OFFSET(stimeout), AV_OPT_TYPE_INT, {.i64 = 0}, INT_MIN, INT_MAX, DEC },
RTSP_REORDERING_OPTS(), RTSP_REORDERING_OPTS(),
{ "user-agent", "override User-Agent header", OFFSET(user_agent), AV_OPT_TYPE_STRING, {.str = LIBAVFORMAT_IDENT}, 0, 0, DEC }, { "user-agent", "override User-Agent header", OFFSET(user_agent), AV_OPT_TYPE_STRING, {.str = LIBAVFORMAT_IDENT}, 0, 0, DEC },
{ NULL }, { NULL },
...@@ -98,15 +98,15 @@ const AVOption ff_rtsp_options[] = { ...@@ -98,15 +98,15 @@ const AVOption ff_rtsp_options[] = {
static const AVOption sdp_options[] = { static const AVOption sdp_options[] = {
RTSP_FLAG_OPTS("sdp_flags", "SDP flags"), RTSP_FLAG_OPTS("sdp_flags", "SDP flags"),
{ "custom_io", "Use custom IO", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_CUSTOM_IO}, 0, 0, DEC, "rtsp_flags" }, { "custom_io", "use custom I/O", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_CUSTOM_IO}, 0, 0, DEC, "rtsp_flags" },
{ "rtcp_to_source", "Send RTCP packets to the source address of received packets", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_RTCP_TO_SOURCE}, 0, 0, DEC, "rtsp_flags" }, { "rtcp_to_source", "send RTCP packets to the source address of received packets", 0, AV_OPT_TYPE_CONST, {.i64 = RTSP_FLAG_RTCP_TO_SOURCE}, 0, 0, DEC, "rtsp_flags" },
RTSP_MEDIATYPE_OPTS("allowed_media_types", "Media types to accept from the server"), RTSP_MEDIATYPE_OPTS("allowed_media_types", "set media types to accept from the server"),
RTSP_REORDERING_OPTS(), RTSP_REORDERING_OPTS(),
{ NULL }, { NULL },
}; };
static const AVOption rtp_options[] = { static const AVOption rtp_options[] = {
RTSP_FLAG_OPTS("rtp_flags", "RTP flags"), RTSP_FLAG_OPTS("rtp_flags", "set RTP flags"),
RTSP_REORDERING_OPTS(), RTSP_REORDERING_OPTS(),
{ NULL }, { NULL },
}; };
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment