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