avfilter/af_firequalizer: add min_phase option
[ffmpeg.git] / doc / utils.texi
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 @samp{'} and @samp{\} 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 @samp{\}.
22
23 @item
24 All characters enclosed between @samp{''} are included literally in the
25 parsed string. The quote character @samp{'} 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 @samp{\} 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 @item 2kdci
242 2048x1080
243 @item 4kdci
244 4096x2160
245 @item uhd2160
246 3840x2160
247 @item uhd4320
248 7680x4320
249 @end table
250
251 @anchor{video rate syntax}
252 @section Video rate
253
254 Specify the frame rate of a video, expressed as the number of frames
255 generated per second. It has to be a string in the format
256 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
257 number or a valid video frame rate abbreviation.
258
259 The following abbreviations are recognized:
260 @table @samp
261 @item ntsc
262 30000/1001
263 @item pal
264 25/1
265 @item qntsc
266 30000/1001
267 @item qpal
268 25/1
269 @item sntsc
270 30000/1001
271 @item spal
272 25/1
273 @item film
274 24/1
275 @item ntsc-film
276 24000/1001
277 @end table
278
279 @anchor{ratio syntax}
280 @section Ratio
281
282 A ratio can be expressed as an expression, or in the form
283 @var{numerator}:@var{denominator}.
284
285 Note that a ratio with infinite (1/0) or negative value is
286 considered valid, so you should check on the returned value if you
287 want to exclude those values.
288
289 The undefined value can be expressed using the "0:0" string.
290
291 @anchor{color syntax}
292 @section Color
293
294 It can be the name of a color as defined below (case insensitive match) or a
295 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
296 representing the alpha component.
297
298 The alpha component may be a string composed by "0x" followed by an
299 hexadecimal number or a decimal number between 0.0 and 1.0, which
300 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
301 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
302 component is not specified then @samp{0xff} is assumed.
303
304 The string @samp{random} will result in a random color.
305
306 The following names of colors are recognized:
307 @table @samp
308 @item AliceBlue
309 0xF0F8FF
310 @item AntiqueWhite
311 0xFAEBD7
312 @item Aqua
313 0x00FFFF
314 @item Aquamarine
315 0x7FFFD4
316 @item Azure
317 0xF0FFFF
318 @item Beige
319 0xF5F5DC
320 @item Bisque
321 0xFFE4C4
322 @item Black
323 0x000000
324 @item BlanchedAlmond
325 0xFFEBCD
326 @item Blue
327 0x0000FF
328 @item BlueViolet
329 0x8A2BE2
330 @item Brown
331 0xA52A2A
332 @item BurlyWood
333 0xDEB887
334 @item CadetBlue
335 0x5F9EA0
336 @item Chartreuse
337 0x7FFF00
338 @item Chocolate
339 0xD2691E
340 @item Coral
341 0xFF7F50
342 @item CornflowerBlue
343 0x6495ED
344 @item Cornsilk
345 0xFFF8DC
346 @item Crimson
347 0xDC143C
348 @item Cyan
349 0x00FFFF
350 @item DarkBlue
351 0x00008B
352 @item DarkCyan
353 0x008B8B
354 @item DarkGoldenRod
355 0xB8860B
356 @item DarkGray
357 0xA9A9A9
358 @item DarkGreen
359 0x006400
360 @item DarkKhaki
361 0xBDB76B
362 @item DarkMagenta
363 0x8B008B
364 @item DarkOliveGreen
365 0x556B2F
366 @item Darkorange
367 0xFF8C00
368 @item DarkOrchid
369 0x9932CC
370 @item DarkRed
371 0x8B0000
372 @item DarkSalmon
373 0xE9967A
374 @item DarkSeaGreen
375 0x8FBC8F
376 @item DarkSlateBlue
377 0x483D8B
378 @item DarkSlateGray
379 0x2F4F4F
380 @item DarkTurquoise
381 0x00CED1
382 @item DarkViolet
383 0x9400D3
384 @item DeepPink
385 0xFF1493
386 @item DeepSkyBlue
387 0x00BFFF
388 @item DimGray
389 0x696969
390 @item DodgerBlue
391 0x1E90FF
392 @item FireBrick
393 0xB22222
394 @item FloralWhite
395 0xFFFAF0
396 @item ForestGreen
397 0x228B22
398 @item Fuchsia
399 0xFF00FF
400 @item Gainsboro
401 0xDCDCDC
402 @item GhostWhite
403 0xF8F8FF
404 @item Gold
405 0xFFD700
406 @item GoldenRod
407 0xDAA520
408 @item Gray
409 0x808080
410 @item Green
411 0x008000
412 @item GreenYellow
413 0xADFF2F
414 @item HoneyDew
415 0xF0FFF0
416 @item HotPink
417 0xFF69B4
418 @item IndianRed
419 0xCD5C5C
420 @item Indigo
421 0x4B0082
422 @item Ivory
423 0xFFFFF0
424 @item Khaki
425 0xF0E68C
426 @item Lavender
427 0xE6E6FA
428 @item LavenderBlush
429 0xFFF0F5
430 @item LawnGreen
431 0x7CFC00
432 @item LemonChiffon
433 0xFFFACD
434 @item LightBlue
435 0xADD8E6
436 @item LightCoral
437 0xF08080
438 @item LightCyan
439 0xE0FFFF
440 @item LightGoldenRodYellow
441 0xFAFAD2
442 @item LightGreen
443 0x90EE90
444 @item LightGrey
445 0xD3D3D3
446 @item LightPink
447 0xFFB6C1
448 @item LightSalmon
449 0xFFA07A
450 @item LightSeaGreen
451 0x20B2AA
452 @item LightSkyBlue
453 0x87CEFA
454 @item LightSlateGray
455 0x778899
456 @item LightSteelBlue
457 0xB0C4DE
458 @item LightYellow
459 0xFFFFE0
460 @item Lime
461 0x00FF00
462 @item LimeGreen
463 0x32CD32
464 @item Linen
465 0xFAF0E6
466 @item Magenta
467 0xFF00FF
468 @item Maroon
469 0x800000
470 @item MediumAquaMarine
471 0x66CDAA
472 @item MediumBlue
473 0x0000CD
474 @item MediumOrchid
475 0xBA55D3
476 @item MediumPurple
477 0x9370D8
478 @item MediumSeaGreen
479 0x3CB371
480 @item MediumSlateBlue
481 0x7B68EE
482 @item MediumSpringGreen
483 0x00FA9A
484 @item MediumTurquoise
485 0x48D1CC
486 @item MediumVioletRed
487 0xC71585
488 @item MidnightBlue
489 0x191970
490 @item MintCream
491 0xF5FFFA
492 @item MistyRose
493 0xFFE4E1
494 @item Moccasin
495 0xFFE4B5
496 @item NavajoWhite
497 0xFFDEAD
498 @item Navy
499 0x000080
500 @item OldLace
501 0xFDF5E6
502 @item Olive
503 0x808000
504 @item OliveDrab
505 0x6B8E23
506 @item Orange
507 0xFFA500
508 @item OrangeRed
509 0xFF4500
510 @item Orchid
511 0xDA70D6
512 @item PaleGoldenRod
513 0xEEE8AA
514 @item PaleGreen
515 0x98FB98
516 @item PaleTurquoise
517 0xAFEEEE
518 @item PaleVioletRed
519 0xD87093
520 @item PapayaWhip
521 0xFFEFD5
522 @item PeachPuff
523 0xFFDAB9
524 @item Peru
525 0xCD853F
526 @item Pink
527 0xFFC0CB
528 @item Plum
529 0xDDA0DD
530 @item PowderBlue
531 0xB0E0E6
532 @item Purple
533 0x800080
534 @item Red
535 0xFF0000
536 @item RosyBrown
537 0xBC8F8F
538 @item RoyalBlue
539 0x4169E1
540 @item SaddleBrown
541 0x8B4513
542 @item Salmon
543 0xFA8072
544 @item SandyBrown
545 0xF4A460
546 @item SeaGreen
547 0x2E8B57
548 @item SeaShell
549 0xFFF5EE
550 @item Sienna
551 0xA0522D
552 @item Silver
553 0xC0C0C0
554 @item SkyBlue
555 0x87CEEB
556 @item SlateBlue
557 0x6A5ACD
558 @item SlateGray
559 0x708090
560 @item Snow
561 0xFFFAFA
562 @item SpringGreen
563 0x00FF7F
564 @item SteelBlue
565 0x4682B4
566 @item Tan
567 0xD2B48C
568 @item Teal
569 0x008080
570 @item Thistle
571 0xD8BFD8
572 @item Tomato
573 0xFF6347
574 @item Turquoise
575 0x40E0D0
576 @item Violet
577 0xEE82EE
578 @item Wheat
579 0xF5DEB3
580 @item White
581 0xFFFFFF
582 @item WhiteSmoke
583 0xF5F5F5
584 @item Yellow
585 0xFFFF00
586 @item YellowGreen
587 0x9ACD32
588 @end table
589
590 @anchor{channel layout syntax}
591 @section Channel Layout
592
593 A channel layout specifies the spatial disposition of the channels in
594 a multi-channel audio stream. To specify a channel layout, FFmpeg
595 makes use of a special syntax.
596
597 Individual channels are identified by an id, as given by the table
598 below:
599 @table @samp
600 @item FL
601 front left
602 @item FR
603 front right
604 @item FC
605 front center
606 @item LFE
607 low frequency
608 @item BL
609 back left
610 @item BR
611 back right
612 @item FLC
613 front left-of-center
614 @item FRC
615 front right-of-center
616 @item BC
617 back center
618 @item SL
619 side left
620 @item SR
621 side right
622 @item TC
623 top center
624 @item TFL
625 top front left
626 @item TFC
627 top front center
628 @item TFR
629 top front right
630 @item TBL
631 top back left
632 @item TBC
633 top back center
634 @item TBR
635 top back right
636 @item DL
637 downmix left
638 @item DR
639 downmix right
640 @item WL
641 wide left
642 @item WR
643 wide right
644 @item SDL
645 surround direct left
646 @item SDR
647 surround direct right
648 @item LFE2
649 low frequency 2
650 @end table
651
652 Standard channel layout compositions can be specified by using the
653 following identifiers:
654 @table @samp
655 @item mono
656 FC
657 @item stereo
658 FL+FR
659 @item 2.1
660 FL+FR+LFE
661 @item 3.0
662 FL+FR+FC
663 @item 3.0(back)
664 FL+FR+BC
665 @item 4.0
666 FL+FR+FC+BC
667 @item quad
668 FL+FR+BL+BR
669 @item quad(side)
670 FL+FR+SL+SR
671 @item 3.1
672 FL+FR+FC+LFE
673 @item 5.0
674 FL+FR+FC+BL+BR
675 @item 5.0(side)
676 FL+FR+FC+SL+SR
677 @item 4.1
678 FL+FR+FC+LFE+BC
679 @item 5.1
680 FL+FR+FC+LFE+BL+BR
681 @item 5.1(side)
682 FL+FR+FC+LFE+SL+SR
683 @item 6.0
684 FL+FR+FC+BC+SL+SR
685 @item 6.0(front)
686 FL+FR+FLC+FRC+SL+SR
687 @item hexagonal
688 FL+FR+FC+BL+BR+BC
689 @item 6.1
690 FL+FR+FC+LFE+BC+SL+SR
691 @item 6.1
692 FL+FR+FC+LFE+BL+BR+BC
693 @item 6.1(front)
694 FL+FR+LFE+FLC+FRC+SL+SR
695 @item 7.0
696 FL+FR+FC+BL+BR+SL+SR
697 @item 7.0(front)
698 FL+FR+FC+FLC+FRC+SL+SR
699 @item 7.1
700 FL+FR+FC+LFE+BL+BR+SL+SR
701 @item 7.1(wide)
702 FL+FR+FC+LFE+BL+BR+FLC+FRC
703 @item 7.1(wide-side)
704 FL+FR+FC+LFE+FLC+FRC+SL+SR
705 @item octagonal
706 FL+FR+FC+BL+BR+BC+SL+SR
707 @item downmix
708 DL+DR
709 @end table
710
711 A custom channel layout can be specified as a sequence of terms, separated by
712 '+' or '|'. Each term can be:
713 @itemize
714 @item
715 the name of a standard channel layout (e.g. @samp{mono},
716 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
717
718 @item
719 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
720
721 @item
722 a number of channels, in decimal, followed by 'c', yielding the default channel
723 layout for that number of channels (see the function
724 @code{av_get_default_channel_layout}). Note that not all channel counts have a
725 default layout.
726
727 @item
728 a number of channels, in decimal, followed by 'C', yielding an unknown channel
729 layout with the specified number of channels. Note that not all channel layout
730 specification strings support unknown channel layouts.
731
732 @item
733 a channel layout mask, in hexadecimal starting with "0x" (see the
734 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
735 @end itemize
736
737 Before libavutil version 53 the trailing character "c" to specify a number of
738 channels was optional, but now it is required, while a channel layout mask can
739 also be specified as a decimal number (if and only if not followed by "c" or "C").
740
741 See also the function @code{av_get_channel_layout} defined in
742 @file{libavutil/channel_layout.h}.
743 @c man end SYNTAX
744
745 @chapter Expression Evaluation
746 @c man begin EXPRESSION EVALUATION
747
748 When evaluating an arithmetic expression, FFmpeg uses an internal
749 formula evaluator, implemented through the @file{libavutil/eval.h}
750 interface.
751
752 An expression may contain unary, binary operators, constants, and
753 functions.
754
755 Two expressions @var{expr1} and @var{expr2} can be combined to form
756 another expression "@var{expr1};@var{expr2}".
757 @var{expr1} and @var{expr2} are evaluated in turn, and the new
758 expression evaluates to the value of @var{expr2}.
759
760 The following binary operators are available: @code{+}, @code{-},
761 @code{*}, @code{/}, @code{^}.
762
763 The following unary operators are available: @code{+}, @code{-}.
764
765 The following functions are available:
766 @table @option
767 @item abs(x)
768 Compute absolute value of @var{x}.
769
770 @item acos(x)
771 Compute arccosine of @var{x}.
772
773 @item asin(x)
774 Compute arcsine of @var{x}.
775
776 @item atan(x)
777 Compute arctangent of @var{x}.
778
779 @item atan2(x, y)
780 Compute principal value of the arc tangent of @var{y}/@var{x}.
781
782 @item between(x, min, max)
783 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
784 equal to @var{max}, 0 otherwise.
785
786 @item bitand(x, y)
787 @item bitor(x, y)
788 Compute bitwise and/or operation on @var{x} and @var{y}.
789
790 The results of the evaluation of @var{x} and @var{y} are converted to
791 integers before executing the bitwise operation.
792
793 Note that both the conversion to integer and the conversion back to
794 floating point can lose precision. Beware of unexpected results for
795 large numbers (usually 2^53 and larger).
796
797 @item ceil(expr)
798 Round the value of expression @var{expr} upwards to the nearest
799 integer. For example, "ceil(1.5)" is "2.0".
800
801 @item clip(x, min, max)
802 Return the value of @var{x} clipped between @var{min} and @var{max}.
803
804 @item cos(x)
805 Compute cosine of @var{x}.
806
807 @item cosh(x)
808 Compute hyperbolic cosine of @var{x}.
809
810 @item eq(x, y)
811 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
812
813 @item exp(x)
814 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
815
816 @item floor(expr)
817 Round the value of expression @var{expr} downwards to the nearest
818 integer. For example, "floor(-1.5)" is "-2.0".
819
820 @item gauss(x)
821 Compute Gauss function of @var{x}, corresponding to
822 @code{exp(-x*x/2) / sqrt(2*PI)}.
823
824 @item gcd(x, y)
825 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
826 @var{y} are 0 or either or both are less than zero then behavior is undefined.
827
828 @item gt(x, y)
829 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
830
831 @item gte(x, y)
832 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
833
834 @item hypot(x, y)
835 This function is similar to the C function with the same name; it returns
836 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
837 right triangle with sides of length @var{x} and @var{y}, or the distance of the
838 point (@var{x}, @var{y}) from the origin.
839
840 @item if(x, y)
841 Evaluate @var{x}, and if the result is non-zero return the result of
842 the evaluation of @var{y}, return 0 otherwise.
843
844 @item if(x, y, z)
845 Evaluate @var{x}, and if the result is non-zero return the evaluation
846 result of @var{y}, otherwise the evaluation result of @var{z}.
847
848 @item ifnot(x, y)
849 Evaluate @var{x}, and if the result is zero return the result of the
850 evaluation of @var{y}, return 0 otherwise.
851
852 @item ifnot(x, y, z)
853 Evaluate @var{x}, and if the result is zero return the evaluation
854 result of @var{y}, otherwise the evaluation result of @var{z}.
855
856 @item isinf(x)
857 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
858
859 @item isnan(x)
860 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
861
862 @item ld(var)
863 Load the value of the internal variable with number
864 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
865 The function returns the loaded value.
866
867 @item lerp(x, y, z)
868 Return linear interpolation between @var{x} and @var{y} by amount of @var{z}.
869
870 @item log(x)
871 Compute natural logarithm of @var{x}.
872
873 @item lt(x, y)
874 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
875
876 @item lte(x, y)
877 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
878
879 @item max(x, y)
880 Return the maximum between @var{x} and @var{y}.
881
882 @item min(x, y)
883 Return the minimum between @var{x} and @var{y}.
884
885 @item mod(x, y)
886 Compute the remainder of division of @var{x} by @var{y}.
887
888 @item not(expr)
889 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
890
891 @item pow(x, y)
892 Compute the power of @var{x} elevated @var{y}, it is equivalent to
893 "(@var{x})^(@var{y})".
894
895 @item print(t)
896 @item print(t, l)
897 Print the value of expression @var{t} with loglevel @var{l}. If
898 @var{l} is not specified then a default log level is used.
899 Returns the value of the expression printed.
900
901 Prints t with loglevel l
902
903 @item random(x)
904 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
905 internal variable which will be used to save the seed/state.
906
907 @item root(expr, max)
908 Find an input value for which the function represented by @var{expr}
909 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
910
911 The expression in @var{expr} must denote a continuous function or the
912 result is undefined.
913
914 @var{ld(0)} is used to represent the function input value, which means
915 that the given expression will be evaluated multiple times with
916 various input values that the expression can access through
917 @code{ld(0)}. When the expression evaluates to 0 then the
918 corresponding input value will be returned.
919
920 @item round(expr)
921 Round the value of expression @var{expr} to the nearest integer. For example, "round(1.5)" is "2.0".
922
923 @item sin(x)
924 Compute sine of @var{x}.
925
926 @item sinh(x)
927 Compute hyperbolic sine of @var{x}.
928
929 @item sqrt(expr)
930 Compute the square root of @var{expr}. This is equivalent to
931 "(@var{expr})^.5".
932
933 @item squish(x)
934 Compute expression @code{1/(1 + exp(4*x))}.
935
936 @item st(var, expr)
937 Store the value of the expression @var{expr} in an internal
938 variable. @var{var} specifies the number of the variable where to
939 store the value, and it is a value ranging from 0 to 9. The function
940 returns the value stored in the internal variable.
941 Note, Variables are currently not shared between expressions.
942
943 @item tan(x)
944 Compute tangent of @var{x}.
945
946 @item tanh(x)
947 Compute hyperbolic tangent of @var{x}.
948
949 @item taylor(expr, x)
950 @item taylor(expr, x, id)
951 Evaluate a Taylor series at @var{x}, given an expression representing
952 the @code{ld(id)}-th derivative of a function at 0.
953
954 When the series does not converge the result is undefined.
955
956 @var{ld(id)} is used to represent the derivative order in @var{expr},
957 which means that the given expression will be evaluated multiple times
958 with various input values that the expression can access through
959 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
960
961 Note, when you have the derivatives at y instead of 0,
962 @code{taylor(expr, x-y)} can be used.
963
964 @item time(0)
965 Return the current (wallclock) time in seconds.
966
967 @item trunc(expr)
968 Round the value of expression @var{expr} towards zero to the nearest
969 integer. For example, "trunc(-1.5)" is "-1.0".
970
971 @item while(cond, expr)
972 Evaluate expression @var{expr} while the expression @var{cond} is
973 non-zero, and returns the value of the last @var{expr} evaluation, or
974 NAN if @var{cond} was always false.
975 @end table
976
977 The following constants are available:
978 @table @option
979 @item PI
980 area of the unit disc, approximately 3.14
981 @item E
982 exp(1) (Euler's number), approximately 2.718
983 @item PHI
984 golden ratio (1+sqrt(5))/2, approximately 1.618
985 @end table
986
987 Assuming that an expression is considered "true" if it has a non-zero
988 value, note that:
989
990 @code{*} works like AND
991
992 @code{+} works like OR
993
994 For example the construct:
995 @example
996 if (A AND B) then C
997 @end example
998 is equivalent to:
999 @example
1000 if(A*B, C)
1001 @end example
1002
1003 In your C code, you can extend the list of unary and binary functions,
1004 and define recognized constants, so that they are available for your
1005 expressions.
1006
1007 The evaluator also recognizes the International System unit prefixes.
1008 If 'i' is appended after the prefix, binary prefixes are used, which
1009 are based on powers of 1024 instead of powers of 1000.
1010 The 'B' postfix multiplies the value by 8, and can be appended after a
1011 unit prefix or used alone. This allows using for example 'KB', 'MiB',
1012 'G' and 'B' as number postfix.
1013
1014 The list of available International System prefixes follows, with
1015 indication of the corresponding powers of 10 and of 2.
1016 @table @option
1017 @item y
1018 10^-24 / 2^-80
1019 @item z
1020 10^-21 / 2^-70
1021 @item a
1022 10^-18 / 2^-60
1023 @item f
1024 10^-15 / 2^-50
1025 @item p
1026 10^-12 / 2^-40
1027 @item n
1028 10^-9 / 2^-30
1029 @item u
1030 10^-6 / 2^-20
1031 @item m
1032 10^-3 / 2^-10
1033 @item c
1034 10^-2
1035 @item d
1036 10^-1
1037 @item h
1038 10^2
1039 @item k
1040 10^3 / 2^10
1041 @item K
1042 10^3 / 2^10
1043 @item M
1044 10^6 / 2^20
1045 @item G
1046 10^9 / 2^30
1047 @item T
1048 10^12 / 2^40
1049 @item P
1050 10^15 / 2^40
1051 @item E
1052 10^18 / 2^50
1053 @item Z
1054 10^21 / 2^60
1055 @item Y
1056 10^24 / 2^70
1057 @end table
1058
1059 @c man end EXPRESSION EVALUATION
1060
1061 @chapter OpenCL Options
1062 @c man begin OPENCL OPTIONS
1063
1064 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1065 to set the options for the global OpenCL context.
1066
1067 The list of supported options follows:
1068
1069 @table @option
1070 @item build_options
1071 Set build options used to compile the registered kernels.
1072
1073 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1074
1075 @item platform_idx
1076 Select the index of the platform to run OpenCL code.
1077
1078 The specified index must be one of the indexes in the device list
1079 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1080
1081 @item device_idx
1082 Select the index of the device used to run OpenCL code.
1083
1084 The specified index must be one of the indexes in the device list which
1085 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1086
1087 @end table
1088
1089 @c man end OPENCL OPTIONS