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 @samp{'} and @samp{\} 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 @samp{\}.
24 All characters enclosed between @samp{''} are included literally in the
25 parsed string. The quote character @samp{'} 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 @samp{\} 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:
251 @anchor{video rate syntax}
254 Specify the frame rate of a video, expressed as the number of frames
255 generated per second. It has to be a string in the format
256 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
257 number or a valid video frame rate abbreviation.
259 The following abbreviations are recognized:
279 @anchor{ratio syntax}
282 A ratio can be expressed as an expression, or in the form
283 @var{numerator}:@var{denominator}.
285 Note that a ratio with infinite (1/0) or negative value is
286 considered valid, so you should check on the returned value if you
287 want to exclude those values.
289 The undefined value can be expressed using the "0:0" string.
291 @anchor{color syntax}
294 It can be the name of a color as defined below (case insensitive match) or a
295 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
296 representing the alpha component.
298 The alpha component may be a string composed by "0x" followed by an
299 hexadecimal number or a decimal number between 0.0 and 1.0, which
300 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
301 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
302 component is not specified then @samp{0xff} is assumed.
304 The string @samp{random} will result in a random color.
306 The following names of colors are recognized:
440 @item LightGoldenRodYellow
470 @item MediumAquaMarine
480 @item MediumSlateBlue
482 @item MediumSpringGreen
484 @item MediumTurquoise
486 @item MediumVioletRed
590 @anchor{channel layout syntax}
591 @section Channel Layout
593 A channel layout specifies the spatial disposition of the channels in
594 a multi-channel audio stream. To specify a channel layout, FFmpeg
595 makes use of a special syntax.
597 Individual channels are identified by an id, as given by the table
615 front right-of-center
647 surround direct right
652 Standard channel layout compositions can be specified by using the
653 following identifiers:
690 FL+FR+FC+LFE+BC+SL+SR
692 FL+FR+FC+LFE+BL+BR+BC
694 FL+FR+LFE+FLC+FRC+SL+SR
698 FL+FR+FC+FLC+FRC+SL+SR
700 FL+FR+FC+LFE+BL+BR+SL+SR
702 FL+FR+FC+LFE+BL+BR+FLC+FRC
704 FL+FR+FC+LFE+FLC+FRC+SL+SR
706 FL+FR+FC+BL+BR+BC+SL+SR
711 A custom channel layout can be specified as a sequence of terms, separated by
712 '+' or '|'. Each term can be:
715 the name of a standard channel layout (e.g. @samp{mono},
716 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
719 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
722 a number of channels, in decimal, followed by 'c', yielding the default channel
723 layout for that number of channels (see the function
724 @code{av_get_default_channel_layout}). Note that not all channel counts have a
728 a number of channels, in decimal, followed by 'C', yielding an unknown channel
729 layout with the specified number of channels. Note that not all channel layout
730 specification strings support unknown channel layouts.
733 a channel layout mask, in hexadecimal starting with "0x" (see the
734 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
737 Before libavutil version 53 the trailing character "c" to specify a number of
738 channels was optional, but now it is required, while a channel layout mask can
739 also be specified as a decimal number (if and only if not followed by "c" or "C").
741 See also the function @code{av_get_channel_layout} defined in
742 @file{libavutil/channel_layout.h}.
745 @chapter Expression Evaluation
746 @c man begin EXPRESSION EVALUATION
748 When evaluating an arithmetic expression, FFmpeg uses an internal
749 formula evaluator, implemented through the @file{libavutil/eval.h}
752 An expression may contain unary, binary operators, constants, and
755 Two expressions @var{expr1} and @var{expr2} can be combined to form
756 another expression "@var{expr1};@var{expr2}".
757 @var{expr1} and @var{expr2} are evaluated in turn, and the new
758 expression evaluates to the value of @var{expr2}.
760 The following binary operators are available: @code{+}, @code{-},
761 @code{*}, @code{/}, @code{^}.
763 The following unary operators are available: @code{+}, @code{-}.
765 The following functions are available:
768 Compute absolute value of @var{x}.
771 Compute arccosine of @var{x}.
774 Compute arcsine of @var{x}.
777 Compute arctangent of @var{x}.
780 Compute principal value of the arc tangent of @var{y}/@var{x}.
782 @item between(x, min, max)
783 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
784 equal to @var{max}, 0 otherwise.
788 Compute bitwise and/or operation on @var{x} and @var{y}.
790 The results of the evaluation of @var{x} and @var{y} are converted to
791 integers before executing the bitwise operation.
793 Note that both the conversion to integer and the conversion back to
794 floating point can lose precision. Beware of unexpected results for
795 large numbers (usually 2^53 and larger).
798 Round the value of expression @var{expr} upwards to the nearest
799 integer. For example, "ceil(1.5)" is "2.0".
801 @item clip(x, min, max)
802 Return the value of @var{x} clipped between @var{min} and @var{max}.
805 Compute cosine of @var{x}.
808 Compute hyperbolic cosine of @var{x}.
811 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
814 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
817 Round the value of expression @var{expr} downwards to the nearest
818 integer. For example, "floor(-1.5)" is "-2.0".
821 Compute Gauss function of @var{x}, corresponding to
822 @code{exp(-x*x/2) / sqrt(2*PI)}.
825 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
826 @var{y} are 0 or either or both are less than zero then behavior is undefined.
829 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
832 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
835 This function is similar to the C function with the same name; it returns
836 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
837 right triangle with sides of length @var{x} and @var{y}, or the distance of the
838 point (@var{x}, @var{y}) from the origin.
841 Evaluate @var{x}, and if the result is non-zero return the result of
842 the evaluation of @var{y}, return 0 otherwise.
845 Evaluate @var{x}, and if the result is non-zero return the evaluation
846 result of @var{y}, otherwise the evaluation result of @var{z}.
849 Evaluate @var{x}, and if the result is zero return the result of the
850 evaluation of @var{y}, return 0 otherwise.
853 Evaluate @var{x}, and if the result is zero return the evaluation
854 result of @var{y}, otherwise the evaluation result of @var{z}.
857 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
860 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
863 Load the value of the internal variable with number
864 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
865 The function returns the loaded value.
868 Compute natural logarithm of @var{x}.
871 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
874 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
877 Return the maximum between @var{x} and @var{y}.
880 Return the minimum between @var{x} and @var{y}.
883 Compute the remainder of division of @var{x} by @var{y}.
886 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
889 Compute the power of @var{x} elevated @var{y}, it is equivalent to
890 "(@var{x})^(@var{y})".
894 Print the value of expression @var{t} with loglevel @var{l}. If
895 @var{l} is not specified then a default log level is used.
896 Returns the value of the expression printed.
898 Prints t with loglevel l
901 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
902 internal variable which will be used to save the seed/state.
904 @item root(expr, max)
905 Find an input value for which the function represented by @var{expr}
906 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
908 The expression in @var{expr} must denote a continuous function or the
911 @var{ld(0)} is used to represent the function input value, which means
912 that the given expression will be evaluated multiple times with
913 various input values that the expression can access through
914 @code{ld(0)}. When the expression evaluates to 0 then the
915 corresponding input value will be returned.
918 Compute sine of @var{x}.
921 Compute hyperbolic sine of @var{x}.
924 Compute the square root of @var{expr}. This is equivalent to
928 Compute expression @code{1/(1 + exp(4*x))}.
931 Store the value of the expression @var{expr} in an internal
932 variable. @var{var} specifies the number of the variable where to
933 store the value, and it is a value ranging from 0 to 9. The function
934 returns the value stored in the internal variable.
935 Note, Variables are currently not shared between expressions.
938 Compute tangent of @var{x}.
941 Compute hyperbolic tangent of @var{x}.
943 @item taylor(expr, x)
944 @item taylor(expr, x, id)
945 Evaluate a Taylor series at @var{x}, given an expression representing
946 the @code{ld(id)}-th derivative of a function at 0.
948 When the series does not converge the result is undefined.
950 @var{ld(id)} is used to represent the derivative order in @var{expr},
951 which means that the given expression will be evaluated multiple times
952 with various input values that the expression can access through
953 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
955 Note, when you have the derivatives at y instead of 0,
956 @code{taylor(expr, x-y)} can be used.
959 Return the current (wallclock) time in seconds.
962 Round the value of expression @var{expr} towards zero to the nearest
963 integer. For example, "trunc(-1.5)" is "-1.0".
965 @item while(cond, expr)
966 Evaluate expression @var{expr} while the expression @var{cond} is
967 non-zero, and returns the value of the last @var{expr} evaluation, or
968 NAN if @var{cond} was always false.
971 The following constants are available:
974 area of the unit disc, approximately 3.14
976 exp(1) (Euler's number), approximately 2.718
978 golden ratio (1+sqrt(5))/2, approximately 1.618
981 Assuming that an expression is considered "true" if it has a non-zero
984 @code{*} works like AND
986 @code{+} works like OR
988 For example the construct:
997 In your C code, you can extend the list of unary and binary functions,
998 and define recognized constants, so that they are available for your
1001 The evaluator also recognizes the International System unit prefixes.
1002 If 'i' is appended after the prefix, binary prefixes are used, which
1003 are based on powers of 1024 instead of powers of 1000.
1004 The 'B' postfix multiplies the value by 8, and can be appended after a
1005 unit prefix or used alone. This allows using for example 'KB', 'MiB',
1006 'G' and 'B' as number postfix.
1008 The list of available International System prefixes follows, with
1009 indication of the corresponding powers of 10 and of 2.
1053 @c man end EXPRESSION EVALUATION
1055 @chapter OpenCL Options
1056 @c man begin OPENCL OPTIONS
1058 When FFmpeg is configured with @code{--enable-opencl}, it is possible
1059 to set the options for the global OpenCL context.
1061 The list of supported options follows:
1065 Set build options used to compile the registered kernels.
1067 See reference "OpenCL Specification Version: 1.2 chapter 5.6.4".
1070 Select the index of the platform to run OpenCL code.
1072 The specified index must be one of the indexes in the device list
1073 which can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1076 Select the index of the device used to run OpenCL code.
1078 The specified index must be one of the indexes in the device list which
1079 can be obtained with @code{ffmpeg -opencl_bench} or @code{av_opencl_get_device_list()}.
1083 @c man end OPENCL OPTIONS