| 1 | @chapter Syntax |
| 2 | @c man begin SYNTAX |
| 3 | |
| 4 | This section documents the syntax and formats employed by the FFmpeg |
| 5 | libraries and tools. |
| 6 | |
| 7 | @anchor{quoting_and_escaping} |
| 8 | @section Quoting and escaping |
| 9 | |
| 10 | FFmpeg adopts the following quoting and escaping mechanism, unless |
| 11 | explicitly specified. The following rules are applied: |
| 12 | |
| 13 | @itemize |
| 14 | @item |
| 15 | @code{'} and @code{\} are special characters (respectively used for |
| 16 | quoting and escaping). In addition to them, there might be other |
| 17 | special characters depending on the specific syntax where the escaping |
| 18 | and quoting are employed. |
| 19 | |
| 20 | @item |
| 21 | A special character is escaped by prefixing it with a '\'. |
| 22 | |
| 23 | @item |
| 24 | All characters enclosed between '' are included literally in the |
| 25 | parsed string. The quote character @code{'} itself cannot be quoted, |
| 26 | so you may need to close the quote and escape it. |
| 27 | |
| 28 | @item |
| 29 | Leading and trailing whitespaces, unless escaped or quoted, are |
| 30 | removed from the parsed string. |
| 31 | @end itemize |
| 32 | |
| 33 | Note that you may need to add a second level of escaping when using |
| 34 | the command line or a script, which depends on the syntax of the |
| 35 | adopted shell language. |
| 36 | |
| 37 | The function @code{av_get_token} defined in |
| 38 | @file{libavutil/avstring.h} can be used to parse a token quoted or |
| 39 | escaped according to the rules defined above. |
| 40 | |
| 41 | The tool @file{tools/ffescape} in the FFmpeg source tree can be used |
| 42 | to automatically quote or escape a string in a script. |
| 43 | |
| 44 | @subsection Examples |
| 45 | |
| 46 | @itemize |
| 47 | @item |
| 48 | Escape the string @code{Crime d'Amour} containing the @code{'} special |
| 49 | character: |
| 50 | @example |
| 51 | Crime d\'Amour |
| 52 | @end example |
| 53 | |
| 54 | @item |
| 55 | The string above contains a quote, so the @code{'} needs to be escaped |
| 56 | when quoting it: |
| 57 | @example |
| 58 | 'Crime d'\''Amour' |
| 59 | @end example |
| 60 | |
| 61 | @item |
| 62 | Include leading or trailing whitespaces using quoting: |
| 63 | @example |
| 64 | ' this string starts and ends with whitespaces ' |
| 65 | @end example |
| 66 | |
| 67 | @item |
| 68 | Escaping and quoting can be mixed together: |
| 69 | @example |
| 70 | ' The string '\'string\'' is a string ' |
| 71 | @end example |
| 72 | |
| 73 | @item |
| 74 | To include a literal @code{\} you can use either escaping or quoting: |
| 75 | @example |
| 76 | 'c:\foo' can be written as c:\\foo |
| 77 | @end example |
| 78 | @end itemize |
| 79 | |
| 80 | @anchor{date syntax} |
| 81 | @section Date |
| 82 | |
| 83 | The accepted syntax is: |
| 84 | @example |
| 85 | [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z] |
| 86 | now |
| 87 | @end example |
| 88 | |
| 89 | If the value is "now" it takes the current time. |
| 90 | |
| 91 | Time is local time unless Z is appended, in which case it is |
| 92 | interpreted as UTC. |
| 93 | If the year-month-day part is not specified it takes the current |
| 94 | year-month-day. |
| 95 | |
| 96 | @anchor{time duration syntax} |
| 97 | @section Time duration |
| 98 | |
| 99 | There are two accepted syntaxes for expressing time duration. |
| 100 | |
| 101 | @example |
| 102 | [-][@var{HH}:]@var{MM}:@var{SS}[.@var{m}...] |
| 103 | @end example |
| 104 | |
| 105 | @var{HH} expresses the number of hours, @var{MM} the number of minutes |
| 106 | for a maximum of 2 digits, and @var{SS} the number of seconds for a |
| 107 | maximum of 2 digits. The @var{m} at the end expresses decimal value for |
| 108 | @var{SS}. |
| 109 | |
| 110 | @emph{or} |
| 111 | |
| 112 | @example |
| 113 | [-]@var{S}+[.@var{m}...] |
| 114 | @end example |
| 115 | |
| 116 | @var{S} expresses the number of seconds, with the optional decimal part |
| 117 | @var{m}. |
| 118 | |
| 119 | In both expressions, the optional @samp{-} indicates negative duration. |
| 120 | |
| 121 | @subsection Examples |
| 122 | |
| 123 | The following examples are all valid time duration: |
| 124 | |
| 125 | @table @samp |
| 126 | @item 55 |
| 127 | 55 seconds |
| 128 | |
| 129 | @item 12:03:45 |
| 130 | 12 hours, 03 minutes and 45 seconds |
| 131 | |
| 132 | @item 23.189 |
| 133 | 23.189 seconds |
| 134 | @end table |
| 135 | |
| 136 | @anchor{video size syntax} |
| 137 | @section Video size |
| 138 | Specify the size of the sourced video, it may be a string of the form |
| 139 | @var{width}x@var{height}, or the name of a size abbreviation. |
| 140 | |
| 141 | The following abbreviations are recognized: |
| 142 | @table @samp |
| 143 | @item ntsc |
| 144 | 720x480 |
| 145 | @item pal |
| 146 | 720x576 |
| 147 | @item qntsc |
| 148 | 352x240 |
| 149 | @item qpal |
| 150 | 352x288 |
| 151 | @item sntsc |
| 152 | 640x480 |
| 153 | @item spal |
| 154 | 768x576 |
| 155 | @item film |
| 156 | 352x240 |
| 157 | @item ntsc-film |
| 158 | 352x240 |
| 159 | @item sqcif |
| 160 | 128x96 |
| 161 | @item qcif |
| 162 | 176x144 |
| 163 | @item cif |
| 164 | 352x288 |
| 165 | @item 4cif |
| 166 | 704x576 |
| 167 | @item 16cif |
| 168 | 1408x1152 |
| 169 | @item qqvga |
| 170 | 160x120 |
| 171 | @item qvga |
| 172 | 320x240 |
| 173 | @item vga |
| 174 | 640x480 |
| 175 | @item svga |
| 176 | 800x600 |
| 177 | @item xga |
| 178 | 1024x768 |
| 179 | @item uxga |
| 180 | 1600x1200 |
| 181 | @item qxga |
| 182 | 2048x1536 |
| 183 | @item sxga |
| 184 | 1280x1024 |
| 185 | @item qsxga |
| 186 | 2560x2048 |
| 187 | @item hsxga |
| 188 | 5120x4096 |
| 189 | @item wvga |
| 190 | 852x480 |
| 191 | @item wxga |
| 192 | 1366x768 |
| 193 | @item wsxga |
| 194 | 1600x1024 |
| 195 | @item wuxga |
| 196 | 1920x1200 |
| 197 | @item woxga |
| 198 | 2560x1600 |
| 199 | @item wqsxga |
| 200 | 3200x2048 |
| 201 | @item wquxga |
| 202 | 3840x2400 |
| 203 | @item whsxga |
| 204 | 6400x4096 |
| 205 | @item whuxga |
| 206 | 7680x4800 |
| 207 | @item cga |
| 208 | 320x200 |
| 209 | @item ega |
| 210 | 640x350 |
| 211 | @item hd480 |
| 212 | 852x480 |
| 213 | @item hd720 |
| 214 | 1280x720 |
| 215 | @item hd1080 |
| 216 | 1920x1080 |
| 217 | @item 2k |
| 218 | 2048x1080 |
| 219 | @item 2kflat |
| 220 | 1998x1080 |
| 221 | @item 2kscope |
| 222 | 2048x858 |
| 223 | @item 4k |
| 224 | 4096x2160 |
| 225 | @item 4kflat |
| 226 | 3996x2160 |
| 227 | @item 4kscope |
| 228 | 4096x1716 |
| 229 | @item nhd |
| 230 | 640x360 |
| 231 | @item hqvga |
| 232 | 240x160 |
| 233 | @item wqvga |
| 234 | 400x240 |
| 235 | @item fwqvga |
| 236 | 432x240 |
| 237 | @item hvga |
| 238 | 480x320 |
| 239 | @item qhd |
| 240 | 960x540 |
| 241 | @end table |
| 242 | |
| 243 | @anchor{video rate syntax} |
| 244 | @section Video rate |
| 245 | |
| 246 | Specify the frame rate of a video, expressed as the number of frames |
| 247 | generated per second. It has to be a string in the format |
| 248 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float |
| 249 | number or a valid video frame rate abbreviation. |
| 250 | |
| 251 | The following abbreviations are recognized: |
| 252 | @table @samp |
| 253 | @item ntsc |
| 254 | 30000/1001 |
| 255 | @item pal |
| 256 | 25/1 |
| 257 | @item qntsc |
| 258 | 30000/1001 |
| 259 | @item qpal |
| 260 | 25/1 |
| 261 | @item sntsc |
| 262 | 30000/1001 |
| 263 | @item spal |
| 264 | 25/1 |
| 265 | @item film |
| 266 | 24/1 |
| 267 | @item ntsc-film |
| 268 | 24000/1001 |
| 269 | @end table |
| 270 | |
| 271 | @anchor{ratio syntax} |
| 272 | @section Ratio |
| 273 | |
| 274 | A ratio can be expressed as an expression, or in the form |
| 275 | @var{numerator}:@var{denominator}. |
| 276 | |
| 277 | Note that a ratio with infinite (1/0) or negative value is |
| 278 | considered valid, so you should check on the returned value if you |
| 279 | want to exclude those values. |
| 280 | |
| 281 | The undefined value can be expressed using the "0:0" string. |
| 282 | |
| 283 | @anchor{color syntax} |
| 284 | @section Color |
| 285 | |
| 286 | It can be the name of a color as defined below (case insensitive match) or a |
| 287 | @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string |
| 288 | representing the alpha component. |
| 289 | |
| 290 | The alpha component may be a string composed by "0x" followed by an |
| 291 | hexadecimal number or a decimal number between 0.0 and 1.0, which |
| 292 | represents the opacity value (@samp{0x00} or @samp{0.0} means completely |
| 293 | transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha |
| 294 | component is not specified then @samp{0xff} is assumed. |
| 295 | |
| 296 | The string @samp{random} will result in a random color. |
| 297 | |
| 298 | The following names of colors are recognized: |
| 299 | @table @samp |
| 300 | @item AliceBlue |
| 301 | 0xF0F8FF |
| 302 | @item AntiqueWhite |
| 303 | 0xFAEBD7 |
| 304 | @item Aqua |
| 305 | 0x00FFFF |
| 306 | @item Aquamarine |
| 307 | 0x7FFFD4 |
| 308 | @item Azure |
| 309 | 0xF0FFFF |
| 310 | @item Beige |
| 311 | 0xF5F5DC |
| 312 | @item Bisque |
| 313 | 0xFFE4C4 |
| 314 | @item Black |
| 315 | 0x000000 |
| 316 | @item BlanchedAlmond |
| 317 | 0xFFEBCD |
| 318 | @item Blue |
| 319 | 0x0000FF |
| 320 | @item BlueViolet |
| 321 | 0x8A2BE2 |
| 322 | @item Brown |
| 323 | 0xA52A2A |
| 324 | @item BurlyWood |
| 325 | 0xDEB887 |
| 326 | @item CadetBlue |
| 327 | 0x5F9EA0 |
| 328 | @item Chartreuse |
| 329 | 0x7FFF00 |
| 330 | @item Chocolate |
| 331 | 0xD2691E |
| 332 | @item Coral |
| 333 | 0xFF7F50 |
| 334 | @item CornflowerBlue |
| 335 | 0x6495ED |
| 336 | @item Cornsilk |
| 337 | 0xFFF8DC |
| 338 | @item Crimson |
| 339 | 0xDC143C |
| 340 | @item Cyan |
| 341 | 0x00FFFF |
| 342 | @item DarkBlue |
| 343 | 0x00008B |
| 344 | @item DarkCyan |
| 345 | 0x008B8B |
| 346 | @item DarkGoldenRod |
| 347 | 0xB8860B |
| 348 | @item DarkGray |
| 349 | 0xA9A9A9 |
| 350 | @item DarkGreen |
| 351 | 0x006400 |
| 352 | @item DarkKhaki |
| 353 | 0xBDB76B |
| 354 | @item DarkMagenta |
| 355 | 0x8B008B |
| 356 | @item DarkOliveGreen |
| 357 | 0x556B2F |
| 358 | @item Darkorange |
| 359 | 0xFF8C00 |
| 360 | @item DarkOrchid |
| 361 | 0x9932CC |
| 362 | @item DarkRed |
| 363 | 0x8B0000 |
| 364 | @item DarkSalmon |
| 365 | 0xE9967A |
| 366 | @item DarkSeaGreen |
| 367 | 0x8FBC8F |
| 368 | @item DarkSlateBlue |
| 369 | 0x483D8B |
| 370 | @item DarkSlateGray |
| 371 | 0x2F4F4F |
| 372 | @item DarkTurquoise |
| 373 | 0x00CED1 |
| 374 | @item DarkViolet |
| 375 | 0x9400D3 |
| 376 | @item DeepPink |
| 377 | 0xFF1493 |
| 378 | @item DeepSkyBlue |
| 379 | 0x00BFFF |
| 380 | @item DimGray |
| 381 | 0x696969 |
| 382 | @item DodgerBlue |
| 383 | 0x1E90FF |
| 384 | @item FireBrick |
| 385 | 0xB22222 |
| 386 | @item FloralWhite |
| 387 | 0xFFFAF0 |
| 388 | @item ForestGreen |
| 389 | 0x228B22 |
| 390 | @item Fuchsia |
| 391 | 0xFF00FF |
| 392 | @item Gainsboro |
| 393 | 0xDCDCDC |
| 394 | @item GhostWhite |
| 395 | 0xF8F8FF |
| 396 | @item Gold |
| 397 | 0xFFD700 |
| 398 | @item GoldenRod |
| 399 | 0xDAA520 |
| 400 | @item Gray |
| 401 | 0x808080 |
| 402 | @item Green |
| 403 | 0x008000 |
| 404 | @item GreenYellow |
| 405 | 0xADFF2F |
| 406 | @item HoneyDew |
| 407 | 0xF0FFF0 |
| 408 | @item HotPink |
| 409 | 0xFF69B4 |
| 410 | @item IndianRed |
| 411 | 0xCD5C5C |
| 412 | @item Indigo |
| 413 | 0x4B0082 |
| 414 | @item Ivory |
| 415 | 0xFFFFF0 |
| 416 | @item Khaki |
| 417 | 0xF0E68C |
| 418 | @item Lavender |
| 419 | 0xE6E6FA |
| 420 | @item LavenderBlush |
| 421 | 0xFFF0F5 |
| 422 | @item LawnGreen |
| 423 | 0x7CFC00 |
| 424 | @item LemonChiffon |
| 425 | 0xFFFACD |
| 426 | @item LightBlue |
| 427 | 0xADD8E6 |
| 428 | @item LightCoral |
| 429 | 0xF08080 |
| 430 | @item LightCyan |
| 431 | 0xE0FFFF |
| 432 | @item LightGoldenRodYellow |
| 433 | 0xFAFAD2 |
| 434 | @item LightGreen |
| 435 | 0x90EE90 |
| 436 | @item LightGrey |
| 437 | 0xD3D3D3 |
| 438 | @item LightPink |
| 439 | 0xFFB6C1 |
| 440 | @item LightSalmon |
| 441 | 0xFFA07A |
| 442 | @item LightSeaGreen |
| 443 | 0x20B2AA |
| 444 | @item LightSkyBlue |
| 445 | 0x87CEFA |
| 446 | @item LightSlateGray |
| 447 | 0x778899 |
| 448 | @item LightSteelBlue |
| 449 | 0xB0C4DE |
| 450 | @item LightYellow |
| 451 | 0xFFFFE0 |
| 452 | @item Lime |
| 453 | 0x00FF00 |
| 454 | @item LimeGreen |
| 455 | 0x32CD32 |
| 456 | @item Linen |
| 457 | 0xFAF0E6 |
| 458 | @item Magenta |
| 459 | 0xFF00FF |
| 460 | @item Maroon |
| 461 | 0x800000 |
| 462 | @item MediumAquaMarine |
| 463 | 0x66CDAA |
| 464 | @item MediumBlue |
| 465 | 0x0000CD |
| 466 | @item MediumOrchid |
| 467 | 0xBA55D3 |
| 468 | @item MediumPurple |
| 469 | 0x9370D8 |
| 470 | @item MediumSeaGreen |
| 471 | 0x3CB371 |
| 472 | @item MediumSlateBlue |
| 473 | 0x7B68EE |
| 474 | @item MediumSpringGreen |
| 475 | 0x00FA9A |
| 476 | @item MediumTurquoise |
| 477 | 0x48D1CC |
| 478 | @item MediumVioletRed |
| 479 | 0xC71585 |
| 480 | @item MidnightBlue |
| 481 | 0x191970 |
| 482 | @item MintCream |
| 483 | 0xF5FFFA |
| 484 | @item MistyRose |
| 485 | 0xFFE4E1 |
| 486 | @item Moccasin |
| 487 | 0xFFE4B5 |
| 488 | @item NavajoWhite |
| 489 | 0xFFDEAD |
| 490 | @item Navy |
| 491 | 0x000080 |
| 492 | @item OldLace |
| 493 | 0xFDF5E6 |
| 494 | @item Olive |
| 495 | 0x808000 |
| 496 | @item OliveDrab |
| 497 | 0x6B8E23 |
| 498 | @item Orange |
| 499 | 0xFFA500 |
| 500 | @item OrangeRed |
| 501 | 0xFF4500 |
| 502 | @item Orchid |
| 503 | 0xDA70D6 |
| 504 | @item PaleGoldenRod |
| 505 | 0xEEE8AA |
| 506 | @item PaleGreen |
| 507 | 0x98FB98 |
| 508 | @item PaleTurquoise |
| 509 | 0xAFEEEE |
| 510 | @item PaleVioletRed |
| 511 | 0xD87093 |
| 512 | @item PapayaWhip |
| 513 | 0xFFEFD5 |
| 514 | @item PeachPuff |
| 515 | 0xFFDAB9 |
| 516 | @item Peru |
| 517 | 0xCD853F |
| 518 | @item Pink |
| 519 | 0xFFC0CB |
| 520 | @item Plum |
| 521 | 0xDDA0DD |
| 522 | @item PowderBlue |
| 523 | 0xB0E0E6 |
| 524 | @item Purple |
| 525 | 0x800080 |
| 526 | @item Red |
| 527 | 0xFF0000 |
| 528 | @item RosyBrown |
| 529 | 0xBC8F8F |
| 530 | @item RoyalBlue |
| 531 | 0x4169E1 |
| 532 | @item SaddleBrown |
| 533 | 0x8B4513 |
| 534 | @item Salmon |
| 535 | 0xFA8072 |
| 536 | @item SandyBrown |
| 537 | 0xF4A460 |
| 538 | @item SeaGreen |
| 539 | 0x2E8B57 |
| 540 | @item SeaShell |
| 541 | 0xFFF5EE |
| 542 | @item Sienna |
| 543 | 0xA0522D |
| 544 | @item Silver |
| 545 | 0xC0C0C0 |
| 546 | @item SkyBlue |
| 547 | 0x87CEEB |
| 548 | @item SlateBlue |
| 549 | 0x6A5ACD |
| 550 | @item SlateGray |
| 551 | 0x708090 |
| 552 | @item Snow |
| 553 | 0xFFFAFA |
| 554 | @item SpringGreen |
| 555 | 0x00FF7F |
| 556 | @item SteelBlue |
| 557 | 0x4682B4 |
| 558 | @item Tan |
| 559 | 0xD2B48C |
| 560 | @item Teal |
| 561 | 0x008080 |
| 562 | @item Thistle |
| 563 | 0xD8BFD8 |
| 564 | @item Tomato |
| 565 | 0xFF6347 |
| 566 | @item Turquoise |
| 567 | 0x40E0D0 |
| 568 | @item Violet |
| 569 | 0xEE82EE |
| 570 | @item Wheat |
| 571 | 0xF5DEB3 |
| 572 | @item White |
| 573 | 0xFFFFFF |
| 574 | @item WhiteSmoke |
| 575 | 0xF5F5F5 |
| 576 | @item Yellow |
| 577 | 0xFFFF00 |
| 578 | @item YellowGreen |
| 579 | 0x9ACD32 |
| 580 | @end table |
| 581 | |
| 582 | @anchor{channel layout syntax} |
| 583 | @section Channel Layout |
| 584 | |
| 585 | A channel layout specifies the spatial disposition of the channels in |
| 586 | a multi-channel audio stream. To specify a channel layout, FFmpeg |
| 587 | makes use of a special syntax. |
| 588 | |
| 589 | Individual channels are identified by an id, as given by the table |
| 590 | below: |
| 591 | @table @samp |
| 592 | @item FL |
| 593 | front left |
| 594 | @item FR |
| 595 | front right |
| 596 | @item FC |
| 597 | front center |
| 598 | @item LFE |
| 599 | low frequency |
| 600 | @item BL |
| 601 | back left |
| 602 | @item BR |
| 603 | back right |
| 604 | @item FLC |
| 605 | front left-of-center |
| 606 | @item FRC |
| 607 | front right-of-center |
| 608 | @item BC |
| 609 | back center |
| 610 | @item SL |
| 611 | side left |
| 612 | @item SR |
| 613 | side right |
| 614 | @item TC |
| 615 | top center |
| 616 | @item TFL |
| 617 | top front left |
| 618 | @item TFC |
| 619 | top front center |
| 620 | @item TFR |
| 621 | top front right |
| 622 | @item TBL |
| 623 | top back left |
| 624 | @item TBC |
| 625 | top back center |
| 626 | @item TBR |
| 627 | top back right |
| 628 | @item DL |
| 629 | downmix left |
| 630 | @item DR |
| 631 | downmix right |
| 632 | @item WL |
| 633 | wide left |
| 634 | @item WR |
| 635 | wide right |
| 636 | @item SDL |
| 637 | surround direct left |
| 638 | @item SDR |
| 639 | surround direct right |
| 640 | @item LFE2 |
| 641 | low frequency 2 |
| 642 | @end table |
| 643 | |
| 644 | Standard channel layout compositions can be specified by using the |
| 645 | following identifiers: |
| 646 | @table @samp |
| 647 | @item mono |
| 648 | FC |
| 649 | @item stereo |
| 650 | FL+FR |
| 651 | @item 2.1 |
| 652 | FL+FR+LFE |
| 653 | @item 3.0 |
| 654 | FL+FR+FC |
| 655 | @item 3.0(back) |
| 656 | FL+FR+BC |
| 657 | @item 4.0 |
| 658 | FL+FR+FC+BC |
| 659 | @item quad |
| 660 | FL+FR+BL+BR |
| 661 | @item quad(side) |
| 662 | FL+FR+SL+SR |
| 663 | @item 3.1 |
| 664 | FL+FR+FC+LFE |
| 665 | @item 5.0 |
| 666 | FL+FR+FC+BL+BR |
| 667 | @item 5.0(side) |
| 668 | FL+FR+FC+SL+SR |
| 669 | @item 4.1 |
| 670 | FL+FR+FC+LFE+BC |
| 671 | @item 5.1 |
| 672 | FL+FR+FC+LFE+BL+BR |
| 673 | @item 5.1(side) |
| 674 | FL+FR+FC+LFE+SL+SR |
| 675 | @item 6.0 |
| 676 | FL+FR+FC+BC+SL+SR |
| 677 | @item 6.0(front) |
| 678 | FL+FR+FLC+FRC+SL+SR |
| 679 | @item hexagonal |
| 680 | FL+FR+FC+BL+BR+BC |
| 681 | @item 6.1 |
| 682 | FL+FR+FC+LFE+BC+SL+SR |
| 683 | @item 6.1 |
| 684 | FL+FR+FC+LFE+BL+BR+BC |
| 685 | @item 6.1(front) |
| 686 | FL+FR+LFE+FLC+FRC+SL+SR |
| 687 | @item 7.0 |
| 688 | FL+FR+FC+BL+BR+SL+SR |
| 689 | @item 7.0(front) |
| 690 | FL+FR+FC+FLC+FRC+SL+SR |
| 691 | @item 7.1 |
| 692 | FL+FR+FC+LFE+BL+BR+SL+SR |
| 693 | @item 7.1(wide) |
| 694 | FL+FR+FC+LFE+BL+BR+FLC+FRC |
| 695 | @item 7.1(wide-side) |
| 696 | FL+FR+FC+LFE+FLC+FRC+SL+SR |
| 697 | @item octagonal |
| 698 | FL+FR+FC+BL+BR+BC+SL+SR |
| 699 | @item downmix |
| 700 | DL+DR |
| 701 | @end table |
| 702 | |
| 703 | A custom channel layout can be specified as a sequence of terms, separated by |
| 704 | '+' or '|'. Each term can be: |
| 705 | @itemize |
| 706 | @item |
| 707 | the name of a standard channel layout (e.g. @samp{mono}, |
| 708 | @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.) |
| 709 | |
| 710 | @item |
| 711 | the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.) |
| 712 | |
| 713 | @item |
| 714 | a number of channels, in decimal, optionally followed by 'c', yielding |
| 715 | the default channel layout for that number of channels (see the |
| 716 | function @code{av_get_default_channel_layout}) |
| 717 | |
| 718 | @item |
| 719 | a channel layout mask, in hexadecimal starting with "0x" (see the |
| 720 | @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}. |
| 721 | @end itemize |
| 722 | |
| 723 | Starting from libavutil version 53 the trailing character "c" to |
| 724 | specify a number of channels will be required, while a channel layout |
| 725 | mask could also be specified as a decimal number (if and only if not |
| 726 | followed by "c"). |
| 727 | |
| 728 | See also the function @code{av_get_channel_layout} defined in |
| 729 | @file{libavutil/channel_layout.h}. |
| 730 | @c man end SYNTAX |
| 731 | |
| 732 | @chapter Expression Evaluation |
| 733 | @c man begin EXPRESSION EVALUATION |
| 734 | |
| 735 | When evaluating an arithmetic expression, FFmpeg uses an internal |
| 736 | formula evaluator, implemented through the @file{libavutil/eval.h} |
| 737 | interface. |
| 738 | |
| 739 | An expression may contain unary, binary operators, constants, and |
| 740 | functions. |
| 741 | |
| 742 | Two expressions @var{expr1} and @var{expr2} can be combined to form |
| 743 | another expression "@var{expr1};@var{expr2}". |
| 744 | @var{expr1} and @var{expr2} are evaluated in turn, and the new |
| 745 | expression evaluates to the value of @var{expr2}. |
| 746 | |
| 747 | The following binary operators are available: @code{+}, @code{-}, |
| 748 | @code{*}, @code{/}, @code{^}. |
| 749 | |
| 750 | The following unary operators are available: @code{+}, @code{-}. |
| 751 | |
| 752 | The following functions are available: |
| 753 | @table @option |
| 754 | @item abs(x) |
| 755 | Compute absolute value of @var{x}. |
| 756 | |
| 757 | @item acos(x) |
| 758 | Compute arccosine of @var{x}. |
| 759 | |
| 760 | @item asin(x) |
| 761 | Compute arcsine of @var{x}. |
| 762 | |
| 763 | @item atan(x) |
| 764 | Compute arctangent of @var{x}. |
| 765 | |
| 766 | @item between(x, min, max) |
| 767 | Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or |
| 768 | equal to @var{max}, 0 otherwise. |
| 769 | |
| 770 | @item bitand(x, y) |
| 771 | @item bitor(x, y) |
| 772 | Compute bitwise and/or operation on @var{x} and @var{y}. |
| 773 | |
| 774 | The results of the evaluation of @var{x} and @var{y} are converted to |
| 775 | integers before executing the bitwise operation. |
| 776 | |
| 777 | Note that both the conversion to integer and the conversion back to |
| 778 | floating point can lose precision. Beware of unexpected results for |
| 779 | large numbers (usually 2^53 and larger). |
| 780 | |
| 781 | @item ceil(expr) |
| 782 | Round the value of expression @var{expr} upwards to the nearest |
| 783 | integer. For example, "ceil(1.5)" is "2.0". |
| 784 | |
| 785 | @item clip(x, min, max) |
| 786 | Return the value of @var{x} clipped between @var{min} and @var{max}. |
| 787 | |
| 788 | @item cos(x) |
| 789 | Compute cosine of @var{x}. |
| 790 | |
| 791 | @item cosh(x) |
| 792 | Compute hyperbolic cosine of @var{x}. |
| 793 | |
| 794 | @item eq(x, y) |
| 795 | Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. |
| 796 | |
| 797 | @item exp(x) |
| 798 | Compute exponential of @var{x} (with base @code{e}, the Euler's number). |
| 799 | |
| 800 | @item floor(expr) |
| 801 | Round the value of expression @var{expr} downwards to the nearest |
| 802 | integer. For example, "floor(-1.5)" is "-2.0". |
| 803 | |
| 804 | @item gauss(x) |
| 805 | Compute Gauss function of @var{x}, corresponding to |
| 806 | @code{exp(-x*x/2) / sqrt(2*PI)}. |
| 807 | |
| 808 | @item gcd(x, y) |
| 809 | Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and |
| 810 | @var{y} are 0 or either or both are less than zero then behavior is undefined. |
| 811 | |
| 812 | @item gt(x, y) |
| 813 | Return 1 if @var{x} is greater than @var{y}, 0 otherwise. |
| 814 | |
| 815 | @item gte(x, y) |
| 816 | Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. |
| 817 | |
| 818 | @item hypot(x, y) |
| 819 | This function is similar to the C function with the same name; it returns |
| 820 | "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a |
| 821 | right triangle with sides of length @var{x} and @var{y}, or the distance of the |
| 822 | point (@var{x}, @var{y}) from the origin. |
| 823 | |
| 824 | @item if(x, y) |
| 825 | Evaluate @var{x}, and if the result is non-zero return the result of |
| 826 | the evaluation of @var{y}, return 0 otherwise. |
| 827 | |
| 828 | @item if(x, y, z) |
| 829 | Evaluate @var{x}, and if the result is non-zero return the evaluation |
| 830 | result of @var{y}, otherwise the evaluation result of @var{z}. |
| 831 | |
| 832 | @item ifnot(x, y) |
| 833 | Evaluate @var{x}, and if the result is zero return the result of the |
| 834 | evaluation of @var{y}, return 0 otherwise. |
| 835 | |
| 836 | @item ifnot(x, y, z) |
| 837 | Evaluate @var{x}, and if the result is zero return the evaluation |
| 838 | result of @var{y}, otherwise the evaluation result of @var{z}. |
| 839 | |
| 840 | @item isinf(x) |
| 841 | Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise. |
| 842 | |
| 843 | @item isnan(x) |
| 844 | Return 1.0 if @var{x} is NAN, 0.0 otherwise. |
| 845 | |
| 846 | @item ld(var) |
| 847 | Allow to load the value of the internal variable with number |
| 848 | @var{var}, which was previously stored with st(@var{var}, @var{expr}). |
| 849 | The function returns the loaded value. |
| 850 | |
| 851 | @item log(x) |
| 852 | Compute natural logarithm of @var{x}. |
| 853 | |
| 854 | @item lt(x, y) |
| 855 | Return 1 if @var{x} is lesser than @var{y}, 0 otherwise. |
| 856 | |
| 857 | @item lte(x, y) |
| 858 | Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise. |
| 859 | |
| 860 | @item max(x, y) |
| 861 | Return the maximum between @var{x} and @var{y}. |
| 862 | |
| 863 | @item min(x, y) |
| 864 | Return the maximum between @var{x} and @var{y}. |
| 865 | |
| 866 | @item mod(x, y) |
| 867 | Compute the remainder of division of @var{x} by @var{y}. |
| 868 | |
| 869 | @item not(expr) |
| 870 | Return 1.0 if @var{expr} is zero, 0.0 otherwise. |
| 871 | |
| 872 | @item pow(x, y) |
| 873 | Compute the power of @var{x} elevated @var{y}, it is equivalent to |
| 874 | "(@var{x})^(@var{y})". |
| 875 | |
| 876 | @item print(t) |
| 877 | @item print(t, l) |
| 878 | Print the value of expression @var{t} with loglevel @var{l}. If |
| 879 | @var{l} is not specified then a default log level is used. |
| 880 | Returns the value of the expression printed. |
| 881 | |
| 882 | Prints t with loglevel l |
| 883 | |
| 884 | @item random(x) |
| 885 | Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the |
| 886 | internal variable which will be used to save the seed/state. |
| 887 | |
| 888 | @item root(expr, max) |
| 889 | Find an input value for which the function represented by @var{expr} |
| 890 | with argument @var{ld(0)} is 0 in the interval 0..@var{max}. |
| 891 | |
| 892 | The expression in @var{expr} must denote a continuous function or the |
| 893 | result is undefined. |
| 894 | |
| 895 | @var{ld(0)} is used to represent the function input value, which means |
| 896 | that the given expression will be evaluated multiple times with |
| 897 | various input values that the expression can access through |
| 898 | @code{ld(0)}. When the expression evaluates to 0 then the |
| 899 | corresponding input value will be returned. |
| 900 | |
| 901 | @item sin(x) |
| 902 | Compute sine of @var{x}. |
| 903 | |
| 904 | @item sinh(x) |
| 905 | Compute hyperbolic sine of @var{x}. |
| 906 | |
| 907 | @item sqrt(expr) |
| 908 | Compute the square root of @var{expr}. This is equivalent to |
| 909 | "(@var{expr})^.5". |
| 910 | |
| 911 | @item squish(x) |
| 912 | Compute expression @code{1/(1 + exp(4*x))}. |
| 913 | |
| 914 | @item st(var, expr) |
| 915 | Allow to store the value of the expression @var{expr} in an internal |
| 916 | variable. @var{var} specifies the number of the variable where to |
| 917 | store the value, and it is a value ranging from 0 to 9. The function |
| 918 | returns the value stored in the internal variable. |
| 919 | Note, Variables are currently not shared between expressions. |
| 920 | |
| 921 | @item tan(x) |
| 922 | Compute tangent of @var{x}. |
| 923 | |
| 924 | @item tanh(x) |
| 925 | Compute hyperbolic tangent of @var{x}. |
| 926 | |
| 927 | @item taylor(expr, x) |
| 928 | @item taylor(expr, x, id) |
| 929 | Evaluate a Taylor series at @var{x}, given an expression representing |
| 930 | the @code{ld(id)}-th derivative of a function at 0. |
| 931 | |
| 932 | When the series does not converge the result is undefined. |
| 933 | |
| 934 | @var{ld(id)} is used to represent the derivative order in @var{expr}, |
| 935 | which means that the given expression will be evaluated multiple times |
| 936 | with various input values that the expression can access through |
| 937 | @code{ld(id)}. If @var{id} is not specified then 0 is assumed. |
| 938 | |
| 939 | Note, when you have the derivatives at y instead of 0, |
| 940 | @code{taylor(expr, x-y)} can be used. |
| 941 | |
| 942 | @item time(0) |
| 943 | Return the current (wallclock) time in seconds. |
| 944 | |
| 945 | @item trunc(expr) |
| 946 | Round the value of expression @var{expr} towards zero to the nearest |
| 947 | integer. For example, "trunc(-1.5)" is "-1.0". |
| 948 | |
| 949 | @item while(cond, expr) |
| 950 | Evaluate expression @var{expr} while the expression @var{cond} is |
| 951 | non-zero, and returns the value of the last @var{expr} evaluation, or |
| 952 | NAN if @var{cond} was always false. |
| 953 | @end table |
| 954 | |
| 955 | The following constants are available: |
| 956 | @table @option |
| 957 | @item PI |
| 958 | area of the unit disc, approximately 3.14 |
| 959 | @item E |
| 960 | exp(1) (Euler's number), approximately 2.718 |
| 961 | @item PHI |
| 962 | golden ratio (1+sqrt(5))/2, approximately 1.618 |
| 963 | @end table |
| 964 | |
| 965 | Assuming that an expression is considered "true" if it has a non-zero |
| 966 | value, note that: |
| 967 | |
| 968 | @code{*} works like AND |
| 969 | |
| 970 | @code{+} works like OR |
| 971 | |
| 972 | For example the construct: |
| 973 | @example |
| 974 | if (A AND B) then C |
| 975 | @end example |
| 976 | is equivalent to: |
| 977 | @example |
| 978 | if(A*B, C) |
| 979 | @end example |
| 980 | |
| 981 | In your C code, you can extend the list of unary and binary functions, |
| 982 | and define recognized constants, so that they are available for your |
| 983 | expressions. |
| 984 | |
| 985 | The evaluator also recognizes the International System unit prefixes. |
| 986 | If 'i' is appended after the prefix, binary prefixes are used, which |
| 987 | are based on powers of 1024 instead of powers of 1000. |
| 988 | The 'B' postfix multiplies the value by 8, and can be appended after a |
| 989 | unit prefix or used alone. This allows using for example 'KB', 'MiB', |
| 990 | 'G' and 'B' as number postfix. |
| 991 | |
| 992 | The list of available International System prefixes follows, with |
| 993 | indication of the corresponding powers of 10 and of 2. |
| 994 | @table @option |
| 995 | @item y |
| 996 | 10^-24 / 2^-80 |
| 997 | @item z |
| 998 | 10^-21 / 2^-70 |
| 999 | @item a |
| 1000 | 10^-18 / 2^-60 |
| 1001 | @item f |
| 1002 | 10^-15 / 2^-50 |
| 1003 | @item p |
| 1004 | 10^-12 / 2^-40 |
| 1005 | @item n |
| 1006 | 10^-9 / 2^-30 |
| 1007 | @item u |
| 1008 | 10^-6 / 2^-20 |
| 1009 | @item m |
| 1010 | 10^-3 / 2^-10 |
| 1011 | @item c |
| 1012 | 10^-2 |
| 1013 | @item d |
| 1014 | 10^-1 |
| 1015 | @item h |
| 1016 | 10^2 |
| 1017 | @item k |
| 1018 | 10^3 / 2^10 |
| 1019 | @item K |
| 1020 | 10^3 / 2^10 |
| 1021 | @item M |
| 1022 | 10^6 / 2^20 |
| 1023 | @item G |
| 1024 | 10^9 / 2^30 |
| 1025 | @item T |
| 1026 | 10^12 / 2^40 |
| 1027 | @item P |
| 1028 | 10^15 / 2^40 |
| 1029 | @item E |
| 1030 | 10^18 / 2^50 |
| 1031 | @item Z |
| 1032 | 10^21 / 2^60 |
| 1033 | @item Y |
| 1034 | 10^24 / 2^70 |
| 1035 | @end table |
| 1036 | |
| 1037 | @c man end EXPRESSION EVALUATION |
| 1038 | |
| 1039 | @chapter OpenCL Options |
| 1040 | @c man begin OPENCL OPTIONS |
| 1041 | |
| 1042 | When FFmpeg is configured with @code{--enable-opencl}, it is possible |
| 1043 | to set the options for the global OpenCL context. |
| 1044 | |
| 1045 | The list of supported options follows: |
| 1046 | |
| 1047 | @table @option |
| 1048 | @item build_options |
| 1049 | Set build options used to compile the registered kernels. |
| 1050 | |
| 1051 | See reference "OpenCL Specification Version: 1.2 chapter 5.6.4". |
| 1052 | |
| 1053 | @item platform_idx |
| 1054 | Select the index of the platform to run OpenCL code. |
| 1055 | |
| 1056 | The specified index must be one of the indexes in the device list |
| 1057 | which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}. |
| 1058 | |
| 1059 | @item device_idx |
| 1060 | Select the index of the device used to run OpenCL code. |
| 1061 | |
| 1062 | The specified index must be one of the indexes in the device list which |
| 1063 | can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}. |
| 1064 | |
| 1065 | @end table |
| 1066 | |
| 1067 | @c man end OPENCL OPTIONS |