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
708 FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR
713 A custom channel layout can be specified as a sequence of terms, separated by
714 '+' or '|'. Each term can be:
717 the name of a standard channel layout (e.g. @samp{mono},
718 @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
721 the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
724 a number of channels, in decimal, followed by 'c', yielding the default channel
725 layout for that number of channels (see the function
726 @code{av_get_default_channel_layout}). Note that not all channel counts have a
730 a number of channels, in decimal, followed by 'C', yielding an unknown channel
731 layout with the specified number of channels. Note that not all channel layout
732 specification strings support unknown channel layouts.
735 a channel layout mask, in hexadecimal starting with "0x" (see the
736 @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
739 Before libavutil version 53 the trailing character "c" to specify a number of
740 channels was optional, but now it is required, while a channel layout mask can
741 also be specified as a decimal number (if and only if not followed by "c" or "C").
743 See also the function @code{av_get_channel_layout} defined in
744 @file{libavutil/channel_layout.h}.
747 @chapter Expression Evaluation
748 @c man begin EXPRESSION EVALUATION
750 When evaluating an arithmetic expression, FFmpeg uses an internal
751 formula evaluator, implemented through the @file{libavutil/eval.h}
754 An expression may contain unary, binary operators, constants, and
757 Two expressions @var{expr1} and @var{expr2} can be combined to form
758 another expression "@var{expr1};@var{expr2}".
759 @var{expr1} and @var{expr2} are evaluated in turn, and the new
760 expression evaluates to the value of @var{expr2}.
762 The following binary operators are available: @code{+}, @code{-},
763 @code{*}, @code{/}, @code{^}.
765 The following unary operators are available: @code{+}, @code{-}.
767 The following functions are available:
770 Compute absolute value of @var{x}.
773 Compute arccosine of @var{x}.
776 Compute arcsine of @var{x}.
779 Compute arctangent of @var{x}.
782 Compute principal value of the arc tangent of @var{y}/@var{x}.
784 @item between(x, min, max)
785 Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or
786 equal to @var{max}, 0 otherwise.
790 Compute bitwise and/or operation on @var{x} and @var{y}.
792 The results of the evaluation of @var{x} and @var{y} are converted to
793 integers before executing the bitwise operation.
795 Note that both the conversion to integer and the conversion back to
796 floating point can lose precision. Beware of unexpected results for
797 large numbers (usually 2^53 and larger).
800 Round the value of expression @var{expr} upwards to the nearest
801 integer. For example, "ceil(1.5)" is "2.0".
803 @item clip(x, min, max)
804 Return the value of @var{x} clipped between @var{min} and @var{max}.
807 Compute cosine of @var{x}.
810 Compute hyperbolic cosine of @var{x}.
813 Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise.
816 Compute exponential of @var{x} (with base @code{e}, the Euler's number).
819 Round the value of expression @var{expr} downwards to the nearest
820 integer. For example, "floor(-1.5)" is "-2.0".
823 Compute Gauss function of @var{x}, corresponding to
824 @code{exp(-x*x/2) / sqrt(2*PI)}.
827 Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and
828 @var{y} are 0 or either or both are less than zero then behavior is undefined.
831 Return 1 if @var{x} is greater than @var{y}, 0 otherwise.
834 Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise.
837 This function is similar to the C function with the same name; it returns
838 "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a
839 right triangle with sides of length @var{x} and @var{y}, or the distance of the
840 point (@var{x}, @var{y}) from the origin.
843 Evaluate @var{x}, and if the result is non-zero return the result of
844 the evaluation of @var{y}, return 0 otherwise.
847 Evaluate @var{x}, and if the result is non-zero return the evaluation
848 result of @var{y}, otherwise the evaluation result of @var{z}.
851 Evaluate @var{x}, and if the result is zero return the result of the
852 evaluation of @var{y}, return 0 otherwise.
855 Evaluate @var{x}, and if the result is zero return the evaluation
856 result of @var{y}, otherwise the evaluation result of @var{z}.
859 Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
862 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
865 Load the value of the internal variable with number
866 @var{var}, which was previously stored with st(@var{var}, @var{expr}).
867 The function returns the loaded value.
870 Return linear interpolation between @var{x} and @var{y} by amount of @var{z}.
873 Compute natural logarithm of @var{x}.
876 Return 1 if @var{x} is lesser than @var{y}, 0 otherwise.
879 Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise.
882 Return the maximum between @var{x} and @var{y}.
885 Return the minimum between @var{x} and @var{y}.
888 Compute the remainder of division of @var{x} by @var{y}.
891 Return 1.0 if @var{expr} is zero, 0.0 otherwise.
894 Compute the power of @var{x} elevated @var{y}, it is equivalent to
895 "(@var{x})^(@var{y})".
899 Print the value of expression @var{t} with loglevel @var{l}. If
900 @var{l} is not specified then a default log level is used.
901 Returns the value of the expression printed.
903 Prints t with loglevel l
906 Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the
907 internal variable which will be used to save the seed/state.
909 @item root(expr, max)
910 Find an input value for which the function represented by @var{expr}
911 with argument @var{ld(0)} is 0 in the interval 0..@var{max}.
913 The expression in @var{expr} must denote a continuous function or the
916 @var{ld(0)} is used to represent the function input value, which means
917 that the given expression will be evaluated multiple times with
918 various input values that the expression can access through
919 @code{ld(0)}. When the expression evaluates to 0 then the
920 corresponding input value will be returned.
923 Round the value of expression @var{expr} to the nearest integer. For example, "round(1.5)" is "2.0".
926 Compute sign of @var{x}.
929 Compute sine of @var{x}.
932 Compute hyperbolic sine of @var{x}.
935 Compute the square root of @var{expr}. This is equivalent to
939 Compute expression @code{1/(1 + exp(4*x))}.
942 Store the value of the expression @var{expr} in an internal
943 variable. @var{var} specifies the number of the variable where to
944 store the value, and it is a value ranging from 0 to 9. The function
945 returns the value stored in the internal variable.
946 Note, Variables are currently not shared between expressions.
949 Compute tangent of @var{x}.
952 Compute hyperbolic tangent of @var{x}.
954 @item taylor(expr, x)
955 @item taylor(expr, x, id)
956 Evaluate a Taylor series at @var{x}, given an expression representing
957 the @code{ld(id)}-th derivative of a function at 0.
959 When the series does not converge the result is undefined.
961 @var{ld(id)} is used to represent the derivative order in @var{expr},
962 which means that the given expression will be evaluated multiple times
963 with various input values that the expression can access through
964 @code{ld(id)}. If @var{id} is not specified then 0 is assumed.
966 Note, when you have the derivatives at y instead of 0,
967 @code{taylor(expr, x-y)} can be used.
970 Return the current (wallclock) time in seconds.
973 Round the value of expression @var{expr} towards zero to the nearest
974 integer. For example, "trunc(-1.5)" is "-1.0".
976 @item while(cond, expr)
977 Evaluate expression @var{expr} while the expression @var{cond} is
978 non-zero, and returns the value of the last @var{expr} evaluation, or
979 NAN if @var{cond} was always false.
982 The following constants are available:
985 area of the unit disc, approximately 3.14
987 exp(1) (Euler's number), approximately 2.718
989 golden ratio (1+sqrt(5))/2, approximately 1.618
992 Assuming that an expression is considered "true" if it has a non-zero
995 @code{*} works like AND
997 @code{+} works like OR
999 For example the construct:
1008 In your C code, you can extend the list of unary and binary functions,
1009 and define recognized constants, so that they are available for your
1012 The evaluator also recognizes the International System unit prefixes.
1013 If 'i' is appended after the prefix, binary prefixes are used, which
1014 are based on powers of 1024 instead of powers of 1000.
1015 The 'B' postfix multiplies the value by 8, and can be appended after a
1016 unit prefix or used alone. This allows using for example 'KB', 'MiB',
1017 'G' and 'B' as number postfix.
1019 The list of available International System prefixes follows, with
1020 indication of the corresponding powers of 10 and of 2.
1064 @c man end EXPRESSION EVALUATION
projects / ffmpeg / blob