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