X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fprotocols.texi;h=c136c74e41eacef42c913f382d7d5131ba294c29;hb=74383def8f46805faf3391c98516b248108a9a6b;hp=45918221f4bc648dfcfae504e5db93e5a9668dc6;hpb=6aedabc9b68cab7b65833415953e958ac2c77f80;p=ffmpeg

diff --git a/doc/protocols.texi b/doc/protocols.texi
index 45918221f4b..c136c74e41e 100644
--- a/doc/protocols.texi
+++ b/doc/protocols.texi
@@ -14,9 +14,17 @@ option "--enable-protocol=@var{PROTOCOL}", or you can disable a
 particular protocol using the option
 "--disable-protocol=@var{PROTOCOL}".
 
-The option "-protocols" of the ff* tools will display the list of
+The option "-protocols" of the av* tools will display the list of
 supported protocols.
 
+All protocols accept the following options:
+
+@table @option
+@item rw_timeout
+Maximum time to wait for (network) read/write operations to complete,
+in microseconds.
+@end table
+
 A description of the currently available protocols follows.
 
 @section concat
@@ -57,10 +65,21 @@ use the command:
 avconv -i file:input.mpeg output.mpeg
 @end example
 
-The ff* tools default to the file protocol, that is a resource
+The av* 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 follow
+If set to 1, the protocol will retry reading at the end of the file, allowing
+reading files that still are being written. In order for this to terminate,
+you either need to use the rw_timeout option, or use the interrupt callback
+(for API users).
+
+@end table
+
 @section gopher
 
 Gopher protocol.
@@ -89,6 +108,95 @@ m3u8 files.
 
 HTTP (Hyper Text Transfer Protocol).
 
+This protocol accepts the following options:
+
+@table @option
+@item chunked_post
+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 multiple_requests
+Use persistent connections if set to 1, default is 0.
+
+@item post_data
+Set custom HTTP post data.
+
+@item user_agent
+Override the User-Agent header. If not specified a string of the form
+"Lavf/<version>" will be used.
+
+@item mime_type
+Export the MIME type.
+
+@item icy
+If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
+supports this, the metadata has to be retrieved by the application by reading
+the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
+The default is 1.
+
+@item icy_metadata_headers
+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. It should be
+polled in regular intervals by applications interested in mid-stream metadata
+updates.
+
+@item offset
+Set initial byte offset.
+
+@item end_offset
+Try to limit the request to bytes preceding this offset.
+@end table
+
+@section Icecast
+
+Icecast (stream to Icecast servers)
+
+This protocol accepts the following options:
+
+@table @option
+@item ice_genre
+Set the stream genre.
+
+@item ice_name
+Set the stream name.
+
+@item ice_description
+Set the stream description.
+
+@item ice_url
+Set the stream website URL.
+
+@item ice_public
+Set if the stream should be public or not.
+The default is 0 (not public).
+
+@item user_agent
+Override the User-Agent header. If not specified a string of the form
+"Lavf/<version>" will be used.
+
+@item password
+Set the Icecast mountpoint password.
+
+@item content_type
+Set the stream content type. This must be set if it is different from
+audio/mpeg.
+
+@item legacy_icecast
+This enables support for Icecast versions < 2.4.0, that do not support the
+HTTP PUT method but the SOURCE method.
+
+@end table
+
 @section mmst
 
 MMS (Microsoft Media Server) protocol over TCP.
@@ -164,12 +272,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.
 
@@ -188,6 +302,11 @@ application specified in @var{app}, may be prefixed by "mp4:". You
 can override the value parsed from the URI through the @code{rtmp_playpath}
 option, too.
 
+@item listen
+Act as a server, listening for an incoming connection.
+
+@item timeout
+Maximum time to wait for the incoming connection. Implies listen.
 @end table
 
 Additionally, the following parameters can be set via command line options
@@ -215,7 +334,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
@@ -229,15 +349,33 @@ playpath. If a live stream of that name is not found, it plays the
 recorded stream. The other possible values are @code{live} and
 @code{recorded}.
 
+@item rtmp_pageurl
+URL of the web page in which the media was embedded. By default no
+value will be sent.
+
 @item rtmp_playpath
 Stream identifier to play or to publish. This option overrides the
 parameter specified in the URI.
 
+@item rtmp_subscribe
+Name of live stream to subscribe to. By default no value will be sent.
+It is only sent if the option is specified or if rtmp_live
+is set to live.
+
+@item rtmp_swfhash
+SHA256 hash of the decompressed SWF file (32 bytes).
+
+@item rtmp_swfsize
+Size of the decompressed SWF file, required for SWFVerification.
+
 @item rtmp_swfurl
 URL of the SWF player for the media. By default no value will be sent.
 
+@item rtmp_swfverify
+URL to player swf file, compute hash/size automatically.
+
 @item rtmp_tcurl
-URL of the target stream.
+URL of the target stream. Defaults to proto://host[:port]/app.
 
 @end table
 
@@ -247,6 +385,21 @@ For example to read with @command{avplay} a multimedia resource named
 avplay rtmp://myserver/vod/sample
 @end example
 
+To publish to a password protected server, passing the playpath and
+app names separately:
+@example
+avconv -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.
+
+The Encrypted Real-Time Messaging Protocol (RTMPE) is used for
+streaming multimedia content within standard cryptographic primitives,
+consisting of Diffie-Hellman key exchange and HMACSHA256, generating
+a pair of RC4 keys.
+
 @section rtmps
 
 Real-Time Messaging Protocol over a secure SSL connection.
@@ -262,7 +415,23 @@ The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used
 for streaming multimedia content within HTTP requests to traverse
 firewalls.
 
-@section rtmp, rtmpe, rtmps, rtmpt, rtmpte
+@section rtmpte
+
+Encrypted Real-Time Messaging Protocol tunneled through HTTP.
+
+The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE)
+is used for streaming multimedia content within HTTP requests to traverse
+firewalls.
+
+@section rtmpts
+
+Real-Time Messaging Protocol tunneled through HTTPS.
+
+The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
+for streaming multimedia content within HTTPS requests to traverse
+firewalls.
+
+@section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte
 
 Real-Time Messaging Protocol and its variants supported through
 librtmp.
@@ -488,7 +657,7 @@ avplay sap://[ff0e::2:7ffe]
 
 @section tcp
 
-Trasmission Control Protocol.
+Transmission Control Protocol.
 
 The required syntax for a TCP url is:
 @example
@@ -507,6 +676,52 @@ avplay tcp://@var{hostname}:@var{port}
 
 @end table
 
+@section tls
+
+Transport Layer Security (TLS) / Secure Sockets Layer (SSL)
+
+The required syntax for a TLS url is:
+@example
+tls://@var{hostname}:@var{port}
+@end example
+
+The following parameters can be set via command line options
+(or in code via @code{AVOption}s):
+
+@table @option
+
+@item ca_file
+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.
+
+@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
+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
+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
+
 @section udp
 
 User Datagram Protocol.
@@ -516,7 +731,7 @@ The required syntax for a UDP url is:
 udp://@var{hostname}:@var{port}[?@var{options}]
 @end example
 
-@var{options} contains a list of &-seperated options of the form @var{key}=@var{val}.
+@var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
 Follow the list of supported options.
 
 @table @option
@@ -578,4 +793,24 @@ To receive over UDP from a remote endpoint:
 avconv -i udp://[@var{multicast-address}]:@var{port}
 @end example
 
+@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