Merge commit 'f8df5e2f31a5ba7b30a0e1caaaf5a03c753b3f9b'
[ffmpeg.git] / doc / protocols.texi
1 @chapter Protocol Options
2 @c man begin PROTOCOL OPTIONS
3
4 The libavformat library provides some generic global options, which
5 can be set on all the protocols. In addition each protocol may support
6 so-called private options, which are specific for that component.
7
8 Options may be set by specifying -@var{option} @var{value} in the
9 FFmpeg tools, or by setting the value explicitly in the
10 @code{AVFormatContext} options or using the @file{libavutil/opt.h} API
11 for programmatic use.
12
13 The list of supported options follows:
14
15 @table @option
16 @item protocol_whitelist @var{list} (@emph{input})
17 Set a ","-separated list of allowed protocols. "ALL" matches all protocols. Protocols
18 prefixed by "-" are disabled.
19 All protocols are allowed by default but protocols used by an another
20 protocol (nested protocols) are restricted to a per protocol subset.
21 @end table
22
23 @c man end PROTOCOL OPTIONS
24
25 @chapter Protocols
26 @c man begin PROTOCOLS
27
28 Protocols are configured elements in FFmpeg that enable access to
29 resources that require specific protocols.
30
31 When you configure your FFmpeg build, all the supported protocols are
32 enabled by default. You can list all available ones using the
33 configure option "--list-protocols".
34
35 You can disable all the protocols using the configure option
36 "--disable-protocols", and selectively enable a protocol using the
37 option "--enable-protocol=@var{PROTOCOL}", or you can disable a
38 particular protocol using the option
39 "--disable-protocol=@var{PROTOCOL}".
40
41 The option "-protocols" of the ff* tools will display the list of
42 supported protocols.
43
44 All protocols accept the following options:
45
46 @table @option
47 @item rw_timeout
48 Maximum time to wait for (network) read/write operations to complete,
49 in microseconds.
50 @end table
51
52 A description of the currently available protocols follows.
53
54 @section async
55
56 Asynchronous data filling wrapper for input stream.
57
58 Fill data in a background thread, to decouple I/O operation from demux thread.
59
60 @example
61 async:@var{URL}
62 async:http://host/resource
63 async:cache:http://host/resource
64 @end example
65
66 @section bluray
67
68 Read BluRay playlist.
69
70 The accepted options are:
71 @table @option
72
73 @item angle
74 BluRay angle
75
76 @item chapter
77 Start chapter (1...N)
78
79 @item playlist
80 Playlist to read (BDMV/PLAYLIST/?????.mpls)
81
82 @end table
83
84 Examples:
85
86 Read longest playlist from BluRay mounted to /mnt/bluray:
87 @example
88 bluray:/mnt/bluray
89 @end example
90
91 Read angle 2 of playlist 4 from BluRay mounted to /mnt/bluray, start from chapter 2:
92 @example
93 -playlist 4 -angle 2 -chapter 2 bluray:/mnt/bluray
94 @end example
95
96 @section cache
97
98 Caching wrapper for input stream.
99
100 Cache the input stream to temporary file. It brings seeking capability to live streams.
101
102 @example
103 cache:@var{URL}
104 @end example
105
106 @section concat
107
108 Physical concatenation protocol.
109
110 Read and seek from many resources in sequence as if they were
111 a unique resource.
112
113 A URL accepted by this protocol has the syntax:
114 @example
115 concat:@var{URL1}|@var{URL2}|...|@var{URLN}
116 @end example
117
118 where @var{URL1}, @var{URL2}, ..., @var{URLN} are the urls of the
119 resource to be concatenated, each one possibly specifying a distinct
120 protocol.
121
122 For example to read a sequence of files @file{split1.mpeg},
123 @file{split2.mpeg}, @file{split3.mpeg} with @command{ffplay} use the
124 command:
125 @example
126 ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
127 @end example
128
129 Note that you may need to escape the character "|" which is special for
130 many shells.
131
132 @section crypto
133
134 AES-encrypted stream reading protocol.
135
136 The accepted options are:
137 @table @option
138 @item key
139 Set the AES decryption key binary block from given hexadecimal representation.
140
141 @item iv
142 Set the AES decryption initialization vector binary block from given hexadecimal representation.
143 @end table
144
145 Accepted URL formats:
146 @example
147 crypto:@var{URL}
148 crypto+@var{URL}
149 @end example
150
151 @section data
152
153 Data in-line in the URI. See @url{http://en.wikipedia.org/wiki/Data_URI_scheme}.
154
155 For example, to convert a GIF file given inline with @command{ffmpeg}:
156 @example
157 ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
158 @end example
159
160 @section file
161
162 File access protocol.
163
164 Read from or write to a file.
165
166 A file URL can have the form:
167 @example
168 file:@var{filename}
169 @end example
170
171 where @var{filename} is the path of the file to read.
172
173 An URL that does not have a protocol prefix will be assumed to be a
174 file URL. Depending on the build, an URL that looks like a Windows
175 path with the drive letter at the beginning will also be assumed to be
176 a file URL (usually not the case in builds for unix-like systems).
177
178 For example to read from a file @file{input.mpeg} with @command{ffmpeg}
179 use the command:
180 @example
181 ffmpeg -i file:input.mpeg output.mpeg
182 @end example
183
184 This protocol accepts the following options:
185
186 @table @option
187 @item truncate
188 Truncate existing files on write, if set to 1. A value of 0 prevents
189 truncating. Default value is 1.
190
191 @item blocksize
192 Set I/O operation maximum block size, in bytes. Default value is
193 @code{INT_MAX}, which results in not limiting the requested block size.
194 Setting this value reasonably low improves user termination request reaction
195 time, which is valuable for files on slow medium.
196
197 @item follow
198 If set to 1, the protocol will retry reading at the end of the file, allowing
199 reading files that still are being written. In order for this to terminate,
200 you either need to use the rw_timeout option, or use the interrupt callback
201 (for API users).
202 @end table
203
204 @section ftp
205
206 FTP (File Transfer Protocol).
207
208 Read from or write to remote resources using FTP protocol.
209
210 Following syntax is required.
211 @example
212 ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
213 @end example
214
215 This protocol accepts the following options.
216
217 @table @option
218 @item timeout
219 Set timeout in microseconds of socket I/O operations used by the underlying low level
220 operation. By default it is set to -1, which means that the timeout is
221 not specified.
222
223 @item ftp-anonymous-password
224 Password used when login as anonymous user. Typically an e-mail address
225 should be used.
226
227 @item ftp-write-seekable
228 Control seekability of connection during encoding. If set to 1 the
229 resource is supposed to be seekable, if set to 0 it is assumed not
230 to be seekable. Default value is 0.
231 @end table
232
233 NOTE: Protocol can be used as output, but it is recommended to not do
234 it, unless special care is taken (tests, customized server configuration
235 etc.). Different FTP servers behave in different way during seek
236 operation. ff* tools may produce incomplete content due to server limitations.
237
238 @section gopher
239
240 Gopher protocol.
241
242 @section hls
243
244 Read Apple HTTP Live Streaming compliant segmented stream as
245 a uniform one. The M3U8 playlists describing the segments can be
246 remote HTTP resources or local files, accessed using the standard
247 file protocol.
248 The nested protocol is declared by specifying
249 "+@var{proto}" after the hls URI scheme name, where @var{proto}
250 is either "file" or "http".
251
252 @example
253 hls+http://host/path/to/remote/resource.m3u8
254 hls+file://path/to/local/resource.m3u8
255 @end example
256
257 Using this protocol is discouraged - the hls demuxer should work
258 just as well (if not, please report the issues) and is more complete.
259 To use the hls demuxer instead, simply use the direct URLs to the
260 m3u8 files.
261
262 @section http
263
264 HTTP (Hyper Text Transfer Protocol).
265
266 This protocol accepts the following options:
267
268 @table @option
269 @item seekable
270 Control seekability of connection. If set to 1 the resource is
271 supposed to be seekable, if set to 0 it is assumed not to be seekable,
272 if set to -1 it will try to autodetect if it is seekable. Default
273 value is -1.
274
275 @item chunked_post
276 If set to 1 use chunked Transfer-Encoding for posts, default is 1.
277
278 @item content_type
279 Set a specific content type for the POST messages or for listen mode.
280
281 @item http_proxy
282 set HTTP proxy to tunnel through e.g. http://example.com:1234
283
284 @item headers
285 Set custom HTTP headers, can override built in default headers. The
286 value must be a string encoding the headers.
287
288 @item multiple_requests
289 Use persistent connections if set to 1, default is 0.
290
291 @item post_data
292 Set custom HTTP post data.
293
294 @item referer
295 Set the Referer header. Include 'Referer: URL' header in HTTP request.
296
297 @item user_agent
298 Override the User-Agent header. If not specified the protocol will use a
299 string describing the libavformat build. ("Lavf/<version>")
300
301 @item user-agent
302 This is a deprecated option, you can use user_agent instead it.
303
304 @item timeout
305 Set timeout in microseconds of socket I/O operations used by the underlying low level
306 operation. By default it is set to -1, which means that the timeout is
307 not specified.
308
309 @item reconnect_at_eof
310 If set then eof is treated like an error and causes reconnection, this is useful
311 for live / endless streams.
312
313 @item reconnect_streamed
314 If set then even streamed/non seekable streams will be reconnected on errors.
315
316 @item reconnect_delay_max
317 Sets the maximum delay in seconds after which to give up reconnecting
318
319 @item mime_type
320 Export the MIME type.
321
322 @item http_version
323 Exports the HTTP response version number. Usually "1.0" or "1.1".
324
325 @item icy
326 If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
327 supports this, the metadata has to be retrieved by the application by reading
328 the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
329 The default is 1.
330
331 @item icy_metadata_headers
332 If the server supports ICY metadata, this contains the ICY-specific HTTP reply
333 headers, separated by newline characters.
334
335 @item icy_metadata_packet
336 If the server supports ICY metadata, and @option{icy} was set to 1, this
337 contains the last non-empty metadata packet sent by the server. It should be
338 polled in regular intervals by applications interested in mid-stream metadata
339 updates.
340
341 @item cookies
342 Set the cookies to be sent in future requests. The format of each cookie is the
343 same as the value of a Set-Cookie HTTP response field. Multiple cookies can be
344 delimited by a newline character.
345
346 @item offset
347 Set initial byte offset.
348
349 @item end_offset
350 Try to limit the request to bytes preceding this offset.
351
352 @item method
353 When used as a client option it sets the HTTP method for the request.
354
355 When used as a server option it sets the HTTP method that is going to be
356 expected from the client(s).
357 If the expected and the received HTTP method do not match the client will
358 be given a Bad Request response.
359 When unset the HTTP method is not checked for now. This will be replaced by
360 autodetection in the future.
361
362 @item listen
363 If set to 1 enables experimental HTTP server. This can be used to send data when
364 used as an output option, or read data from a client with HTTP POST when used as
365 an input option.
366 If set to 2 enables experimental multi-client HTTP server. This is not yet implemented
367 in ffmpeg.c and thus must not be used as a command line option.
368 @example
369 # Server side (sending):
370 ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://@var{server}:@var{port}
371
372 # Client side (receiving):
373 ffmpeg -i http://@var{server}:@var{port} -c copy somefile.ogg
374
375 # Client can also be done with wget:
376 wget http://@var{server}:@var{port} -O somefile.ogg
377
378 # Server side (receiving):
379 ffmpeg -listen 1 -i http://@var{server}:@var{port} -c copy somefile.ogg
380
381 # Client side (sending):
382 ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://@var{server}:@var{port}
383
384 # Client can also be done with wget:
385 wget --post-file=somefile.ogg http://@var{server}:@var{port}
386 @end example
387
388 @end table
389
390 @subsection HTTP Cookies
391
392 Some HTTP requests will be denied unless cookie values are passed in with the
393 request. The @option{cookies} option allows these cookies to be specified. At
394 the very least, each cookie must specify a value along with a path and domain.
395 HTTP requests that match both the domain and path will automatically include the
396 cookie value in the HTTP Cookie header field. Multiple cookies can be delimited
397 by a newline.
398
399 The required syntax to play a stream specifying a cookie is:
400 @example
401 ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
402 @end example
403
404 @section Icecast
405
406 Icecast protocol (stream to Icecast servers)
407
408 This protocol accepts the following options:
409
410 @table @option
411 @item ice_genre
412 Set the stream genre.
413
414 @item ice_name
415 Set the stream name.
416
417 @item ice_description
418 Set the stream description.
419
420 @item ice_url
421 Set the stream website URL.
422
423 @item ice_public
424 Set if the stream should be public.
425 The default is 0 (not public).
426
427 @item user_agent
428 Override the User-Agent header. If not specified a string of the form
429 "Lavf/<version>" will be used.
430
431 @item password
432 Set the Icecast mountpoint password.
433
434 @item content_type
435 Set the stream content type. This must be set if it is different from
436 audio/mpeg.
437
438 @item legacy_icecast
439 This enables support for Icecast versions < 2.4.0, that do not support the
440 HTTP PUT method but the SOURCE method.
441
442 @end table
443
444 @example
445 icecast://[@var{username}[:@var{password}]@@]@var{server}:@var{port}/@var{mountpoint}
446 @end example
447
448 @section mmst
449
450 MMS (Microsoft Media Server) protocol over TCP.
451
452 @section mmsh
453
454 MMS (Microsoft Media Server) protocol over HTTP.
455
456 The required syntax is:
457 @example
458 mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
459 @end example
460
461 @section md5
462
463 MD5 output protocol.
464
465 Computes the MD5 hash of the data to be written, and on close writes
466 this to the designated output or stdout if none is specified. It can
467 be used to test muxers without writing an actual file.
468
469 Some examples follow.
470 @example
471 # Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
472 ffmpeg -i input.flv -f avi -y md5:output.avi.md5
473
474 # Write the MD5 hash of the encoded AVI file to stdout.
475 ffmpeg -i input.flv -f avi -y md5:
476 @end example
477
478 Note that some formats (typically MOV) require the output protocol to
479 be seekable, so they will fail with the MD5 output protocol.
480
481 @section pipe
482
483 UNIX pipe access protocol.
484
485 Read and write from UNIX pipes.
486
487 The accepted syntax is:
488 @example
489 pipe:[@var{number}]
490 @end example
491
492 @var{number} is the number corresponding to the file descriptor of the
493 pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).  If @var{number}
494 is not specified, by default the stdout file descriptor will be used
495 for writing, stdin for reading.
496
497 For example to read from stdin with @command{ffmpeg}:
498 @example
499 cat test.wav | ffmpeg -i pipe:0
500 # ...this is the same as...
501 cat test.wav | ffmpeg -i pipe:
502 @end example
503
504 For writing to stdout with @command{ffmpeg}:
505 @example
506 ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
507 # ...this is the same as...
508 ffmpeg -i test.wav -f avi pipe: | cat > test.avi
509 @end example
510
511 This protocol accepts the following options:
512
513 @table @option
514 @item blocksize
515 Set I/O operation maximum block size, in bytes. Default value is
516 @code{INT_MAX}, which results in not limiting the requested block size.
517 Setting this value reasonably low improves user termination request reaction
518 time, which is valuable if data transmission is slow.
519 @end table
520
521 Note that some formats (typically MOV), require the output protocol to
522 be seekable, so they will fail with the pipe output protocol.
523
524 @section prompeg
525
526 Pro-MPEG Code of Practice #3 Release 2 FEC protocol.
527
528 The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism
529 for MPEG-2 Transport Streams sent over RTP.
530
531 This protocol must be used in conjunction with the @code{rtp_mpegts} muxer and
532 the @code{rtp} protocol.
533
534 The required syntax is:
535 @example
536 -f rtp_mpegts -fec prompeg=@var{option}=@var{val}... rtp://@var{hostname}:@var{port}
537 @end example
538
539 The destination UDP ports are @code{port + 2} for the column FEC stream
540 and @code{port + 4} for the row FEC stream.
541
542 This protocol accepts the following options:
543 @table @option
544
545 @item l=@var{n}
546 The number of columns (4-20, LxD <= 100)
547
548 @item d=@var{n}
549 The number of rows (4-20, LxD <= 100)
550
551 @end table
552
553 Example usage:
554
555 @example
556 -f rtp_mpegts -fec prompeg=l=8:d=4 rtp://@var{hostname}:@var{port}
557 @end example
558
559 @section rtmp
560
561 Real-Time Messaging Protocol.
562
563 The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia
564 content across a TCP/IP network.
565
566 The required syntax is:
567 @example
568 rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
569 @end example
570
571 The accepted parameters are:
572 @table @option
573
574 @item username
575 An optional username (mostly for publishing).
576
577 @item password
578 An optional password (mostly for publishing).
579
580 @item server
581 The address of the RTMP server.
582
583 @item port
584 The number of the TCP port to use (by default is 1935).
585
586 @item app
587 It is the name of the application to access. It usually corresponds to
588 the path where the application is installed on the RTMP server
589 (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override
590 the value parsed from the URI through the @code{rtmp_app} option, too.
591
592 @item playpath
593 It is the path or name of the resource to play with reference to the
594 application specified in @var{app}, may be prefixed by "mp4:". You
595 can override the value parsed from the URI through the @code{rtmp_playpath}
596 option, too.
597
598 @item listen
599 Act as a server, listening for an incoming connection.
600
601 @item timeout
602 Maximum time to wait for the incoming connection. Implies listen.
603 @end table
604
605 Additionally, the following parameters can be set via command line options
606 (or in code via @code{AVOption}s):
607 @table @option
608
609 @item rtmp_app
610 Name of application to connect on the RTMP server. This option
611 overrides the parameter specified in the URI.
612
613 @item rtmp_buffer
614 Set the client buffer time in milliseconds. The default is 3000.
615
616 @item rtmp_conn
617 Extra arbitrary AMF connection parameters, parsed from a string,
618 e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}.
619 Each value is prefixed by a single character denoting the type,
620 B for Boolean, N for number, S for string, O for object, or Z for null,
621 followed by a colon. For Booleans the data must be either 0 or 1 for
622 FALSE or TRUE, respectively.  Likewise for Objects the data must be 0 or
623 1 to end or begin an object, respectively. Data items in subobjects may
624 be named, by prefixing the type with 'N' and specifying the name before
625 the value (i.e. @code{NB:myFlag:1}). This option may be used multiple
626 times to construct arbitrary AMF sequences.
627
628 @item rtmp_flashver
629 Version of the Flash plugin used to run the SWF player. The default
630 is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible;
631 <libavformat version>).)
632
633 @item rtmp_flush_interval
634 Number of packets flushed in the same request (RTMPT only). The default
635 is 10.
636
637 @item rtmp_live
638 Specify that the media is a live stream. No resuming or seeking in
639 live streams is possible. The default value is @code{any}, which means the
640 subscriber first tries to play the live stream specified in the
641 playpath. If a live stream of that name is not found, it plays the
642 recorded stream. The other possible values are @code{live} and
643 @code{recorded}.
644
645 @item rtmp_pageurl
646 URL of the web page in which the media was embedded. By default no
647 value will be sent.
648
649 @item rtmp_playpath
650 Stream identifier to play or to publish. This option overrides the
651 parameter specified in the URI.
652
653 @item rtmp_subscribe
654 Name of live stream to subscribe to. By default no value will be sent.
655 It is only sent if the option is specified or if rtmp_live
656 is set to live.
657
658 @item rtmp_swfhash
659 SHA256 hash of the decompressed SWF file (32 bytes).
660
661 @item rtmp_swfsize
662 Size of the decompressed SWF file, required for SWFVerification.
663
664 @item rtmp_swfurl
665 URL of the SWF player for the media. By default no value will be sent.
666
667 @item rtmp_swfverify
668 URL to player swf file, compute hash/size automatically.
669
670 @item rtmp_tcurl
671 URL of the target stream. Defaults to proto://host[:port]/app.
672
673 @end table
674
675 For example to read with @command{ffplay} a multimedia resource named
676 "sample" from the application "vod" from an RTMP server "myserver":
677 @example
678 ffplay rtmp://myserver/vod/sample
679 @end example
680
681 To publish to a password protected server, passing the playpath and
682 app names separately:
683 @example
684 ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/
685 @end example
686
687 @section rtmpe
688
689 Encrypted Real-Time Messaging Protocol.
690
691 The Encrypted Real-Time Messaging Protocol (RTMPE) is used for
692 streaming multimedia content within standard cryptographic primitives,
693 consisting of Diffie-Hellman key exchange and HMACSHA256, generating
694 a pair of RC4 keys.
695
696 @section rtmps
697
698 Real-Time Messaging Protocol over a secure SSL connection.
699
700 The Real-Time Messaging Protocol (RTMPS) is used for streaming
701 multimedia content across an encrypted connection.
702
703 @section rtmpt
704
705 Real-Time Messaging Protocol tunneled through HTTP.
706
707 The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used
708 for streaming multimedia content within HTTP requests to traverse
709 firewalls.
710
711 @section rtmpte
712
713 Encrypted Real-Time Messaging Protocol tunneled through HTTP.
714
715 The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE)
716 is used for streaming multimedia content within HTTP requests to traverse
717 firewalls.
718
719 @section rtmpts
720
721 Real-Time Messaging Protocol tunneled through HTTPS.
722
723 The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
724 for streaming multimedia content within HTTPS requests to traverse
725 firewalls.
726
727 @section libsmbclient
728
729 libsmbclient permits one to manipulate CIFS/SMB network resources.
730
731 Following syntax is required.
732
733 @example
734 smb://[[domain:]user[:password@@]]server[/share[/path[/file]]]
735 @end example
736
737 This protocol accepts the following options.
738
739 @table @option
740 @item timeout
741 Set timeout in milliseconds of socket I/O operations used by the underlying
742 low level operation. By default it is set to -1, which means that the timeout
743 is not specified.
744
745 @item truncate
746 Truncate existing files on write, if set to 1. A value of 0 prevents
747 truncating. Default value is 1.
748
749 @item workgroup
750 Set the workgroup used for making connections. By default workgroup is not specified.
751
752 @end table
753
754 For more information see: @url{http://www.samba.org/}.
755
756 @section libssh
757
758 Secure File Transfer Protocol via libssh
759
760 Read from or write to remote resources using SFTP protocol.
761
762 Following syntax is required.
763
764 @example
765 sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
766 @end example
767
768 This protocol accepts the following options.
769
770 @table @option
771 @item timeout
772 Set timeout of socket I/O operations used by the underlying low level
773 operation. By default it is set to -1, which means that the timeout
774 is not specified.
775
776 @item truncate
777 Truncate existing files on write, if set to 1. A value of 0 prevents
778 truncating. Default value is 1.
779
780 @item private_key
781 Specify the path of the file containing private key to use during authorization.
782 By default libssh searches for keys in the @file{~/.ssh/} directory.
783
784 @end table
785
786 Example: Play a file stored on remote server.
787
788 @example
789 ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg
790 @end example
791
792 @section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte
793
794 Real-Time Messaging Protocol and its variants supported through
795 librtmp.
796
797 Requires the presence of the librtmp headers and library during
798 configuration. You need to explicitly configure the build with
799 "--enable-librtmp". If enabled this will replace the native RTMP
800 protocol.
801
802 This protocol provides most client functions and a few server
803 functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT),
804 encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled
805 variants of these encrypted types (RTMPTE, RTMPTS).
806
807 The required syntax is:
808 @example
809 @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options}
810 @end example
811
812 where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe",
813 "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and
814 @var{server}, @var{port}, @var{app} and @var{playpath} have the same
815 meaning as specified for the RTMP native protocol.
816 @var{options} contains a list of space-separated options of the form
817 @var{key}=@var{val}.
818
819 See the librtmp manual page (man 3 librtmp) for more information.
820
821 For example, to stream a file in real-time to an RTMP server using
822 @command{ffmpeg}:
823 @example
824 ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
825 @end example
826
827 To play the same stream using @command{ffplay}:
828 @example
829 ffplay "rtmp://myserver/live/mystream live=1"
830 @end example
831
832 @section rtp
833
834 Real-time Transport Protocol.
835
836 The required syntax for an RTP URL is:
837 rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...]
838
839 @var{port} specifies the RTP port to use.
840
841 The following URL options are supported:
842
843 @table @option
844
845 @item ttl=@var{n}
846 Set the TTL (Time-To-Live) value (for multicast only).
847
848 @item rtcpport=@var{n}
849 Set the remote RTCP port to @var{n}.
850
851 @item localrtpport=@var{n}
852 Set the local RTP port to @var{n}.
853
854 @item localrtcpport=@var{n}'
855 Set the local RTCP port to @var{n}.
856
857 @item pkt_size=@var{n}
858 Set max packet size (in bytes) to @var{n}.
859
860 @item connect=0|1
861 Do a @code{connect()} on the UDP socket (if set to 1) or not (if set
862 to 0).
863
864 @item sources=@var{ip}[,@var{ip}]
865 List allowed source IP addresses.
866
867 @item block=@var{ip}[,@var{ip}]
868 List disallowed (blocked) source IP addresses.
869
870 @item write_to_source=0|1
871 Send packets to the source address of the latest received packet (if
872 set to 1) or to a default remote address (if set to 0).
873
874 @item localport=@var{n}
875 Set the local RTP port to @var{n}.
876
877 This is a deprecated option. Instead, @option{localrtpport} should be
878 used.
879
880 @end table
881
882 Important notes:
883
884 @enumerate
885
886 @item
887 If @option{rtcpport} is not set the RTCP port will be set to the RTP
888 port value plus 1.
889
890 @item
891 If @option{localrtpport} (the local RTP port) is not set any available
892 port will be used for the local RTP and RTCP ports.
893
894 @item
895 If @option{localrtcpport} (the local RTCP port) is not set it will be
896 set to the local RTP port value plus 1.
897 @end enumerate
898
899 @section rtsp
900
901 Real-Time Streaming Protocol.
902
903 RTSP is not technically a protocol handler in libavformat, it is a demuxer
904 and muxer. The demuxer supports both normal RTSP (with data transferred
905 over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
906 data transferred over RDT).
907
908 The muxer can be used to send a stream using RTSP ANNOUNCE to a server
909 supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's
910 @uref{https://github.com/revmischa/rtsp-server, RTSP server}).
911
912 The required syntax for a RTSP url is:
913 @example
914 rtsp://@var{hostname}[:@var{port}]/@var{path}
915 @end example
916
917 Options can be set on the @command{ffmpeg}/@command{ffplay} command
918 line, or set in code via @code{AVOption}s or in
919 @code{avformat_open_input}.
920
921 The following options are supported.
922
923 @table @option
924 @item initial_pause
925 Do not start playing the stream immediately if set to 1. Default value
926 is 0.
927
928 @item rtsp_transport
929 Set RTSP transport protocols.
930
931 It accepts the following values:
932 @table @samp
933 @item udp
934 Use UDP as lower transport protocol.
935
936 @item tcp
937 Use TCP (interleaving within the RTSP control channel) as lower
938 transport protocol.
939
940 @item udp_multicast
941 Use UDP multicast as lower transport protocol.
942
943 @item http
944 Use HTTP tunneling as lower transport protocol, which is useful for
945 passing proxies.
946 @end table
947
948 Multiple lower transport protocols may be specified, in that case they are
949 tried one at a time (if the setup of one fails, the next one is tried).
950 For the muxer, only the @samp{tcp} and @samp{udp} options are supported.
951
952 @item rtsp_flags
953 Set RTSP flags.
954
955 The following values are accepted:
956 @table @samp
957 @item filter_src
958 Accept packets only from negotiated peer address and port.
959 @item listen
960 Act as a server, listening for an incoming connection.
961 @item prefer_tcp
962 Try TCP for RTP transport first, if TCP is available as RTSP RTP transport.
963 @end table
964
965 Default value is @samp{none}.
966
967 @item allowed_media_types
968 Set media types to accept from the server.
969
970 The following flags are accepted:
971 @table @samp
972 @item video
973 @item audio
974 @item data
975 @end table
976
977 By default it accepts all media types.
978
979 @item min_port
980 Set minimum local UDP port. Default value is 5000.
981
982 @item max_port
983 Set maximum local UDP port. Default value is 65000.
984
985 @item timeout
986 Set maximum timeout (in seconds) to wait for incoming connections.
987
988 A value of -1 means infinite (default). This option implies the
989 @option{rtsp_flags} set to @samp{listen}.
990
991 @item reorder_queue_size
992 Set number of packets to buffer for handling of reordered packets.
993
994 @item stimeout
995 Set socket TCP I/O timeout in microseconds.
996
997 @item user-agent
998 Override User-Agent header. If not specified, it defaults to the
999 libavformat identifier string.
1000 @end table
1001
1002 When receiving data over UDP, the demuxer tries to reorder received packets
1003 (since they may arrive out of order, or packets may get lost totally). This
1004 can be disabled by setting the maximum demuxing delay to zero (via
1005 the @code{max_delay} field of AVFormatContext).
1006
1007 When watching multi-bitrate Real-RTSP streams with @command{ffplay}, the
1008 streams to display can be chosen with @code{-vst} @var{n} and
1009 @code{-ast} @var{n} for video and audio respectively, and can be switched
1010 on the fly by pressing @code{v} and @code{a}.
1011
1012 @subsection Examples
1013
1014 The following examples all make use of the @command{ffplay} and
1015 @command{ffmpeg} tools.
1016
1017 @itemize
1018 @item
1019 Watch a stream over UDP, with a max reordering delay of 0.5 seconds:
1020 @example
1021 ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
1022 @end example
1023
1024 @item
1025 Watch a stream tunneled over HTTP:
1026 @example
1027 ffplay -rtsp_transport http rtsp://server/video.mp4
1028 @end example
1029
1030 @item
1031 Send a stream in realtime to a RTSP server, for others to watch:
1032 @example
1033 ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
1034 @end example
1035
1036 @item
1037 Receive a stream in realtime:
1038 @example
1039 ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
1040 @end example
1041 @end itemize
1042
1043 @section sap
1044
1045 Session Announcement Protocol (RFC 2974). This is not technically a
1046 protocol handler in libavformat, it is a muxer and demuxer.
1047 It is used for signalling of RTP streams, by announcing the SDP for the
1048 streams regularly on a separate port.
1049
1050 @subsection Muxer
1051
1052 The syntax for a SAP url given to the muxer is:
1053 @example
1054 sap://@var{destination}[:@var{port}][?@var{options}]
1055 @end example
1056
1057 The RTP packets are sent to @var{destination} on port @var{port},
1058 or to port 5004 if no port is specified.
1059 @var{options} is a @code{&}-separated list. The following options
1060 are supported:
1061
1062 @table @option
1063
1064 @item announce_addr=@var{address}
1065 Specify the destination IP address for sending the announcements to.
1066 If omitted, the announcements are sent to the commonly used SAP
1067 announcement multicast address 224.2.127.254 (sap.mcast.net), or
1068 ff0e::2:7ffe if @var{destination} is an IPv6 address.
1069
1070 @item announce_port=@var{port}
1071 Specify the port to send the announcements on, defaults to
1072 9875 if not specified.
1073
1074 @item ttl=@var{ttl}
1075 Specify the time to live value for the announcements and RTP packets,
1076 defaults to 255.
1077
1078 @item same_port=@var{0|1}
1079 If set to 1, send all RTP streams on the same port pair. If zero (the
1080 default), all streams are sent on unique ports, with each stream on a
1081 port 2 numbers higher than the previous.
1082 VLC/Live555 requires this to be set to 1, to be able to receive the stream.
1083 The RTP stack in libavformat for receiving requires all streams to be sent
1084 on unique ports.
1085 @end table
1086
1087 Example command lines follow.
1088
1089 To broadcast a stream on the local subnet, for watching in VLC:
1090
1091 @example
1092 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
1093 @end example
1094
1095 Similarly, for watching in @command{ffplay}:
1096
1097 @example
1098 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255
1099 @end example
1100
1101 And for watching in @command{ffplay}, over IPv6:
1102
1103 @example
1104 ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4]
1105 @end example
1106
1107 @subsection Demuxer
1108
1109 The syntax for a SAP url given to the demuxer is:
1110 @example
1111 sap://[@var{address}][:@var{port}]
1112 @end example
1113
1114 @var{address} is the multicast address to listen for announcements on,
1115 if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port}
1116 is the port that is listened on, 9875 if omitted.
1117
1118 The demuxers listens for announcements on the given address and port.
1119 Once an announcement is received, it tries to receive that particular stream.
1120
1121 Example command lines follow.
1122
1123 To play back the first stream announced on the normal SAP multicast address:
1124
1125 @example
1126 ffplay sap://
1127 @end example
1128
1129 To play back the first stream announced on one the default IPv6 SAP multicast address:
1130
1131 @example
1132 ffplay sap://[ff0e::2:7ffe]
1133 @end example
1134
1135 @section sctp
1136
1137 Stream Control Transmission Protocol.
1138
1139 The accepted URL syntax is:
1140 @example
1141 sctp://@var{host}:@var{port}[?@var{options}]
1142 @end example
1143
1144 The protocol accepts the following options:
1145 @table @option
1146 @item listen
1147 If set to any value, listen for an incoming connection. Outgoing connection is done by default.
1148
1149 @item max_streams
1150 Set the maximum number of streams. By default no limit is set.
1151 @end table
1152
1153 @section srt
1154
1155 Haivision Secure Reliable Transport Protocol via libsrt.
1156
1157 The supported syntax for a SRT URL is:
1158 @example
1159 srt://@var{hostname}:@var{port}[?@var{options}]
1160 @end example
1161
1162 @var{options} contains a list of &-separated options of the form
1163 @var{key}=@var{val}.
1164
1165 or
1166
1167 @example
1168 @var{options} srt://@var{hostname}:@var{port}
1169 @end example
1170
1171 @var{options} contains a list of '-@var{key} @var{val}'
1172 options.
1173
1174 This protocol accepts the following options.
1175
1176 @table @option
1177 @item connect_timeout
1178 Connection timeout; SRT cannot connect for RTT > 1500 msec
1179 (2 handshake exchanges) with the default connect timeout of
1180 3 seconds. This option applies to the caller and rendezvous
1181 connection modes. The connect timeout is 10 times the value
1182 set for the rendezvous mode (which can be used as a
1183 workaround for this connection problem with earlier versions).
1184
1185 @item ffs=@var{bytes}
1186 Flight Flag Size (Window Size), in bytes. FFS is actually an
1187 internal parameter and you should set it to not less than
1188 @option{recv_buffer_size} and @option{mss}. The default value
1189 is relatively large, therefore unless you set a very large receiver buffer,
1190 you do not need to change this option. Default value is 25600.
1191
1192 @item inputbw=@var{bytes/seconds}
1193 Sender nominal input rate, in bytes per seconds. Used along with
1194 @option{oheadbw}, when @option{maxbw} is set to relative (0), to
1195 calculate maximum sending rate when recovery packets are sent
1196 along with the main media stream:
1197 @option{inputbw} * (100 + @option{oheadbw}) / 100
1198 if @option{inputbw} is not set while @option{maxbw} is set to
1199 relative (0), the actual input rate is evaluated inside
1200 the library. Default value is 0.
1201
1202 @item iptos=@var{tos}
1203 IP Type of Service. Applies to sender only. Default value is 0xB8.
1204
1205 @item ipttl=@var{ttl}
1206 IP Time To Live. Applies to sender only. Default value is 64.
1207
1208 @item latency
1209 Timestamp-based Packet Delivery Delay.
1210 Used to absorb bursts of missed packet retransmissions.
1211 This flag sets both @option{rcvlatency} and @option{peerlatency}
1212 to the same value. Note that prior to version 1.3.0
1213 this is the only flag to set the latency, however
1214 this is effectively equivalent to setting @option{peerlatency},
1215 when side is sender and @option{rcvlatency}
1216 when side is receiver, and the bidirectional stream
1217 sending is not supported.
1218
1219 @item listen_timeout
1220 Set socket listen timeout.
1221
1222 @item maxbw=@var{bytes/seconds}
1223 Maximum sending bandwidth, in bytes per seconds.
1224 -1 infinite (CSRTCC limit is 30mbps)
1225 0 relative to input rate (see @option{inputbw})
1226 >0 absolute limit value
1227 Default value is 0 (relative)
1228
1229 @item mode=@var{caller|listener|rendezvous}
1230 Connection mode.
1231 @option{caller} opens client connection.
1232 @option{listener} starts server to listen for incoming connections.
1233 @option{rendezvous} use Rendez-Vous connection mode.
1234 Default value is caller.
1235
1236 @item mss=@var{bytes}
1237 Maximum Segment Size, in bytes. Used for buffer allocation
1238 and rate calculation using a packet counter assuming fully
1239 filled packets. The smallest MSS between the peers is
1240 used. This is 1500 by default in the overall internet.
1241 This is the maximum size of the UDP packet and can be
1242 only decreased, unless you have some unusual dedicated
1243 network settings. Default value is 1500.
1244
1245 @item nakreport=@var{1|0}
1246 If set to 1, Receiver will send `UMSG_LOSSREPORT` messages
1247 periodically until a lost packet is retransmitted or
1248 intentionally dropped. Default value is 1.
1249
1250 @item oheadbw=@var{percents}
1251 Recovery bandwidth overhead above input rate, in percents.
1252 See @option{inputbw}. Default value is 25%.
1253
1254 @item passphrase=@var{string}
1255 HaiCrypt Encryption/Decryption Passphrase string, length
1256 from 10 to 79 characters. The passphrase is the shared
1257 secret between the sender and the receiver. It is used
1258 to generate the Key Encrypting Key using PBKDF2
1259 (Password-Based Key Derivation Function). It is used
1260 only if @option{pbkeylen} is non-zero. It is used on
1261 the receiver only if the received data is encrypted.
1262 The configured passphrase cannot be recovered (write-only).
1263
1264 @item payload_size=@var{bytes}
1265 Sets the maximum declared size of a packet transferred
1266 during the single call to the sending function in Live
1267 mode. Use 0 if this value isn't used (which is default in
1268 file mode).
1269 Default is -1 (automatic), which typically means MPEG-TS;
1270 if you are going to use SRT
1271 to send any different kind of payload, such as, for example,
1272 wrapping a live stream in very small frames, then you can
1273 use a bigger maximum frame size, though not greater than
1274 1456 bytes.
1275
1276 @item pkt_size=@var{bytes}
1277 Alias for @samp{payload_size}.
1278
1279 @item peerlatency
1280 The latency value (as described in @option{rcvlatency}) that is
1281 set by the sender side as a minimum value for the receiver.
1282
1283 @item pbkeylen=@var{bytes}
1284 Sender encryption key length, in bytes.
1285 Only can be set to 0, 16, 24 and 32.
1286 Enable sender encryption if not 0.
1287 Not required on receiver (set to 0),
1288 key size obtained from sender in HaiCrypt handshake.
1289 Default value is 0.
1290
1291 @item rcvlatency
1292 The time that should elapse since the moment when the
1293 packet was sent and the moment when it's delivered to
1294 the receiver application in the receiving function.
1295 This time should be a buffer time large enough to cover
1296 the time spent for sending, unexpectedly extended RTT
1297 time, and the time needed to retransmit the lost UDP
1298 packet. The effective latency value will be the maximum
1299 of this options' value and the value of @option{peerlatency}
1300 set by the peer side. Before version 1.3.0 this option
1301 is only available as @option{latency}.
1302
1303 @item recv_buffer_size=@var{bytes}
1304 Set UDP receive buffer size, expressed in bytes.
1305
1306 @item send_buffer_size=@var{bytes}
1307 Set UDP send buffer size, expressed in bytes.
1308
1309 @item rw_timeout
1310 Set raise error timeout for read/write optations.
1311
1312 This option is only relevant in read mode:
1313 if no data arrived in more than this time
1314 interval, raise error.
1315
1316 @item tlpktdrop=@var{1|0}
1317 Too-late Packet Drop. When enabled on receiver, it skips
1318 missing packets that have not been delivered in time and
1319 delivers the following packets to the application when
1320 their time-to-play has come. It also sends a fake ACK to
1321 the sender. When enabled on sender and enabled on the
1322 receiving peer, the sender drops the older packets that
1323 have no chance of being delivered in time. It was
1324 automatically enabled in the sender if the receiver
1325 supports it.
1326
1327 @item sndbuf=@var{bytes}
1328 Set send buffer size, expressed in bytes.
1329
1330 @item rcvbuf=@var{bytes}
1331 Set receive buffer size, expressed in bytes.
1332
1333 Receive buffer must not be greater than @option{ffs}.
1334
1335 @item lossmaxttl=@var{packets}
1336 The value up to which the Reorder Tolerance may grow. When
1337 Reorder Tolerance is > 0, then packet loss report is delayed
1338 until that number of packets come in. Reorder Tolerance
1339 increases every time a "belated" packet has come, but it
1340 wasn't due to retransmission (that is, when UDP packets tend
1341 to come out of order), with the difference between the latest
1342 sequence and this packet's sequence, and not more than the
1343 value of this option. By default it's 0, which means that this
1344 mechanism is turned off, and the loss report is always sent
1345 immediately upon experiencing a "gap" in sequences.
1346
1347 @item minversion
1348 The minimum SRT version that is required from the peer. A connection
1349 to a peer that does not satisfy the minimum version requirement
1350 will be rejected.
1351
1352 The version format in hex is 0xXXYYZZ for x.y.z in human readable
1353 form.
1354
1355 @item streamid=@var{string}
1356 A string limited to 512 characters that can be set on the socket prior
1357 to connecting. This stream ID will be able to be retrieved by the
1358 listener side from the socket that is returned from srt_accept and
1359 was connected by a socket with that set stream ID. SRT does not enforce
1360 any special interpretation of the contents of this string.
1361 This option doesn’t make sense in Rendezvous connection; the result
1362 might be that simply one side will override the value from the other
1363 side and it’s the matter of luck which one would win
1364
1365 @item smoother=@var{live|file}
1366 The type of Smoother used for the transmission for that socket, which
1367 is responsible for the transmission and congestion control. The Smoother
1368 type must be exactly the same on both connecting parties, otherwise
1369 the connection is rejected.
1370
1371 @item messageapi=@var{1|0}
1372 When set, this socket uses the Message API, otherwise it uses Buffer
1373 API. Note that in live mode (see @option{transtype}) there’s only
1374 message API available. In File mode you can chose to use one of two modes:
1375
1376 Stream API (default, when this option is false). In this mode you may
1377 send as many data as you wish with one sending instruction, or even use
1378 dedicated functions that read directly from a file. The internal facility
1379 will take care of any speed and congestion control. When receiving, you
1380 can also receive as many data as desired, the data not extracted will be
1381 waiting for the next call. There is no boundary between data portions in
1382 the Stream mode.
1383
1384 Message API. In this mode your single sending instruction passes exactly
1385 one piece of data that has boundaries (a message). Contrary to Live mode,
1386 this message may span across multiple UDP packets and the only size
1387 limitation is that it shall fit as a whole in the sending buffer. The
1388 receiver shall use as large buffer as necessary to receive the message,
1389 otherwise the message will not be given up. When the message is not
1390 complete (not all packets received or there was a packet loss) it will
1391 not be given up.
1392
1393 @item transtype=@var{live|file}
1394 Sets the transmission type for the socket, in particular, setting this
1395 option sets multiple other parameters to their default values as required
1396 for a particular transmission type.
1397
1398 live: Set options as for live transmission. In this mode, you should
1399 send by one sending instruction only so many data that fit in one UDP packet,
1400 and limited to the value defined first in @option{payload_size} (1316 is
1401 default in this mode). There is no speed control in this mode, only the
1402 bandwidth control, if configured, in order to not exceed the bandwidth with
1403 the overhead transmission (retransmitted and control packets).
1404
1405 file: Set options as for non-live transmission. See @option{messageapi}
1406 for further explanations
1407
1408 @end table
1409
1410 For more information see: @url{https://github.com/Haivision/srt}.
1411
1412 @section srtp
1413
1414 Secure Real-time Transport Protocol.
1415
1416 The accepted options are:
1417 @table @option
1418 @item srtp_in_suite
1419 @item srtp_out_suite
1420 Select input and output encoding suites.
1421
1422 Supported values:
1423 @table @samp
1424 @item AES_CM_128_HMAC_SHA1_80
1425 @item SRTP_AES128_CM_HMAC_SHA1_80
1426 @item AES_CM_128_HMAC_SHA1_32
1427 @item SRTP_AES128_CM_HMAC_SHA1_32
1428 @end table
1429
1430 @item srtp_in_params
1431 @item srtp_out_params
1432 Set input and output encoding parameters, which are expressed by a
1433 base64-encoded representation of a binary block. The first 16 bytes of
1434 this binary block are used as master key, the following 14 bytes are
1435 used as master salt.
1436 @end table
1437
1438 @section subfile
1439
1440 Virtually extract a segment of a file or another stream.
1441 The underlying stream must be seekable.
1442
1443 Accepted options:
1444 @table @option
1445 @item start
1446 Start offset of the extracted segment, in bytes.
1447 @item end
1448 End offset of the extracted segment, in bytes.
1449 If set to 0, extract till end of file.
1450 @end table
1451
1452 Examples:
1453
1454 Extract a chapter from a DVD VOB file (start and end sectors obtained
1455 externally and multiplied by 2048):
1456 @example
1457 subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB
1458 @end example
1459
1460 Play an AVI file directly from a TAR archive:
1461 @example
1462 subfile,,start,183241728,end,366490624,,:archive.tar
1463 @end example
1464
1465 Play a MPEG-TS file from start offset till end:
1466 @example
1467 subfile,,start,32815239,end,0,,:video.ts
1468 @end example
1469
1470 @section tee
1471
1472 Writes the output to multiple protocols. The individual outputs are separated
1473 by |
1474
1475 @example
1476 tee:file://path/to/local/this.avi|file://path/to/local/that.avi
1477 @end example
1478
1479 @section tcp
1480
1481 Transmission Control Protocol.
1482
1483 The required syntax for a TCP url is:
1484 @example
1485 tcp://@var{hostname}:@var{port}[?@var{options}]
1486 @end example
1487
1488 @var{options} contains a list of &-separated options of the form
1489 @var{key}=@var{val}.
1490
1491 The list of supported options follows.
1492
1493 @table @option
1494 @item listen=@var{1|0}
1495 Listen for an incoming connection. Default value is 0.
1496
1497 @item timeout=@var{microseconds}
1498 Set raise error timeout, expressed in microseconds.
1499
1500 This option is only relevant in read mode: if no data arrived in more
1501 than this time interval, raise error.
1502
1503 @item listen_timeout=@var{milliseconds}
1504 Set listen timeout, expressed in milliseconds.
1505
1506 @item recv_buffer_size=@var{bytes}
1507 Set receive buffer size, expressed bytes.
1508
1509 @item send_buffer_size=@var{bytes}
1510 Set send buffer size, expressed bytes.
1511
1512 @item tcp_nodelay=@var{1|0}
1513 Set TCP_NODELAY to disable Nagle's algorithm. Default value is 0.
1514
1515 @item tcp_mss=@var{bytes}
1516 Set maximum segment size for outgoing TCP packets, expressed in bytes.
1517 @end table
1518
1519 The following example shows how to setup a listening TCP connection
1520 with @command{ffmpeg}, which is then accessed with @command{ffplay}:
1521 @example
1522 ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen
1523 ffplay tcp://@var{hostname}:@var{port}
1524 @end example
1525
1526 @section tls
1527
1528 Transport Layer Security (TLS) / Secure Sockets Layer (SSL)
1529
1530 The required syntax for a TLS/SSL url is:
1531 @example
1532 tls://@var{hostname}:@var{port}[?@var{options}]
1533 @end example
1534
1535 The following parameters can be set via command line options
1536 (or in code via @code{AVOption}s):
1537
1538 @table @option
1539
1540 @item ca_file, cafile=@var{filename}
1541 A file containing certificate authority (CA) root certificates to treat
1542 as trusted. If the linked TLS library contains a default this might not
1543 need to be specified for verification to work, but not all libraries and
1544 setups have defaults built in.
1545 The file must be in OpenSSL PEM format.
1546
1547 @item tls_verify=@var{1|0}
1548 If enabled, try to verify the peer that we are communicating with.
1549 Note, if using OpenSSL, this currently only makes sure that the
1550 peer certificate is signed by one of the root certificates in the CA
1551 database, but it does not validate that the certificate actually
1552 matches the host name we are trying to connect to. (With other backends,
1553 the host name is validated as well.)
1554
1555 This is disabled by default since it requires a CA database to be
1556 provided by the caller in many cases.
1557
1558 @item cert_file, cert=@var{filename}
1559 A file containing a certificate to use in the handshake with the peer.
1560 (When operating as server, in listen mode, this is more often required
1561 by the peer, while client certificates only are mandated in certain
1562 setups.)
1563
1564 @item key_file, key=@var{filename}
1565 A file containing the private key for the certificate.
1566
1567 @item listen=@var{1|0}
1568 If enabled, listen for connections on the provided port, and assume
1569 the server role in the handshake instead of the client role.
1570
1571 @end table
1572
1573 Example command lines:
1574
1575 To create a TLS/SSL server that serves an input stream.
1576
1577 @example
1578 ffmpeg -i @var{input} -f @var{format} tls://@var{hostname}:@var{port}?listen&cert=@var{server.crt}&key=@var{server.key}
1579 @end example
1580
1581 To play back a stream from the TLS/SSL server using @command{ffplay}:
1582
1583 @example
1584 ffplay tls://@var{hostname}:@var{port}
1585 @end example
1586
1587 @section udp
1588
1589 User Datagram Protocol.
1590
1591 The required syntax for an UDP URL is:
1592 @example
1593 udp://@var{hostname}:@var{port}[?@var{options}]
1594 @end example
1595
1596 @var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
1597
1598 In case threading is enabled on the system, a circular buffer is used
1599 to store the incoming data, which allows one to reduce loss of data due to
1600 UDP socket buffer overruns. The @var{fifo_size} and
1601 @var{overrun_nonfatal} options are related to this buffer.
1602
1603 The list of supported options follows.
1604
1605 @table @option
1606 @item buffer_size=@var{size}
1607 Set the UDP maximum socket buffer size in bytes. This is used to set either
1608 the receive or send buffer size, depending on what the socket is used for.
1609 Default is 64KB.  See also @var{fifo_size}.
1610
1611 @item bitrate=@var{bitrate}
1612 If set to nonzero, the output will have the specified constant bitrate if the
1613 input has enough packets to sustain it.
1614
1615 @item burst_bits=@var{bits}
1616 When using @var{bitrate} this specifies the maximum number of bits in
1617 packet bursts.
1618
1619 @item localport=@var{port}
1620 Override the local UDP port to bind with.
1621
1622 @item localaddr=@var{addr}
1623 Local IP address of a network interface used for sending packets or joining
1624 multicast groups.
1625
1626 @item pkt_size=@var{size}
1627 Set the size in bytes of UDP packets.
1628
1629 @item reuse=@var{1|0}
1630 Explicitly allow or disallow reusing UDP sockets.
1631
1632 @item ttl=@var{ttl}
1633 Set the time to live value (for multicast only).
1634
1635 @item connect=@var{1|0}
1636 Initialize the UDP socket with @code{connect()}. In this case, the
1637 destination address can't be changed with ff_udp_set_remote_url later.
1638 If the destination address isn't known at the start, this option can
1639 be specified in ff_udp_set_remote_url, too.
1640 This allows finding out the source address for the packets with getsockname,
1641 and makes writes return with AVERROR(ECONNREFUSED) if "destination
1642 unreachable" is received.
1643 For receiving, this gives the benefit of only receiving packets from
1644 the specified peer address/port.
1645
1646 @item sources=@var{address}[,@var{address}]
1647 Only receive packets sent from the specified addresses. In case of multicast,
1648 also subscribe to multicast traffic coming from these addresses only.
1649
1650 @item block=@var{address}[,@var{address}]
1651 Ignore packets sent from the specified addresses. In case of multicast, also
1652 exclude the source addresses in the multicast subscription.
1653
1654 @item fifo_size=@var{units}
1655 Set the UDP receiving circular buffer size, expressed as a number of
1656 packets with size of 188 bytes. If not specified defaults to 7*4096.
1657
1658 @item overrun_nonfatal=@var{1|0}
1659 Survive in case of UDP receiving circular buffer overrun. Default
1660 value is 0.
1661
1662 @item timeout=@var{microseconds}
1663 Set raise error timeout, expressed in microseconds.
1664
1665 This option is only relevant in read mode: if no data arrived in more
1666 than this time interval, raise error.
1667
1668 @item broadcast=@var{1|0}
1669 Explicitly allow or disallow UDP broadcasting.
1670
1671 Note that broadcasting may not work properly on networks having
1672 a broadcast storm protection.
1673 @end table
1674
1675 @subsection Examples
1676
1677 @itemize
1678 @item
1679 Use @command{ffmpeg} to stream over UDP to a remote endpoint:
1680 @example
1681 ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port}
1682 @end example
1683
1684 @item
1685 Use @command{ffmpeg} to stream in mpegts format over UDP using 188
1686 sized UDP packets, using a large input buffer:
1687 @example
1688 ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535
1689 @end example
1690
1691 @item
1692 Use @command{ffmpeg} to receive over UDP from a remote endpoint:
1693 @example
1694 ffmpeg -i udp://[@var{multicast-address}]:@var{port} ...
1695 @end example
1696 @end itemize
1697
1698 @section unix
1699
1700 Unix local socket
1701
1702 The required syntax for a Unix socket URL is:
1703
1704 @example
1705 unix://@var{filepath}
1706 @end example
1707
1708 The following parameters can be set via command line options
1709 (or in code via @code{AVOption}s):
1710
1711 @table @option
1712 @item timeout
1713 Timeout in ms.
1714 @item listen
1715 Create the Unix socket in listening mode.
1716 @end table
1717
1718 @c man end PROTOCOLS