doc: Improve references to external URLs.
[ffmpeg.git] / doc / protocols.texi
index cbabaf3..5990631 100644 (file)
@@ -1,10 +1,10 @@
 @chapter Protocols
 @c man begin PROTOCOLS
 
-Protocols are configured elements in FFmpeg which allow to access
+Protocols are configured elements in Libav which allow to access
 resources which require the use of a particular protocol.
 
-When you configure your FFmpeg build, all the supported protocols are
+When you configure your Libav build, all the supported protocols are
 enabled by default. You can list all available ones using the
 configure option "--list-protocols".
 
@@ -19,6 +19,22 @@ supported protocols.
 
 A description of the currently available protocols follows.
 
+@section applehttp
+
+Read Apple HTTP Live Streaming compliant segmented stream as
+a uniform one. The M3U8 playlists describing the segments can be
+remote HTTP resources or local files, accessed using the standard
+file protocol.
+HTTP is default, specific protocol can be declared by specifying
+"+@var{proto}" after the applehttp URI scheme name, where @var{proto}
+is either "file" or "http".
+
+@example
+applehttp://host/path/to/remote/resource.m3u8
+applehttp+http://host/path/to/remote/resource.m3u8
+applehttp+file://path/to/local/resource.m3u8
+@end example
+
 @section concat
 
 Physical concatenation protocol.
@@ -26,7 +42,7 @@ Physical concatenation protocol.
 Allow to read and seek from many resource in sequence as if they were
 a unique resource.
 
-An URL accepted by this protocol has the syntax:
+A URL accepted by this protocol has the syntax:
 @example
 concat:@var{URL1}|@var{URL2}|...|@var{URLN}
 @end example
@@ -73,6 +89,15 @@ HTTP (Hyper Text Transfer Protocol).
 
 MMS (Microsoft Media Server) protocol over TCP.
 
+@section mmsh
+
+MMS (Microsoft Media Server) protocol over HTTP.
+
+The required syntax is:
+@example
+mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
+@end example
+
 @section md5
 
 MD5 output protocol.
@@ -83,7 +108,7 @@ be used to test muxers without writing an actual file.
 
 Some examples follow.
 @example
-# Write the MD5 hash of the encoded AVI file in the file output.avi.md5.
+# Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
 ffmpeg -i input.flv -f avi -y md5:output.avi.md5
 
 # Write the MD5 hash of the encoded AVI file to stdout.
@@ -208,12 +233,248 @@ ffplay "rtmp://myserver/live/mystream live=1"
 
 Real-Time Protocol.
 
+@section rtsp
+
+RTSP is not technically a protocol handler in libavformat, it is a demuxer
+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
+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
+@uref{http://github.com/revmischa/rtsp-server, RTSP server}).
+
+The required syntax for a RTSP url is:
+@example
+rtsp://@var{hostname}[:@var{port}]/@var{path}[?@var{options}]
+@end example
+
+@var{options} is a @code{&}-separated list. The following options
+are supported:
+
+@table @option
+
+@item udp
+Use UDP as lower transport protocol.
+
+@item tcp
+Use TCP (interleaving within the RTSP control channel) as lower
+transport protocol.
+
+@item multicast
+Use UDP multicast as lower transport protocol.
+
+@item http
+Use HTTP tunneling as lower transport protocol, which is useful for
+passing proxies.
+
+@item filter_src
+Accept packets only from negotiated peer address and port.
+@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 @code{tcp} and @code{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
+@code{max_delay} field of AVFormatContext.
+
+When watching multi-bitrate Real-RTSP streams with @file{ffplay}, the
+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
+on the fly by pressing @code{v} and @code{a}.
+
+Example command lines:
+
+To watch a stream over UDP, with a max reordering delay of 0.5 seconds:
+
+@example
+ffplay -max_delay 500000 rtsp://server/video.mp4?udp
+@end example
+
+To watch a stream tunneled over HTTP:
+
+@example
+ffplay rtsp://server/video.mp4?http
+@end example
+
+To send a stream in realtime to a RTSP server, for others to watch:
+
+@example
+ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
+@end example
+
+@section sap
+
+Session Announcement Protocol (RFC 2974). This is not technically a
+protocol handler in libavformat, it is a muxer and demuxer.
+It is used for signalling of RTP streams, by announcing the SDP for the
+streams regularly on a separate port.
+
+@subsection Muxer
+
+The syntax for a SAP url given to the muxer is:
+@example
+sap://@var{destination}[:@var{port}][?@var{options}]
+@end example
+
+The RTP packets are sent to @var{destination} on port @var{port},
+or to port 5004 if no port is specified.
+@var{options} is a @code{&}-separated list. The following options
+are supported:
+
+@table @option
+
+@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.
+
+@item announce_port=@var{port}
+Specify the port to send the announcements on, defaults to
+9875 if not specified.
+
+@item ttl=@var{ttl}
+Specify the time to live value for the announcements and RTP packets,
+defaults to 255.
+
+@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.
+The RTP stack in libavformat for receiving requires all streams to be sent
+on unique ports.
+@end table
+
+Example command lines follow.
+
+To broadcast a stream on the local subnet, for watching in VLC:
+
+@example
+ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
+@end example
+
+Similarly, for watching in ffplay:
+
+@example
+ffmpeg -re -i @var{input} -f sap sap://224.0.0.255
+@end example
+
+And for watching in ffplay, over IPv6:
+
+@example
+ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4]
+@end example
+
+@subsection Demuxer
+
+The syntax for a SAP url given to the demuxer is:
+@example
+sap://[@var{address}][:@var{port}]
+@end example
+
+@var{address} is the multicast address to listen for announcements on,
+if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port}
+is the port that is listened on, 9875 if omitted.
+
+The demuxers listens for announcements on the given address and port.
+Once an announcement is received, it tries to receive that particular stream.
+
+Example command lines follow.
+
+To play back the first stream announced on the normal SAP multicast address:
+
+@example
+ffplay sap://
+@end example
+
+To play back the first stream announced on one the default IPv6 SAP multicast address:
+
+@example
+ffplay sap://[ff0e::2:7ffe]
+@end example
+
 @section tcp
 
 Trasmission Control Protocol.
 
+The required syntax for a TCP url is:
+@example
+tcp://@var{hostname}:@var{port}[?@var{options}]
+@end example
+
+@table @option
+
+@item listen
+Listen for an incoming connection
+
+@example
+ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen
+ffplay tcp://@var{hostname}:@var{port}
+@end example
+
+@end table
+
 @section udp
 
 User Datagram Protocol.
 
+The required syntax for a UDP url is:
+@example
+udp://@var{hostname}:@var{port}[?@var{options}]
+@end example
+
+@var{options} contains a list of &-seperated options of the form @var{key}=@var{val}.
+Follow the list of supported options.
+
+@table @option
+
+@item buffer_size=@var{size}
+set the UDP buffer size in bytes
+
+@item localport=@var{port}
+override the local UDP port to bind with
+
+@item pkt_size=@var{size}
+set the size in bytes of UDP packets
+
+@item reuse=@var{1|0}
+explicitly allow or disallow reusing UDP sockets
+
+@item ttl=@var{ttl}
+set the time to live value (for multicast only)
+
+@item connect=@var{1|0}
+Initialize the UDP socket with @code{connect()}. In this case, the
+destination address can't be changed with ff_udp_set_remote_url later.
+If the destination address isn't known at the start, this option can
+be specified in ff_udp_set_remote_url, too.
+This allows finding out the source address for the packets with getsockname,
+and makes writes return with AVERROR(ECONNREFUSED) if "destination
+unreachable" is received.
+For receiving, this gives the benefit of only receiving packets from
+the specified peer address/port.
+@end table
+
+Some usage examples of the udp protocol with @file{ffmpeg} follow.
+
+To stream over UDP to a remote endpoint:
+@example
+ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port}
+@end example
+
+To stream in mpegts format over UDP using 188 sized UDP packets, using a large input buffer:
+@example
+ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535
+@end example
+
+To receive over UDP from a remote endpoint:
+@example
+ffmpeg -i udp://[@var{multicast-address}]:@var{port}
+@end example
+
 @c man end PROTOCOLS