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}...][s|ms|us]
116 @var{S} expresses the number of seconds, with the optional decimal part
117 @var{m}. The optional literal suffixes @samp{s}, @samp{ms} or @samp{us}
118 indicate to interpret the value as seconds, milliseconds or microseconds,
121 In both expressions, the optional @samp{-} indicates negative duration.
125 The following examples are all valid time duration:
135 200 milliseconds, that's 0.2s
138 200000 microseconds, that's 0.2s
141 12 hours, 03 minutes and 45 seconds
147 @anchor{video size syntax}
149 Specify the size of the sourced video, it may be a string of the form
150 @var{width}x@var{height}, or the name of a size abbreviation.
152 The following abbreviations are recognized:
262 @anchor{video rate syntax}
265 Specify the frame rate of a video, expressed as the number of frames
266 generated per second. It has to be a string in the format
267 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
268 number or a valid video frame rate abbreviation.
270 The following abbreviations are recognized:
290 @anchor{ratio syntax}
293 A ratio can be expressed as an expression, or in the form
294 @var{numerator}:@var{denominator}.
296 Note that a ratio with infinite (1/0) or negative value is
297 considered valid, so you should check on the returned value if you
298 want to exclude those values.
300 The undefined value can be expressed using the "0:0" string.
302 @anchor{color syntax}
305 It can be the name of a color as defined below (case insensitive match) or a
306 @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string
307 representing the alpha component.
309 The alpha component may be a string composed by "0x" followed by an
310 hexadecimal number or a decimal number between 0.0 and 1.0, which
311 represents the opacity value (@samp{0x00} or @samp{0.0} means completely
312 transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha
313 component is not specified then @samp{0xff} is assumed.
315 The string @samp{random} will result in a random color.
317 The following names of colors are recognized:
451 @item LightGoldenRodYellow
481 @item MediumAquaMarine
491 @item MediumSlateBlue
493 @item MediumSpringGreen
495 @item MediumTurquoise
497 @item MediumVioletRed
601 @anchor{channel layout syntax}
602 @section Channel Layout
604 A channel layout specifies the spatial disposition of the channels in
605 a multi-channel audio stream. To specify a channel layout, FFmpeg
606 makes use of a special syntax.
608 Individual channels are identified by an id, as given by the table
626 front right-of-center
658 surround direct right
663 Standard channel layout compositions can be specified by using the
664 following identifiers:
701 FL+FR+FC+LFE+BC+SL+SR
703 FL+FR+FC+LFE+BL+BR+BC
705 FL+FR+LFE+FLC+FRC+SL+SR
709 FL+FR+FC+FLC+FRC+SL+SR
711 FL+FR+FC+LFE+BL+BR+SL+SR
713 FL+FR+FC+LFE+BL+BR+FLC+FRC
715 FL+FR+FC+LFE+FLC+FRC+SL+SR
717 FL+FR+FC+BL+BR+BC+SL+SR
719 FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR
724 A custom channel layout can be specified as a sequence of terms, separated by
725 '+' or '|'. Each term can be:
728 the name of a standard channel layout (e.g. @samp{mono},
729 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
732 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
735 a number of channels, in decimal, followed by 'c', yielding the default channel
736 layout for that number of channels (see the function
737 @code{av_get_default_channel_layout}). Note that not all channel counts have a
741 a number of channels, in decimal, followed by 'C', yielding an unknown channel
742 layout with the specified number of channels. Note that not all channel layout
743 specification strings support unknown channel layouts.
746 a channel layout mask, in hexadecimal starting with "0x" (see the
747 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
750 Before libavutil version 53 the trailing character "c" to specify a number of
751 channels was optional, but now it is required, while a channel layout mask can
752 also be specified as a decimal number (if and only if not followed by "c" or "C").
754 See also the function @code{av_get_channel_layout} defined in
755 @file{libavutil/channel_layout.h}.
758 @chapter Expression Evaluation
759 @c man begin EXPRESSION EVALUATION
761 When evaluating an arithmetic expression, FFmpeg uses an internal
762 formula evaluator, implemented through the @file{libavutil/eval.h}
765 An expression may contain unary, binary operators, constants, and
768 Two expressions @var{expr1} and @var{expr2} can be combined to form
769 another expression "@var{expr1};@var{expr2}".
770 @var{expr1} and @var{expr2} are evaluated in turn, and the new
771 expression evaluates to the value of @var{expr2}.
773 The following binary operators are available: @code{+}, @code{-},
774 @code{*}, @code{/}, @code{^}.
776 The following unary operators are available: @code{+}, @code{-}.
778 The following functions are available:
781 Compute absolute value of @var{x}.
784 Compute arccosine of @var{x}.
787 Compute arcsine of @var{x}.
790 Compute arctangent of @var{x}.
793 Compute principal value of the arc tangent of @var{y}/@var{x}.
795 @item between(x, min, max)
796 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
797 equal to @var{max}, 0 otherwise.
801 Compute bitwise and/or operation on @var{x} and @var{y}.
803 The results of the evaluation of @var{x} and @var{y} are converted to
804 integers before executing the bitwise operation.
806 Note that both the conversion to integer and the conversion back to
807 floating point can lose precision. Beware of unexpected results for
808 large numbers (usually 2^53 and larger).
811 Round the value of expression @var{expr} upwards to the nearest
812 integer. For example, "ceil(1.5)" is "2.0".
814 @item clip(x, min, max)
815 Return the value of @var{x} clipped between @var{min} and @var{max}.
818 Compute cosine of @var{x}.
821 Compute hyperbolic cosine of @var{x}.
824 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
827 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
830 Round the value of expression @var{expr} downwards to the nearest
831 integer. For example, "floor(-1.5)" is "-2.0".
834 Compute Gauss function of @var{x}, corresponding to
835 @code{exp(-x*x/2) / sqrt(2*PI)}.
838 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
839 @var{y} are 0 or either or both are less than zero then behavior is undefined.
842 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
845 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
848 This function is similar to the C function with the same name; it returns
849 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
850 right triangle with sides of length @var{x} and @var{y}, or the distance of the
851 point (@var{x}, @var{y}) from the origin.
854 Evaluate @var{x}, and if the result is non-zero return the result of
855 the evaluation of @var{y}, return 0 otherwise.
858 Evaluate @var{x}, and if the result is non-zero return the evaluation
859 result of @var{y}, otherwise the evaluation result of @var{z}.
862 Evaluate @var{x}, and if the result is zero return the result of the
863 evaluation of @var{y}, return 0 otherwise.
866 Evaluate @var{x}, and if the result is zero return the evaluation
867 result of @var{y}, otherwise the evaluation result of @var{z}.
870 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
873 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
876 Load the value of the internal variable with number
877 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
878 The function returns the loaded value.
881 Return linear interpolation between @var{x} and @var{y} by amount of @var{z}.
884 Compute natural logarithm of @var{x}.
887 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
890 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
893 Return the maximum between @var{x} and @var{y}.
896 Return the minimum between @var{x} and @var{y}.
899 Compute the remainder of division of @var{x} by @var{y}.
902 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
905 Compute the power of @var{x} elevated @var{y}, it is equivalent to
906 "(@var{x})^(@var{y})".
910 Print the value of expression @var{t} with loglevel @var{l}. If
911 @var{l} is not specified then a default log level is used.
912 Returns the value of the expression printed.
914 Prints t with loglevel l
917 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
918 internal variable which will be used to save the seed/state.
920 @item root(expr, max)
921 Find an input value for which the function represented by @var{expr}
922 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
924 The expression in @var{expr} must denote a continuous function or the
927 @var{ld(0)} is used to represent the function input value, which means
928 that the given expression will be evaluated multiple times with
929 various input values that the expression can access through
930 @code{ld(0)}. When the expression evaluates to 0 then the
931 corresponding input value will be returned.
934 Round the value of expression @var{expr} to the nearest integer. For example, "round(1.5)" is "2.0".
937 Compute sign of @var{x}.
940 Compute sine of @var{x}.
943 Compute hyperbolic sine of @var{x}.
946 Compute the square root of @var{expr}. This is equivalent to
950 Compute expression @code{1/(1 + exp(4*x))}.
953 Store the value of the expression @var{expr} in an internal
954 variable. @var{var} specifies the number of the variable where to
955 store the value, and it is a value ranging from 0 to 9. The function
956 returns the value stored in the internal variable.
957 Note, Variables are currently not shared between expressions.
960 Compute tangent of @var{x}.
963 Compute hyperbolic tangent of @var{x}.
965 @item taylor(expr, x)
966 @item taylor(expr, x, id)
967 Evaluate a Taylor series at @var{x}, given an expression representing
968 the @code{ld(id)}-th derivative of a function at 0.
970 When the series does not converge the result is undefined.
972 @var{ld(id)} is used to represent the derivative order in @var{expr},
973 which means that the given expression will be evaluated multiple times
974 with various input values that the expression can access through
975 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
977 Note, when you have the derivatives at y instead of 0,
978 @code{taylor(expr, x-y)} can be used.
981 Return the current (wallclock) time in seconds.
984 Round the value of expression @var{expr} towards zero to the nearest
985 integer. For example, "trunc(-1.5)" is "-1.0".
987 @item while(cond, expr)
988 Evaluate expression @var{expr} while the expression @var{cond} is
989 non-zero, and returns the value of the last @var{expr} evaluation, or
990 NAN if @var{cond} was always false.
993 The following constants are available:
996 area of the unit disc, approximately 3.14
998 exp(1) (Euler's number), approximately 2.718
1000 golden ratio (1+sqrt(5))/2, approximately 1.618
1003 Assuming that an expression is considered "true" if it has a non-zero
1006 @code{*} works like AND
1008 @code{+} works like OR
1010 For example the construct:
1019 In your C code, you can extend the list of unary and binary functions,
1020 and define recognized constants, so that they are available for your
1023 The evaluator also recognizes the International System unit prefixes.
1024 If 'i' is appended after the prefix, binary prefixes are used, which
1025 are based on powers of 1024 instead of powers of 1000.
1026 The 'B' postfix multiplies the value by 8, and can be appended after a
1027 unit prefix or used alone. This allows using for example 'KB', 'MiB',
1028 'G' and 'B' as number postfix.
1030 The list of available International System prefixes follows, with
1031 indication of the corresponding powers of 10 and of 2.
1075 @c man end EXPRESSION EVALUATION
projects / ffmpeg / blob