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".
785 @item clip(x, min, max)
786 Return the value of @var{x} clipped between @var{min} and @var{max}.
789 Compute cosine of @var{x}.
792 Compute hyperbolic cosine of @var{x}.
795 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
798 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
801 Round the value of expression @var{expr} downwards to the nearest
802 integer. For example, "floor(-1.5)" is "-2.0".
805 Compute Gauss function of @var{x}, corresponding to
806 @code{exp(-x*x/2) / sqrt(2*PI)}.
809 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
810 @var{y} are 0 or either or both are less than zero then behavior is undefined.
813 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
816 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
819 This function is similar to the C function with the same name; it returns
820 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
821 right triangle with sides of length @var{x} and @var{y}, or the distance of the
822 point (@var{x}, @var{y}) from the origin.
825 Evaluate @var{x}, and if the result is non-zero return the result of
826 the evaluation of @var{y}, return 0 otherwise.
829 Evaluate @var{x}, and if the result is non-zero return the evaluation
830 result of @var{y}, otherwise the evaluation result of @var{z}.
833 Evaluate @var{x}, and if the result is zero return the result of the
834 evaluation of @var{y}, return 0 otherwise.
837 Evaluate @var{x}, and if the result is zero return the evaluation
838 result of @var{y}, otherwise the evaluation result of @var{z}.
841 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
844 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
847 Allow to load the value of the internal variable with number
848 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
849 The function returns the loaded value.
852 Compute natural logarithm of @var{x}.
855 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
858 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
861 Return the maximum between @var{x} and @var{y}.
864 Return the maximum between @var{x} and @var{y}.
867 Compute the remainder of division of @var{x} by @var{y}.
870 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
873 Compute the power of @var{x} elevated @var{y}, it is equivalent to
874 "(@var{x})^(@var{y})".
878 Print the value of expression @var{t} with loglevel @var{l}. If
879 @var{l} is not specified then a default log level is used.
880 Returns the value of the expression printed.
882 Prints t with loglevel l
885 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
886 internal variable which will be used to save the seed/state.
888 @item root(expr, max)
889 Find an input value for which the function represented by @var{expr}
890 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
892 The expression in @var{expr} must denote a continuous function or the
895 @var{ld(0)} is used to represent the function input value, which means
896 that the given expression will be evaluated multiple times with
897 various input values that the expression can access through
898 @code{ld(0)}. When the expression evaluates to 0 then the
899 corresponding input value will be returned.
902 Compute sine of @var{x}.
905 Compute hyperbolic sine of @var{x}.
908 Compute the square root of @var{expr}. This is equivalent to
912 Compute expression @code{1/(1 + exp(4*x))}.
915 Allow to store the value of the expression @var{expr} in an internal
916 variable. @var{var} specifies the number of the variable where to
917 store the value, and it is a value ranging from 0 to 9. The function
918 returns the value stored in the internal variable.
919 Note, Variables are currently not shared between expressions.
922 Compute tangent of @var{x}.
925 Compute hyperbolic tangent of @var{x}.
927 @item taylor(expr, x)
928 @item taylor(expr, x, id)
929 Evaluate a Taylor series at @var{x}, given an expression representing
930 the @code{ld(id)}-th derivative of a function at 0.
932 When the series does not converge the result is undefined.
934 @var{ld(id)} is used to represent the derivative order in @var{expr},
935 which means that the given expression will be evaluated multiple times
936 with various input values that the expression can access through
937 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
939 Note, when you have the derivatives at y instead of 0,
940 @code{taylor(expr, x-y)} can be used.
943 Return the current (wallclock) time in seconds.
946 Round the value of expression @var{expr} towards zero to the nearest
947 integer. For example, "trunc(-1.5)" is "-1.0".
949 @item while(cond, expr)
950 Evaluate expression @var{expr} while the expression @var{cond} is
951 non-zero, and returns the value of the last @var{expr} evaluation, or
952 NAN if @var{cond} was always false.
955 The following constants are available:
958 area of the unit disc, approximately 3.14
960 exp(1) (Euler's number), approximately 2.718
962 golden ratio (1+sqrt(5))/2, approximately 1.618
965 Assuming that an expression is considered "true" if it has a non-zero
968 @code{*} works like AND
970 @code{+} works like OR
972 For example the construct:
981 In your C code, you can extend the list of unary and binary functions,
982 and define recognized constants, so that they are available for your
985 The evaluator also recognizes the International System unit prefixes.
986 If 'i' is appended after the prefix, binary prefixes are used, which
987 are based on powers of 1024 instead of powers of 1000.
988 The 'B' postfix multiplies the value by 8, and can be appended after a
989 unit prefix or used alone. This allows using for example 'KB', 'MiB',
990 'G' and 'B' as number postfix.
992 The list of available International System prefixes follows, with
993 indication of the corresponding powers of 10 and of 2.
1037 @c man end EXPRESSION EVALUATION
1039 @chapter OpenCL Options
1040 @c man begin OPENCL OPTIONS
1042 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1043 to set the options for the global OpenCL context.
1045 The list of supported options follows:
1049 Set build options used to compile the registered kernels.
1051 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1054 Select the index of the platform to run OpenCL code.
1056 The specified index must be one of the indexes in the device list
1057 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1060 Select the index of the device used to run OpenCL code.
1062 The specified index must be one of the indexes in the device list which
1063 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1067 @c man end OPENCL OPTIONS