X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fprotocols.texi;h=8371f830592e9ac10fccaaab41d6ff137471a141;hb=6f34f031908b8f16482e951ee5232116fb42b46a;hp=fb7725e058c70d7df9b851c279df04fe7baf42b7;hpb=0c126431f9b290f5651ec62f45627632d94c51ea;p=ffmpeg

diff --git a/doc/protocols.texi b/doc/protocols.texi
index fb7725e058c..8371f830592 100644
--- a/doc/protocols.texi
+++ b/doc/protocols.texi
@@ -51,6 +51,82 @@ in microseconds.
 
 A description of the currently available protocols follows.
 
+@section amqp
+
+Advanced Message Queueing Protocol (AMQP) version 0-9-1 is a broker based
+publish-subscribe communication protocol.
+
+FFmpeg must be compiled with --enable-librabbitmq to support AMQP. A separate
+AMQP broker must also be run. An example open-source AMQP broker is RabbitMQ.
+
+After starting the broker, an FFmpeg client may stream data to the broker using
+the command:
+
+@example
+ffmpeg -re -i input -f mpegts amqp://[[user]:[password]@@]hostname[:port][/vhost]
+@end example
+
+Where hostname and port (default is 5672) is the address of the broker. The
+client may also set a user/password for authentication. The default for both
+fields is "guest". Name of virtual host on broker can be set with vhost. The
+default value is "/".
+
+Muliple subscribers may stream from the broker using the command:
+@example
+ffplay amqp://[[user]:[password]@@]hostname[:port][/vhost]
+@end example
+
+In RabbitMQ all data published to the broker flows through a specific exchange,
+and each subscribing client has an assigned queue/buffer. When a packet arrives
+at an exchange, it may be copied to a client's queue depending on the exchange
+and routing_key fields.
+
+The following options are supported:
+
+@table @option
+
+@item exchange
+Sets the exchange to use on the broker. RabbitMQ has several predefined
+exchanges: "amq.direct" is the default exchange, where the publisher and
+subscriber must have a matching routing_key; "amq.fanout" is the same as a
+broadcast operation (i.e. the data is forwarded to all queues on the fanout
+exchange independent of the routing_key); and "amq.topic" is similar to
+"amq.direct", but allows for more complex pattern matching (refer to the RabbitMQ
+documentation).
+
+@item routing_key
+Sets the routing key. The default value is "amqp". The routing key is used on
+the "amq.direct" and "amq.topic" exchanges to decide whether packets are written
+to the queue of a subscriber.
+
+@item pkt_size
+Maximum size of each packet sent/received to the broker. Default is 131072.
+Minimum is 4096 and max is any large value (representable by an int). When
+receiving packets, this sets an internal buffer size in FFmpeg. It should be
+equal to or greater than the size of the published packets to the broker. Otherwise
+the received message may be truncated causing decoding errors.
+
+@item connection_timeout
+The timeout in seconds during the initial connection to the broker. The
+default value is rw_timeout, or 5 seconds if rw_timeout is not set.
+
+@item delivery_mode @var{mode}
+Sets the delivery mode of each message sent to broker.
+The following values are accepted:
+@table @samp
+@item persistent
+Delivery mode set to "persistent" (2). This is the default value.
+Messages may be written to the broker's disk depending on its setup.
+
+@item non-persistent
+Delivery mode set to "non-persistent" (1).
+Messages will stay in broker's memory unless the broker is under memory
+pressure.
+
+@end table
+
+@end table
+
 @section async
 
 Asynchronous data filling wrapper for input stream.
@@ -99,6 +175,16 @@ Caching wrapper for input stream.
 
 Cache the input stream to temporary file. It brings seeking capability to live streams.
 
+The accepted options are:
+@table @option
+
+@item read_ahead_limit
+Amount in bytes that may be read ahead when seeking isn't supported. Range is -1 to INT_MAX.
+-1 for unlimited. Default is 65536.
+
+@end table
+
+URL Syntax is
 @example
 cache:@var{URL}
 @end example
@@ -193,6 +279,20 @@ 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.
+
+@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).
+
+@item seekable
+Controls if seekability is advertised on the file. 0 means non-seekable, -1
+means auto (seekable for normal files, non-seekable for named pipes).
+
+Many demuxers handle seekable and non-seekable resources differently,
+overriding this might speed up opening certain files at the cost of losing some
+features (e.g. accurate seeking).
 @end table
 
 @section ftp
@@ -214,6 +314,14 @@ Set timeout in microseconds of socket I/O operations used by the underlying low
 operation. By default it is set to -1, which means that the timeout is
 not specified.
 
+@item ftp-user
+Set a user to be used for authenticating to the FTP server. This is overridden by the
+user in the FTP URL.
+
+@item ftp-password
+Set a password to be used for authenticating to the FTP server. This is overridden by
+the password in the FTP URL, or by @option{ftp-anonymous-password} if no user is set.
+
 @item ftp-anonymous-password
 Password used when login as anonymous user. Typically an e-mail address
 should be used.
@@ -229,20 +337,15 @@ it, unless special care is taken (tests, customized server configuration
 etc.). Different FTP servers behave in different way during seek
 operation. ff* tools may produce incomplete content due to server limitations.
 
-This protocol accepts the following options:
+@section gopher
 
-@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).
+Gopher protocol.
 
-@end table
+@section gophers
 
-@section gopher
+Gophers protocol.
 
-Gopher protocol.
+The Gopher protocol with TLS encapsulation.
 
 @section hls
 
@@ -303,14 +406,6 @@ Set the Referer header. Include 'Referer: URL' header in HTTP request.
 Override the User-Agent header. If not specified the protocol will use a
 string describing the libavformat build. ("Lavf/<version>")
 
-@item user-agent
-This is a deprecated option, you can use user_agent instead it.
-
-@item timeout
-Set timeout in microseconds 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 reconnect_at_eof
 If set then eof is treated like an error and causes reconnection, this is useful
 for live / endless streams.
@@ -318,6 +413,13 @@ for live / endless streams.
 @item reconnect_streamed
 If set then even streamed/non seekable streams will be reconnected on errors.
 
+@item reconnect_on_network_error
+Reconnect automatically in case of TCP/TLS errors during connect.
+
+@item reconnect_on_http_error
+A comma separated list of HTTP status codes to reconnect on. The list can
+include specific status codes (e.g. '503') or the strings '4xx' / '5xx'.
+
 @item reconnect_delay_max
 Sets the maximum delay in seconds after which to give up reconnecting
 
@@ -390,6 +492,33 @@ ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://@var{server}:@var{p
 wget --post-file=somefile.ogg http://@var{server}:@var{port}
 @end example
 
+@item send_expect_100
+Send an Expect: 100-continue header for POST. If set to 1 it will send, if set
+to 0 it won't, if set to -1 it will try to send if it is applicable. Default
+value is -1.
+
+@item auth_type
+
+Set HTTP authentication type. No option for Digest, since this method requires
+getting nonce parameters from the server first and can't be used straight away like
+Basic.
+
+@table @option
+@item none
+Choose the HTTP authentication type automatically. This is the default.
+@item basic
+
+Choose the HTTP basic authentication.
+
+Basic authentication sends a Base64-encoded string that contains a user name and password
+for the client. Base64 is not a form of encryption and should be considered the same as
+sending the user name and password in clear text (Base64 is a reversible encoding).
+If a resource needs to be protected, strongly consider using an authentication scheme
+other than basic authentication. HTTPS/TLS should be used with basic authentication.
+Without these additional security enhancements, basic authentication should not be used
+to protect sensitive or valuable information.
+@end table
+
 @end table
 
 @subsection HTTP Cookies
@@ -444,6 +573,9 @@ audio/mpeg.
 This enables support for Icecast versions < 2.4.0, that do not support the
 HTTP PUT method but the SOURCE method.
 
+@item tls
+Establish a TLS (HTTPS) connection to Icecast.
+
 @end table
 
 @example
@@ -561,6 +693,42 @@ Example usage:
 -f rtp_mpegts -fec prompeg=l=8:d=4 rtp://@var{hostname}:@var{port}
 @end example
 
+@section rist
+
+Reliable Internet Streaming Transport protocol
+
+The accepted options are:
+@table @option
+@item rist_profile
+Supported values:
+@table @samp
+@item simple
+@item main
+This one is default.
+@item advanced
+@end table
+
+@item buffer_size
+Set internal RIST buffer size in milliseconds for retransmission of data.
+Default value is 0 which means the librist default (1 sec). Maximum value is 30
+seconds.
+
+@item pkt_size
+Set maximum packet size for sending data. 1316 by default.
+
+@item log_level
+Set loglevel for RIST logging messages. You only need to set this if you
+explicitly want to enable debug level messages or packet loss simulation,
+otherwise the regular loglevel is respected.
+
+@item secret
+Set override of encryption secret, by default is unset.
+
+@item encryption
+Set encryption type, by default is disabled.
+Acceptable values are 128 and 256.
+@end table
+
 @section rtmp
 
 Real-Time Messaging Protocol.
@@ -862,6 +1030,9 @@ Set the local RTCP port to @var{n}.
 @item pkt_size=@var{n}
 Set max packet size (in bytes) to @var{n}.
 
+@item buffer_size=@var{size}
+Set the maximum UDP socket buffer size in bytes.
+
 @item connect=0|1
 Do a @code{connect()} on the UDP socket (if set to 1) or not (if set
 to 0).
@@ -879,6 +1050,9 @@ 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}.
 
+@item timeout=@var{n}
+Set timeout (in microseconds) of socket I/O operations to @var{n}.
+
 This is a deprecated option. Instead, @option{localrtpport} should be
 used.
 
@@ -987,19 +1161,18 @@ 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 means infinite (default). This option implies the
-@option{rtsp_flags} set to @samp{listen}.
+@item listen_timeout
+Set maximum timeout (in seconds) to establish an initial connection. Setting
+@option{listen_timeout} > 0 sets @option{rtsp_flags} to @samp{listen}. Default is -1
+which means an infinite timeout when @samp{listen} mode is set.
 
 @item reorder_queue_size
 Set number of packets to buffer for handling of reordered packets.
 
-@item stimeout
+@item timeout
 Set socket TCP I/O timeout in microseconds.
 
-@item user-agent
+@item user_agent
 Override User-Agent header. If not specified, it defaults to the
 libavformat identifier string.
 @end table
@@ -1179,7 +1352,7 @@ options.
 This protocol accepts the following options.
 
 @table @option
-@item connect_timeout
+@item connect_timeout=@var{milliseconds}
 Connection timeout; SRT cannot connect for RTT > 1500 msec
 (2 handshake exchanges) with the default connect timeout of
 3 seconds. This option applies to the caller and rendezvous
@@ -1210,7 +1383,7 @@ IP Type of Service. Applies to sender only. Default value is 0xB8.
 @item ipttl=@var{ttl}
 IP Time To Live. Applies to sender only. Default value is 64.
 
-@item latency
+@item latency=@var{microseconds}
 Timestamp-based Packet Delivery Delay.
 Used to absorb bursts of missed packet retransmissions.
 This flag sets both @option{rcvlatency} and @option{peerlatency}
@@ -1221,7 +1394,7 @@ when side is sender and @option{rcvlatency}
 when side is receiver, and the bidirectional stream
 sending is not supported.
 
-@item listen_timeout
+@item listen_timeout=@var{microseconds}
 Set socket listen timeout.
 
 @item maxbw=@var{bytes/seconds}
@@ -1266,6 +1439,26 @@ only if @option{pbkeylen} is non-zero. It is used on
 the receiver only if the received data is encrypted.
 The configured passphrase cannot be recovered (write-only).
 
+@item enforced_encryption=@var{1|0}
+If true, both connection parties must have the same password
+set (including empty, that is, with no encryption). If the
+password doesn't match or only one side is unencrypted,
+the connection is rejected. Default is true.
+
+@item kmrefreshrate=@var{packets}
+The number of packets to be transmitted after which the
+encryption key is switched to a new key. Default is -1.
+-1 means auto (0x1000000 in srt library). The range for
+this option is integers in the 0 - @code{INT_MAX}.
+
+@item kmpreannounce=@var{packets}
+The interval between when a new encryption key is sent and
+when switchover occurs. This value also applies to the
+subsequent interval between when switchover occurs and
+when the old encryption key is decommissioned. Default is -1.
+-1 means auto (0x1000 in srt library). The range for
+this option is integers in the 0 - @code{INT_MAX}.
+
 @item payload_size=@var{bytes}
 Sets the maximum declared size of a packet transferred
 during the single call to the sending function in Live
@@ -1281,7 +1474,7 @@ use a bigger maximum frame size, though not greater than
 @item pkt_size=@var{bytes}
 Alias for @samp{payload_size}.
 
-@item peerlatency
+@item peerlatency=@var{microseconds}
 The latency value (as described in @option{rcvlatency}) that is
 set by the sender side as a minimum value for the receiver.
 
@@ -1293,7 +1486,7 @@ Not required on receiver (set to 0),
 key size obtained from sender in HaiCrypt handshake.
 Default value is 0.
 
-@item rcvlatency
+@item rcvlatency=@var{microseconds}
 The time that should elapse since the moment when the
 packet was sent and the moment when it's delivered to
 the receiver application in the receiving function.
@@ -1311,12 +1504,10 @@ Set UDP receive buffer size, expressed in bytes.
 @item send_buffer_size=@var{bytes}
 Set UDP send buffer size, expressed in bytes.
 
-@item rw_timeout
-Set raise error timeout for read/write optations.
-
-This option is only relevant in read mode:
-if no data arrived in more than this time
-interval, raise error.
+@item timeout=@var{microseconds}
+Set raise error timeouts for read, write and connect operations. Note that the
+SRT library has internal timeouts which can be controlled separately, the
+value set here is only a cap on those.
 
 @item tlpktdrop=@var{1|0}
 Too-late Packet Drop. When enabled on receiver, it skips
@@ -1410,6 +1601,12 @@ the overhead transmission (retransmitted and control packets).
 file: Set options as for non-live transmission. See @option{messageapi}
 for further explanations
 
+@item linger=@var{seconds}
+The number of seconds that the socket waits for unsent data when closing.
+Default is -1. -1 means auto (off with 0 seconds in live mode, on with 180
+seconds in file mode). The range for this option is integers in the
+0 - @code{INT_MAX}.
+
 @end table
 
 For more information see: @url{https://github.com/Haivision/srt}.
@@ -1496,8 +1693,9 @@ tcp://@var{hostname}:@var{port}[?@var{options}]
 The list of supported options follows.
 
 @table @option
-@item listen=@var{1|0}
-Listen for an incoming connection. Default value is 0.
+@item listen=@var{2|1|0}
+Listen for an incoming connection. 0 disables listen, 1 enables listen in
+single client mode, 2 enables listen in multi-client mode. Default value is 0.
 
 @item timeout=@var{microseconds}
 Set raise error timeout, expressed in microseconds.
@@ -1573,6 +1771,10 @@ A file containing the private key for the certificate.
 If enabled, listen for connections on the provided port, and assume
 the server role in the handshake instead of the client role.
 
+@item http_proxy
+The HTTP proxy to tunnel through, e.g. @code{http://example.com:1234}.
+The proxy must support the CONNECT method.
+
 @end table
 
 Example command lines:
@@ -1611,7 +1813,7 @@ The list of supported options follows.
 @item buffer_size=@var{size}
 Set the UDP maximum socket buffer size in bytes. This is used to set either
 the receive or send buffer size, depending on what the socket is used for.
-Default is 64KB.  See also @var{fifo_size}.
+Default is 32 KB for output, 384 KB for input.  See also @var{fifo_size}.
 
 @item bitrate=@var{bitrate}
 If set to nonzero, the output will have the specified constant bitrate if the
@@ -1720,4 +1922,51 @@ Timeout in ms.
 Create the Unix socket in listening mode.
 @end table
 
+@section zmq
+
+ZeroMQ asynchronous messaging using the libzmq library.
+
+This library supports unicast streaming to multiple clients without relying on
+an external server.
+
+The required syntax for streaming or connecting to a stream is:
+@example
+zmq:tcp://ip-address:port
+@end example
+
+Example:
+Create a localhost stream on port 5555:
+@example
+ffmpeg -re -i input -f mpegts zmq:tcp://127.0.0.1:5555
+@end example
+
+Multiple clients may connect to the stream using:
+@example
+ffplay zmq:tcp://127.0.0.1:5555
+@end example
+
+Streaming to multiple clients is implemented using a ZeroMQ Pub-Sub pattern.
+The server side binds to a port and publishes data. Clients connect to the
+server (via IP address/port) and subscribe to the stream. The order in which
+the server and client start generally does not matter.
+
+ffmpeg must be compiled with the --enable-libzmq option to support
+this protocol.
+
+Options can be set on the @command{ffmpeg}/@command{ffplay} command
+line. The following options are supported:
+
+@table @option
+
+@item pkt_size
+Forces the maximum packet size for sending/receiving data. The default value is
+131,072 bytes. On the server side, this sets the maximum size of sent packets
+via ZeroMQ. On the clients, it sets an internal buffer size for receiving
+packets. Note that pkt_size on the clients should be equal to or greater than
+pkt_size on the server. Otherwise the received message may be truncated causing
+decoding errors.
+
+@end table
+
+
 @c man end PROTOCOLS