yading@10: @chapter Syntax
yading@10: @c man begin SYNTAX
yading@10: 
yading@10: This section documents the syntax and formats employed by the FFmpeg
yading@10: libraries and tools.
yading@10: 
yading@10: @anchor{quoting_and_escaping}
yading@10: @section Quoting and escaping
yading@10: 
yading@10: FFmpeg adopts the following quoting and escaping mechanism, unless
yading@10: explicitly specified. The following rules are applied:
yading@10: 
yading@10: @itemize
yading@10: @item
yading@10: @code{'} and @code{\} are special characters (respectively used for
yading@10: quoting and escaping). In addition to them, there might be other
yading@10: special characters depending on the specific syntax where the escaping
yading@10: and quoting are employed.
yading@10: 
yading@10: @item
yading@10: A special character is escaped by prefixing it with a '\'.
yading@10: 
yading@10: @item
yading@10: All characters enclosed between '' are included literally in the
yading@10: parsed string. The quote character @code{'} itself cannot be quoted,
yading@10: so you may need to close the quote and escape it.
yading@10: 
yading@10: @item
yading@10: Leading and trailing whitespaces, unless escaped or quoted, are
yading@10: removed from the parsed string.
yading@10: @end itemize
yading@10: 
yading@10: Note that you may need to add a second level of escaping when using
yading@10: the command line or a script, which depends on the syntax of the
yading@10: adopted shell language.
yading@10: 
yading@10: The function @code{av_get_token} defined in
yading@10: @file{libavutil/avstring.h} can be used to parse a token quoted or
yading@10: escaped according to the rules defined above.
yading@10: 
yading@10: The tool @file{tools/ffescape} in the FFmpeg source tree can be used
yading@10: to automatically quote or escape a string in a script.
yading@10: 
yading@10: @subsection Examples
yading@10: 
yading@10: @itemize
yading@10: @item
yading@10: Escape the string @code{Crime d'Amour} containing the @code{'} special
yading@10: character:
yading@10: @example
yading@10: Crime d\'Amour
yading@10: @end example
yading@10: 
yading@10: @item
yading@10: The string above contains a quote, so the @code{'} needs to be escaped
yading@10: when quoting it:
yading@10: @example
yading@10: 'Crime d'\''Amour'
yading@10: @end example
yading@10: 
yading@10: @item
yading@10: Include leading or trailing whitespaces using quoting:
yading@10: @example
yading@10: '  this string starts and ends with whitespaces  '
yading@10: @end example
yading@10: 
yading@10: @item
yading@10: Escaping and quoting can be mixed together:
yading@10: @example
yading@10: ' The string '\'string\'' is a string '
yading@10: @end example
yading@10: 
yading@10: @item
yading@10: To include a literal @code{\} you can use either escaping or quoting:
yading@10: @example
yading@10: 'c:\foo' can be written as c:\\foo
yading@10: @end example
yading@10: @end itemize
yading@10: 
yading@10: @anchor{date syntax}
yading@10: @section Date
yading@10: 
yading@10: The accepted syntax is:
yading@10: @example
yading@10: [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
yading@10: now
yading@10: @end example
yading@10: 
yading@10: If the value is "now" it takes the current time.
yading@10: 
yading@10: Time is local time unless Z is appended, in which case it is
yading@10: interpreted as UTC.
yading@10: If the year-month-day part is not specified it takes the current
yading@10: year-month-day.
yading@10: 
yading@10: @anchor{time duration syntax}
yading@10: @section Time duration
yading@10: 
yading@10: The accepted syntax is:
yading@10: @example
yading@10: [-][HH:]MM:SS[.m...]
yading@10: [-]S+[.m...]
yading@10: @end example
yading@10: 
yading@10: @var{HH} expresses the number of hours, @var{MM} the number a of minutes
yading@10: and @var{SS} the number of seconds.
yading@10: 
yading@10: @anchor{video size syntax}
yading@10: @section Video size
yading@10: Specify the size of the sourced video, it may be a string of the form
yading@10: @var{width}x@var{height}, or the name of a size abbreviation.
yading@10: 
yading@10: The following abbreviations are recognized:
yading@10: @table @samp
yading@10: @item ntsc
yading@10: 720x480
yading@10: @item pal
yading@10: 720x576
yading@10: @item qntsc
yading@10: 352x240
yading@10: @item qpal
yading@10: 352x288
yading@10: @item sntsc
yading@10: 640x480
yading@10: @item spal
yading@10: 768x576
yading@10: @item film
yading@10: 352x240
yading@10: @item ntsc-film
yading@10: 352x240
yading@10: @item sqcif
yading@10: 128x96
yading@10: @item qcif
yading@10: 176x144
yading@10: @item cif
yading@10: 352x288
yading@10: @item 4cif
yading@10: 704x576
yading@10: @item 16cif
yading@10: 1408x1152
yading@10: @item qqvga
yading@10: 160x120
yading@10: @item qvga
yading@10: 320x240
yading@10: @item vga
yading@10: 640x480
yading@10: @item svga
yading@10: 800x600
yading@10: @item xga
yading@10: 1024x768
yading@10: @item uxga
yading@10: 1600x1200
yading@10: @item qxga
yading@10: 2048x1536
yading@10: @item sxga
yading@10: 1280x1024
yading@10: @item qsxga
yading@10: 2560x2048
yading@10: @item hsxga
yading@10: 5120x4096
yading@10: @item wvga
yading@10: 852x480
yading@10: @item wxga
yading@10: 1366x768
yading@10: @item wsxga
yading@10: 1600x1024
yading@10: @item wuxga
yading@10: 1920x1200
yading@10: @item woxga
yading@10: 2560x1600
yading@10: @item wqsxga
yading@10: 3200x2048
yading@10: @item wquxga
yading@10: 3840x2400
yading@10: @item whsxga
yading@10: 6400x4096
yading@10: @item whuxga
yading@10: 7680x4800
yading@10: @item cga
yading@10: 320x200
yading@10: @item ega
yading@10: 640x350
yading@10: @item hd480
yading@10: 852x480
yading@10: @item hd720
yading@10: 1280x720
yading@10: @item hd1080
yading@10: 1920x1080
yading@10: @item 2k
yading@10: 2048x1080
yading@10: @item 2kflat
yading@10: 1998x1080
yading@10: @item 2kscope
yading@10: 2048x858
yading@10: @item 4k
yading@10: 4096x2160
yading@10: @item 4kflat
yading@10: 3996x2160
yading@10: @item 4kscope
yading@10: 4096x1716
yading@10: @end table
yading@10: 
yading@10: @anchor{video rate syntax}
yading@10: @section Video rate
yading@10: 
yading@10: Specify the frame rate of a video, expressed as the number of frames
yading@10: generated per second. It has to be a string in the format
yading@10: @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
yading@10: number or a valid video frame rate abbreviation.
yading@10: 
yading@10: The following abbreviations are recognized:
yading@10: @table @samp
yading@10: @item ntsc
yading@10: 30000/1001
yading@10: @item pal
yading@10: 25/1
yading@10: @item qntsc
yading@10: 30000/1001
yading@10: @item qpal
yading@10: 25/1
yading@10: @item sntsc
yading@10: 30000/1001
yading@10: @item spal
yading@10: 25/1
yading@10: @item film
yading@10: 24/1
yading@10: @item ntsc-film
yading@10: 24000/1001
yading@10: @end table
yading@10: 
yading@10: @anchor{ratio syntax}
yading@10: @section Ratio
yading@10: 
yading@10: A ratio can be expressed as an expression, or in the form
yading@10: @var{numerator}:@var{denominator}.
yading@10: 
yading@10: Note that a ratio with infinite (1/0) or negative value is
yading@10: considered valid, so you should check on the returned value if you
yading@10: want to exclude those values.
yading@10: 
yading@10: The undefined value can be expressed using the "0:0" string.
yading@10: 
yading@10: @anchor{color syntax}
yading@10: @section Color
yading@10: 
yading@10: It can be the name of a color (case insensitive match) or a
yading@10: [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
yading@10: representing the alpha component.
yading@10: 
yading@10: The alpha component may be a string composed by "0x" followed by an
yading@10: hexadecimal number or a decimal number between 0.0 and 1.0, which
yading@10: represents the opacity value (0x00/0.0 means completely transparent,
yading@10: 0xff/1.0 completely opaque).
yading@10: If the alpha component is not specified then 0xff is assumed.
yading@10: 
yading@10: The string "random" will result in a random color.
yading@10: 
yading@10: @c man end SYNTAX
yading@10: 
yading@10: @chapter Expression Evaluation
yading@10: @c man begin EXPRESSION EVALUATION
yading@10: 
yading@10: When evaluating an arithmetic expression, FFmpeg uses an internal
yading@10: formula evaluator, implemented through the @file{libavutil/eval.h}
yading@10: interface.
yading@10: 
yading@10: An expression may contain unary, binary operators, constants, and
yading@10: functions.
yading@10: 
yading@10: Two expressions @var{expr1} and @var{expr2} can be combined to form
yading@10: another expression "@var{expr1};@var{expr2}".
yading@10: @var{expr1} and @var{expr2} are evaluated in turn, and the new
yading@10: expression evaluates to the value of @var{expr2}.
yading@10: 
yading@10: The following binary operators are available: @code{+}, @code{-},
yading@10: @code{*}, @code{/}, @code{^}.
yading@10: 
yading@10: The following unary operators are available: @code{+}, @code{-}.
yading@10: 
yading@10: The following functions are available:
yading@10: @table @option
yading@10: @item abs(x)
yading@10: Compute absolute value of @var{x}.
yading@10: 
yading@10: @item acos(x)
yading@10: Compute arccosine of @var{x}.
yading@10: 
yading@10: @item asin(x)
yading@10: Compute arcsine of @var{x}.
yading@10: 
yading@10: @item atan(x)
yading@10: Compute arctangent of @var{x}.
yading@10: 
yading@10: @item between(x, min, max)
yading@10: Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
yading@10: equal to @var{max}, 0 otherwise.
yading@10: 
yading@10: @item bitand(x, y)
yading@10: @item bitor(x, y)
yading@10: Compute bitwise and/or operation on @var{x} and @var{y}.
yading@10: 
yading@10: The results of the evaluation of @var{x} and @var{y} are converted to
yading@10: integers before executing the bitwise operation.
yading@10: 
yading@10: Note that both the conversion to integer and the conversion back to
yading@10: floating point can lose precision. Beware of unexpected results for
yading@10: large numbers (usually 2^53 and larger).
yading@10: 
yading@10: @item ceil(expr)
yading@10: Round the value of expression @var{expr} upwards to the nearest
yading@10: integer. For example, "ceil(1.5)" is "2.0".
yading@10: 
yading@10: @item cos(x)
yading@10: Compute cosine of @var{x}.
yading@10: 
yading@10: @item cosh(x)
yading@10: Compute hyperbolic cosine of @var{x}.
yading@10: 
yading@10: @item eq(x, y)
yading@10: Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
yading@10: 
yading@10: @item exp(x)
yading@10: Compute exponential of @var{x} (with base @code{e}, the Euler's number).
yading@10: 
yading@10: @item floor(expr)
yading@10: Round the value of expression @var{expr} downwards to the nearest
yading@10: integer. For example, "floor(-1.5)" is "-2.0".
yading@10: 
yading@10: @item gauss(x)
yading@10: Compute Gauss function of @var{x}, corresponding to
yading@10: @code{exp(-x*x/2) / sqrt(2*PI)}.
yading@10: 
yading@10: @item gcd(x, y)
yading@10: Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
yading@10: @var{y} are 0 or either or both are less than zero then behavior is undefined.
yading@10: 
yading@10: @item gt(x, y)
yading@10: Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
yading@10: 
yading@10: @item gte(x, y)
yading@10: Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
yading@10: 
yading@10: @item hypot(x, y)
yading@10: This function is similar to the C function with the same name; it returns
yading@10: "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
yading@10: right triangle with sides of length @var{x} and @var{y}, or the distance of the
yading@10: point (@var{x}, @var{y}) from the origin.
yading@10: 
yading@10: @item if(x, y)
yading@10: Evaluate @var{x}, and if the result is non-zero return the result of
yading@10: the evaluation of @var{y}, return 0 otherwise.
yading@10: 
yading@10: @item if(x, y, z)
yading@10: Evaluate @var{x}, and if the result is non-zero return the evaluation
yading@10: result of @var{y}, otherwise the evaluation result of @var{z}.
yading@10: 
yading@10: @item ifnot(x, y)
yading@10: Evaluate @var{x}, and if the result is zero return the result of the
yading@10: evaluation of @var{y}, return 0 otherwise.
yading@10: 
yading@10: @item ifnot(x, y, z)
yading@10: Evaluate @var{x}, and if the result is zero return the evaluation
yading@10: result of @var{y}, otherwise the evaluation result of @var{z}.
yading@10: 
yading@10: @item isinf(x)
yading@10: Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
yading@10: 
yading@10: @item isnan(x)
yading@10: Return 1.0 if @var{x} is NAN, 0.0 otherwise.
yading@10: 
yading@10: @item ld(var)
yading@10: Allow to load the value of the internal variable with number
yading@10: @var{var}, which was previously stored with st(@var{var}, @var{expr}).
yading@10: The function returns the loaded value.
yading@10: 
yading@10: @item log(x)
yading@10: Compute natural logarithm of @var{x}.
yading@10: 
yading@10: @item lt(x, y)
yading@10: Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
yading@10: 
yading@10: @item lte(x, y)
yading@10: Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
yading@10: 
yading@10: @item max(x, y)
yading@10: Return the maximum between @var{x} and @var{y}.
yading@10: 
yading@10: @item min(x, y)
yading@10: Return the maximum between @var{x} and @var{y}.
yading@10: 
yading@10: @item mod(x, y)
yading@10: Compute the remainder of division of @var{x} by @var{y}.
yading@10: 
yading@10: @item not(expr)
yading@10: Return 1.0 if @var{expr} is zero, 0.0 otherwise.
yading@10: 
yading@10: @item pow(x, y)
yading@10: Compute the power of @var{x} elevated @var{y}, it is equivalent to
yading@10: "(@var{x})^(@var{y})".
yading@10: 
yading@10: @item print(t)
yading@10: @item print(t, l)
yading@10: Print the value of expression @var{t} with loglevel @var{l}. If
yading@10: @var{l} is not specified then a default log level is used.
yading@10: Returns the value of the expression printed.
yading@10: 
yading@10: Prints t with loglevel l
yading@10: 
yading@10: @item random(x)
yading@10: Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
yading@10: internal variable which will be used to save the seed/state.
yading@10: 
yading@10: @item root(expr, max)
yading@10: Find an input value for which the function represented by @var{expr}
yading@10: with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
yading@10: 
yading@10: The expression in @var{expr} must denote a continuous function or the
yading@10: result is undefined.
yading@10: 
yading@10: @var{ld(0)} is used to represent the function input value, which means
yading@10: that the given expression will be evaluated multiple times with
yading@10: various input values that the expression can access through
yading@10: @code{ld(0)}. When the expression evaluates to 0 then the
yading@10: corresponding input value will be returned.
yading@10: 
yading@10: @item sin(x)
yading@10: Compute sine of @var{x}.
yading@10: 
yading@10: @item sinh(x)
yading@10: Compute hyperbolic sine of @var{x}.
yading@10: 
yading@10: @item sqrt(expr)
yading@10: Compute the square root of @var{expr}. This is equivalent to
yading@10: "(@var{expr})^.5".
yading@10: 
yading@10: @item squish(x)
yading@10: Compute expression @code{1/(1 + exp(4*x))}.
yading@10: 
yading@10: @item st(var, expr)
yading@10: Allow to store the value of the expression @var{expr} in an internal
yading@10: variable. @var{var} specifies the number of the variable where to
yading@10: store the value, and it is a value ranging from 0 to 9. The function
yading@10: returns the value stored in the internal variable.
yading@10: Note, Variables are currently not shared between expressions.
yading@10: 
yading@10: @item tan(x)
yading@10: Compute tangent of @var{x}.
yading@10: 
yading@10: @item tanh(x)
yading@10: Compute hyperbolic tangent of @var{x}.
yading@10: 
yading@10: @item taylor(expr, x)
yading@10: @item taylor(expr, x, id)
yading@10: Evaluate a Taylor series at @var{x}, given an expression representing
yading@10: the @code{ld(id)}-th derivative of a function at 0.
yading@10: 
yading@10: When the series does not converge the result is undefined.
yading@10: 
yading@10: @var{ld(id)} is used to represent the derivative order in @var{expr},
yading@10: which means that the given expression will be evaluated multiple times
yading@10: with various input values that the expression can access through
yading@10: @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
yading@10: 
yading@10: Note, when you have the derivatives at y instead of 0,
yading@10: @code{taylor(expr, x-y)} can be used.
yading@10: 
yading@10: @item time(0)
yading@10: Return the current (wallclock) time in seconds.
yading@10: 
yading@10: @item trunc(expr)
yading@10: Round the value of expression @var{expr} towards zero to the nearest
yading@10: integer. For example, "trunc(-1.5)" is "-1.0".
yading@10: 
yading@10: @item while(cond, expr)
yading@10: Evaluate expression @var{expr} while the expression @var{cond} is
yading@10: non-zero, and returns the value of the last @var{expr} evaluation, or
yading@10: NAN if @var{cond} was always false.
yading@10: @end table
yading@10: 
yading@10: The following constants are available:
yading@10: @table @option
yading@10: @item PI
yading@10: area of the unit disc, approximately 3.14
yading@10: @item E
yading@10: exp(1) (Euler's number), approximately 2.718
yading@10: @item PHI
yading@10: golden ratio (1+sqrt(5))/2, approximately 1.618
yading@10: @end table
yading@10: 
yading@10: Assuming that an expression is considered "true" if it has a non-zero
yading@10: value, note that:
yading@10: 
yading@10: @code{*} works like AND
yading@10: 
yading@10: @code{+} works like OR
yading@10: 
yading@10: For example the construct:
yading@10: @example
yading@10: if (A AND B) then C
yading@10: @end example
yading@10: is equivalent to:
yading@10: @example
yading@10: if(A*B, C)
yading@10: @end example
yading@10: 
yading@10: In your C code, you can extend the list of unary and binary functions,
yading@10: and define recognized constants, so that they are available for your
yading@10: expressions.
yading@10: 
yading@10: The evaluator also recognizes the International System unit prefixes.
yading@10: If 'i' is appended after the prefix, binary prefixes are used, which
yading@10: are based on powers of 1024 instead of powers of 1000.
yading@10: The 'B' postfix multiplies the value by 8, and can be appended after a
yading@10: unit prefix or used alone. This allows using for example 'KB', 'MiB',
yading@10: 'G' and 'B' as number postfix.
yading@10: 
yading@10: The list of available International System prefixes follows, with
yading@10: indication of the corresponding powers of 10 and of 2.
yading@10: @table @option
yading@10: @item y
yading@10: 10^-24 / 2^-80
yading@10: @item z
yading@10: 10^-21 / 2^-70
yading@10: @item a
yading@10: 10^-18 / 2^-60
yading@10: @item f
yading@10: 10^-15 / 2^-50
yading@10: @item p
yading@10: 10^-12 / 2^-40
yading@10: @item n
yading@10: 10^-9 / 2^-30
yading@10: @item u
yading@10: 10^-6 / 2^-20
yading@10: @item m
yading@10: 10^-3 / 2^-10
yading@10: @item c
yading@10: 10^-2
yading@10: @item d
yading@10: 10^-1
yading@10: @item h
yading@10: 10^2
yading@10: @item k
yading@10: 10^3 / 2^10
yading@10: @item K
yading@10: 10^3 / 2^10
yading@10: @item M
yading@10: 10^6 / 2^20
yading@10: @item G
yading@10: 10^9 / 2^30
yading@10: @item T
yading@10: 10^12 / 2^40
yading@10: @item P
yading@10: 10^15 / 2^40
yading@10: @item E
yading@10: 10^18 / 2^50
yading@10: @item Z
yading@10: 10^21 / 2^60
yading@10: @item Y
yading@10: 10^24 / 2^70
yading@10: @end table
yading@10: 
yading@10: @c man end
yading@10: 
yading@10: @chapter OpenCL Options
yading@10: @c man begin OPENCL OPTIONS
yading@10: 
yading@10: When FFmpeg is configured with @code{--enable-opencl}, it is possible
yading@10: to set the options for the global OpenCL context.
yading@10: 
yading@10: The list of supported options follows:
yading@10: 
yading@10: @table @option
yading@10: @item build_options
yading@10: Set build options used to compile the registered kernels.
yading@10: 
yading@10: See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
yading@10: 
yading@10: @item platform_idx
yading@10: Select the index of the platform to run OpenCL code.
yading@10: 
yading@10: The specified index must be one of the indexes in the device list
yading@10: which can be obtained with @code{av_opencl_get_device_list()}.
yading@10: 
yading@10: @item device_idx
yading@10: Select the index of the device used to run OpenCL code.
yading@10: 
yading@10: The specifed index must be one of the indexes in the device list which
yading@10: can be obtained with @code{av_opencl_get_device_list()}.
yading@10: 
yading@10: @end table
yading@10: 
yading@10: @c man end OPENCL OPTIONS