doc/filters: clarify documentation for overlay repeatlast option
[ffmpeg.git] / doc / protocols.texi
1 @chapter Protocols
2 @c man begin PROTOCOLS
3
4 Protocols are configured elements in FFmpeg which allow to access
5 resources which require the use of a particular protocol.
6
7 When you configure your FFmpeg build, all the supported protocols are
8 enabled by default. You can list all available ones using the
9 configure option "--list-protocols".
10
11 You can disable all the protocols using the configure option
12 "--disable-protocols", and selectively enable a protocol using the
13 option "--enable-protocol=@var{PROTOCOL}", or you can disable a
14 particular protocol using the option
15 "--disable-protocol=@var{PROTOCOL}".
16
17 The option "-protocols" of the ff* tools will display the list of
18 supported protocols.
19
20 A description of the currently available protocols follows.
21
22 @section bluray
23
24 Read BluRay playlist.
25
26 The accepted options are:
27 @table @option
28
29 @item angle
30 BluRay angle
31
32 @item chapter
33 Start chapter (1...N)
34
35 @item playlist
36 Playlist to read (BDMV/PLAYLIST/?????.mpls)
37
38 @end table
39
40 Examples:
41
42 Read longest playlist from BluRay mounted to /mnt/bluray:
43 @example
44 bluray:/mnt/bluray
45 @end example
46
47 Read 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
54 Caching wrapper for input stream.
55
56 Cache the input stream to temporary file. It brings seeking capability to live streams.
57
58 @example
59 cache:@var{URL}
60 @end example
61
62 @section concat
63
64 Physical concatenation protocol.
65
66 Allow to read and seek from many resource in sequence as if they were
67 a unique resource.
68
69 A URL accepted by this protocol has the syntax:
70 @example
71 concat:@var{URL1}|@var{URL2}|...|@var{URLN}
72 @end example
73
74 where @var{URL1}, @var{URL2}, ..., @var{URLN} are the urls of the
75 resource to be concatenated, each one possibly specifying a distinct
76 protocol.
77
78 For example to read a sequence of files @file{split1.mpeg},
79 @file{split2.mpeg}, @file{split3.mpeg} with @command{ffplay} use the
80 command:
81 @example
82 ffplay concat:split1.mpeg\|split2.mpeg\|split3.mpeg
83 @end example
84
85 Note that you may need to escape the character "|" which is special for
86 many shells.
87
88 @section crypto
89
90 AES-encrypted stream reading protocol.
91
92 The accepted options are:
93 @table @option
94 @item key
95 Set the AES decryption key binary block from given hexadecimal representation.
96
97 @item iv
98 Set the AES decryption initialization vector binary block from given hexadecimal representation.
99 @end table
100
101 Accepted URL formats:
102 @example
103 crypto:@var{URL}
104 crypto+@var{URL}
105 @end example
106
107 @section data
108
109 Data in-line in the URI. See @url{http://en.wikipedia.org/wiki/Data_URI_scheme}.
110
111 For example, to convert a GIF file given inline with @command{ffmpeg}:
112 @example
113 ffmpeg -i "data:image/gif;base64,R0lGODdhCAAIAMIEAAAAAAAA//8AAP//AP///////////////ywAAAAACAAIAAADF0gEDLojDgdGiJdJqUX02iB4E8Q9jUMkADs=" smiley.png
114 @end example
115
116 @section file
117
118 File access protocol.
119
120 Allow to read from or read to a file.
121
122 For example to read from a file @file{input.mpeg} with @command{ffmpeg}
123 use the command:
124 @example
125 ffmpeg -i file:input.mpeg output.mpeg
126 @end example
127
128 The ff* tools default to the file protocol, that is a resource
129 specified with the name "FILE.mpeg" is interpreted as the URL
130 "file:FILE.mpeg".
131
132 @section ftp
133
134 FTP (File Transfer Protocol).
135
136 Allow to read from or write to remote resources using FTP protocol.
137
138 Following syntax is required.
139 @example
140 ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg
141 @end example
142
143 This protocol accepts the following options.
144
145 @table @option
146 @item timeout
147 Set timeout of socket I/O operations used by the underlying low level
148 operation. By default it is set to -1, which means that the timeout is
149 not specified.
150
151 @item ftp-anonymous-password
152 Password used when login as anonymous user. Typically an e-mail address
153 should be used.
154
155 @item ftp-write-seekable
156 Control seekability of connection during encoding. If set to 1 the
157 resource is supposed to be seekable, if set to 0 it is assumed not
158 to be seekable. Default value is 0.
159 @end table
160
161 NOTE: Protocol can be used as output, but it is recommended to not do
162 it, unless special care is taken (tests, customized server configuration
163 etc.). Different FTP servers behave in different way during seek
164 operation. ff* tools may produce incomplete content due to server limitations.
165
166 @section gopher
167
168 Gopher protocol.
169
170 @section hls
171
172 Read Apple HTTP Live Streaming compliant segmented stream as
173 a uniform one. The M3U8 playlists describing the segments can be
174 remote HTTP resources or local files, accessed using the standard
175 file protocol.
176 The nested protocol is declared by specifying
177 "+@var{proto}" after the hls URI scheme name, where @var{proto}
178 is either "file" or "http".
179
180 @example
181 hls+http://host/path/to/remote/resource.m3u8
182 hls+file://path/to/local/resource.m3u8
183 @end example
184
185 Using this protocol is discouraged - the hls demuxer should work
186 just as well (if not, please report the issues) and is more complete.
187 To use the hls demuxer instead, simply use the direct URLs to the
188 m3u8 files.
189
190 @section http
191
192 HTTP (Hyper Text Transfer Protocol).
193
194 This protocol accepts the following options.
195
196 @table @option
197 @item seekable
198 Control seekability of connection. If set to 1 the resource is
199 supposed to be seekable, if set to 0 it is assumed not to be seekable,
200 if set to -1 it will try to autodetect if it is seekable. Default
201 value is -1.
202
203 @item chunked_post
204 If set to 1 use chunked transfer-encoding for posts, default is 1.
205
206 @item headers
207 Set custom HTTP headers, can override built in default headers. The
208 value must be a string encoding the headers.
209
210 @item content_type
211 Force a content type.
212
213 @item user-agent
214 Override User-Agent header. If not specified the protocol will use a
215 string describing the libavformat build.
216
217 @item multiple_requests
218 Use persistent connections if set to 1. By default it is 0.
219
220 @item post_data
221 Set custom HTTP post data.
222
223 @item timeout
224 Set timeout of socket I/O operations used by the underlying low level
225 operation. By default it is set to -1, which means that the timeout is
226 not specified.
227
228 @item mime_type
229 Set MIME type.
230
231 @item icy
232 If set to 1 request ICY (SHOUTcast) metadata from the server. If the server
233 supports this, the metadata has to be retrieved by the application by reading
234 the @option{icy_metadata_headers} and @option{icy_metadata_packet} options.
235 The default is 0.
236
237 @item icy_metadata_headers
238 If the server supports ICY metadata, this contains the ICY specific HTTP reply
239 headers, separated with newline characters.
240
241 @item icy_metadata_packet
242 If the server supports ICY metadata, and @option{icy} was set to 1, this
243 contains the last non-empty metadata packet sent by the server.
244
245 @item cookies
246 Set the cookies to be sent in future requests. The format of each cookie is the
247 same as the value of a Set-Cookie HTTP response field. Multiple cookies can be
248 delimited by a newline character.
249 @end table
250
251 @subsection HTTP Cookies
252
253 Some HTTP requests will be denied unless cookie values are passed in with the
254 request. The @option{cookies} option allows these cookies to be specified. At
255 the very least, each cookie must specify a value along with a path and domain.
256 HTTP requests that match both the domain and path will automatically include the
257 cookie value in the HTTP Cookie header field. Multiple cookies can be delimited
258 by a newline.
259
260 The required syntax to play a stream specifying a cookie is:
261 @example
262 ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8
263 @end example
264
265 @section mmst
266
267 MMS (Microsoft Media Server) protocol over TCP.
268
269 @section mmsh
270
271 MMS (Microsoft Media Server) protocol over HTTP.
272
273 The required syntax is:
274 @example
275 mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}]
276 @end example
277
278 @section md5
279
280 MD5 output protocol.
281
282 Computes the MD5 hash of the data to be written, and on close writes
283 this to the designated output or stdout if none is specified. It can
284 be used to test muxers without writing an actual file.
285
286 Some examples follow.
287 @example
288 # Write the MD5 hash of the encoded AVI file to the file output.avi.md5.
289 ffmpeg -i input.flv -f avi -y md5:output.avi.md5
290
291 # Write the MD5 hash of the encoded AVI file to stdout.
292 ffmpeg -i input.flv -f avi -y md5:
293 @end example
294
295 Note that some formats (typically MOV) require the output protocol to
296 be seekable, so they will fail with the MD5 output protocol.
297
298 @section pipe
299
300 UNIX pipe access protocol.
301
302 Allow to read and write from UNIX pipes.
303
304 The accepted syntax is:
305 @example
306 pipe:[@var{number}]
307 @end example
308
309 @var{number} is the number corresponding to the file descriptor of the
310 pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr).  If @var{number}
311 is not specified, by default the stdout file descriptor will be used
312 for writing, stdin for reading.
313
314 For example to read from stdin with @command{ffmpeg}:
315 @example
316 cat test.wav | ffmpeg -i pipe:0
317 # ...this is the same as...
318 cat test.wav | ffmpeg -i pipe:
319 @end example
320
321 For writing to stdout with @command{ffmpeg}:
322 @example
323 ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi
324 # ...this is the same as...
325 ffmpeg -i test.wav -f avi pipe: | cat > test.avi
326 @end example
327
328 Note that some formats (typically MOV), require the output protocol to
329 be seekable, so they will fail with the pipe output protocol.
330
331 @section rtmp
332
333 Real-Time Messaging Protocol.
334
335 The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia
336 content across a TCP/IP network.
337
338 The required syntax is:
339 @example
340 rtmp://@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}]
341 @end example
342
343 The accepted parameters are:
344 @table @option
345
346 @item server
347 The address of the RTMP server.
348
349 @item port
350 The number of the TCP port to use (by default is 1935).
351
352 @item app
353 It is the name of the application to access. It usually corresponds to
354 the path where the application is installed on the RTMP server
355 (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override
356 the value parsed from the URI through the @code{rtmp_app} option, too.
357
358 @item playpath
359 It is the path or name of the resource to play with reference to the
360 application specified in @var{app}, may be prefixed by "mp4:". You
361 can override the value parsed from the URI through the @code{rtmp_playpath}
362 option, too.
363
364 @item listen
365 Act as a server, listening for an incoming connection.
366
367 @item timeout
368 Maximum time to wait for the incoming connection. Implies listen.
369 @end table
370
371 Additionally, the following parameters can be set via command line options
372 (or in code via @code{AVOption}s):
373 @table @option
374
375 @item rtmp_app
376 Name of application to connect on the RTMP server. This option
377 overrides the parameter specified in the URI.
378
379 @item rtmp_buffer
380 Set the client buffer time in milliseconds. The default is 3000.
381
382 @item rtmp_conn
383 Extra arbitrary AMF connection parameters, parsed from a string,
384 e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}.
385 Each value is prefixed by a single character denoting the type,
386 B for Boolean, N for number, S for string, O for object, or Z for null,
387 followed by a colon. For Booleans the data must be either 0 or 1 for
388 FALSE or TRUE, respectively.  Likewise for Objects the data must be 0 or
389 1 to end or begin an object, respectively. Data items in subobjects may
390 be named, by prefixing the type with 'N' and specifying the name before
391 the value (i.e. @code{NB:myFlag:1}). This option may be used multiple
392 times to construct arbitrary AMF sequences.
393
394 @item rtmp_flashver
395 Version of the Flash plugin used to run the SWF player. The default
396 is LNX 9,0,124,2.
397
398 @item rtmp_flush_interval
399 Number of packets flushed in the same request (RTMPT only). The default
400 is 10.
401
402 @item rtmp_live
403 Specify that the media is a live stream. No resuming or seeking in
404 live streams is possible. The default value is @code{any}, which means the
405 subscriber first tries to play the live stream specified in the
406 playpath. If a live stream of that name is not found, it plays the
407 recorded stream. The other possible values are @code{live} and
408 @code{recorded}.
409
410 @item rtmp_pageurl
411 URL of the web page in which the media was embedded. By default no
412 value will be sent.
413
414 @item rtmp_playpath
415 Stream identifier to play or to publish. This option overrides the
416 parameter specified in the URI.
417
418 @item rtmp_subscribe
419 Name of live stream to subscribe to. By default no value will be sent.
420 It is only sent if the option is specified or if rtmp_live
421 is set to live.
422
423 @item rtmp_swfhash
424 SHA256 hash of the decompressed SWF file (32 bytes).
425
426 @item rtmp_swfsize
427 Size of the decompressed SWF file, required for SWFVerification.
428
429 @item rtmp_swfurl
430 URL of the SWF player for the media. By default no value will be sent.
431
432 @item rtmp_swfverify
433 URL to player swf file, compute hash/size automatically.
434
435 @item rtmp_tcurl
436 URL of the target stream. Defaults to proto://host[:port]/app.
437
438 @end table
439
440 For example to read with @command{ffplay} a multimedia resource named
441 "sample" from the application "vod" from an RTMP server "myserver":
442 @example
443 ffplay rtmp://myserver/vod/sample
444 @end example
445
446 @section rtmpe
447
448 Encrypted Real-Time Messaging Protocol.
449
450 The Encrypted Real-Time Messaging Protocol (RTMPE) is used for
451 streaming multimedia content within standard cryptographic primitives,
452 consisting of Diffie-Hellman key exchange and HMACSHA256, generating
453 a pair of RC4 keys.
454
455 @section rtmps
456
457 Real-Time Messaging Protocol over a secure SSL connection.
458
459 The Real-Time Messaging Protocol (RTMPS) is used for streaming
460 multimedia content across an encrypted connection.
461
462 @section rtmpt
463
464 Real-Time Messaging Protocol tunneled through HTTP.
465
466 The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used
467 for streaming multimedia content within HTTP requests to traverse
468 firewalls.
469
470 @section rtmpte
471
472 Encrypted Real-Time Messaging Protocol tunneled through HTTP.
473
474 The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE)
475 is used for streaming multimedia content within HTTP requests to traverse
476 firewalls.
477
478 @section rtmpts
479
480 Real-Time Messaging Protocol tunneled through HTTPS.
481
482 The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used
483 for streaming multimedia content within HTTPS requests to traverse
484 firewalls.
485
486 @section rtmp, rtmpe, rtmps, rtmpt, rtmpte
487
488 Real-Time Messaging Protocol and its variants supported through
489 librtmp.
490
491 Requires the presence of the librtmp headers and library during
492 configuration. You need to explicitly configure the build with
493 "--enable-librtmp". If enabled this will replace the native RTMP
494 protocol.
495
496 This protocol provides most client functions and a few server
497 functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT),
498 encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled
499 variants of these encrypted types (RTMPTE, RTMPTS).
500
501 The required syntax is:
502 @example
503 @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options}
504 @end example
505
506 where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe",
507 "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and
508 @var{server}, @var{port}, @var{app} and @var{playpath} have the same
509 meaning as specified for the RTMP native protocol.
510 @var{options} contains a list of space-separated options of the form
511 @var{key}=@var{val}.
512
513 See the librtmp manual page (man 3 librtmp) for more information.
514
515 For example, to stream a file in real-time to an RTMP server using
516 @command{ffmpeg}:
517 @example
518 ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream
519 @end example
520
521 To play the same stream using @command{ffplay}:
522 @example
523 ffplay "rtmp://myserver/live/mystream live=1"
524 @end example
525
526 @section rtp
527
528 Real-Time Protocol.
529
530 @section rtsp
531
532 RTSP is not technically a protocol handler in libavformat, it is a demuxer
533 and muxer. The demuxer supports both normal RTSP (with data transferred
534 over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with
535 data transferred over RDT).
536
537 The muxer can be used to send a stream using RTSP ANNOUNCE to a server
538 supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's
539 @uref{http://github.com/revmischa/rtsp-server, RTSP server}).
540
541 The required syntax for a RTSP url is:
542 @example
543 rtsp://@var{hostname}[:@var{port}]/@var{path}
544 @end example
545
546 The following options (set on the @command{ffmpeg}/@command{ffplay} command
547 line, or set in code via @code{AVOption}s or in @code{avformat_open_input}),
548 are supported:
549
550 Flags for @code{rtsp_transport}:
551
552 @table @option
553
554 @item udp
555 Use UDP as lower transport protocol.
556
557 @item tcp
558 Use TCP (interleaving within the RTSP control channel) as lower
559 transport protocol.
560
561 @item udp_multicast
562 Use UDP multicast as lower transport protocol.
563
564 @item http
565 Use HTTP tunneling as lower transport protocol, which is useful for
566 passing proxies.
567 @end table
568
569 Multiple lower transport protocols may be specified, in that case they are
570 tried one at a time (if the setup of one fails, the next one is tried).
571 For the muxer, only the @code{tcp} and @code{udp} options are supported.
572
573 Flags for @code{rtsp_flags}:
574
575 @table @option
576 @item filter_src
577 Accept packets only from negotiated peer address and port.
578 @item listen
579 Act as a server, listening for an incoming connection.
580 @end table
581
582 When receiving data over UDP, the demuxer tries to reorder received packets
583 (since they may arrive out of order, or packets may get lost totally). This
584 can be disabled by setting the maximum demuxing delay to zero (via
585 the @code{max_delay} field of AVFormatContext).
586
587 When watching multi-bitrate Real-RTSP streams with @command{ffplay}, the
588 streams to display can be chosen with @code{-vst} @var{n} and
589 @code{-ast} @var{n} for video and audio respectively, and can be switched
590 on the fly by pressing @code{v} and @code{a}.
591
592 Example command lines:
593
594 To watch a stream over UDP, with a max reordering delay of 0.5 seconds:
595
596 @example
597 ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4
598 @end example
599
600 To watch a stream tunneled over HTTP:
601
602 @example
603 ffplay -rtsp_transport http rtsp://server/video.mp4
604 @end example
605
606 To send a stream in realtime to a RTSP server, for others to watch:
607
608 @example
609 ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp
610 @end example
611
612 To receive a stream in realtime:
613
614 @example
615 ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output}
616 @end example
617
618 @table @option
619 @item stimeout
620 Socket IO timeout in micro seconds.
621 @end table
622
623 @section sap
624
625 Session Announcement Protocol (RFC 2974). This is not technically a
626 protocol handler in libavformat, it is a muxer and demuxer.
627 It is used for signalling of RTP streams, by announcing the SDP for the
628 streams regularly on a separate port.
629
630 @subsection Muxer
631
632 The syntax for a SAP url given to the muxer is:
633 @example
634 sap://@var{destination}[:@var{port}][?@var{options}]
635 @end example
636
637 The RTP packets are sent to @var{destination} on port @var{port},
638 or to port 5004 if no port is specified.
639 @var{options} is a @code{&}-separated list. The following options
640 are supported:
641
642 @table @option
643
644 @item announce_addr=@var{address}
645 Specify the destination IP address for sending the announcements to.
646 If omitted, the announcements are sent to the commonly used SAP
647 announcement multicast address 224.2.127.254 (sap.mcast.net), or
648 ff0e::2:7ffe if @var{destination} is an IPv6 address.
649
650 @item announce_port=@var{port}
651 Specify the port to send the announcements on, defaults to
652 9875 if not specified.
653
654 @item ttl=@var{ttl}
655 Specify the time to live value for the announcements and RTP packets,
656 defaults to 255.
657
658 @item same_port=@var{0|1}
659 If set to 1, send all RTP streams on the same port pair. If zero (the
660 default), all streams are sent on unique ports, with each stream on a
661 port 2 numbers higher than the previous.
662 VLC/Live555 requires this to be set to 1, to be able to receive the stream.
663 The RTP stack in libavformat for receiving requires all streams to be sent
664 on unique ports.
665 @end table
666
667 Example command lines follow.
668
669 To broadcast a stream on the local subnet, for watching in VLC:
670
671 @example
672 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1
673 @end example
674
675 Similarly, for watching in @command{ffplay}:
676
677 @example
678 ffmpeg -re -i @var{input} -f sap sap://224.0.0.255
679 @end example
680
681 And for watching in @command{ffplay}, over IPv6:
682
683 @example
684 ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4]
685 @end example
686
687 @subsection Demuxer
688
689 The syntax for a SAP url given to the demuxer is:
690 @example
691 sap://[@var{address}][:@var{port}]
692 @end example
693
694 @var{address} is the multicast address to listen for announcements on,
695 if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port}
696 is the port that is listened on, 9875 if omitted.
697
698 The demuxers listens for announcements on the given address and port.
699 Once an announcement is received, it tries to receive that particular stream.
700
701 Example command lines follow.
702
703 To play back the first stream announced on the normal SAP multicast address:
704
705 @example
706 ffplay sap://
707 @end example
708
709 To play back the first stream announced on one the default IPv6 SAP multicast address:
710
711 @example
712 ffplay sap://[ff0e::2:7ffe]
713 @end example
714
715 @section sctp
716
717 Stream Control Transmission Protocol.
718
719 The accepted URL syntax is:
720 @example
721 sctp://@var{host}:@var{port}[?@var{options}]
722 @end example
723
724 The protocol accepts the following options:
725 @table @option
726 @item listen
727 If set to any value, listen for an incoming connection. Outgoing connection is done by default.
728
729 @item max_streams
730 Set the maximum number of streams. By default no limit is set.
731 @end table
732
733 @section srtp
734
735 Secure Real-time Transport Protocol.
736
737 The accepted options are:
738 @table @option
739 @item srtp_in_suite
740 @item srtp_out_suite
741 Select input and output encoding suites.
742
743 Supported values:
744 @table @samp
745 @item AES_CM_128_HMAC_SHA1_80
746 @item SRTP_AES128_CM_HMAC_SHA1_80
747 @item AES_CM_128_HMAC_SHA1_32
748 @item SRTP_AES128_CM_HMAC_SHA1_32
749 @end table
750
751 @item srtp_in_params
752 @item srtp_out_params
753 Set input and output encoding parameters, which are expressed by a
754 base64-encoded representation of a binary block. The first 16 bytes of
755 this binary block are used as master key, the following 14 bytes are
756 used as master salt.
757 @end table
758
759 @section tcp
760
761 Trasmission Control Protocol.
762
763 The required syntax for a TCP url is:
764 @example
765 tcp://@var{hostname}:@var{port}[?@var{options}]
766 @end example
767
768 @table @option
769
770 @item listen
771 Listen for an incoming connection
772
773 @item timeout=@var{microseconds}
774 In read mode: if no data arrived in more than this time interval, raise error.
775 In write mode: if socket cannot be written in more than this time interval, raise error.
776 This also sets timeout on TCP connection establishing.
777
778 @example
779 ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen
780 ffplay tcp://@var{hostname}:@var{port}
781 @end example
782
783 @end table
784
785 @section tls
786
787 Transport Layer Security/Secure Sockets Layer
788
789 The required syntax for a TLS/SSL url is:
790 @example
791 tls://@var{hostname}:@var{port}[?@var{options}]
792 @end example
793
794 @table @option
795
796 @item listen
797 Act as a server, listening for an incoming connection.
798
799 @item cafile=@var{filename}
800 Certificate authority file. The file must be in OpenSSL PEM format.
801
802 @item cert=@var{filename}
803 Certificate file. The file must be in OpenSSL PEM format.
804
805 @item key=@var{filename}
806 Private key file.
807
808 @item verify=@var{0|1}
809 Verify the peer's certificate.
810
811 @end table
812
813 Example command lines:
814
815 To create a TLS/SSL server that serves an input stream.
816
817 @example
818 ffmpeg -i @var{input} -f @var{format} tls://@var{hostname}:@var{port}?listen&cert=@var{server.crt}&key=@var{server.key}
819 @end example
820
821 To play back a stream from the TLS/SSL server using @command{ffplay}:
822
823 @example
824 ffplay tls://@var{hostname}:@var{port}
825 @end example
826
827 @section udp
828
829 User Datagram Protocol.
830
831 The required syntax for a UDP url is:
832 @example
833 udp://@var{hostname}:@var{port}[?@var{options}]
834 @end example
835
836 @var{options} contains a list of &-separated options of the form @var{key}=@var{val}.
837
838 In case threading is enabled on the system, a circular buffer is used
839 to store the incoming data, which allows to reduce loss of data due to
840 UDP socket buffer overruns. The @var{fifo_size} and
841 @var{overrun_nonfatal} options are related to this buffer.
842
843 The list of supported options follows.
844
845 @table @option
846
847 @item buffer_size=@var{size}
848 Set the UDP socket buffer size in bytes. This is used both for the
849 receiving and the sending buffer size.
850
851 @item localport=@var{port}
852 Override the local UDP port to bind with.
853
854 @item localaddr=@var{addr}
855 Choose the local IP address. This is useful e.g. if sending multicast
856 and the host has multiple interfaces, where the user can choose
857 which interface to send on by specifying the IP address of that interface.
858
859 @item pkt_size=@var{size}
860 Set the size in bytes of UDP packets.
861
862 @item reuse=@var{1|0}
863 Explicitly allow or disallow reusing UDP sockets.
864
865 @item ttl=@var{ttl}
866 Set the time to live value (for multicast only).
867
868 @item connect=@var{1|0}
869 Initialize the UDP socket with @code{connect()}. In this case, the
870 destination address can't be changed with ff_udp_set_remote_url later.
871 If the destination address isn't known at the start, this option can
872 be specified in ff_udp_set_remote_url, too.
873 This allows finding out the source address for the packets with getsockname,
874 and makes writes return with AVERROR(ECONNREFUSED) if "destination
875 unreachable" is received.
876 For receiving, this gives the benefit of only receiving packets from
877 the specified peer address/port.
878
879 @item sources=@var{address}[,@var{address}]
880 Only receive packets sent to the multicast group from one of the
881 specified sender IP addresses.
882
883 @item block=@var{address}[,@var{address}]
884 Ignore packets sent to the multicast group from the specified
885 sender IP addresses.
886
887 @item fifo_size=@var{units}
888 Set the UDP receiving circular buffer size, expressed as a number of
889 packets with size of 188 bytes. If not specified defaults to 7*4096.
890
891 @item overrun_nonfatal=@var{1|0}
892 Survive in case of UDP receiving circular buffer overrun. Default
893 value is 0.
894
895 @item timeout=@var{microseconds}
896 In read mode: if no data arrived in more than this time interval, raise error.
897 @end table
898
899 Some usage examples of the UDP protocol with @command{ffmpeg} follow.
900
901 To stream over UDP to a remote endpoint:
902 @example
903 ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port}
904 @end example
905
906 To stream in mpegts format over UDP using 188 sized UDP packets, using a large input buffer:
907 @example
908 ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535
909 @end example
910
911 To receive over UDP from a remote endpoint:
912 @example
913 ffmpeg -i udp://[@var{multicast-address}]:@var{port}
914 @end example
915
916 @c man end PROTOCOLS