doc: switch github urls to https
[ffmpeg.git] / doc / protocols.texi
index bae05d5..1380c05 100644 (file)
@@ -1,8 +1,8 @@
 @chapter Protocols
 @c man begin PROTOCOLS
 
-Protocols are configured elements in FFmpeg which allow to access
-resources which require the use of a particular protocol.
+Protocols are configured elements in FFmpeg that enable access to
+resources that require specific protocols.
 
 When you configure your FFmpeg build, all the supported protocols are
 enabled by default. You can list all available ones using the
@@ -117,7 +117,19 @@ ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP/////////////
 
 File access protocol.
 
-Allow to read from or read to a file.
+Allow to read from or write to a file.
+
+A file URL can have the form:
+@example
+file:@var{filename}
+@end example
+
+where @var{filename} is the path of the file to read.
+
+An URL that does not have a protocol prefix will be assumed to be a
+file URL. Depending on the build, an URL that looks like a Windows
+path with the drive letter at the beginning will also be assumed to be
+a file URL (usually not the case in builds for unix-like systems).
 
 For example to read from a file @file{input.mpeg} with @command{ffmpeg}
 use the command:
@@ -125,9 +137,19 @@ use the command:
 ffmpeg -i file:input.mpeg output.mpeg
 @end example
 
-The ff* tools default to the file protocol, that is a resource
-specified with the name "FILE.mpeg" is interpreted as the URL
-"file:FILE.mpeg".
+This protocol accepts the following options:
+
+@table @option
+@item truncate
+Truncate existing files on write, if set to 1. A value of 0 prevents
+truncating. Default value is 1.
+
+@item blocksize
+Set I/O operation maximum block size, in bytes. Default value is
+@code{INT_MAX}, which results in not limiting the requested block size.
+Setting this value reasonably low improves user termination request reaction
+time, which is valuable for files on slow medium.
+@end table
 
 @section ftp
 
@@ -191,7 +213,7 @@ m3u8 files.
 
 HTTP (Hyper Text Transfer Protocol).
 
-This protocol accepts the following options.
+This protocol accepts the following options:
 
 @table @option
 @item seekable
@@ -201,32 +223,33 @@ if set to -1 it will try to autodetect if it is seekable. Default
 value is -1.
 
 @item chunked_post
-If set to 1 use chunked transfer-encoding for posts, default is 1.
+If set to 1 use chunked Transfer-Encoding for posts, default is 1.
+
+@item content_type
+Set a specific content type for the POST messages.
 
 @item headers
 Set custom HTTP headers, can override built in default headers. The
 value must be a string encoding the headers.
 
-@item content_type
-Force a content type.
-
-@item user-agent
-Override User-Agent header. If not specified the protocol will use a
-string describing the libavformat build.
-
 @item multiple_requests
-Use persistent connections if set to 1. By default it is 0.
+Use persistent connections if set to 1, default is 0.
 
 @item post_data
 Set custom HTTP post data.
 
+@item user-agent
+@item user_agent
+Override the User-Agent header. If not specified the protocol will use a
+string describing the libavformat build. ("Lavf/<version>")
+
 @item timeout
 Set timeout of socket I/O operations used by the underlying low level
 operation. By default it is set to -1, which means that the timeout is
 not specified.
 
 @item mime_type
-Set MIME type.
+Export the MIME type.
 
 @item icy
 If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
@@ -235,17 +258,25 @@ the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
 The default is 0.
 
 @item icy_metadata_headers
-If the server supports ICY metadata, this contains the ICY specific HTTP reply
-headers, separated with newline characters.
+If the server supports ICY metadata, this contains the ICY-specific HTTP reply
+headers, separated by newline characters.
 
 @item icy_metadata_packet
 If the server supports ICY metadata, and @option{icy} was set to 1, this
-contains the last non-empty metadata packet sent by the server.
+contains the last non-empty metadata packet sent by the server. It should be
+polled in regular intervals by applications interested in mid-stream metadata
+updates.
 
 @item cookies
 Set the cookies to be sent in future requests. The format of each cookie is the
 same as the value of a Set-Cookie HTTP response field. Multiple cookies can be
 delimited by a newline character.
+
+@item offset
+Set initial byte offset.
+
+@item end_offset
+Try to limit the request to bytes preceding this offset.
 @end table
 
 @subsection HTTP Cookies
@@ -347,12 +378,18 @@ content across a TCP/IP network.
 
 The required syntax is:
 @example
-rtmp://@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
+rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
 @end example
 
 The accepted parameters are:
 @table @option
 
+@item username
+An optional username (mostly for publishing).
+
+@item password
+An optional password (mostly for publishing).
+
 @item server
 The address of the RTMP server.
 
@@ -403,7 +440,8 @@ times to construct arbitrary AMF sequences.
 
 @item rtmp_flashver
 Version of the Flash plugin used to run the SWF player. The default
-is LNX 9,0,124,2.
+is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible;
+<libavformat version>).)
 
 @item rtmp_flush_interval
 Number of packets flushed in the same request (RTMPT only). The default
@@ -453,6 +491,12 @@ For example to read with @command{ffplay} a multimedia resource named
 ffplay rtmp://myserver/vod/sample
 @end example
 
+To publish to a password protected server, passing the playpath and
+app names separately:
+@example
+ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/
+@end example
+
 @section rtmpe
 
 Encrypted Real-Time Messaging Protocol.
@@ -493,7 +537,43 @@ The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
 for streaming multimedia content within HTTPS requests to traverse
 firewalls.
 
-@section rtmp, rtmpe, rtmps, rtmpt, rtmpte
+@section libssh
+
+Secure File Transfer Protocol via libssh
+
+Allow to read from or write to remote resources using SFTP protocol.
+
+Following syntax is required.
+
+@example
+sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
+@end example
+
+This protocol accepts the following options.
+
+@table @option
+@item timeout
+Set timeout of socket I/O operations used by the underlying low level
+operation. By default it is set to -1, which means that the timeout
+is not specified.
+
+@item truncate
+Truncate existing files on write, if set to 1. A value of 0 prevents
+truncating. Default value is 1.
+
+@item private_key
+Specify the path of the file containing private key to use during authorization.
+By default libssh searches for keys in the @file{~/.ssh/} directory.
+
+@end table
+
+Example: Play a file stored on remote server.
+
+@example
+ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg
+@end example
+
+@section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte
 
 Real-Time Messaging Protocol and its variants supported through
 librtmp.
@@ -535,10 +615,75 @@ ffplay "rtmp://myserver/live/mystream live=1"
 
 @section rtp
 
-Real-Time Protocol.
+Real-time Transport Protocol.
+
+The required syntax for an RTP URL is:
+rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...]
+
+@var{port} specifies the RTP port to use.
+
+The following URL options are supported:
+
+@table @option
+
+@item ttl=@var{n}
+Set the TTL (Time-To-Live) value (for multicast only).
+
+@item rtcpport=@var{n}
+Set the remote RTCP port to @var{n}.
+
+@item localrtpport=@var{n}
+Set the local RTP port to @var{n}.
+
+@item localrtcpport=@var{n}'
+Set the local RTCP port to @var{n}.
+
+@item pkt_size=@var{n}
+Set max packet size (in bytes) to @var{n}.
+
+@item connect=0|1
+Do a @code{connect()} on the UDP socket (if set to 1) or not (if set
+to 0).
+
+@item sources=@var{ip}[,@var{ip}]
+List allowed source IP addresses.
+
+@item block=@var{ip}[,@var{ip}]
+List disallowed (blocked) source IP addresses.
+
+@item write_to_source=0|1
+Send packets to the source address of the latest received packet (if
+set to 1) or to a default remote address (if set to 0).
+
+@item localport=@var{n}
+Set the local RTP port to @var{n}.
+
+This is a deprecated option. Instead, @option{localrtpport} should be
+used.
+
+@end table
+
+Important notes:
+
+@enumerate
+
+@item
+If @option{rtcpport} is not set the RTCP port will be set to the RTP
+port value plus 1.
+
+@item
+If @option{localrtpport} (the local RTP port) is not set any available
+port will be used for the local RTP and RTCP ports.
+
+@item
+If @option{localrtcpport} (the local RTCP port) is not set it will be
+set to the the local RTP port value plus 1.
+@end enumerate
 
 @section rtsp
 
+Real-Time Streaming Protocol.
+
 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
@@ -546,21 +691,29 @@ 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}).
+@uref{https://github.com/revmischa/rtsp-server, RTSP server}).
 
 The required syntax for a RTSP url is:
 @example
 rtsp://@var{hostname}[:@var{port}]/@var{path}
 @end example
 
-The following options (set on the @command{ffmpeg}/@command{ffplay} command
-line, or set in code via @code{AVOption}s or in @code{avformat_open_input}),
-are supported:
+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}.
 
-Flags for @code{rtsp_transport}:
+The following options are supported.
 
 @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
 Use UDP as lower transport protocol.
 
@@ -578,15 +731,56 @@ passing proxies.
 
 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.
+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
 Accept packets only from negotiated peer address and port.
 @item listen
 Act as a server, listening for an incoming connection.
+@item prefer_tcp
+Try TCP for RTP transport first, if TCP is available as RTSP RTP transport.
+@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
@@ -599,36 +793,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
 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
 ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
 @end example
 
-To watch a stream tunneled over HTTP:
-
+@item
+Watch a stream tunneled over HTTP:
 @example
 ffplay -rtsp_transport http rtsp://server/video.mp4
 @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
 ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
 @end example
 
-To receive a stream in realtime:
-
+@item
+Receive a stream in realtime:
 @example
 ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
 @end example
-
-@table @option
-@item stimeout
-Socket IO timeout in micro seconds.
-@end table
+@end itemize
 
 @section sap
 
@@ -766,57 +960,109 @@ this binary block are used as master key, the following 14 bytes are
 used as master salt.
 @end table
 
+@section subfile
+
+Virtually extract a segment of a file or another stream.
+The underlying stream must be seekable.
+
+Accepted options:
+@table @option
+@item start
+Start offset of the extracted segment, in bytes.
+@item end
+End offset of the extracted segment, in bytes.
+@end table
+
+Examples:
+
+Extract a chapter from a DVD VOB file (start and end sectors obtained
+externally and multiplied by 2048):
+@example
+subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
+@end example
+
+Play an AVI file directly from a TAR archive:
+subfile,,start,183241728,end,366490624,,:archive.tar
+
 @section tcp
 
-Trasmission Control Protocol.
+Transmission Control Protocol.
 
 The required syntax for a TCP url is:
 @example
 tcp://@var{hostname}:@var{port}[?@var{options}]
 @end example
 
-@table @option
+@var{options} contains a list of &-separated options of the form
+@var{key}=@var{val}.
 
-@item listen
-Listen for an incoming connection
+The list of supported options follows.
+
+@table @option
+@item listen=@var{1|0}
+Listen for an incoming connection. Default value is 0.
 
 @item timeout=@var{microseconds}
-In read mode: if no data arrived in more than this time interval, raise error.
-In write mode: if socket cannot be written in more than this time interval, raise error.
-This also sets timeout on TCP connection establishing.
+Set raise error timeout, expressed in microseconds.
 
+This option is only relevant in read mode: if no data arrived in more
+than this time interval, raise error.
+
+@item listen_timeout=@var{microseconds}
+Set listen timeout, expressed in microseconds.
+@end table
+
+The following example shows how to setup a listening TCP connection
+with @command{ffmpeg}, which is then accessed with @command{ffplay}:
 @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 tls
 
-Transport Layer Security/Secure Sockets Layer
+Transport Layer Security (TLS) / Secure Sockets Layer (SSL)
 
 The required syntax for a TLS/SSL url is:
 @example
 tls://@var{hostname}:@var{port}[?@var{options}]
 @end example
 
-@table @option
-
-@item listen
-Act as a server, listening for an incoming connection.
-
-@item cafile=@var{filename}
-Certificate authority file. The file must be in OpenSSL PEM format.
-
-@item cert=@var{filename}
-Certificate file. The file must be in OpenSSL PEM format.
+The following parameters can be set via command line options
+(or in code via @code{AVOption}s):
 
-@item key=@var{filename}
-Private key file.
+@table @option
 
-@item verify=@var{0|1}
-Verify the peer's certificate.
+@item ca_file, cafile=@var{filename}
+A file containing certificate authority (CA) root certificates to treat
+as trusted. If the linked TLS library contains a default this might not
+need to be specified for verification to work, but not all libraries and
+setups have defaults built in.
+The file must be in OpenSSL PEM format.
+
+@item tls_verify=@var{1|0}
+If enabled, try to verify the peer that we are communicating with.
+Note, if using OpenSSL, this currently only makes sure that the
+peer certificate is signed by one of the root certificates in the CA
+database, but it does not validate that the certificate actually
+matches the host name we are trying to connect to. (With GnuTLS,
+the host name is validated as well.)
+
+This is disabled by default since it requires a CA database to be
+provided by the caller in many cases.
+
+@item cert_file, cert=@var{filename}
+A file containing a certificate to use in the handshake with the peer.
+(When operating as server, in listen mode, this is more often required
+by the peer, while client certificates only are mandated in certain
+setups.)
+
+@item key_file, key=@var{filename}
+A file containing the private key for the certificate.
+
+@item listen=@var{1|0}
+If enabled, listen for connections on the provided port, and assume
+the server role in the handshake instead of the client role.
 
 @end table
 
@@ -838,7 +1084,7 @@ ffplay tls://@var{hostname}:@var{port}
 
 User Datagram Protocol.
 
-The required syntax for a UDP url is:
+The required syntax for an UDP URL is:
 @example
 udp://@var{hostname}:@var{port}[?@var{options}]
 @end example
@@ -846,14 +1092,13 @@ udp://@var{hostname}:@var{port}[?@var{options}]
 @var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
 
 In case threading is enabled on the system, a circular buffer is used
-to store the incoming data, which allows to reduce loss of data due to
+to store the incoming data, which allows one to reduce loss of data due to
 UDP socket buffer overruns. The @var{fifo_size} and
 @var{overrun_nonfatal} options are related to this buffer.
 
 The list of supported options follows.
 
 @table @option
-
 @item buffer_size=@var{size}
 Set the UDP socket buffer size in bytes. This is used both for the
 receiving and the sending buffer size.
@@ -903,24 +1148,53 @@ Survive in case of UDP receiving circular buffer overrun. Default
 value is 0.
 
 @item timeout=@var{microseconds}
-In read mode: if no data arrived in more than this time interval, raise error.
+Set raise error timeout, expressed in microseconds.
+
+This option is only relevant in read mode: if no data arrived in more
+than this time interval, raise error.
 @end table
 
-Some usage examples of the UDP protocol with @command{ffmpeg} follow.
+@subsection Examples
 
-To stream over UDP to a remote endpoint:
+@itemize
+@item
+Use @command{ffmpeg} 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:
+@item
+Use @command{ffmpeg} 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:
+@item
+Use @command{ffmpeg} to receive over UDP from a remote endpoint:
 @example
-ffmpeg -i udp://[@var{multicast-address}]:@var{port}
+ffmpeg -i udp://[@var{multicast-address}]:@var{port} ...
 @end example
+@end itemize
+
+@section unix
+
+Unix local socket
+
+The required syntax for a Unix socket URL is:
+
+@example
+unix://@var{filepath}
+@end example
+
+The following parameters can be set via command line options
+(or in code via @code{AVOption}s):
+
+@table @option
+@item timeout
+Timeout in ms.
+@item listen
+Create the Unix socket in listening mode.
+@end table
 
 @c man end PROTOCOLS