Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 |