lavu/parseutils: add more resolutions
[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 @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 The accepted syntax is:
100 @example
101 [-][HH:]MM:SS[.m...]
102 [-]S+[.m...]
103 @end example
104
105 @var{HH} expresses the number of hours, @var{MM} the number a of minutes
106 and @var{SS} the number of seconds.
107
108 @anchor{video size syntax}
109 @section Video size
110 Specify the size of the sourced video, it may be a string of the form
111 @var{width}x@var{height}, or the name of a size abbreviation.
112
113 The following abbreviations are recognized:
114 @table @samp
115 @item ntsc
116 720x480
117 @item pal
118 720x576
119 @item qntsc
120 352x240
121 @item qpal
122 352x288
123 @item sntsc
124 640x480
125 @item spal
126 768x576
127 @item film
128 352x240
129 @item ntsc-film
130 352x240
131 @item sqcif
132 128x96
133 @item qcif
134 176x144
135 @item cif
136 352x288
137 @item 4cif
138 704x576
139 @item 16cif
140 1408x1152
141 @item qqvga
142 160x120
143 @item qvga
144 320x240
145 @item vga
146 640x480
147 @item svga
148 800x600
149 @item xga
150 1024x768
151 @item uxga
152 1600x1200
153 @item qxga
154 2048x1536
155 @item sxga
156 1280x1024
157 @item qsxga
158 2560x2048
159 @item hsxga
160 5120x4096
161 @item wvga
162 852x480
163 @item wxga
164 1366x768
165 @item wsxga
166 1600x1024
167 @item wuxga
168 1920x1200
169 @item woxga
170 2560x1600
171 @item wqsxga
172 3200x2048
173 @item wquxga
174 3840x2400
175 @item whsxga
176 6400x4096
177 @item whuxga
178 7680x4800
179 @item cga
180 320x200
181 @item ega
182 640x350
183 @item hd480
184 852x480
185 @item hd720
186 1280x720
187 @item hd1080
188 1920x1080
189 @item 2k
190 2048x1080
191 @item 2kflat
192 1998x1080
193 @item 2kscope
194 2048x858
195 @item 4k
196 4096x2160
197 @item 4kflat
198 3996x2160
199 @item 4kscope
200 4096x1716
201 @item nhd
202 640x360
203 @item hqvga
204 240x160
205 @item wqvga
206 400x240
207 @item fwqvga
208 432x240
209 @item hvga
210 480x320
211 @item qhd
212 960x540
213 @end table
214
215 @anchor{video rate syntax}
216 @section Video rate
217
218 Specify the frame rate of a video, expressed as the number of frames
219 generated per second. It has to be a string in the format
220 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
221 number or a valid video frame rate abbreviation.
222
223 The following abbreviations are recognized:
224 @table @samp
225 @item ntsc
226 30000/1001
227 @item pal
228 25/1
229 @item qntsc
230 30000/1001
231 @item qpal
232 25/1
233 @item sntsc
234 30000/1001
235 @item spal
236 25/1
237 @item film
238 24/1
239 @item ntsc-film
240 24000/1001
241 @end table
242
243 @anchor{ratio syntax}
244 @section Ratio
245
246 A ratio can be expressed as an expression, or in the form
247 @var{numerator}:@var{denominator}.
248
249 Note that a ratio with infinite (1/0) or negative value is
250 considered valid, so you should check on the returned value if you
251 want to exclude those values.
252
253 The undefined value can be expressed using the "0:0" string.
254
255 @anchor{color syntax}
256 @section Color
257
258 It can be the name of a color (case insensitive match) or a
259 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
260 representing the alpha component.
261
262 The alpha component may be a string composed by "0x" followed by an
263 hexadecimal number or a decimal number between 0.0 and 1.0, which
264 represents the opacity value (0x00/0.0 means completely transparent,
265 0xff/1.0 completely opaque).
266 If the alpha component is not specified then 0xff is assumed.
267
268 The string "random" will result in a random color.
269
270 @c man end SYNTAX
271
272 @chapter Expression Evaluation
273 @c man begin EXPRESSION EVALUATION
274
275 When evaluating an arithmetic expression, FFmpeg uses an internal
276 formula evaluator, implemented through the @file{libavutil/eval.h}
277 interface.
278
279 An expression may contain unary, binary operators, constants, and
280 functions.
281
282 Two expressions @var{expr1} and @var{expr2} can be combined to form
283 another expression "@var{expr1};@var{expr2}".
284 @var{expr1} and @var{expr2} are evaluated in turn, and the new
285 expression evaluates to the value of @var{expr2}.
286
287 The following binary operators are available: @code{+}, @code{-},
288 @code{*}, @code{/}, @code{^}.
289
290 The following unary operators are available: @code{+}, @code{-}.
291
292 The following functions are available:
293 @table @option
294 @item abs(x)
295 Compute absolute value of @var{x}.
296
297 @item acos(x)
298 Compute arccosine of @var{x}.
299
300 @item asin(x)
301 Compute arcsine of @var{x}.
302
303 @item atan(x)
304 Compute arctangent of @var{x}.
305
306 @item between(x, min, max)
307 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
308 equal to @var{max}, 0 otherwise.
309
310 @item bitand(x, y)
311 @item bitor(x, y)
312 Compute bitwise and/or operation on @var{x} and @var{y}.
313
314 The results of the evaluation of @var{x} and @var{y} are converted to
315 integers before executing the bitwise operation.
316
317 Note that both the conversion to integer and the conversion back to
318 floating point can lose precision. Beware of unexpected results for
319 large numbers (usually 2^53 and larger).
320
321 @item ceil(expr)
322 Round the value of expression @var{expr} upwards to the nearest
323 integer. For example, "ceil(1.5)" is "2.0".
324
325 @item cos(x)
326 Compute cosine of @var{x}.
327
328 @item cosh(x)
329 Compute hyperbolic cosine of @var{x}.
330
331 @item eq(x, y)
332 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
333
334 @item exp(x)
335 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
336
337 @item floor(expr)
338 Round the value of expression @var{expr} downwards to the nearest
339 integer. For example, "floor(-1.5)" is "-2.0".
340
341 @item gauss(x)
342 Compute Gauss function of @var{x}, corresponding to
343 @code{exp(-x*x/2) / sqrt(2*PI)}.
344
345 @item gcd(x, y)
346 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
347 @var{y} are 0 or either or both are less than zero then behavior is undefined.
348
349 @item gt(x, y)
350 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
351
352 @item gte(x, y)
353 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
354
355 @item hypot(x, y)
356 This function is similar to the C function with the same name; it returns
357 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
358 right triangle with sides of length @var{x} and @var{y}, or the distance of the
359 point (@var{x}, @var{y}) from the origin.
360
361 @item if(x, y)
362 Evaluate @var{x}, and if the result is non-zero return the result of
363 the evaluation of @var{y}, return 0 otherwise.
364
365 @item if(x, y, z)
366 Evaluate @var{x}, and if the result is non-zero return the evaluation
367 result of @var{y}, otherwise the evaluation result of @var{z}.
368
369 @item ifnot(x, y)
370 Evaluate @var{x}, and if the result is zero return the result of the
371 evaluation of @var{y}, return 0 otherwise.
372
373 @item ifnot(x, y, z)
374 Evaluate @var{x}, and if the result is zero return the evaluation
375 result of @var{y}, otherwise the evaluation result of @var{z}.
376
377 @item isinf(x)
378 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
379
380 @item isnan(x)
381 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
382
383 @item ld(var)
384 Allow to load the value of the internal variable with number
385 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
386 The function returns the loaded value.
387
388 @item log(x)
389 Compute natural logarithm of @var{x}.
390
391 @item lt(x, y)
392 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
393
394 @item lte(x, y)
395 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
396
397 @item max(x, y)
398 Return the maximum between @var{x} and @var{y}.
399
400 @item min(x, y)
401 Return the maximum between @var{x} and @var{y}.
402
403 @item mod(x, y)
404 Compute the remainder of division of @var{x} by @var{y}.
405
406 @item not(expr)
407 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
408
409 @item pow(x, y)
410 Compute the power of @var{x} elevated @var{y}, it is equivalent to
411 "(@var{x})^(@var{y})".
412
413 @item print(t)
414 @item print(t, l)
415 Print the value of expression @var{t} with loglevel @var{l}. If
416 @var{l} is not specified then a default log level is used.
417 Returns the value of the expression printed.
418
419 Prints t with loglevel l
420
421 @item random(x)
422 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
423 internal variable which will be used to save the seed/state.
424
425 @item root(expr, max)
426 Find an input value for which the function represented by @var{expr}
427 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
428
429 The expression in @var{expr} must denote a continuous function or the
430 result is undefined.
431
432 @var{ld(0)} is used to represent the function input value, which means
433 that the given expression will be evaluated multiple times with
434 various input values that the expression can access through
435 @code{ld(0)}. When the expression evaluates to 0 then the
436 corresponding input value will be returned.
437
438 @item sin(x)
439 Compute sine of @var{x}.
440
441 @item sinh(x)
442 Compute hyperbolic sine of @var{x}.
443
444 @item sqrt(expr)
445 Compute the square root of @var{expr}. This is equivalent to
446 "(@var{expr})^.5".
447
448 @item squish(x)
449 Compute expression @code{1/(1 + exp(4*x))}.
450
451 @item st(var, expr)
452 Allow to store the value of the expression @var{expr} in an internal
453 variable. @var{var} specifies the number of the variable where to
454 store the value, and it is a value ranging from 0 to 9. The function
455 returns the value stored in the internal variable.
456 Note, Variables are currently not shared between expressions.
457
458 @item tan(x)
459 Compute tangent of @var{x}.
460
461 @item tanh(x)
462 Compute hyperbolic tangent of @var{x}.
463
464 @item taylor(expr, x)
465 @item taylor(expr, x, id)
466 Evaluate a Taylor series at @var{x}, given an expression representing
467 the @code{ld(id)}-th derivative of a function at 0.
468
469 When the series does not converge the result is undefined.
470
471 @var{ld(id)} is used to represent the derivative order in @var{expr},
472 which means that the given expression will be evaluated multiple times
473 with various input values that the expression can access through
474 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
475
476 Note, when you have the derivatives at y instead of 0,
477 @code{taylor(expr, x-y)} can be used.
478
479 @item time(0)
480 Return the current (wallclock) time in seconds.
481
482 @item trunc(expr)
483 Round the value of expression @var{expr} towards zero to the nearest
484 integer. For example, "trunc(-1.5)" is "-1.0".
485
486 @item while(cond, expr)
487 Evaluate expression @var{expr} while the expression @var{cond} is
488 non-zero, and returns the value of the last @var{expr} evaluation, or
489 NAN if @var{cond} was always false.
490 @end table
491
492 The following constants are available:
493 @table @option
494 @item PI
495 area of the unit disc, approximately 3.14
496 @item E
497 exp(1) (Euler's number), approximately 2.718
498 @item PHI
499 golden ratio (1+sqrt(5))/2, approximately 1.618
500 @end table
501
502 Assuming that an expression is considered "true" if it has a non-zero
503 value, note that:
504
505 @code{*} works like AND
506
507 @code{+} works like OR
508
509 For example the construct:
510 @example
511 if (A AND B) then C
512 @end example
513 is equivalent to:
514 @example
515 if(A*B, C)
516 @end example
517
518 In your C code, you can extend the list of unary and binary functions,
519 and define recognized constants, so that they are available for your
520 expressions.
521
522 The evaluator also recognizes the International System unit prefixes.
523 If 'i' is appended after the prefix, binary prefixes are used, which
524 are based on powers of 1024 instead of powers of 1000.
525 The 'B' postfix multiplies the value by 8, and can be appended after a
526 unit prefix or used alone. This allows using for example 'KB', 'MiB',
527 'G' and 'B' as number postfix.
528
529 The list of available International System prefixes follows, with
530 indication of the corresponding powers of 10 and of 2.
531 @table @option
532 @item y
533 10^-24 / 2^-80
534 @item z
535 10^-21 / 2^-70
536 @item a
537 10^-18 / 2^-60
538 @item f
539 10^-15 / 2^-50
540 @item p
541 10^-12 / 2^-40
542 @item n
543 10^-9 / 2^-30
544 @item u
545 10^-6 / 2^-20
546 @item m
547 10^-3 / 2^-10
548 @item c
549 10^-2
550 @item d
551 10^-1
552 @item h
553 10^2
554 @item k
555 10^3 / 2^10
556 @item K
557 10^3 / 2^10
558 @item M
559 10^6 / 2^20
560 @item G
561 10^9 / 2^30
562 @item T
563 10^12 / 2^40
564 @item P
565 10^15 / 2^40
566 @item E
567 10^18 / 2^50
568 @item Z
569 10^21 / 2^60
570 @item Y
571 10^24 / 2^70
572 @end table
573
574 @c man end
575
576 @chapter OpenCL Options
577 @c man begin OPENCL OPTIONS
578
579 When FFmpeg is configured with @code{--enable-opencl}, it is possible
580 to set the options for the global OpenCL context.
581
582 The list of supported options follows:
583
584 @table @option
585 @item build_options
586 Set build options used to compile the registered kernels.
587
588 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
589
590 @item platform_idx
591 Select the index of the platform to run OpenCL code.
592
593 The specified index must be one of the indexes in the device list
594 which can be obtained with @code{av_opencl_get_device_list()}.
595
596 @item device_idx
597 Select the index of the device used to run OpenCL code.
598
599 The specifed index must be one of the indexes in the device list which
600 can be obtained with @code{av_opencl_get_device_list()}.
601
602 @end table
603
604 @c man end OPENCL OPTIONS