4 This section documents the syntax and formats employed by the FFmpeg
7 @anchor{quoting_and_escaping}
8 @section Quoting and escaping
10 FFmpeg adopts the following quoting and escaping mechanism, unless
11 explicitly specified. The following rules are applied:
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.
21 A special character is escaped by prefixing it with a '\'.
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.
29 Leading and trailing whitespaces, unless escaped or quoted, are
30 removed from the parsed string.
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.
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.
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.
48 Escape the string @code{Crime d'Amour} containing the @code{'} special
55 The string above contains a quote, so the @code{'} needs to be escaped
62 Include leading or trailing whitespaces using quoting:
64 ' this string starts and ends with whitespaces '
68 Escaping and quoting can be mixed together:
70 ' The string '\'string\'' is a string '
74 To include a literal @code{\} you can use either escaping or quoting:
76 'c:\foo' can be written as c:\\foo
83 The accepted syntax is:
85 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
89 If the value is "now" it takes the current time.
91 Time is local time unless Z is appended, in which case it is
93 If the year-month-day part is not specified it takes the current
96 @anchor{time duration syntax}
97 @section Time duration
99 The accepted syntax is:
105 @var{HH} expresses the number of hours, @var{MM} the number a of minutes
106 and @var{SS} the number of seconds.
108 @anchor{video size syntax}
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.
113 The following abbreviations are recognized:
203 @anchor{video rate syntax}
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.
211 The following abbreviations are recognized:
231 @anchor{ratio syntax}
234 A ratio can be expressed as an expression, or in the form
235 @var{numerator}:@var{denominator}.
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.
241 The undefined value can be expressed using the "0:0" string.
243 @anchor{color syntax}
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.
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.
256 The string "random" will result in a random color.
260 @chapter Expression Evaluation
261 @c man begin EXPRESSION EVALUATION
263 When evaluating an arithmetic expression, FFmpeg uses an internal
264 formula evaluator, implemented through the @file{libavutil/eval.h}
267 An expression may contain unary, binary operators, constants, and
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}.
275 The following binary operators are available: @code{+}, @code{-},
276 @code{*}, @code{/}, @code{^}.
278 The following unary operators are available: @code{+}, @code{-}.
280 The following functions are available:
283 Compute absolute value of @var{x}.
286 Compute arccosine of @var{x}.
289 Compute arcsine of @var{x}.
292 Compute arctangent of @var{x}.
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.
300 Compute bitwise and/or operation on @var{x} and @var{y}.
302 The results of the evaluation of @var{x} and @var{y} are converted to
303 integers before executing the bitwise operation.
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).
310 Round the value of expression @var{expr} upwards to the nearest
311 integer. For example, "ceil(1.5)" is "2.0".
314 Compute cosine of @var{x}.
317 Compute hyperbolic cosine of @var{x}.
320 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
323 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
326 Round the value of expression @var{expr} downwards to the nearest
327 integer. For example, "floor(-1.5)" is "-2.0".
330 Compute Gauss function of @var{x}, corresponding to
331 @code{exp(-x*x/2) / sqrt(2*PI)}.
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.
338 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
341 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
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.
350 Evaluate @var{x}, and if the result is non-zero return the result of
351 the evaluation of @var{y}, return 0 otherwise.
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}.
358 Evaluate @var{x}, and if the result is zero return the result of the
359 evaluation of @var{y}, return 0 otherwise.
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}.
366 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
369 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
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.
377 Compute natural logarithm of @var{x}.
380 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
383 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
386 Return the maximum between @var{x} and @var{y}.
389 Return the maximum between @var{x} and @var{y}.
392 Compute the remainder of division of @var{x} by @var{y}.
395 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
398 Compute the power of @var{x} elevated @var{y}, it is equivalent to
399 "(@var{x})^(@var{y})".
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.
407 Prints t with loglevel l
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.
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}.
417 The expression in @var{expr} must denote a continuous function or the
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.
427 Compute sine of @var{x}.
430 Compute hyperbolic sine of @var{x}.
433 Compute the square root of @var{expr}. This is equivalent to
437 Compute expression @code{1/(1 + exp(4*x))}.
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.
447 Compute tangent of @var{x}.
450 Compute hyperbolic tangent of @var{x}.
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.
457 When the series does not converge the result is undefined.
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.
464 Note, when you have the derivatives at y instead of 0,
465 @code{taylor(expr, x-y)} can be used.
468 Return the current (wallclock) time in seconds.
471 Round the value of expression @var{expr} towards zero to the nearest
472 integer. For example, "trunc(-1.5)" is "-1.0".
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.
480 The following constants are available:
483 area of the unit disc, approximately 3.14
485 exp(1) (Euler's number), approximately 2.718
487 golden ratio (1+sqrt(5))/2, approximately 1.618
490 Assuming that an expression is considered "true" if it has a non-zero
493 @code{*} works like AND
495 @code{+} works like OR
497 For example the construct:
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
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.
517 The list of available International System prefixes follows, with
518 indication of the corresponding powers of 10 and of 2.
564 @chapter OpenCL Options
565 @c man begin OPENCL OPTIONS
567 When FFmpeg is configured with @code{--enable-opencl}, it is possible
568 to set the options for the global OpenCL context.
570 The list of supported options follows:
574 Set build options used to compile the registered kernels.
576 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
579 Select the index of the platform to run OpenCL code.
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()}.
585 Select the index of the device used to run OpenCL code.
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()}.
592 @c man end OPENCL OPTIONS