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