blob: a7968ff56e3e1fc1c8c81bff4578bd309f8b95e7
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 | @end table |
197 | |
198 | @section ftp |
199 | |
200 | FTP (File Transfer Protocol). |
201 | |
202 | Read from or write to remote resources using FTP protocol. |
203 | |
204 | Following syntax is required. |
205 | @example |
206 | ftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg |
207 | @end example |
208 | |
209 | This protocol accepts the following options. |
210 | |
211 | @table @option |
212 | @item timeout |
213 | Set timeout in microseconds of socket I/O operations used by the underlying low level |
214 | operation. By default it is set to -1, which means that the timeout is |
215 | not specified. |
216 | |
217 | @item ftp-anonymous-password |
218 | Password used when login as anonymous user. Typically an e-mail address |
219 | should be used. |
220 | |
221 | @item ftp-write-seekable |
222 | Control seekability of connection during encoding. If set to 1 the |
223 | resource is supposed to be seekable, if set to 0 it is assumed not |
224 | to be seekable. Default value is 0. |
225 | @end table |
226 | |
227 | NOTE: Protocol can be used as output, but it is recommended to not do |
228 | it, unless special care is taken (tests, customized server configuration |
229 | etc.). Different FTP servers behave in different way during seek |
230 | operation. ff* tools may produce incomplete content due to server limitations. |
231 | |
232 | This protocol accepts the following options: |
233 | |
234 | @table @option |
235 | @item follow |
236 | If set to 1, the protocol will retry reading at the end of the file, allowing |
237 | reading files that still are being written. In order for this to terminate, |
238 | you either need to use the rw_timeout option, or use the interrupt callback |
239 | (for API users). |
240 | |
241 | @end table |
242 | |
243 | @section gopher |
244 | |
245 | Gopher protocol. |
246 | |
247 | @section hls |
248 | |
249 | Read Apple HTTP Live Streaming compliant segmented stream as |
250 | a uniform one. The M3U8 playlists describing the segments can be |
251 | remote HTTP resources or local files, accessed using the standard |
252 | file protocol. |
253 | The nested protocol is declared by specifying |
254 | "+@var{proto}" after the hls URI scheme name, where @var{proto} |
255 | is either "file" or "http". |
256 | |
257 | @example |
258 | hls+http://host/path/to/remote/resource.m3u8 |
259 | hls+file://path/to/local/resource.m3u8 |
260 | @end example |
261 | |
262 | Using this protocol is discouraged - the hls demuxer should work |
263 | just as well (if not, please report the issues) and is more complete. |
264 | To use the hls demuxer instead, simply use the direct URLs to the |
265 | m3u8 files. |
266 | |
267 | @section http |
268 | |
269 | HTTP (Hyper Text Transfer Protocol). |
270 | |
271 | This protocol accepts the following options: |
272 | |
273 | @table @option |
274 | @item seekable |
275 | Control seekability of connection. If set to 1 the resource is |
276 | supposed to be seekable, if set to 0 it is assumed not to be seekable, |
277 | if set to -1 it will try to autodetect if it is seekable. Default |
278 | value is -1. |
279 | |
280 | @item chunked_post |
281 | If set to 1 use chunked Transfer-Encoding for posts, default is 1. |
282 | |
283 | @item content_type |
284 | Set a specific content type for the POST messages or for listen mode. |
285 | |
286 | @item http_proxy |
287 | set HTTP proxy to tunnel through e.g. http://example.com:1234 |
288 | |
289 | @item headers |
290 | Set custom HTTP headers, can override built in default headers. The |
291 | value must be a string encoding the headers. |
292 | |
293 | @item multiple_requests |
294 | Use persistent connections if set to 1, default is 0. |
295 | |
296 | @item post_data |
297 | Set custom HTTP post data. |
298 | |
299 | @item user_agent |
300 | Override the User-Agent header. If not specified the protocol will use a |
301 | string describing the libavformat build. ("Lavf/<version>") |
302 | |
303 | @item user-agent |
304 | This is a deprecated option, you can use user_agent instead it. |
305 | |
306 | @item timeout |
307 | Set timeout in microseconds of socket I/O operations used by the underlying low level |
308 | operation. By default it is set to -1, which means that the timeout is |
309 | not specified. |
310 | |
311 | @item reconnect_at_eof |
312 | If set then eof is treated like an error and causes reconnection, this is useful |
313 | for live / endless streams. |
314 | |
315 | @item reconnect_streamed |
316 | If set then even streamed/non seekable streams will be reconnected on errors. |
317 | |
318 | @item reconnect_delay_max |
319 | Sets the maximum delay in seconds after which to give up reconnecting |
320 | |
321 | @item mime_type |
322 | Export the MIME type. |
323 | |
324 | @item icy |
325 | If set to 1 request ICY (SHOUTcast) metadata from the server. If the server |
326 | supports this, the metadata has to be retrieved by the application by reading |
327 | the @option{icy_metadata_headers} and @option{icy_metadata_packet} options. |
328 | The default is 1. |
329 | |
330 | @item icy_metadata_headers |
331 | If the server supports ICY metadata, this contains the ICY-specific HTTP reply |
332 | headers, separated by newline characters. |
333 | |
334 | @item icy_metadata_packet |
335 | If the server supports ICY metadata, and @option{icy} was set to 1, this |
336 | contains the last non-empty metadata packet sent by the server. It should be |
337 | polled in regular intervals by applications interested in mid-stream metadata |
338 | updates. |
339 | |
340 | @item cookies |
341 | Set the cookies to be sent in future requests. The format of each cookie is the |
342 | same as the value of a Set-Cookie HTTP response field. Multiple cookies can be |
343 | delimited by a newline character. |
344 | |
345 | @item offset |
346 | Set initial byte offset. |
347 | |
348 | @item end_offset |
349 | Try to limit the request to bytes preceding this offset. |
350 | |
351 | @item method |
352 | When used as a client option it sets the HTTP method for the request. |
353 | |
354 | When used as a server option it sets the HTTP method that is going to be |
355 | expected from the client(s). |
356 | If the expected and the received HTTP method do not match the client will |
357 | be given a Bad Request response. |
358 | When unset the HTTP method is not checked for now. This will be replaced by |
359 | autodetection in the future. |
360 | |
361 | @item listen |
362 | If set to 1 enables experimental HTTP server. This can be used to send data when |
363 | used as an output option, or read data from a client with HTTP POST when used as |
364 | an input option. |
365 | If set to 2 enables experimental multi-client HTTP server. This is not yet implemented |
366 | in ffmpeg.c or ffserver.c and thus must not be used as a command line option. |
367 | @example |
368 | # Server side (sending): |
369 | ffmpeg -i somefile.ogg -c copy -listen 1 -f ogg http://@var{server}:@var{port} |
370 | |
371 | # Client side (receiving): |
372 | ffmpeg -i http://@var{server}:@var{port} -c copy somefile.ogg |
373 | |
374 | # Client can also be done with wget: |
375 | wget http://@var{server}:@var{port} -O somefile.ogg |
376 | |
377 | # Server side (receiving): |
378 | ffmpeg -listen 1 -i http://@var{server}:@var{port} -c copy somefile.ogg |
379 | |
380 | # Client side (sending): |
381 | ffmpeg -i somefile.ogg -chunked_post 0 -c copy -f ogg http://@var{server}:@var{port} |
382 | |
383 | # Client can also be done with wget: |
384 | wget --post-file=somefile.ogg http://@var{server}:@var{port} |
385 | @end example |
386 | |
387 | @end table |
388 | |
389 | @subsection HTTP Cookies |
390 | |
391 | Some HTTP requests will be denied unless cookie values are passed in with the |
392 | request. The @option{cookies} option allows these cookies to be specified. At |
393 | the very least, each cookie must specify a value along with a path and domain. |
394 | HTTP requests that match both the domain and path will automatically include the |
395 | cookie value in the HTTP Cookie header field. Multiple cookies can be delimited |
396 | by a newline. |
397 | |
398 | The required syntax to play a stream specifying a cookie is: |
399 | @example |
400 | ffplay -cookies "nlqptid=nltid=tsn; path=/; domain=somedomain.com;" http://somedomain.com/somestream.m3u8 |
401 | @end example |
402 | |
403 | @section Icecast |
404 | |
405 | Icecast protocol (stream to Icecast servers) |
406 | |
407 | This protocol accepts the following options: |
408 | |
409 | @table @option |
410 | @item ice_genre |
411 | Set the stream genre. |
412 | |
413 | @item ice_name |
414 | Set the stream name. |
415 | |
416 | @item ice_description |
417 | Set the stream description. |
418 | |
419 | @item ice_url |
420 | Set the stream website URL. |
421 | |
422 | @item ice_public |
423 | Set if the stream should be public. |
424 | The default is 0 (not public). |
425 | |
426 | @item user_agent |
427 | Override the User-Agent header. If not specified a string of the form |
428 | "Lavf/<version>" will be used. |
429 | |
430 | @item password |
431 | Set the Icecast mountpoint password. |
432 | |
433 | @item content_type |
434 | Set the stream content type. This must be set if it is different from |
435 | audio/mpeg. |
436 | |
437 | @item legacy_icecast |
438 | This enables support for Icecast versions < 2.4.0, that do not support the |
439 | HTTP PUT method but the SOURCE method. |
440 | |
441 | @end table |
442 | |
443 | @example |
444 | icecast://[@var{username}[:@var{password}]@@]@var{server}:@var{port}/@var{mountpoint} |
445 | @end example |
446 | |
447 | @section mmst |
448 | |
449 | MMS (Microsoft Media Server) protocol over TCP. |
450 | |
451 | @section mmsh |
452 | |
453 | MMS (Microsoft Media Server) protocol over HTTP. |
454 | |
455 | The required syntax is: |
456 | @example |
457 | mmsh://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] |
458 | @end example |
459 | |
460 | @section md5 |
461 | |
462 | MD5 output protocol. |
463 | |
464 | Computes the MD5 hash of the data to be written, and on close writes |
465 | this to the designated output or stdout if none is specified. It can |
466 | be used to test muxers without writing an actual file. |
467 | |
468 | Some examples follow. |
469 | @example |
470 | # Write the MD5 hash of the encoded AVI file to the file output.avi.md5. |
471 | ffmpeg -i input.flv -f avi -y md5:output.avi.md5 |
472 | |
473 | # Write the MD5 hash of the encoded AVI file to stdout. |
474 | ffmpeg -i input.flv -f avi -y md5: |
475 | @end example |
476 | |
477 | Note that some formats (typically MOV) require the output protocol to |
478 | be seekable, so they will fail with the MD5 output protocol. |
479 | |
480 | @section pipe |
481 | |
482 | UNIX pipe access protocol. |
483 | |
484 | Read and write from UNIX pipes. |
485 | |
486 | The accepted syntax is: |
487 | @example |
488 | pipe:[@var{number}] |
489 | @end example |
490 | |
491 | @var{number} is the number corresponding to the file descriptor of the |
492 | pipe (e.g. 0 for stdin, 1 for stdout, 2 for stderr). If @var{number} |
493 | is not specified, by default the stdout file descriptor will be used |
494 | for writing, stdin for reading. |
495 | |
496 | For example to read from stdin with @command{ffmpeg}: |
497 | @example |
498 | cat test.wav | ffmpeg -i pipe:0 |
499 | # ...this is the same as... |
500 | cat test.wav | ffmpeg -i pipe: |
501 | @end example |
502 | |
503 | For writing to stdout with @command{ffmpeg}: |
504 | @example |
505 | ffmpeg -i test.wav -f avi pipe:1 | cat > test.avi |
506 | # ...this is the same as... |
507 | ffmpeg -i test.wav -f avi pipe: | cat > test.avi |
508 | @end example |
509 | |
510 | This protocol accepts the following options: |
511 | |
512 | @table @option |
513 | @item blocksize |
514 | Set I/O operation maximum block size, in bytes. Default value is |
515 | @code{INT_MAX}, which results in not limiting the requested block size. |
516 | Setting this value reasonably low improves user termination request reaction |
517 | time, which is valuable if data transmission is slow. |
518 | @end table |
519 | |
520 | Note that some formats (typically MOV), require the output protocol to |
521 | be seekable, so they will fail with the pipe output protocol. |
522 | |
523 | @section prompeg |
524 | |
525 | Pro-MPEG Code of Practice #3 Release 2 FEC protocol. |
526 | |
527 | The Pro-MPEG CoP#3 FEC is a 2D parity-check forward error correction mechanism |
528 | for MPEG-2 Transport Streams sent over RTP. |
529 | |
530 | This protocol must be used in conjunction with the @code{rtp_mpegts} muxer and |
531 | the @code{rtp} protocol. |
532 | |
533 | The required syntax is: |
534 | @example |
535 | -f rtp_mpegts -fec prompeg=@var{option}=@var{val}... rtp://@var{hostname}:@var{port} |
536 | @end example |
537 | |
538 | The destination UDP ports are @code{port + 2} for the column FEC stream |
539 | and @code{port + 4} for the row FEC stream. |
540 | |
541 | This protocol accepts the following options: |
542 | @table @option |
543 | |
544 | @item l=@var{n} |
545 | The number of columns (4-20, LxD <= 100) |
546 | |
547 | @item d=@var{n} |
548 | The number of rows (4-20, LxD <= 100) |
549 | |
550 | @end table |
551 | |
552 | Example usage: |
553 | |
554 | @example |
555 | -f rtp_mpegts -fec prompeg=l=8:d=4 rtp://@var{hostname}:@var{port} |
556 | @end example |
557 | |
558 | @section rtmp |
559 | |
560 | Real-Time Messaging Protocol. |
561 | |
562 | The Real-Time Messaging Protocol (RTMP) is used for streaming multimedia |
563 | content across a TCP/IP network. |
564 | |
565 | The required syntax is: |
566 | @example |
567 | rtmp://[@var{username}:@var{password}@@]@var{server}[:@var{port}][/@var{app}][/@var{instance}][/@var{playpath}] |
568 | @end example |
569 | |
570 | The accepted parameters are: |
571 | @table @option |
572 | |
573 | @item username |
574 | An optional username (mostly for publishing). |
575 | |
576 | @item password |
577 | An optional password (mostly for publishing). |
578 | |
579 | @item server |
580 | The address of the RTMP server. |
581 | |
582 | @item port |
583 | The number of the TCP port to use (by default is 1935). |
584 | |
585 | @item app |
586 | It is the name of the application to access. It usually corresponds to |
587 | the path where the application is installed on the RTMP server |
588 | (e.g. @file{/ondemand/}, @file{/flash/live/}, etc.). You can override |
589 | the value parsed from the URI through the @code{rtmp_app} option, too. |
590 | |
591 | @item playpath |
592 | It is the path or name of the resource to play with reference to the |
593 | application specified in @var{app}, may be prefixed by "mp4:". You |
594 | can override the value parsed from the URI through the @code{rtmp_playpath} |
595 | option, too. |
596 | |
597 | @item listen |
598 | Act as a server, listening for an incoming connection. |
599 | |
600 | @item timeout |
601 | Maximum time to wait for the incoming connection. Implies listen. |
602 | @end table |
603 | |
604 | Additionally, the following parameters can be set via command line options |
605 | (or in code via @code{AVOption}s): |
606 | @table @option |
607 | |
608 | @item rtmp_app |
609 | Name of application to connect on the RTMP server. This option |
610 | overrides the parameter specified in the URI. |
611 | |
612 | @item rtmp_buffer |
613 | Set the client buffer time in milliseconds. The default is 3000. |
614 | |
615 | @item rtmp_conn |
616 | Extra arbitrary AMF connection parameters, parsed from a string, |
617 | e.g. like @code{B:1 S:authMe O:1 NN:code:1.23 NS:flag:ok O:0}. |
618 | Each value is prefixed by a single character denoting the type, |
619 | B for Boolean, N for number, S for string, O for object, or Z for null, |
620 | followed by a colon. For Booleans the data must be either 0 or 1 for |
621 | FALSE or TRUE, respectively. Likewise for Objects the data must be 0 or |
622 | 1 to end or begin an object, respectively. Data items in subobjects may |
623 | be named, by prefixing the type with 'N' and specifying the name before |
624 | the value (i.e. @code{NB:myFlag:1}). This option may be used multiple |
625 | times to construct arbitrary AMF sequences. |
626 | |
627 | @item rtmp_flashver |
628 | Version of the Flash plugin used to run the SWF player. The default |
629 | is LNX 9,0,124,2. (When publishing, the default is FMLE/3.0 (compatible; |
630 | <libavformat version>).) |
631 | |
632 | @item rtmp_flush_interval |
633 | Number of packets flushed in the same request (RTMPT only). The default |
634 | is 10. |
635 | |
636 | @item rtmp_live |
637 | Specify that the media is a live stream. No resuming or seeking in |
638 | live streams is possible. The default value is @code{any}, which means the |
639 | subscriber first tries to play the live stream specified in the |
640 | playpath. If a live stream of that name is not found, it plays the |
641 | recorded stream. The other possible values are @code{live} and |
642 | @code{recorded}. |
643 | |
644 | @item rtmp_pageurl |
645 | URL of the web page in which the media was embedded. By default no |
646 | value will be sent. |
647 | |
648 | @item rtmp_playpath |
649 | Stream identifier to play or to publish. This option overrides the |
650 | parameter specified in the URI. |
651 | |
652 | @item rtmp_subscribe |
653 | Name of live stream to subscribe to. By default no value will be sent. |
654 | It is only sent if the option is specified or if rtmp_live |
655 | is set to live. |
656 | |
657 | @item rtmp_swfhash |
658 | SHA256 hash of the decompressed SWF file (32 bytes). |
659 | |
660 | @item rtmp_swfsize |
661 | Size of the decompressed SWF file, required for SWFVerification. |
662 | |
663 | @item rtmp_swfurl |
664 | URL of the SWF player for the media. By default no value will be sent. |
665 | |
666 | @item rtmp_swfverify |
667 | URL to player swf file, compute hash/size automatically. |
668 | |
669 | @item rtmp_tcurl |
670 | URL of the target stream. Defaults to proto://host[:port]/app. |
671 | |
672 | @end table |
673 | |
674 | For example to read with @command{ffplay} a multimedia resource named |
675 | "sample" from the application "vod" from an RTMP server "myserver": |
676 | @example |
677 | ffplay rtmp://myserver/vod/sample |
678 | @end example |
679 | |
680 | To publish to a password protected server, passing the playpath and |
681 | app names separately: |
682 | @example |
683 | ffmpeg -re -i <input> -f flv -rtmp_playpath some/long/path -rtmp_app long/app/name rtmp://username:password@@myserver/ |
684 | @end example |
685 | |
686 | @section rtmpe |
687 | |
688 | Encrypted Real-Time Messaging Protocol. |
689 | |
690 | The Encrypted Real-Time Messaging Protocol (RTMPE) is used for |
691 | streaming multimedia content within standard cryptographic primitives, |
692 | consisting of Diffie-Hellman key exchange and HMACSHA256, generating |
693 | a pair of RC4 keys. |
694 | |
695 | @section rtmps |
696 | |
697 | Real-Time Messaging Protocol over a secure SSL connection. |
698 | |
699 | The Real-Time Messaging Protocol (RTMPS) is used for streaming |
700 | multimedia content across an encrypted connection. |
701 | |
702 | @section rtmpt |
703 | |
704 | Real-Time Messaging Protocol tunneled through HTTP. |
705 | |
706 | The Real-Time Messaging Protocol tunneled through HTTP (RTMPT) is used |
707 | for streaming multimedia content within HTTP requests to traverse |
708 | firewalls. |
709 | |
710 | @section rtmpte |
711 | |
712 | Encrypted Real-Time Messaging Protocol tunneled through HTTP. |
713 | |
714 | The Encrypted Real-Time Messaging Protocol tunneled through HTTP (RTMPTE) |
715 | is used for streaming multimedia content within HTTP requests to traverse |
716 | firewalls. |
717 | |
718 | @section rtmpts |
719 | |
720 | Real-Time Messaging Protocol tunneled through HTTPS. |
721 | |
722 | The Real-Time Messaging Protocol tunneled through HTTPS (RTMPTS) is used |
723 | for streaming multimedia content within HTTPS requests to traverse |
724 | firewalls. |
725 | |
726 | @section libsmbclient |
727 | |
728 | libsmbclient permits one to manipulate CIFS/SMB network resources. |
729 | |
730 | Following syntax is required. |
731 | |
732 | @example |
733 | smb://[[domain:]user[:password@@]]server[/share[/path[/file]]] |
734 | @end example |
735 | |
736 | This protocol accepts the following options. |
737 | |
738 | @table @option |
739 | @item timeout |
740 | Set timeout in milliseconds of socket I/O operations used by the underlying |
741 | low level operation. By default it is set to -1, which means that the timeout |
742 | is not specified. |
743 | |
744 | @item truncate |
745 | Truncate existing files on write, if set to 1. A value of 0 prevents |
746 | truncating. Default value is 1. |
747 | |
748 | @item workgroup |
749 | Set the workgroup used for making connections. By default workgroup is not specified. |
750 | |
751 | @end table |
752 | |
753 | For more information see: @url{http://www.samba.org/}. |
754 | |
755 | @section libssh |
756 | |
757 | Secure File Transfer Protocol via libssh |
758 | |
759 | Read from or write to remote resources using SFTP protocol. |
760 | |
761 | Following syntax is required. |
762 | |
763 | @example |
764 | sftp://[user[:password]@@]server[:port]/path/to/remote/resource.mpeg |
765 | @end example |
766 | |
767 | This protocol accepts the following options. |
768 | |
769 | @table @option |
770 | @item timeout |
771 | Set timeout of socket I/O operations used by the underlying low level |
772 | operation. By default it is set to -1, which means that the timeout |
773 | is not specified. |
774 | |
775 | @item truncate |
776 | Truncate existing files on write, if set to 1. A value of 0 prevents |
777 | truncating. Default value is 1. |
778 | |
779 | @item private_key |
780 | Specify the path of the file containing private key to use during authorization. |
781 | By default libssh searches for keys in the @file{~/.ssh/} directory. |
782 | |
783 | @end table |
784 | |
785 | Example: Play a file stored on remote server. |
786 | |
787 | @example |
788 | ffplay sftp://user:password@@server_address:22/home/user/resource.mpeg |
789 | @end example |
790 | |
791 | @section librtmp rtmp, rtmpe, rtmps, rtmpt, rtmpte |
792 | |
793 | Real-Time Messaging Protocol and its variants supported through |
794 | librtmp. |
795 | |
796 | Requires the presence of the librtmp headers and library during |
797 | configuration. You need to explicitly configure the build with |
798 | "--enable-librtmp". If enabled this will replace the native RTMP |
799 | protocol. |
800 | |
801 | This protocol provides most client functions and a few server |
802 | functions needed to support RTMP, RTMP tunneled in HTTP (RTMPT), |
803 | encrypted RTMP (RTMPE), RTMP over SSL/TLS (RTMPS) and tunneled |
804 | variants of these encrypted types (RTMPTE, RTMPTS). |
805 | |
806 | The required syntax is: |
807 | @example |
808 | @var{rtmp_proto}://@var{server}[:@var{port}][/@var{app}][/@var{playpath}] @var{options} |
809 | @end example |
810 | |
811 | where @var{rtmp_proto} is one of the strings "rtmp", "rtmpt", "rtmpe", |
812 | "rtmps", "rtmpte", "rtmpts" corresponding to each RTMP variant, and |
813 | @var{server}, @var{port}, @var{app} and @var{playpath} have the same |
814 | meaning as specified for the RTMP native protocol. |
815 | @var{options} contains a list of space-separated options of the form |
816 | @var{key}=@var{val}. |
817 | |
818 | See the librtmp manual page (man 3 librtmp) for more information. |
819 | |
820 | For example, to stream a file in real-time to an RTMP server using |
821 | @command{ffmpeg}: |
822 | @example |
823 | ffmpeg -re -i myfile -f flv rtmp://myserver/live/mystream |
824 | @end example |
825 | |
826 | To play the same stream using @command{ffplay}: |
827 | @example |
828 | ffplay "rtmp://myserver/live/mystream live=1" |
829 | @end example |
830 | |
831 | @section rtp |
832 | |
833 | Real-time Transport Protocol. |
834 | |
835 | The required syntax for an RTP URL is: |
836 | rtp://@var{hostname}[:@var{port}][?@var{option}=@var{val}...] |
837 | |
838 | @var{port} specifies the RTP port to use. |
839 | |
840 | The following URL options are supported: |
841 | |
842 | @table @option |
843 | |
844 | @item ttl=@var{n} |
845 | Set the TTL (Time-To-Live) value (for multicast only). |
846 | |
847 | @item rtcpport=@var{n} |
848 | Set the remote RTCP port to @var{n}. |
849 | |
850 | @item localrtpport=@var{n} |
851 | Set the local RTP port to @var{n}. |
852 | |
853 | @item localrtcpport=@var{n}' |
854 | Set the local RTCP port to @var{n}. |
855 | |
856 | @item pkt_size=@var{n} |
857 | Set max packet size (in bytes) to @var{n}. |
858 | |
859 | @item connect=0|1 |
860 | Do a @code{connect()} on the UDP socket (if set to 1) or not (if set |
861 | to 0). |
862 | |
863 | @item sources=@var{ip}[,@var{ip}] |
864 | List allowed source IP addresses. |
865 | |
866 | @item block=@var{ip}[,@var{ip}] |
867 | List disallowed (blocked) source IP addresses. |
868 | |
869 | @item write_to_source=0|1 |
870 | Send packets to the source address of the latest received packet (if |
871 | set to 1) or to a default remote address (if set to 0). |
872 | |
873 | @item localport=@var{n} |
874 | Set the local RTP port to @var{n}. |
875 | |
876 | This is a deprecated option. Instead, @option{localrtpport} should be |
877 | used. |
878 | |
879 | @end table |
880 | |
881 | Important notes: |
882 | |
883 | @enumerate |
884 | |
885 | @item |
886 | If @option{rtcpport} is not set the RTCP port will be set to the RTP |
887 | port value plus 1. |
888 | |
889 | @item |
890 | If @option{localrtpport} (the local RTP port) is not set any available |
891 | port will be used for the local RTP and RTCP ports. |
892 | |
893 | @item |
894 | If @option{localrtcpport} (the local RTCP port) is not set it will be |
895 | set to the local RTP port value plus 1. |
896 | @end enumerate |
897 | |
898 | @section rtsp |
899 | |
900 | Real-Time Streaming Protocol. |
901 | |
902 | RTSP is not technically a protocol handler in libavformat, it is a demuxer |
903 | and muxer. The demuxer supports both normal RTSP (with data transferred |
904 | over RTP; this is used by e.g. Apple and Microsoft) and Real-RTSP (with |
905 | data transferred over RDT). |
906 | |
907 | The muxer can be used to send a stream using RTSP ANNOUNCE to a server |
908 | supporting it (currently Darwin Streaming Server and Mischa Spiegelmock's |
909 | @uref{https://github.com/revmischa/rtsp-server, RTSP server}). |
910 | |
911 | The required syntax for a RTSP url is: |
912 | @example |
913 | rtsp://@var{hostname}[:@var{port}]/@var{path} |
914 | @end example |
915 | |
916 | Options can be set on the @command{ffmpeg}/@command{ffplay} command |
917 | line, or set in code via @code{AVOption}s or in |
918 | @code{avformat_open_input}. |
919 | |
920 | The following options are supported. |
921 | |
922 | @table @option |
923 | @item initial_pause |
924 | Do not start playing the stream immediately if set to 1. Default value |
925 | is 0. |
926 | |
927 | @item rtsp_transport |
928 | Set RTSP transport protocols. |
929 | |
930 | It accepts the following values: |
931 | @table @samp |
932 | @item udp |
933 | Use UDP as lower transport protocol. |
934 | |
935 | @item tcp |
936 | Use TCP (interleaving within the RTSP control channel) as lower |
937 | transport protocol. |
938 | |
939 | @item udp_multicast |
940 | Use UDP multicast as lower transport protocol. |
941 | |
942 | @item http |
943 | Use HTTP tunneling as lower transport protocol, which is useful for |
944 | passing proxies. |
945 | @end table |
946 | |
947 | Multiple lower transport protocols may be specified, in that case they are |
948 | tried one at a time (if the setup of one fails, the next one is tried). |
949 | For the muxer, only the @samp{tcp} and @samp{udp} options are supported. |
950 | |
951 | @item rtsp_flags |
952 | Set RTSP flags. |
953 | |
954 | The following values are accepted: |
955 | @table @samp |
956 | @item filter_src |
957 | Accept packets only from negotiated peer address and port. |
958 | @item listen |
959 | Act as a server, listening for an incoming connection. |
960 | @item prefer_tcp |
961 | Try TCP for RTP transport first, if TCP is available as RTSP RTP transport. |
962 | @end table |
963 | |
964 | Default value is @samp{none}. |
965 | |
966 | @item allowed_media_types |
967 | Set media types to accept from the server. |
968 | |
969 | The following flags are accepted: |
970 | @table @samp |
971 | @item video |
972 | @item audio |
973 | @item data |
974 | @end table |
975 | |
976 | By default it accepts all media types. |
977 | |
978 | @item min_port |
979 | Set minimum local UDP port. Default value is 5000. |
980 | |
981 | @item max_port |
982 | Set maximum local UDP port. Default value is 65000. |
983 | |
984 | @item timeout |
985 | Set maximum timeout (in seconds) to wait for incoming connections. |
986 | |
987 | A value of -1 means infinite (default). This option implies the |
988 | @option{rtsp_flags} set to @samp{listen}. |
989 | |
990 | @item reorder_queue_size |
991 | Set number of packets to buffer for handling of reordered packets. |
992 | |
993 | @item stimeout |
994 | Set socket TCP I/O timeout in microseconds. |
995 | |
996 | @item user-agent |
997 | Override User-Agent header. If not specified, it defaults to the |
998 | libavformat identifier string. |
999 | @end table |
1000 | |
1001 | When receiving data over UDP, the demuxer tries to reorder received packets |
1002 | (since they may arrive out of order, or packets may get lost totally). This |
1003 | can be disabled by setting the maximum demuxing delay to zero (via |
1004 | the @code{max_delay} field of AVFormatContext). |
1005 | |
1006 | When watching multi-bitrate Real-RTSP streams with @command{ffplay}, the |
1007 | streams to display can be chosen with @code{-vst} @var{n} and |
1008 | @code{-ast} @var{n} for video and audio respectively, and can be switched |
1009 | on the fly by pressing @code{v} and @code{a}. |
1010 | |
1011 | @subsection Examples |
1012 | |
1013 | The following examples all make use of the @command{ffplay} and |
1014 | @command{ffmpeg} tools. |
1015 | |
1016 | @itemize |
1017 | @item |
1018 | Watch a stream over UDP, with a max reordering delay of 0.5 seconds: |
1019 | @example |
1020 | ffplay -max_delay 500000 -rtsp_transport udp rtsp://server/video.mp4 |
1021 | @end example |
1022 | |
1023 | @item |
1024 | Watch a stream tunneled over HTTP: |
1025 | @example |
1026 | ffplay -rtsp_transport http rtsp://server/video.mp4 |
1027 | @end example |
1028 | |
1029 | @item |
1030 | Send a stream in realtime to a RTSP server, for others to watch: |
1031 | @example |
1032 | ffmpeg -re -i @var{input} -f rtsp -muxdelay 0.1 rtsp://server/live.sdp |
1033 | @end example |
1034 | |
1035 | @item |
1036 | Receive a stream in realtime: |
1037 | @example |
1038 | ffmpeg -rtsp_flags listen -i rtsp://ownaddress/live.sdp @var{output} |
1039 | @end example |
1040 | @end itemize |
1041 | |
1042 | @section sap |
1043 | |
1044 | Session Announcement Protocol (RFC 2974). This is not technically a |
1045 | protocol handler in libavformat, it is a muxer and demuxer. |
1046 | It is used for signalling of RTP streams, by announcing the SDP for the |
1047 | streams regularly on a separate port. |
1048 | |
1049 | @subsection Muxer |
1050 | |
1051 | The syntax for a SAP url given to the muxer is: |
1052 | @example |
1053 | sap://@var{destination}[:@var{port}][?@var{options}] |
1054 | @end example |
1055 | |
1056 | The RTP packets are sent to @var{destination} on port @var{port}, |
1057 | or to port 5004 if no port is specified. |
1058 | @var{options} is a @code{&}-separated list. The following options |
1059 | are supported: |
1060 | |
1061 | @table @option |
1062 | |
1063 | @item announce_addr=@var{address} |
1064 | Specify the destination IP address for sending the announcements to. |
1065 | If omitted, the announcements are sent to the commonly used SAP |
1066 | announcement multicast address 224.2.127.254 (sap.mcast.net), or |
1067 | ff0e::2:7ffe if @var{destination} is an IPv6 address. |
1068 | |
1069 | @item announce_port=@var{port} |
1070 | Specify the port to send the announcements on, defaults to |
1071 | 9875 if not specified. |
1072 | |
1073 | @item ttl=@var{ttl} |
1074 | Specify the time to live value for the announcements and RTP packets, |
1075 | defaults to 255. |
1076 | |
1077 | @item same_port=@var{0|1} |
1078 | If set to 1, send all RTP streams on the same port pair. If zero (the |
1079 | default), all streams are sent on unique ports, with each stream on a |
1080 | port 2 numbers higher than the previous. |
1081 | VLC/Live555 requires this to be set to 1, to be able to receive the stream. |
1082 | The RTP stack in libavformat for receiving requires all streams to be sent |
1083 | on unique ports. |
1084 | @end table |
1085 | |
1086 | Example command lines follow. |
1087 | |
1088 | To broadcast a stream on the local subnet, for watching in VLC: |
1089 | |
1090 | @example |
1091 | ffmpeg -re -i @var{input} -f sap sap://224.0.0.255?same_port=1 |
1092 | @end example |
1093 | |
1094 | Similarly, for watching in @command{ffplay}: |
1095 | |
1096 | @example |
1097 | ffmpeg -re -i @var{input} -f sap sap://224.0.0.255 |
1098 | @end example |
1099 | |
1100 | And for watching in @command{ffplay}, over IPv6: |
1101 | |
1102 | @example |
1103 | ffmpeg -re -i @var{input} -f sap sap://[ff0e::1:2:3:4] |
1104 | @end example |
1105 | |
1106 | @subsection Demuxer |
1107 | |
1108 | The syntax for a SAP url given to the demuxer is: |
1109 | @example |
1110 | sap://[@var{address}][:@var{port}] |
1111 | @end example |
1112 | |
1113 | @var{address} is the multicast address to listen for announcements on, |
1114 | if omitted, the default 224.2.127.254 (sap.mcast.net) is used. @var{port} |
1115 | is the port that is listened on, 9875 if omitted. |
1116 | |
1117 | The demuxers listens for announcements on the given address and port. |
1118 | Once an announcement is received, it tries to receive that particular stream. |
1119 | |
1120 | Example command lines follow. |
1121 | |
1122 | To play back the first stream announced on the normal SAP multicast address: |
1123 | |
1124 | @example |
1125 | ffplay sap:// |
1126 | @end example |
1127 | |
1128 | To play back the first stream announced on one the default IPv6 SAP multicast address: |
1129 | |
1130 | @example |
1131 | ffplay sap://[ff0e::2:7ffe] |
1132 | @end example |
1133 | |
1134 | @section sctp |
1135 | |
1136 | Stream Control Transmission Protocol. |
1137 | |
1138 | The accepted URL syntax is: |
1139 | @example |
1140 | sctp://@var{host}:@var{port}[?@var{options}] |
1141 | @end example |
1142 | |
1143 | The protocol accepts the following options: |
1144 | @table @option |
1145 | @item listen |
1146 | If set to any value, listen for an incoming connection. Outgoing connection is done by default. |
1147 | |
1148 | @item max_streams |
1149 | Set the maximum number of streams. By default no limit is set. |
1150 | @end table |
1151 | |
1152 | @section srtp |
1153 | |
1154 | Secure Real-time Transport Protocol. |
1155 | |
1156 | The accepted options are: |
1157 | @table @option |
1158 | @item srtp_in_suite |
1159 | @item srtp_out_suite |
1160 | Select input and output encoding suites. |
1161 | |
1162 | Supported values: |
1163 | @table @samp |
1164 | @item AES_CM_128_HMAC_SHA1_80 |
1165 | @item SRTP_AES128_CM_HMAC_SHA1_80 |
1166 | @item AES_CM_128_HMAC_SHA1_32 |
1167 | @item SRTP_AES128_CM_HMAC_SHA1_32 |
1168 | @end table |
1169 | |
1170 | @item srtp_in_params |
1171 | @item srtp_out_params |
1172 | Set input and output encoding parameters, which are expressed by a |
1173 | base64-encoded representation of a binary block. The first 16 bytes of |
1174 | this binary block are used as master key, the following 14 bytes are |
1175 | used as master salt. |
1176 | @end table |
1177 | |
1178 | @section subfile |
1179 | |
1180 | Virtually extract a segment of a file or another stream. |
1181 | The underlying stream must be seekable. |
1182 | |
1183 | Accepted options: |
1184 | @table @option |
1185 | @item start |
1186 | Start offset of the extracted segment, in bytes. |
1187 | @item end |
1188 | End offset of the extracted segment, in bytes. |
1189 | @end table |
1190 | |
1191 | Examples: |
1192 | |
1193 | Extract a chapter from a DVD VOB file (start and end sectors obtained |
1194 | externally and multiplied by 2048): |
1195 | @example |
1196 | subfile,,start,153391104,end,268142592,,:/media/dvd/VIDEO_TS/VTS_08_1.VOB |
1197 | @end example |
1198 | |
1199 | Play an AVI file directly from a TAR archive: |
1200 | @example |
1201 | subfile,,start,183241728,end,366490624,,:archive.tar |
1202 | @end example |
1203 | |
1204 | @section tee |
1205 | |
1206 | Writes the output to multiple protocols. The individual outputs are separated |
1207 | by | |
1208 | |
1209 | @example |
1210 | tee:file://path/to/local/this.avi|file://path/to/local/that.avi |
1211 | @end example |
1212 | |
1213 | @section tcp |
1214 | |
1215 | Transmission Control Protocol. |
1216 | |
1217 | The required syntax for a TCP url is: |
1218 | @example |
1219 | tcp://@var{hostname}:@var{port}[?@var{options}] |
1220 | @end example |
1221 | |
1222 | @var{options} contains a list of &-separated options of the form |
1223 | @var{key}=@var{val}. |
1224 | |
1225 | The list of supported options follows. |
1226 | |
1227 | @table @option |
1228 | @item listen=@var{1|0} |
1229 | Listen for an incoming connection. Default value is 0. |
1230 | |
1231 | @item timeout=@var{microseconds} |
1232 | Set raise error timeout, expressed in microseconds. |
1233 | |
1234 | This option is only relevant in read mode: if no data arrived in more |
1235 | than this time interval, raise error. |
1236 | |
1237 | @item listen_timeout=@var{milliseconds} |
1238 | Set listen timeout, expressed in milliseconds. |
1239 | |
1240 | @item recv_buffer_size=@var{bytes} |
1241 | Set receive buffer size, expressed bytes. |
1242 | |
1243 | @item send_buffer_size=@var{bytes} |
1244 | Set send buffer size, expressed bytes. |
1245 | @end table |
1246 | |
1247 | The following example shows how to setup a listening TCP connection |
1248 | with @command{ffmpeg}, which is then accessed with @command{ffplay}: |
1249 | @example |
1250 | ffmpeg -i @var{input} -f @var{format} tcp://@var{hostname}:@var{port}?listen |
1251 | ffplay tcp://@var{hostname}:@var{port} |
1252 | @end example |
1253 | |
1254 | @section tls |
1255 | |
1256 | Transport Layer Security (TLS) / Secure Sockets Layer (SSL) |
1257 | |
1258 | The required syntax for a TLS/SSL url is: |
1259 | @example |
1260 | tls://@var{hostname}:@var{port}[?@var{options}] |
1261 | @end example |
1262 | |
1263 | The following parameters can be set via command line options |
1264 | (or in code via @code{AVOption}s): |
1265 | |
1266 | @table @option |
1267 | |
1268 | @item ca_file, cafile=@var{filename} |
1269 | A file containing certificate authority (CA) root certificates to treat |
1270 | as trusted. If the linked TLS library contains a default this might not |
1271 | need to be specified for verification to work, but not all libraries and |
1272 | setups have defaults built in. |
1273 | The file must be in OpenSSL PEM format. |
1274 | |
1275 | @item tls_verify=@var{1|0} |
1276 | If enabled, try to verify the peer that we are communicating with. |
1277 | Note, if using OpenSSL, this currently only makes sure that the |
1278 | peer certificate is signed by one of the root certificates in the CA |
1279 | database, but it does not validate that the certificate actually |
1280 | matches the host name we are trying to connect to. (With GnuTLS, |
1281 | the host name is validated as well.) |
1282 | |
1283 | This is disabled by default since it requires a CA database to be |
1284 | provided by the caller in many cases. |
1285 | |
1286 | @item cert_file, cert=@var{filename} |
1287 | A file containing a certificate to use in the handshake with the peer. |
1288 | (When operating as server, in listen mode, this is more often required |
1289 | by the peer, while client certificates only are mandated in certain |
1290 | setups.) |
1291 | |
1292 | @item key_file, key=@var{filename} |
1293 | A file containing the private key for the certificate. |
1294 | |
1295 | @item listen=@var{1|0} |
1296 | If enabled, listen for connections on the provided port, and assume |
1297 | the server role in the handshake instead of the client role. |
1298 | |
1299 | @end table |
1300 | |
1301 | Example command lines: |
1302 | |
1303 | To create a TLS/SSL server that serves an input stream. |
1304 | |
1305 | @example |
1306 | ffmpeg -i @var{input} -f @var{format} tls://@var{hostname}:@var{port}?listen&cert=@var{server.crt}&key=@var{server.key} |
1307 | @end example |
1308 | |
1309 | To play back a stream from the TLS/SSL server using @command{ffplay}: |
1310 | |
1311 | @example |
1312 | ffplay tls://@var{hostname}:@var{port} |
1313 | @end example |
1314 | |
1315 | @section udp |
1316 | |
1317 | User Datagram Protocol. |
1318 | |
1319 | The required syntax for an UDP URL is: |
1320 | @example |
1321 | udp://@var{hostname}:@var{port}[?@var{options}] |
1322 | @end example |
1323 | |
1324 | @var{options} contains a list of &-separated options of the form @var{key}=@var{val}. |
1325 | |
1326 | In case threading is enabled on the system, a circular buffer is used |
1327 | to store the incoming data, which allows one to reduce loss of data due to |
1328 | UDP socket buffer overruns. The @var{fifo_size} and |
1329 | @var{overrun_nonfatal} options are related to this buffer. |
1330 | |
1331 | The list of supported options follows. |
1332 | |
1333 | @table @option |
1334 | @item buffer_size=@var{size} |
1335 | Set the UDP maximum socket buffer size in bytes. This is used to set either |
1336 | the receive or send buffer size, depending on what the socket is used for. |
1337 | Default is 64KB. See also @var{fifo_size}. |
1338 | |
1339 | @item bitrate=@var{bitrate} |
1340 | If set to nonzero, the output will have the specified constant bitrate if the |
1341 | input has enough packets to sustain it. |
1342 | |
1343 | @item burst_bits=@var{bits} |
1344 | When using @var{bitrate} this specifies the maximum number of bits in |
1345 | packet bursts. |
1346 | |
1347 | @item localport=@var{port} |
1348 | Override the local UDP port to bind with. |
1349 | |
1350 | @item localaddr=@var{addr} |
1351 | Choose the local IP address. This is useful e.g. if sending multicast |
1352 | and the host has multiple interfaces, where the user can choose |
1353 | which interface to send on by specifying the IP address of that interface. |
1354 | |
1355 | @item pkt_size=@var{size} |
1356 | Set the size in bytes of UDP packets. |
1357 | |
1358 | @item reuse=@var{1|0} |
1359 | Explicitly allow or disallow reusing UDP sockets. |
1360 | |
1361 | @item ttl=@var{ttl} |
1362 | Set the time to live value (for multicast only). |
1363 | |
1364 | @item connect=@var{1|0} |
1365 | Initialize the UDP socket with @code{connect()}. In this case, the |
1366 | destination address can't be changed with ff_udp_set_remote_url later. |
1367 | If the destination address isn't known at the start, this option can |
1368 | be specified in ff_udp_set_remote_url, too. |
1369 | This allows finding out the source address for the packets with getsockname, |
1370 | and makes writes return with AVERROR(ECONNREFUSED) if "destination |
1371 | unreachable" is received. |
1372 | For receiving, this gives the benefit of only receiving packets from |
1373 | the specified peer address/port. |
1374 | |
1375 | @item sources=@var{address}[,@var{address}] |
1376 | Only receive packets sent to the multicast group from one of the |
1377 | specified sender IP addresses. |
1378 | |
1379 | @item block=@var{address}[,@var{address}] |
1380 | Ignore packets sent to the multicast group from the specified |
1381 | sender IP addresses. |
1382 | |
1383 | @item fifo_size=@var{units} |
1384 | Set the UDP receiving circular buffer size, expressed as a number of |
1385 | packets with size of 188 bytes. If not specified defaults to 7*4096. |
1386 | |
1387 | @item overrun_nonfatal=@var{1|0} |
1388 | Survive in case of UDP receiving circular buffer overrun. Default |
1389 | value is 0. |
1390 | |
1391 | @item timeout=@var{microseconds} |
1392 | Set raise error timeout, expressed in microseconds. |
1393 | |
1394 | This option is only relevant in read mode: if no data arrived in more |
1395 | than this time interval, raise error. |
1396 | |
1397 | @item broadcast=@var{1|0} |
1398 | Explicitly allow or disallow UDP broadcasting. |
1399 | |
1400 | Note that broadcasting may not work properly on networks having |
1401 | a broadcast storm protection. |
1402 | @end table |
1403 | |
1404 | @subsection Examples |
1405 | |
1406 | @itemize |
1407 | @item |
1408 | Use @command{ffmpeg} to stream over UDP to a remote endpoint: |
1409 | @example |
1410 | ffmpeg -i @var{input} -f @var{format} udp://@var{hostname}:@var{port} |
1411 | @end example |
1412 | |
1413 | @item |
1414 | Use @command{ffmpeg} to stream in mpegts format over UDP using 188 |
1415 | sized UDP packets, using a large input buffer: |
1416 | @example |
1417 | ffmpeg -i @var{input} -f mpegts udp://@var{hostname}:@var{port}?pkt_size=188&buffer_size=65535 |
1418 | @end example |
1419 | |
1420 | @item |
1421 | Use @command{ffmpeg} to receive over UDP from a remote endpoint: |
1422 | @example |
1423 | ffmpeg -i udp://[@var{multicast-address}]:@var{port} ... |
1424 | @end example |
1425 | @end itemize |
1426 | |
1427 | @section unix |
1428 | |
1429 | Unix local socket |
1430 | |
1431 | The required syntax for a Unix socket URL is: |
1432 | |
1433 | @example |
1434 | unix://@var{filepath} |
1435 | @end example |
1436 | |
1437 | The following parameters can be set via command line options |
1438 | (or in code via @code{AVOption}s): |
1439 | |
1440 | @table @option |
1441 | @item timeout |
1442 | Timeout in ms. |
1443 | @item listen |
1444 | Create the Unix socket in listening mode. |
1445 | @end table |
1446 | |
1447 | @c man end PROTOCOLS |
1448 |