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 There are two accepted syntaxes for expressing time duration.
102 [-][@var{HH}:]@var{MM}:@var{SS}[.@var{m}...]
105 @var{HH} expresses the number of hours, @var{MM} the number of minutes
106 for a maximum of 2 digits, and @var{SS} the number of seconds for a
107 maximum of 2 digits. The @var{m} at the end expresses decimal value for
113 [-]@var{S}+[.@var{m}...]
116 @var{S} expresses the number of seconds, with the optional decimal part
119 In both expressions, the optional @samp{-} indicates negative duration.
123 The following examples are all valid time duration:
130 12 hours, 03 minutes and 45 seconds
136 @anchor{video size syntax}
138 Specify the size of the sourced video, it may be a string of the form
139 @var{width}x@var{height}, or the name of a size abbreviation.
141 The following abbreviations are recognized:
243 @anchor{video rate syntax}
246 Specify the frame rate of a video, expressed as the number of frames
247 generated per second. It has to be a string in the format
248 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
249 number or a valid video frame rate abbreviation.
251 The following abbreviations are recognized:
271 @anchor{ratio syntax}
274 A ratio can be expressed as an expression, or in the form
275 @var{numerator}:@var{denominator}.
277 Note that a ratio with infinite (1/0) or negative value is
278 considered valid, so you should check on the returned value if you
279 want to exclude those values.
281 The undefined value can be expressed using the "0:0" string.
283 @anchor{color syntax}
286 It can be the name of a color as defined below (case insensitive match) or a
287 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
288 representing the alpha component.
290 The alpha component may be a string composed by "0x" followed by an
291 hexadecimal number or a decimal number between 0.0 and 1.0, which
292 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
293 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
294 component is not specified then @samp{0xff} is assumed.
296 The string @samp{random} will result in a random color.
298 The following names of colors are recognized:
432 @item LightGoldenRodYellow
462 @item MediumAquaMarine
472 @item MediumSlateBlue
474 @item MediumSpringGreen
476 @item MediumTurquoise
478 @item MediumVioletRed
582 @anchor{channel layout syntax}
583 @section Channel Layout
585 A channel layout specifies the spatial disposition of the channels in
586 a multi-channel audio stream. To specify a channel layout, FFmpeg
587 makes use of a special syntax.
589 Individual channels are identified by an id, as given by the table
607 front right-of-center
639 surround direct right
644 Standard channel layout compositions can be specified by using the
645 following identifiers:
682 FL+FR+FC+LFE+BC+SL+SR
684 FL+FR+FC+LFE+BL+BR+BC
686 FL+FR+LFE+FLC+FRC+SL+SR
690 FL+FR+FC+FLC+FRC+SL+SR
692 FL+FR+FC+LFE+BL+BR+SL+SR
694 FL+FR+FC+LFE+BL+BR+FLC+FRC
696 FL+FR+FC+LFE+FLC+FRC+SL+SR
698 FL+FR+FC+BL+BR+BC+SL+SR
703 A custom channel layout can be specified as a sequence of terms, separated by
704 '+' or '|'. Each term can be:
707 the name of a standard channel layout (e.g. @samp{mono},
708 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
711 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
714 a number of channels, in decimal, optionally followed by 'c', yielding
715 the default channel layout for that number of channels (see the
716 function @code{av_get_default_channel_layout})
719 a channel layout mask, in hexadecimal starting with "0x" (see the
720 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
723 Starting from libavutil version 53 the trailing character "c" to
724 specify a number of channels will be required, while a channel layout
725 mask could also be specified as a decimal number (if and only if not
728 See also the function @code{av_get_channel_layout} defined in
729 @file{libavutil/channel_layout.h}.
732 @chapter Expression Evaluation
733 @c man begin EXPRESSION EVALUATION
735 When evaluating an arithmetic expression, FFmpeg uses an internal
736 formula evaluator, implemented through the @file{libavutil/eval.h}
739 An expression may contain unary, binary operators, constants, and
742 Two expressions @var{expr1} and @var{expr2} can be combined to form
743 another expression "@var{expr1};@var{expr2}".
744 @var{expr1} and @var{expr2} are evaluated in turn, and the new
745 expression evaluates to the value of @var{expr2}.
747 The following binary operators are available: @code{+}, @code{-},
748 @code{*}, @code{/}, @code{^}.
750 The following unary operators are available: @code{+}, @code{-}.
752 The following functions are available:
755 Compute absolute value of @var{x}.
758 Compute arccosine of @var{x}.
761 Compute arcsine of @var{x}.
764 Compute arctangent of @var{x}.
766 @item between(x, min, max)
767 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
768 equal to @var{max}, 0 otherwise.
772 Compute bitwise and/or operation on @var{x} and @var{y}.
774 The results of the evaluation of @var{x} and @var{y} are converted to
775 integers before executing the bitwise operation.
777 Note that both the conversion to integer and the conversion back to
778 floating point can lose precision. Beware of unexpected results for
779 large numbers (usually 2^53 and larger).
782 Round the value of expression @var{expr} upwards to the nearest
783 integer. For example, "ceil(1.5)" is "2.0".
786 Compute cosine of @var{x}.
789 Compute hyperbolic cosine of @var{x}.
792 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
795 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
798 Round the value of expression @var{expr} downwards to the nearest
799 integer. For example, "floor(-1.5)" is "-2.0".
802 Compute Gauss function of @var{x}, corresponding to
803 @code{exp(-x*x/2) / sqrt(2*PI)}.
806 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
807 @var{y} are 0 or either or both are less than zero then behavior is undefined.
810 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
813 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
816 This function is similar to the C function with the same name; it returns
817 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
818 right triangle with sides of length @var{x} and @var{y}, or the distance of the
819 point (@var{x}, @var{y}) from the origin.
822 Evaluate @var{x}, and if the result is non-zero return the result of
823 the evaluation of @var{y}, return 0 otherwise.
826 Evaluate @var{x}, and if the result is non-zero return the evaluation
827 result of @var{y}, otherwise the evaluation result of @var{z}.
830 Evaluate @var{x}, and if the result is zero return the result of the
831 evaluation of @var{y}, return 0 otherwise.
834 Evaluate @var{x}, and if the result is zero return the evaluation
835 result of @var{y}, otherwise the evaluation result of @var{z}.
838 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
841 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
844 Allow to load the value of the internal variable with number
845 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
846 The function returns the loaded value.
849 Compute natural logarithm of @var{x}.
852 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
855 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
858 Return the maximum between @var{x} and @var{y}.
861 Return the maximum between @var{x} and @var{y}.
864 Compute the remainder of division of @var{x} by @var{y}.
867 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
870 Compute the power of @var{x} elevated @var{y}, it is equivalent to
871 "(@var{x})^(@var{y})".
875 Print the value of expression @var{t} with loglevel @var{l}. If
876 @var{l} is not specified then a default log level is used.
877 Returns the value of the expression printed.
879 Prints t with loglevel l
882 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
883 internal variable which will be used to save the seed/state.
885 @item root(expr, max)
886 Find an input value for which the function represented by @var{expr}
887 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
889 The expression in @var{expr} must denote a continuous function or the
892 @var{ld(0)} is used to represent the function input value, which means
893 that the given expression will be evaluated multiple times with
894 various input values that the expression can access through
895 @code{ld(0)}. When the expression evaluates to 0 then the
896 corresponding input value will be returned.
899 Compute sine of @var{x}.
902 Compute hyperbolic sine of @var{x}.
905 Compute the square root of @var{expr}. This is equivalent to
909 Compute expression @code{1/(1 + exp(4*x))}.
912 Allow to store the value of the expression @var{expr} in an internal
913 variable. @var{var} specifies the number of the variable where to
914 store the value, and it is a value ranging from 0 to 9. The function
915 returns the value stored in the internal variable.
916 Note, Variables are currently not shared between expressions.
919 Compute tangent of @var{x}.
922 Compute hyperbolic tangent of @var{x}.
924 @item taylor(expr, x)
925 @item taylor(expr, x, id)
926 Evaluate a Taylor series at @var{x}, given an expression representing
927 the @code{ld(id)}-th derivative of a function at 0.
929 When the series does not converge the result is undefined.
931 @var{ld(id)} is used to represent the derivative order in @var{expr},
932 which means that the given expression will be evaluated multiple times
933 with various input values that the expression can access through
934 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
936 Note, when you have the derivatives at y instead of 0,
937 @code{taylor(expr, x-y)} can be used.
940 Return the current (wallclock) time in seconds.
943 Round the value of expression @var{expr} towards zero to the nearest
944 integer. For example, "trunc(-1.5)" is "-1.0".
946 @item while(cond, expr)
947 Evaluate expression @var{expr} while the expression @var{cond} is
948 non-zero, and returns the value of the last @var{expr} evaluation, or
949 NAN if @var{cond} was always false.
952 The following constants are available:
955 area of the unit disc, approximately 3.14
957 exp(1) (Euler's number), approximately 2.718
959 golden ratio (1+sqrt(5))/2, approximately 1.618
962 Assuming that an expression is considered "true" if it has a non-zero
965 @code{*} works like AND
967 @code{+} works like OR
969 For example the construct:
978 In your C code, you can extend the list of unary and binary functions,
979 and define recognized constants, so that they are available for your
982 The evaluator also recognizes the International System unit prefixes.
983 If 'i' is appended after the prefix, binary prefixes are used, which
984 are based on powers of 1024 instead of powers of 1000.
985 The 'B' postfix multiplies the value by 8, and can be appended after a
986 unit prefix or used alone. This allows using for example 'KB', 'MiB',
987 'G' and 'B' as number postfix.
989 The list of available International System prefixes follows, with
990 indication of the corresponding powers of 10 and of 2.
1034 @c man end EXPRESSION EVALUATION
1036 @chapter OpenCL Options
1037 @c man begin OPENCL OPTIONS
1039 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1040 to set the options for the global OpenCL context.
1042 The list of supported options follows:
1046 Set build options used to compile the registered kernels.
1048 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1051 Select the index of the platform to run OpenCL code.
1053 The specified index must be one of the indexes in the device list
1054 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1057 Select the index of the device used to run OpenCL code.
1059 The specified index must be one of the indexes in the device list which
1060 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1064 @c man end OPENCL OPTIONS