1@chapter Protocols 2@c man begin PROTOCOLS 3 4Protocols are configured elements in FFmpeg that enable access to 5resources that require specific protocols. 6 7When you configure your FFmpeg build, all the supported protocols are 8enabled by default. You can list all available ones using the 9configure option "--list-protocols". 10 11You can disable all the protocols using the configure option 12"--disable-protocols", and selectively enable a protocol using the 13option "--enable-protocol=@var{PROTOCOL}", or you can disable a 14particular protocol using the option 15"--disable-protocol=@var{PROTOCOL}". 16 17The option "-protocols" of the ff* tools will display the list of 18supported protocols. 19 20A description of the currently available protocols follows. 21 22@section bluray 23 24Read BluRay playlist. 25 26The accepted options are: 27@table @option 28 29@item angle 30BluRay angle 31 32@item chapter 33Start chapter (1...N) 34 35@item playlist 36Playlist to read (BDMV/PLAYLIST/?????.mpls) 37 38@end table 39 40Examples: 41 42Read longest playlist from BluRay mounted to /mnt/bluray: 43@example 44bluray:/mnt/bluray 45@end example 46 47Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2: 48@example 49-playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray 50@end example 51 52@section cache 53 54Caching wrapper for input stream. 55 56Cache the input stream to temporary file. It brings seeking capability to live streams. 57 58@example 59cache:@var{URL} 60@end example 61 62@section concat 63 64Physical concatenation protocol. 65 66Allow to read and seek from many resource in sequence as if they were 67a unique resource. 68 69A URL accepted by this protocol has the syntax: 70@example 71concat:@var{URL1}|@var{URL2}|...|@var{URLN} 72@end example 73 74where @var{URL1}, @var{URL2}, ..., @var{URLN} are the urls of the 75resource to be concatenated, each one possibly specifying a distinct 76protocol. 77 78For example to read a sequence of files @file{split1.mpeg}, 79@file{split2.mpeg}, @file{split3.mpeg} with @command{ffplay} use the 80command: 81@example 82ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg 83@end example 84 85Note that you may need to escape the character "|" which is special for 86many shells. 87 88@section crypto 89 90AES-encrypted stream reading protocol. 91 92The accepted options are: 93@table @option 94@item key 95Set the AES decryption key binary block from given hexadecimal representation. 96 97@item iv 98Set the AES decryption initialization vector binary block from given hexadecimal representation. 99@end table 100 101Accepted URL formats: 102@example 103crypto:@var{URL} 104crypto+@var{URL} 105@end example 106 107@section data 108 109Data in-line in the URI. See @url{http://en.wikipedia.org/wiki/Data_URI_scheme}. 110 111For example, to convert a GIF file given inline with @command{ffmpeg}: 112@example 113ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png 114@end example 115 116@section file 117 118File access protocol. 119 120Allow to read from or write to a file. 121 122A file URL can have the form: 123@example 124file:@var{filename} 125@end example 126 127where @var{filename} is the path of the file to read. 128 129An URL that does not have a protocol prefix will be assumed to be a 130file URL. Depending on the build, an URL that looks like a Windows 131path with the drive letter at the beginning will also be assumed to be 132a file URL (usually not the case in builds for unix-like systems). 133 134For example to read from a file @file{input.mpeg} with @command{ffmpeg} 135use the command: 136@example 137ffmpeg -i file:input.mpeg output.mpeg 138@end example 139 140This protocol accepts the following options: 141 142@table @option 143@item truncate 144Truncate existing files on write, if set to 1. A value of 0 prevents 145truncating. Default value is 1. 146 147@item blocksize 148Set I/O operation maximum block size, in bytes. Default value is 149@code{INT_MAX}, which results in not limiting the requested block size. 150Setting this value reasonably low improves user termination request reaction 151time, which is valuable for files on slow medium. 152@end table 153 154@section ftp 155 156FTP (File Transfer Protocol). 157 158Allow to read from or write to remote resources using FTP protocol. 159 160Following syntax is required. 161@example 162ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg 163@end example 164 165This protocol accepts the following options. 166 167@table @option 168@item timeout 169Set timeout in microseconds of socket I/O operations used by the underlying low level 170operation. By default it is set to -1, which means that the timeout is 171not specified. 172 173@item ftp-anonymous-password 174Password used when login as anonymous user. Typically an e-mail address 175should be used. 176 177@item ftp-write-seekable 178Control seekability of connection during encoding. If set to 1 the 179resource is supposed to be seekable, if set to 0 it is assumed not 180to be seekable. Default value is 0. 181@end table 182 183NOTE: Protocol can be used as output, but it is recommended to not do 184it, unless special care is taken (tests, customized server configuration 185etc.). Different FTP servers behave in different way during seek 186operation. ff* tools may produce incomplete content due to server limitations. 187 188@section gopher 189 190Gopher protocol. 191 192@section hls 193 194Read Apple HTTP Live Streaming compliant segmented stream as 195a uniform one. The M3U8 playlists describing the segments can be 196remote HTTP resources or local files, accessed using the standard 197file protocol. 198The nested protocol is declared by specifying 199"+@var{proto}" after the hls URI scheme name, where @var{proto} 200is either "file" or "http". 201 202@example 203hls+http://host/path/to/remote/resource.m3u8 204hls+file://path/to/local/resource.m3u8 205@end example 206 207Using this protocol is discouraged - the hls demuxer should work 208just as well (if not, please report the issues) and is more complete. 209To use the hls demuxer instead, simply use the direct URLs to the 210m3u8 files. 211 212@section http 213 214HTTP (Hyper Text Transfer Protocol). 215 216This protocol accepts the following options: 217 218@table @option 219@item seekable 220Control seekability of connection. If set to 1 the resource is 221supposed to be seekable, if set to 0 it is assumed not to be seekable, 222if set to -1 it will try to autodetect if it is seekable. Default 223value is -1. 224 225@item chunked_post 226If set to 1 use chunked Transfer-Encoding for posts, default is 1. 227 228@item content_type 229Set a specific content type for the POST messages. 230 231@item headers 232Set custom HTTP headers, can override built in default headers. The 233value must be a string encoding the headers. 234 235@item multiple_requests 236Use persistent connections if set to 1, default is 0. 237 238@item post_data 239Set custom HTTP post data. 240 241@item user-agent 242@item user_agent 243Override the User-Agent header. If not specified the protocol will use a 244string describing the libavformat build. ("Lavf/<version>") 245 246@item timeout 247Set timeout in microseconds of socket I/O operations used by the underlying low level 248operation. By default it is set to -1, which means that the timeout is 249not specified. 250 251@item mime_type 252Export the MIME type. 253 254@item icy 255If set to 1 request ICY (SHOUTcast) metadata from the server. If the server 256supports this, the metadata has to be retrieved by the application by reading 257the @option{icy_metadata_headers} and @option{icy_metadata_packet} options. 258The default is 0. 259 260@item icy_metadata_headers 261If the server supports ICY metadata, this contains the ICY-specific HTTP reply 262headers, separated by newline characters. 263 264@item icy_metadata_packet 265If the server supports ICY metadata, and @option{icy} was set to 1, this 266contains the last non-empty metadata packet sent by the server. It should be 267polled in regular intervals by applications interested in mid-stream metadata 268updates. 269 270@item cookies 271Set the cookies to be sent in future requests. The format of each cookie is the 272same as the value of a Set-Cookie HTTP response field. Multiple cookies can be 273delimited by a newline character. 274 275@item offset 276Set initial byte offset. 277 278@item end_offset 279Try to limit the request to bytes preceding this offset. 280@end table 281 282@subsection HTTP Cookies 283 284Some HTTP requests will be denied unless cookie values are passed in with the 285request. The @option{cookies} option allows these cookies to be specified. At 286the very least, each cookie must specify a value along with a path and domain. 287HTTP requests that match both the domain and path will automatically include the 288cookie value in the HTTP Cookie header field. Multiple cookies can be delimited 289by a newline. 290 291The required syntax to play a stream specifying a cookie is: 292@example 293ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8 294@end example 295 296@section mmst 297 298MMS (Microsoft Media Server) protocol over TCP. 299 300@section mmsh 301 302MMS (Microsoft Media Server) protocol over HTTP. 303 304The required syntax is: 305@example 306mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] 307@end example 308 309@section md5 310 311MD5 output protocol. 312 313Computes the MD5 hash of the data to be written, and on close writes 314this to the designated output or stdout if none is specified. It can 315be used to test muxers without writing an actual file. 316 317Some examples follow. 318@example 319# Write the MD5 hash of the encoded AVI file to the file output.avi.md5. 320ffmpeg -i input.flv -f avi -y md5:output.avi.md5 321 322# Write the MD5 hash of the encoded AVI file to stdout. 323ffmpeg -i input.flv -f avi -y md5: 324@end example 325 326Note that some formats (typically MOV) require the output protocol to 327be seekable, so they will fail with the MD5 output protocol. 328 329@section pipe 330 331UNIX pipe access protocol. 332 333Allow to read and write from UNIX pipes. 334 335The accepted syntax is: 336@example 337pipe:[@var{number}] 338@end example 339 340@var{number} is the number corresponding to the file descriptor of the 341pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If @var{number} 342is not specified, by default the stdout file descriptor will be used 343for writing, stdin for reading. 344 345For example to read from stdin with @command{ffmpeg}: 346@example 347cat test.wav | ffmpeg -i pipe:0 348# ...this is the same as... 349cat test.wav | ffmpeg -i pipe: 350@end example 351 352For writing to stdout with @command{ffmpeg}: 353@example 354ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi 355# ...this is the same as... 356ffmpeg -i test.wav -f avi pipe: | cat > test.avi 357@end example 358 359This protocol accepts the following options: 360 361@table @option 362@item blocksize 363Set I/O operation maximum block size, in bytes. Default value is 364@code{INT_MAX}, which results in not limiting the requested block size. 365Setting this value reasonably low improves user termination request reaction 366time, which is valuable if data transmission is slow. 367@end table 368 369Note that some formats (typically MOV), require the output protocol to 370be seekable, so they will fail with the pipe output protocol. 371 372@section rtmp 373 374Real-Time Messaging Protocol. 375 376The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia 377content across a TCP/IP network. 378 379The required syntax is: 380@example 381rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}] 382@end example 383 384The accepted parameters are: 385@table @option 386 387@item username 388An optional username (mostly for publishing). 389 390@item password 391An optional password (mostly for publishing). 392 393@item server 394The address of the RTMP server. 395 396@item port 397The number of the TCP port to use (by default is 1935). 398 399@item app 400It is the name of the application to access. It usually corresponds to 401the path where the application is installed on the RTMP server 402(e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override 403the value parsed from the URI through the @code{rtmp_app} option, too. 404 405@item playpath 406It is the path or name of the resource to play with reference to the 407application specified in @var{app}, may be prefixed by "mp4:". You 408can override the value parsed from the URI through the @code{rtmp_playpath} 409option, too. 410 411@item listen 412Act as a server, listening for an incoming connection. 413 414@item timeout 415Maximum time to wait for the incoming connection. Implies listen. 416@end table 417 418Additionally, the following parameters can be set via command line options 419(or in code via @code{AVOption}s): 420@table @option 421 422@item rtmp_app 423Name of application to connect on the RTMP server. This option 424overrides the parameter specified in the URI. 425 426@item rtmp_buffer 427Set the client buffer time in milliseconds. The default is 3000. 428 429@item rtmp_conn 430Extra arbitrary AMF connection parameters, parsed from a string, 431e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}. 432Each value is prefixed by a single character denoting the type, 433B for Boolean, N for number, S for string, O for object, or Z for null, 434followed by a colon. For Booleans the data must be either 0 or 1 for 435FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or 4361 to end or begin an object, respectively. Data items in subobjects may 437be named, by prefixing the type with 'N' and specifying the name before 438the value (i.e. @code{NB:myFlag:1}). This option may be used multiple 439times to construct arbitrary AMF sequences. 440 441@item rtmp_flashver 442Version of the Flash plugin used to run the SWF player. The default 443is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; 444<libavformat version>).) 445 446@item rtmp_flush_interval 447Number of packets flushed in the same request (RTMPT only). The default 448is 10. 449 450@item rtmp_live 451Specify that the media is a live stream. No resuming or seeking in 452live streams is possible. The default value is @code{any}, which means the 453subscriber first tries to play the live stream specified in the 454playpath. If a live stream of that name is not found, it plays the 455recorded stream. The other possible values are @code{live} and 456@code{recorded}. 457 458@item rtmp_pageurl 459URL of the web page in which the media was embedded. By default no 460value will be sent. 461 462@item rtmp_playpath 463Stream identifier to play or to publish. This option overrides the 464parameter specified in the URI. 465 466@item rtmp_subscribe 467Name of live stream to subscribe to. By default no value will be sent. 468It is only sent if the option is specified or if rtmp_live 469is set to live. 470 471@item rtmp_swfhash 472SHA256 hash of the decompressed SWF file (32 bytes). 473 474@item rtmp_swfsize 475Size of the decompressed SWF file, required for SWFVerification. 476 477@item rtmp_swfurl 478URL of the SWF player for the media. By default no value will be sent. 479 480@item rtmp_swfverify 481URL to player swf file, compute hash/size automatically. 482 483@item rtmp_tcurl 484URL of the target stream. Defaults to proto://host[:port]/app. 485 486@end table 487 488For example to read with @command{ffplay} a multimedia resource named 489"sample" from the application "vod" from an RTMP server "myserver": 490@example 491ffplay rtmp://myserver/vod/sample 492@end example 493 494To publish to a password protected server, passing the playpath and 495app names separately: 496@example 497ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/ 498@end example 499 500@section rtmpe 501 502Encrypted Real-Time Messaging Protocol. 503 504The Encrypted Real-Time Messaging Protocol (RTMPE) is used for 505streaming multimedia content within standard cryptographic primitives, 506consisting of Diffie-Hellman key exchange and HMACSHA256, generating 507a pair of RC4 keys. 508 509@section rtmps 510 511Real-Time Messaging Protocol over a secure SSL connection. 512 513The Real-Time Messaging Protocol (RTMPS) is used for streaming 514multimedia content across an encrypted connection. 515 516@section rtmpt 517 518Real-Time Messaging Protocol tunneled through HTTP. 519 520The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used 521for streaming multimedia content within HTTP requests to traverse 522firewalls. 523 524@section rtmpte 525 526Encrypted Real-Time Messaging Protocol tunneled through HTTP. 527 528The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) 529is used for streaming multimedia content within HTTP requests to traverse 530firewalls. 531 532@section rtmpts 533 534Real-Time Messaging Protocol tunneled through HTTPS. 535 536The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used 537for streaming multimedia content within HTTPS requests to traverse 538firewalls. 539 540@section libsmbclient 541 542libsmbclient permits to manipulate CIFS/SMB network resources. 543 544Following syntax is required. 545 546@example 547smb://[[domain:]user[:password@@]]server[/share[/path[/file]]] 548@end example 549 550This protocol accepts the following options. 551 552@table @option 553@item timeout 554Set timeout in miliseconds of socket I/O operations used by the underlying 555low level operation. By default it is set to -1, which means that the timeout 556is not specified. 557 558@item truncate 559Truncate existing files on write, if set to 1. A value of 0 prevents 560truncating. Default value is 1. 561 562@item workgroup 563Set the workgroup used for making connections. By default workgroup is not specified. 564 565@end table 566 567For more information see: @url{http://www.samba.org/}. 568 569@section libssh 570 571Secure File Transfer Protocol via libssh 572 573Allow to read from or write to remote resources using SFTP protocol. 574 575Following syntax is required. 576 577@example 578sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg 579@end example 580 581This protocol accepts the following options. 582 583@table @option 584@item timeout 585Set timeout of socket I/O operations used by the underlying low level 586operation. By default it is set to -1, which means that the timeout 587is not specified. 588 589@item truncate 590Truncate existing files on write, if set to 1. A value of 0 prevents 591truncating. Default value is 1. 592 593@item private_key 594Specify the path of the file containing private key to use during authorization. 595By default libssh searches for keys in the @file{~/.ssh/} directory. 596 597@end table 598 599Example: Play a file stored on remote server. 600 601@example 602ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg 603@end example 604 605@section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte 606 607Real-Time Messaging Protocol and its variants supported through 608librtmp. 609 610Requires the presence of the librtmp headers and library during 611configuration. You need to explicitly configure the build with 612"--enable-librtmp". If enabled this will replace the native RTMP 613protocol. 614 615This protocol provides most client functions and a few server 616functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), 617encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled 618variants of these encrypted types (RTMPTE, RTMPTS). 619 620The required syntax is: 621@example 622@var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options} 623@end example 624 625where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe", 626"rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and 627@var{server}, @var{port}, @var{app} and @var{playpath} have the same 628meaning as specified for the RTMP native protocol. 629@var{options} contains a list of space-separated options of the form 630@var{key}=@var{val}. 631 632See the librtmp manual page (man 3 librtmp) for more information. 633 634For example, to stream a file in real-time to an RTMP server using 635@command{ffmpeg}: 636@example 637ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream 638@end example 639 640To play the same stream using @command{ffplay}: 641@example 642ffplay "rtmp://myserver/live/mystream live=1" 643@end example 644 645@section rtp 646 647Real-time Transport Protocol. 648 649The required syntax for an RTP URL is: 650rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...] 651 652@var{port} specifies the RTP port to use. 653 654The following URL options are supported: 655 656@table @option 657 658@item ttl=@var{n} 659Set the TTL (Time-To-Live) value (for multicast only). 660 661@item rtcpport=@var{n} 662Set the remote RTCP port to @var{n}. 663 664@item localrtpport=@var{n} 665Set the local RTP port to @var{n}. 666 667@item localrtcpport=@var{n}' 668Set the local RTCP port to @var{n}. 669 670@item pkt_size=@var{n} 671Set max packet size (in bytes) to @var{n}. 672 673@item connect=0|1 674Do a @code{connect()} on the UDP socket (if set to 1) or not (if set 675to 0). 676 677@item sources=@var{ip}[,@var{ip}] 678List allowed source IP addresses. 679 680@item block=@var{ip}[,@var{ip}] 681List disallowed (blocked) source IP addresses. 682 683@item write_to_source=0|1 684Send packets to the source address of the latest received packet (if 685set to 1) or to a default remote address (if set to 0). 686 687@item localport=@var{n} 688Set the local RTP port to @var{n}. 689 690This is a deprecated option. Instead, @option{localrtpport} should be 691used. 692 693@end table 694 695Important notes: 696 697@enumerate 698 699@item 700If @option{rtcpport} is not set the RTCP port will be set to the RTP 701port value plus 1. 702 703@item 704If @option{localrtpport} (the local RTP port) is not set any available 705port will be used for the local RTP and RTCP ports. 706 707@item 708If @option{localrtcpport} (the local RTCP port) is not set it will be 709set to the the local RTP port value plus 1. 710@end enumerate 711 712@section rtsp 713 714Real-Time Streaming Protocol. 715 716RTSP is not technically a protocol handler in libavformat, it is a demuxer 717and muxer. The demuxer supports both normal RTSP (with data transferred 718over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with 719data transferred over RDT). 720 721The muxer can be used to send a stream using RTSP ANNOUNCE to a server 722supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's 723@uref{https://github.com/revmischa/rtsp-server, RTSP server}). 724 725The required syntax for a RTSP url is: 726@example 727rtsp://@var{hostname}[:@var{port}]/@var{path} 728@end example 729 730Options can be set on the @command{ffmpeg}/@command{ffplay} command 731line, or set in code via @code{AVOption}s or in 732@code{avformat_open_input}. 733 734The following options are supported. 735 736@table @option 737@item initial_pause 738Do not start playing the stream immediately if set to 1. Default value 739is 0. 740 741@item rtsp_transport 742Set RTSP transport protocols. 743 744It accepts the following values: 745@table @samp 746@item udp 747Use UDP as lower transport protocol. 748 749@item tcp 750Use TCP (interleaving within the RTSP control channel) as lower 751transport protocol. 752 753@item udp_multicast 754Use UDP multicast as lower transport protocol. 755 756@item http 757Use HTTP tunneling as lower transport protocol, which is useful for 758passing proxies. 759@end table 760 761Multiple lower transport protocols may be specified, in that case they are 762tried one at a time (if the setup of one fails, the next one is tried). 763For the muxer, only the @samp{tcp} and @samp{udp} options are supported. 764 765@item rtsp_flags 766Set RTSP flags. 767 768The following values are accepted: 769@table @samp 770@item filter_src 771Accept packets only from negotiated peer address and port. 772@item listen 773Act as a server, listening for an incoming connection. 774@item prefer_tcp 775Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. 776@end table 777 778Default value is @samp{none}. 779 780@item allowed_media_types 781Set media types to accept from the server. 782 783The following flags are accepted: 784@table @samp 785@item video 786@item audio 787@item data 788@end table 789 790By default it accepts all media types. 791 792@item min_port 793Set minimum local UDP port. Default value is 5000. 794 795@item max_port 796Set maximum local UDP port. Default value is 65000. 797 798@item timeout 799Set maximum timeout (in seconds) to wait for incoming connections. 800 801A value of -1 means infinite (default). This option implies the 802@option{rtsp_flags} set to @samp{listen}. 803 804@item reorder_queue_size 805Set number of packets to buffer for handling of reordered packets. 806 807@item stimeout 808Set socket TCP I/O timeout in microseconds. 809 810@item user-agent 811Override User-Agent header. If not specified, it defaults to the 812libavformat identifier string. 813@end table 814 815When receiving data over UDP, the demuxer tries to reorder received packets 816(since they may arrive out of order, or packets may get lost totally). This 817can be disabled by setting the maximum demuxing delay to zero (via 818the @code{max_delay} field of AVFormatContext). 819 820When watching multi-bitrate Real-RTSP streams with @command{ffplay}, the 821streams to display can be chosen with @code{-vst} @var{n} and 822@code{-ast} @var{n} for video and audio respectively, and can be switched 823on the fly by pressing @code{v} and @code{a}. 824 825@subsection Examples 826 827The following examples all make use of the @command{ffplay} and 828@command{ffmpeg} tools. 829 830@itemize 831@item 832Watch a stream over UDP, with a max reordering delay of 0.5 seconds: 833@example 834ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4 835@end example 836 837@item 838Watch a stream tunneled over HTTP: 839@example 840ffplay -rtsp_transport http rtsp://server/video.mp4 841@end example 842 843@item 844Send a stream in realtime to a RTSP server, for others to watch: 845@example 846ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp 847@end example 848 849@item 850Receive a stream in realtime: 851@example 852ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output} 853@end example 854@end itemize 855 856@section sap 857 858Session Announcement Protocol (RFC 2974). This is not technically a 859protocol handler in libavformat, it is a muxer and demuxer. 860It is used for signalling of RTP streams, by announcing the SDP for the 861streams regularly on a separate port. 862 863@subsection Muxer 864 865The syntax for a SAP url given to the muxer is: 866@example 867sap://@var{destination}[:@var{port}][?@var{options}] 868@end example 869 870The RTP packets are sent to @var{destination} on port @var{port}, 871or to port 5004 if no port is specified. 872@var{options} is a @code{&}-separated list. The following options 873are supported: 874 875@table @option 876 877@item announce_addr=@var{address} 878Specify the destination IP address for sending the announcements to. 879If omitted, the announcements are sent to the commonly used SAP 880announcement multicast address 224.2.127.254 (sap.mcast.net), or 881ff0e::2:7ffe if @var{destination} is an IPv6 address. 882 883@item announce_port=@var{port} 884Specify the port to send the announcements on, defaults to 8859875 if not specified. 886 887@item ttl=@var{ttl} 888Specify the time to live value for the announcements and RTP packets, 889defaults to 255. 890 891@item same_port=@var{0|1} 892If set to 1, send all RTP streams on the same port pair. If zero (the 893default), all streams are sent on unique ports, with each stream on a 894port 2 numbers higher than the previous. 895VLC/Live555 requires this to be set to 1, to be able to receive the stream. 896The RTP stack in libavformat for receiving requires all streams to be sent 897on unique ports. 898@end table 899 900Example command lines follow. 901 902To broadcast a stream on the local subnet, for watching in VLC: 903 904@example 905ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1 906@end example 907 908Similarly, for watching in @command{ffplay}: 909 910@example 911ffmpeg -re -i @var{input} -f sap sap://224.0.0.255 912@end example 913 914And for watching in @command{ffplay}, over IPv6: 915 916@example 917ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4] 918@end example 919 920@subsection Demuxer 921 922The syntax for a SAP url given to the demuxer is: 923@example 924sap://[@var{address}][:@var{port}] 925@end example 926 927@var{address} is the multicast address to listen for announcements on, 928if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port} 929is the port that is listened on, 9875 if omitted. 930 931The demuxers listens for announcements on the given address and port. 932Once an announcement is received, it tries to receive that particular stream. 933 934Example command lines follow. 935 936To play back the first stream announced on the normal SAP multicast address: 937 938@example 939ffplay sap:// 940@end example 941 942To play back the first stream announced on one the default IPv6 SAP multicast address: 943 944@example 945ffplay sap://[ff0e::2:7ffe] 946@end example 947 948@section sctp 949 950Stream Control Transmission Protocol. 951 952The accepted URL syntax is: 953@example 954sctp://@var{host}:@var{port}[?@var{options}] 955@end example 956 957The protocol accepts the following options: 958@table @option 959@item listen 960If set to any value, listen for an incoming connection. Outgoing connection is done by default. 961 962@item max_streams 963Set the maximum number of streams. By default no limit is set. 964@end table 965 966@section srtp 967 968Secure Real-time Transport Protocol. 969 970The accepted options are: 971@table @option 972@item srtp_in_suite 973@item srtp_out_suite 974Select input and output encoding suites. 975 976Supported values: 977@table @samp 978@item AES_CM_128_HMAC_SHA1_80 979@item SRTP_AES128_CM_HMAC_SHA1_80 980@item AES_CM_128_HMAC_SHA1_32 981@item SRTP_AES128_CM_HMAC_SHA1_32 982@end table 983 984@item srtp_in_params 985@item srtp_out_params 986Set input and output encoding parameters, which are expressed by a 987base64-encoded representation of a binary block. The first 16 bytes of 988this binary block are used as master key, the following 14 bytes are 989used as master salt. 990@end table 991 992@section subfile 993 994Virtually extract a segment of a file or another stream. 995The underlying stream must be seekable. 996 997Accepted options: 998@table @option 999@item start 1000Start offset of the extracted segment, in bytes. 1001@item end 1002End offset of the extracted segment, in bytes. 1003@end table 1004 1005Examples: 1006 1007Extract a chapter from a DVD VOB file (start and end sectors obtained 1008externally and multiplied by 2048): 1009@example 1010subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB 1011@end example 1012 1013Play an AVI file directly from a TAR archive: 1014subfile,,start,183241728,end,366490624,,:archive.tar 1015 1016@section tcp 1017 1018Transmission Control Protocol. 1019 1020The required syntax for a TCP url is: 1021@example 1022tcp://@var{hostname}:@var{port}[?@var{options}] 1023@end example 1024 1025@var{options} contains a list of &-separated options of the form 1026@var{key}=@var{val}. 1027 1028The list of supported options follows. 1029 1030@table @option 1031@item listen=@var{1|0} 1032Listen for an incoming connection. Default value is 0. 1033 1034@item timeout=@var{microseconds} 1035Set raise error timeout, expressed in microseconds. 1036 1037This option is only relevant in read mode: if no data arrived in more 1038than this time interval, raise error. 1039 1040@item listen_timeout=@var{microseconds} 1041Set listen timeout, expressed in microseconds. 1042@end table 1043 1044The following example shows how to setup a listening TCP connection 1045with @command{ffmpeg}, which is then accessed with @command{ffplay}: 1046@example 1047ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen 1048ffplay tcp://@var{hostname}:@var{port} 1049@end example 1050 1051@section tls 1052 1053Transport Layer Security (TLS) / Secure Sockets Layer (SSL) 1054 1055The required syntax for a TLS/SSL url is: 1056@example 1057tls://@var{hostname}:@var{port}[?@var{options}] 1058@end example 1059 1060The following parameters can be set via command line options 1061(or in code via @code{AVOption}s): 1062 1063@table @option 1064 1065@item ca_file, cafile=@var{filename} 1066A file containing certificate authority (CA) root certificates to treat 1067as trusted. If the linked TLS library contains a default this might not 1068need to be specified for verification to work, but not all libraries and 1069setups have defaults built in. 1070The file must be in OpenSSL PEM format. 1071 1072@item tls_verify=@var{1|0} 1073If enabled, try to verify the peer that we are communicating with. 1074Note, if using OpenSSL, this currently only makes sure that the 1075peer certificate is signed by one of the root certificates in the CA 1076database, but it does not validate that the certificate actually 1077matches the host name we are trying to connect to. (With GnuTLS, 1078the host name is validated as well.) 1079 1080This is disabled by default since it requires a CA database to be 1081provided by the caller in many cases. 1082 1083@item cert_file, cert=@var{filename} 1084A file containing a certificate to use in the handshake with the peer. 1085(When operating as server, in listen mode, this is more often required 1086by the peer, while client certificates only are mandated in certain 1087setups.) 1088 1089@item key_file, key=@var{filename} 1090A file containing the private key for the certificate. 1091 1092@item listen=@var{1|0} 1093If enabled, listen for connections on the provided port, and assume 1094the server role in the handshake instead of the client role. 1095 1096@end table 1097 1098Example command lines: 1099 1100To create a TLS/SSL server that serves an input stream. 1101 1102@example 1103ffmpeg -i @var{input} -f @var{format} tls://@var{hostname}:@var{port}?listen&cert=@var{server.crt}&key=@var{server.key} 1104@end example 1105 1106To play back a stream from the TLS/SSL server using @command{ffplay}: 1107 1108@example 1109ffplay tls://@var{hostname}:@var{port} 1110@end example 1111 1112@section udp 1113 1114User Datagram Protocol. 1115 1116The required syntax for an UDP URL is: 1117@example 1118udp://@var{hostname}:@var{port}[?@var{options}] 1119@end example 1120 1121@var{options} contains a list of &-separated options of the form @var{key}=@var{val}. 1122 1123In case threading is enabled on the system, a circular buffer is used 1124to store the incoming data, which allows one to reduce loss of data due to 1125UDP socket buffer overruns. The @var{fifo_size} and 1126@var{overrun_nonfatal} options are related to this buffer. 1127 1128The list of supported options follows. 1129 1130@table @option 1131@item buffer_size=@var{size} 1132Set the UDP maximum socket buffer size in bytes. This is used to set either 1133the receive or send buffer size, depending on what the socket is used for. 1134Default is 64KB. See also @var{fifo_size}. 1135 1136@item localport=@var{port} 1137Override the local UDP port to bind with. 1138 1139@item localaddr=@var{addr} 1140Choose the local IP address. This is useful e.g. if sending multicast 1141and the host has multiple interfaces, where the user can choose 1142which interface to send on by specifying the IP address of that interface. 1143 1144@item pkt_size=@var{size} 1145Set the size in bytes of UDP packets. 1146 1147@item reuse=@var{1|0} 1148Explicitly allow or disallow reusing UDP sockets. 1149 1150@item ttl=@var{ttl} 1151Set the time to live value (for multicast only). 1152 1153@item connect=@var{1|0} 1154Initialize the UDP socket with @code{connect()}. In this case, the 1155destination address can't be changed with ff_udp_set_remote_url later. 1156If the destination address isn't known at the start, this option can 1157be specified in ff_udp_set_remote_url, too. 1158This allows finding out the source address for the packets with getsockname, 1159and makes writes return with AVERROR(ECONNREFUSED) if "destination 1160unreachable" is received. 1161For receiving, this gives the benefit of only receiving packets from 1162the specified peer address/port. 1163 1164@item sources=@var{address}[,@var{address}] 1165Only receive packets sent to the multicast group from one of the 1166specified sender IP addresses. 1167 1168@item block=@var{address}[,@var{address}] 1169Ignore packets sent to the multicast group from the specified 1170sender IP addresses. 1171 1172@item fifo_size=@var{units} 1173Set the UDP receiving circular buffer size, expressed as a number of 1174packets with size of 188 bytes. If not specified defaults to 7*4096. 1175 1176@item overrun_nonfatal=@var{1|0} 1177Survive in case of UDP receiving circular buffer overrun. Default 1178value is 0. 1179 1180@item timeout=@var{microseconds} 1181Set raise error timeout, expressed in microseconds. 1182 1183This option is only relevant in read mode: if no data arrived in more 1184than this time interval, raise error. 1185 1186@item broadcast=@var{1|0} 1187Explicitly allow or disallow UDP broadcasting. 1188 1189Note that broadcasting may not work properly on networks having 1190a broadcast storm protection. 1191@end table 1192 1193@subsection Examples 1194 1195@itemize 1196@item 1197Use @command{ffmpeg} to stream over UDP to a remote endpoint: 1198@example 1199ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port} 1200@end example 1201 1202@item 1203Use @command{ffmpeg} to stream in mpegts format over UDP using 188 1204sized UDP packets, using a large input buffer: 1205@example 1206ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535 1207@end example 1208 1209@item 1210Use @command{ffmpeg} to receive over UDP from a remote endpoint: 1211@example 1212ffmpeg -i udp://[@var{multicast-address}]:@var{port} ... 1213@end example 1214@end itemize 1215 1216@section unix 1217 1218Unix local socket 1219 1220The required syntax for a Unix socket URL is: 1221 1222@example 1223unix://@var{filepath} 1224@end example 1225 1226The following parameters can be set via command line options 1227(or in code via @code{AVOption}s): 1228 1229@table @option 1230@item timeout 1231Timeout in ms. 1232@item listen 1233Create the Unix socket in listening mode. 1234@end table 1235 1236@c man end PROTOCOLS 1237