X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fprotocols.texi;h=e2d06a067535dce8ad53cb5a25ea4e32db5c9ea1;hb=52ed83fa1a7f5170447eff6fad0b6c57119596e9;hp=616c9cda781bcd8928d6d447006d651acdf951da;hpb=98df48db6dfc2ed2cef7472e564d0de9639e8774;p=ffmpeg diff --git a/doc/protocols.texi b/doc/protocols.texi index 616c9cda781..e2d06a06753 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/" 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/" 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; +).) @item rtmp_flush_interval Number of packets flushed in the same request (RTMPT only). The default @@ -229,13 +349,31 @@ 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. Defaults to proto://host[:port]/app. @@ -247,6 +385,12 @@ 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 -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. @@ -287,7 +431,7 @@ 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 librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte Real-Time Messaging Protocol and its variants supported through librtmp. @@ -511,9 +655,149 @@ To play back the first stream announced on one the default IPv6 SAP multicast ad avplay sap://[ff0e::2:7ffe] @end example +@section srt + +Haivision Secure Reliable Transport Protocol via libsrt. + +The supported syntax for a SRT URL is: +@example +srt://@var{hostname}:@var{port}[?@var{options}] +@end example + +@var{options} contains a list of &-separated options of the form +@var{key}=@var{val}. + +or + +@example +@var{options} srt://@var{hostname}:@var{port} +@end example + +@var{options} contains a list of '-@var{key} @var{val}' +options. + +This protocol accepts the following options. + +@table @option +@item connect_timeout +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 +connection modes. The connect timeout is 10 times the value +set for the rendezvous mode (which can be used as a +workaround for this connection problem with earlier versions). + +@item ffs=@var{bytes} +Flight Flag Size (Window Size), in bytes. FFS is actually an +internal parameter and you should set it to not less than +@option{recv_buffer_size} and @option{mss}. The default value +is relatively large, therefore unless you set a very large receiver buffer, +you do not need to change this option. Default value is 25600. + +@item inputbw=@var{bytes/seconds} +Sender nominal input rate, in bytes per seconds. Used along with +@option{oheadbw}, when @option{maxbw} is set to relative (0), to +calculate maximum sending rate when recovery packets are sent +along with the main media stream: +@option{inputbw} * (100 + @option{oheadbw}) / 100 +if @option{inputbw} is not set while @option{maxbw} is set to +relative (0), the actual input rate is evaluated inside +the library. Default value is 0. + +@item iptos=@var{tos} +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 listen_timeout +Set socket listen timeout. + +@item maxbw=@var{bytes/seconds} +Maximum sending bandwidth, in bytes per seconds. +-1 infinite (CSRTCC limit is 30mbps) +0 relative to input rate (see @option{inputbw}) +>0 absolute limit value +Default value is 0 (relative) + +@item mode=@var{caller|listener|rendezvous} +Connection mode. +@option{caller} opens client connection. +@option{listener} starts server to listen for incoming connections. +@option{rendezvous} use Rendez-Vous connection mode. +Default value is caller. + +@item mss=@var{bytes} +Maximum Segment Size, in bytes. Used for buffer allocation +and rate calculation using a packet counter assuming fully +filled packets. The smallest MSS between the peers is +used. This is 1500 by default in the overall internet. +This is the maximum size of the UDP packet and can be +only decreased, unless you have some unusual dedicated +network settings. Default value is 1500. + +@item nakreport=@var{1|0} +If set to 1, Receiver will send `UMSG_LOSSREPORT` messages +periodically until a lost packet is retransmitted or +intentionally dropped. Default value is 1. + +@item oheadbw=@var{percents} +Recovery bandwidth overhead above input rate, in percents. +See @option{inputbw}. Default value is 25%. + +@item passphrase=@var{string} +HaiCrypt Encryption/Decryption Passphrase string, length +from 10 to 79 characters. The passphrase is the shared +secret between the sender and the receiver. It is used +to generate the Key Encrypting Key using PBKDF2 +(Password-Based Key Derivation Function). It is used +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 pbkeylen=@var{bytes} +Sender encryption key length, in bytes. +Only can be set to 0, 16, 24 and 32. +Enable sender encryption if not 0. +Not required on receiver (set to 0), +key size obtained from sender in HaiCrypt handshake. +Default value is 0. + +@item recv_buffer_size=@var{bytes} +Set receive buffer size, expressed in bytes. + +@item send_buffer_size=@var{bytes} +Set 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 tlpktdrop=@var{1|0} +Too-late Packet Drop. When enabled on receiver, it skips +missing packets that have not been delivered in time and +delivers the following packets to the application when +their time-to-play has come. It also sends a fake ACK to +the sender. When enabled on sender and enabled on the +receiving peer, the sender drops the older packets that +have no chance of being delivered in time. It was +automatically enabled in the sender if the receiver +supports it. + +@item tsbpddelay +Timestamp-based Packet Delivery Delay. +Used to absorb burst of missed packet retransmission. + +@end table + +For more information see: @url{https://github.com/Haivision/srt}. + @section tcp -Trasmission Control Protocol. +Transmission Control Protocol. The required syntax for a TCP url is: @example @@ -532,6 +816,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. @@ -541,7 +871,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 @@ -603,4 +933,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