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