/
githubmirror
/
FFmpeg
Обзор
Документация
Войти
/
githubmirror
/
FFmpeg
Код
Запросы
0
Пакеты
0
Релизы
0
Аналитика
Безопасность
n4.4.7
doc/utils.texi
1 075 строк
21 KB
Moritz Barsnick
doc/utils: document the "s", "ms" and "us" suffixes for durations
09 июн 2020, 15:25
09 июн 2020, 15:25
7ab375f
Код
Авторство
О чём код?
@chapter Syntax @c man begin SYNTAX This section documents the syntax and formats employed by the FFmpeg libraries and tools. @anchor{quoting_and_escaping} @section Quoting and escaping FFmpeg adopts the following quoting and escaping mechanism, unless explicitly specified. The following rules are applied: @itemize @item @samp{'} and @samp{\} are special characters (respectively used for quoting and escaping). In addition to them, there might be other special characters depending on the specific syntax where the escaping and quoting are employed. @item A special character is escaped by prefixing it with a @samp{\}. @item All characters enclosed between @samp{''} are included literally in the parsed string. The quote character @samp{'} itself cannot be quoted, so you may need to close the quote and escape it. @item Leading and trailing whitespaces, unless escaped or quoted, are removed from the parsed string. @end itemize Note that you may need to add a second level of escaping when using the command line or a script, which depends on the syntax of the adopted shell language. The function @code{av_get_token} defined in @file{libavutil/avstring.h} can be used to parse a token quoted or escaped according to the rules defined above. The tool @file{tools/ffescape} in the FFmpeg source tree can be used to automatically quote or escape a string in a script. @subsection Examples @itemize @item Escape the string @code{Crime d'Amour} containing the @code{'} special character: @example Crime d\'Amour @end example @item The string above contains a quote, so the @code{'} needs to be escaped when quoting it: @example 'Crime d'\''Amour' @end example @item Include leading or trailing whitespaces using quoting: @example ' this string starts and ends with whitespaces ' @end example @item Escaping and quoting can be mixed together: @example ' The string '\'string\'' is a string ' @end example @item To include a literal @samp{\} you can use either escaping or quoting: @example 'c:\foo' can be written as c:\\foo @end example @end itemize @anchor{date syntax} @section Date The accepted syntax is: @example [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z] now @end example If the value is "now" it takes the current time. Time is local time unless Z is appended, in which case it is interpreted as UTC. If the year-month-day part is not specified it takes the current year-month-day. @anchor{time duration syntax} @section Time duration There are two accepted syntaxes for expressing time duration. @example [-][@var{HH}:]@var{MM}:@var{SS}[.@var{m}...] @end example @var{HH} expresses the number of hours, @var{MM} the number of minutes for a maximum of 2 digits, and @var{SS} the number of seconds for a maximum of 2 digits. The @var{m} at the end expresses decimal value for @var{SS}. @emph{or} @example [-]@var{S}+[.@var{m}...][s|ms|us] @end example @var{S} expresses the number of seconds, with the optional decimal part @var{m}. The optional literal suffixes @samp{s}, @samp{ms} or @samp{us} indicate to interpret the value as seconds, milliseconds or microseconds, respectively. In both expressions, the optional @samp{-} indicates negative duration. @subsection Examples The following examples are all valid time duration: @table @samp @item 55 55 seconds @item 0.2 0.2 seconds @item 200ms 200 milliseconds, that's 0.2s @item 200000us 200000 microseconds, that's 0.2s @item 12:03:45 12 hours, 03 minutes and 45 seconds @item 23.189 23.189 seconds @end table @anchor{video size syntax} @section Video size Specify the size of the sourced video, it may be a string of the form @var{width}x@var{height}, or the name of a size abbreviation. The following abbreviations are recognized: @table @samp @item ntsc 720x480 @item pal 720x576 @item qntsc 352x240 @item qpal 352x288 @item sntsc 640x480 @item spal 768x576 @item film 352x240 @item ntsc-film 352x240 @item sqcif 128x96 @item qcif 176x144 @item cif 352x288 @item 4cif 704x576 @item 16cif 1408x1152 @item qqvga 160x120 @item qvga 320x240 @item vga 640x480 @item svga 800x600 @item xga 1024x768 @item uxga 1600x1200 @item qxga 2048x1536 @item sxga 1280x1024 @item qsxga 2560x2048 @item hsxga 5120x4096 @item wvga 852x480 @item wxga 1366x768 @item wsxga 1600x1024 @item wuxga 1920x1200 @item woxga 2560x1600 @item wqsxga 3200x2048 @item wquxga 3840x2400 @item whsxga 6400x4096 @item whuxga 7680x4800 @item cga 320x200 @item ega 640x350 @item hd480 852x480 @item hd720 1280x720 @item hd1080 1920x1080 @item 2k 2048x1080 @item 2kflat 1998x1080 @item 2kscope 2048x858 @item 4k 4096x2160 @item 4kflat 3996x2160 @item 4kscope 4096x1716 @item nhd 640x360 @item hqvga 240x160 @item wqvga 400x240 @item fwqvga 432x240 @item hvga 480x320 @item qhd 960x540 @item 2kdci 2048x1080 @item 4kdci 4096x2160 @item uhd2160 3840x2160 @item uhd4320 7680x4320 @end table @anchor{video rate syntax} @section Video rate Specify the frame rate of a video, expressed as the number of frames generated per second. It has to be a string in the format @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float number or a valid video frame rate abbreviation. The following abbreviations are recognized: @table @samp @item ntsc 30000/1001 @item pal 25/1 @item qntsc 30000/1001 @item qpal 25/1 @item sntsc 30000/1001 @item spal 25/1 @item film 24/1 @item ntsc-film 24000/1001 @end table @anchor{ratio syntax} @section Ratio A ratio can be expressed as an expression, or in the form @var{numerator}:@var{denominator}. Note that a ratio with infinite (1/0) or negative value is considered valid, so you should check on the returned value if you want to exclude those values. The undefined value can be expressed using the "0:0" string. @anchor{color syntax} @section Color It can be the name of a color as defined below (case insensitive match) or a @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string representing the alpha component. The alpha component may be a string composed by "0x" followed by an hexadecimal number or a decimal number between 0.0 and 1.0, which represents the opacity value (@samp{0x00} or @samp{0.0} means completely transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha component is not specified then @samp{0xff} is assumed. The string @samp{random} will result in a random color. The following names of colors are recognized: @table @samp @item AliceBlue 0xF0F8FF @item AntiqueWhite 0xFAEBD7 @item Aqua 0x00FFFF @item Aquamarine 0x7FFFD4 @item Azure 0xF0FFFF @item Beige 0xF5F5DC @item Bisque 0xFFE4C4 @item Black 0x000000 @item BlanchedAlmond 0xFFEBCD @item Blue 0x0000FF @item BlueViolet 0x8A2BE2 @item Brown 0xA52A2A @item BurlyWood 0xDEB887 @item CadetBlue 0x5F9EA0 @item Chartreuse 0x7FFF00 @item Chocolate 0xD2691E @item Coral 0xFF7F50 @item CornflowerBlue 0x6495ED @item Cornsilk 0xFFF8DC @item Crimson 0xDC143C @item Cyan 0x00FFFF @item DarkBlue 0x00008B @item DarkCyan 0x008B8B @item DarkGoldenRod 0xB8860B @item DarkGray 0xA9A9A9 @item DarkGreen 0x006400 @item DarkKhaki 0xBDB76B @item DarkMagenta 0x8B008B @item DarkOliveGreen 0x556B2F @item Darkorange 0xFF8C00 @item DarkOrchid 0x9932CC @item DarkRed 0x8B0000 @item DarkSalmon 0xE9967A @item DarkSeaGreen 0x8FBC8F @item DarkSlateBlue 0x483D8B @item DarkSlateGray 0x2F4F4F @item DarkTurquoise 0x00CED1 @item DarkViolet 0x9400D3 @item DeepPink 0xFF1493 @item DeepSkyBlue 0x00BFFF @item DimGray 0x696969 @item DodgerBlue 0x1E90FF @item FireBrick 0xB22222 @item FloralWhite 0xFFFAF0 @item ForestGreen 0x228B22 @item Fuchsia 0xFF00FF @item Gainsboro 0xDCDCDC @item GhostWhite 0xF8F8FF @item Gold 0xFFD700 @item GoldenRod 0xDAA520 @item Gray 0x808080 @item Green 0x008000 @item GreenYellow 0xADFF2F @item HoneyDew 0xF0FFF0 @item HotPink 0xFF69B4 @item IndianRed 0xCD5C5C @item Indigo 0x4B0082 @item Ivory 0xFFFFF0 @item Khaki 0xF0E68C @item Lavender 0xE6E6FA @item LavenderBlush 0xFFF0F5 @item LawnGreen 0x7CFC00 @item LemonChiffon 0xFFFACD @item LightBlue 0xADD8E6 @item LightCoral 0xF08080 @item LightCyan 0xE0FFFF @item LightGoldenRodYellow 0xFAFAD2 @item LightGreen 0x90EE90 @item LightGrey 0xD3D3D3 @item LightPink 0xFFB6C1 @item LightSalmon 0xFFA07A @item LightSeaGreen 0x20B2AA @item LightSkyBlue 0x87CEFA @item LightSlateGray 0x778899 @item LightSteelBlue 0xB0C4DE @item LightYellow 0xFFFFE0 @item Lime 0x00FF00 @item LimeGreen 0x32CD32 @item Linen 0xFAF0E6 @item Magenta 0xFF00FF @item Maroon 0x800000 @item MediumAquaMarine 0x66CDAA @item MediumBlue 0x0000CD @item MediumOrchid 0xBA55D3 @item MediumPurple 0x9370D8 @item MediumSeaGreen 0x3CB371 @item MediumSlateBlue 0x7B68EE @item MediumSpringGreen 0x00FA9A @item MediumTurquoise 0x48D1CC @item MediumVioletRed 0xC71585 @item MidnightBlue 0x191970 @item MintCream 0xF5FFFA @item MistyRose 0xFFE4E1 @item Moccasin 0xFFE4B5 @item NavajoWhite 0xFFDEAD @item Navy 0x000080 @item OldLace 0xFDF5E6 @item Olive 0x808000 @item OliveDrab 0x6B8E23 @item Orange 0xFFA500 @item OrangeRed 0xFF4500 @item Orchid 0xDA70D6 @item PaleGoldenRod 0xEEE8AA @item PaleGreen 0x98FB98 @item PaleTurquoise 0xAFEEEE @item PaleVioletRed 0xD87093 @item PapayaWhip 0xFFEFD5 @item PeachPuff 0xFFDAB9 @item Peru 0xCD853F @item Pink 0xFFC0CB @item Plum 0xDDA0DD @item PowderBlue 0xB0E0E6 @item Purple 0x800080 @item Red 0xFF0000 @item RosyBrown 0xBC8F8F @item RoyalBlue 0x4169E1 @item SaddleBrown 0x8B4513 @item Salmon 0xFA8072 @item SandyBrown 0xF4A460 @item SeaGreen 0x2E8B57 @item SeaShell 0xFFF5EE @item Sienna 0xA0522D @item Silver 0xC0C0C0 @item SkyBlue 0x87CEEB @item SlateBlue 0x6A5ACD @item SlateGray 0x708090 @item Snow 0xFFFAFA @item SpringGreen 0x00FF7F @item SteelBlue 0x4682B4 @item Tan 0xD2B48C @item Teal 0x008080 @item Thistle 0xD8BFD8 @item Tomato 0xFF6347 @item Turquoise 0x40E0D0 @item Violet 0xEE82EE @item Wheat 0xF5DEB3 @item White 0xFFFFFF @item WhiteSmoke 0xF5F5F5 @item Yellow 0xFFFF00 @item YellowGreen 0x9ACD32 @end table @anchor{channel layout syntax} @section Channel Layout A channel layout specifies the spatial disposition of the channels in a multi-channel audio stream. To specify a channel layout, FFmpeg makes use of a special syntax. Individual channels are identified by an id, as given by the table below: @table @samp @item FL front left @item FR front right @item FC front center @item LFE low frequency @item BL back left @item BR back right @item FLC front left-of-center @item FRC front right-of-center @item BC back center @item SL side left @item SR side right @item TC top center @item TFL top front left @item TFC top front center @item TFR top front right @item TBL top back left @item TBC top back center @item TBR top back right @item DL downmix left @item DR downmix right @item WL wide left @item WR wide right @item SDL surround direct left @item SDR surround direct right @item LFE2 low frequency 2 @end table Standard channel layout compositions can be specified by using the following identifiers: @table @samp @item mono FC @item stereo FL+FR @item 2.1 FL+FR+LFE @item 3.0 FL+FR+FC @item 3.0(back) FL+FR+BC @item 4.0 FL+FR+FC+BC @item quad FL+FR+BL+BR @item quad(side) FL+FR+SL+SR @item 3.1 FL+FR+FC+LFE @item 5.0 FL+FR+FC+BL+BR @item 5.0(side) FL+FR+FC+SL+SR @item 4.1 FL+FR+FC+LFE+BC @item 5.1 FL+FR+FC+LFE+BL+BR @item 5.1(side) FL+FR+FC+LFE+SL+SR @item 6.0 FL+FR+FC+BC+SL+SR @item 6.0(front) FL+FR+FLC+FRC+SL+SR @item hexagonal FL+FR+FC+BL+BR+BC @item 6.1 FL+FR+FC+LFE+BC+SL+SR @item 6.1 FL+FR+FC+LFE+BL+BR+BC @item 6.1(front) FL+FR+LFE+FLC+FRC+SL+SR @item 7.0 FL+FR+FC+BL+BR+SL+SR @item 7.0(front) FL+FR+FC+FLC+FRC+SL+SR @item 7.1 FL+FR+FC+LFE+BL+BR+SL+SR @item 7.1(wide) FL+FR+FC+LFE+BL+BR+FLC+FRC @item 7.1(wide-side) FL+FR+FC+LFE+FLC+FRC+SL+SR @item octagonal FL+FR+FC+BL+BR+BC+SL+SR @item hexadecagonal FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR @item downmix DL+DR @end table A custom channel layout can be specified as a sequence of terms, separated by '+' or '|'. Each term can be: @itemize @item the name of a standard channel layout (e.g. @samp{mono}, @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.) @item the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.) @item a number of channels, in decimal, followed by 'c', yielding the default channel layout for that number of channels (see the function @code{av_get_default_channel_layout}). Note that not all channel counts have a default layout. @item a number of channels, in decimal, followed by 'C', yielding an unknown channel layout with the specified number of channels. Note that not all channel layout specification strings support unknown channel layouts. @item a channel layout mask, in hexadecimal starting with "0x" (see the @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}. @end itemize Before libavutil version 53 the trailing character "c" to specify a number of channels was optional, but now it is required, while a channel layout mask can also be specified as a decimal number (if and only if not followed by "c" or "C"). See also the function @code{av_get_channel_layout} defined in @file{libavutil/channel_layout.h}. @c man end SYNTAX @chapter Expression Evaluation @c man begin EXPRESSION EVALUATION When evaluating an arithmetic expression, FFmpeg uses an internal formula evaluator, implemented through the @file{libavutil/eval.h} interface. An expression may contain unary, binary operators, constants, and functions. Two expressions @var{expr1} and @var{expr2} can be combined to form another expression "@var{expr1};@var{expr2}". @var{expr1} and @var{expr2} are evaluated in turn, and the new expression evaluates to the value of @var{expr2}. The following binary operators are available: @code{+}, @code{-}, @code{*}, @code{/}, @code{^}. The following unary operators are available: @code{+}, @code{-}. The following functions are available: @table @option @item abs(x) Compute absolute value of @var{x}. @item acos(x) Compute arccosine of @var{x}. @item asin(x) Compute arcsine of @var{x}. @item atan(x) Compute arctangent of @var{x}. @item atan2(x, y) Compute principal value of the arc tangent of @var{y}/@var{x}. @item between(x, min, max) Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or equal to @var{max}, 0 otherwise. @item bitand(x, y) @item bitor(x, y) Compute bitwise and/or operation on @var{x} and @var{y}. The results of the evaluation of @var{x} and @var{y} are converted to integers before executing the bitwise operation. Note that both the conversion to integer and the conversion back to floating point can lose precision. Beware of unexpected results for large numbers (usually 2^53 and larger). @item ceil(expr) Round the value of expression @var{expr} upwards to the nearest integer. For example, "ceil(1.5)" is "2.0". @item clip(x, min, max) Return the value of @var{x} clipped between @var{min} and @var{max}. @item cos(x) Compute cosine of @var{x}. @item cosh(x) Compute hyperbolic cosine of @var{x}. @item eq(x, y) Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. @item exp(x) Compute exponential of @var{x} (with base @code{e}, the Euler's number). @item floor(expr) Round the value of expression @var{expr} downwards to the nearest integer. For example, "floor(-1.5)" is "-2.0". @item gauss(x) Compute Gauss function of @var{x}, corresponding to @code{exp(-x*x/2) / sqrt(2*PI)}. @item gcd(x, y) Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and @var{y} are 0 or either or both are less than zero then behavior is undefined. @item gt(x, y) Return 1 if @var{x} is greater than @var{y}, 0 otherwise. @item gte(x, y) Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. @item hypot(x, y) This function is similar to the C function with the same name; it returns "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a right triangle with sides of length @var{x} and @var{y}, or the distance of the point (@var{x}, @var{y}) from the origin. @item if(x, y) Evaluate @var{x}, and if the result is non-zero return the result of the evaluation of @var{y}, return 0 otherwise. @item if(x, y, z) Evaluate @var{x}, and if the result is non-zero return the evaluation result of @var{y}, otherwise the evaluation result of @var{z}. @item ifnot(x, y) Evaluate @var{x}, and if the result is zero return the result of the evaluation of @var{y}, return 0 otherwise. @item ifnot(x, y, z) Evaluate @var{x}, and if the result is zero return the evaluation result of @var{y}, otherwise the evaluation result of @var{z}. @item isinf(x) Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise. @item isnan(x) Return 1.0 if @var{x} is NAN, 0.0 otherwise. @item ld(var) Load the value of the internal variable with number @var{var}, which was previously stored with st(@var{var}, @var{expr}). The function returns the loaded value. @item lerp(x, y, z) Return linear interpolation between @var{x} and @var{y} by amount of @var{z}. @item log(x) Compute natural logarithm of @var{x}. @item lt(x, y) Return 1 if @var{x} is lesser than @var{y}, 0 otherwise. @item lte(x, y) Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise. @item max(x, y) Return the maximum between @var{x} and @var{y}. @item min(x, y) Return the minimum between @var{x} and @var{y}. @item mod(x, y) Compute the remainder of division of @var{x} by @var{y}. @item not(expr) Return 1.0 if @var{expr} is zero, 0.0 otherwise. @item pow(x, y) Compute the power of @var{x} elevated @var{y}, it is equivalent to "(@var{x})^(@var{y})". @item print(t) @item print(t, l) Print the value of expression @var{t} with loglevel @var{l}. If @var{l} is not specified then a default log level is used. Returns the value of the expression printed. Prints t with loglevel l @item random(x) Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the internal variable which will be used to save the seed/state. @item root(expr, max) Find an input value for which the function represented by @var{expr} with argument @var{ld(0)} is 0 in the interval 0..@var{max}. The expression in @var{expr} must denote a continuous function or the result is undefined. @var{ld(0)} is used to represent the function input value, which means that the given expression will be evaluated multiple times with various input values that the expression can access through @code{ld(0)}. When the expression evaluates to 0 then the corresponding input value will be returned. @item round(expr) Round the value of expression @var{expr} to the nearest integer. For example, "round(1.5)" is "2.0". @item sgn(x) Compute sign of @var{x}. @item sin(x) Compute sine of @var{x}. @item sinh(x) Compute hyperbolic sine of @var{x}. @item sqrt(expr) Compute the square root of @var{expr}. This is equivalent to "(@var{expr})^.5". @item squish(x) Compute expression @code{1/(1 + exp(4*x))}. @item st(var, expr) Store the value of the expression @var{expr} in an internal variable. @var{var} specifies the number of the variable where to store the value, and it is a value ranging from 0 to 9. The function returns the value stored in the internal variable. Note, Variables are currently not shared between expressions. @item tan(x) Compute tangent of @var{x}. @item tanh(x) Compute hyperbolic tangent of @var{x}. @item taylor(expr, x) @item taylor(expr, x, id) Evaluate a Taylor series at @var{x}, given an expression representing the @code{ld(id)}-th derivative of a function at 0. When the series does not converge the result is undefined. @var{ld(id)} is used to represent the derivative order in @var{expr}, which means that the given expression will be evaluated multiple times with various input values that the expression can access through @code{ld(id)}. If @var{id} is not specified then 0 is assumed. Note, when you have the derivatives at y instead of 0, @code{taylor(expr, x-y)} can be used. @item time(0) Return the current (wallclock) time in seconds. @item trunc(expr) Round the value of expression @var{expr} towards zero to the nearest integer. For example, "trunc(-1.5)" is "-1.0". @item while(cond, expr) Evaluate expression @var{expr} while the expression @var{cond} is non-zero, and returns the value of the last @var{expr} evaluation, or NAN if @var{cond} was always false. @end table The following constants are available: @table @option @item PI area of the unit disc, approximately 3.14 @item E exp(1) (Euler's number), approximately 2.718 @item PHI golden ratio (1+sqrt(5))/2, approximately 1.618 @end table Assuming that an expression is considered "true" if it has a non-zero value, note that: @code{*} works like AND @code{+} works like OR For example the construct: @example if (A AND B) then C @end example is equivalent to: @example if(A*B, C) @end example In your C code, you can extend the list of unary and binary functions, and define recognized constants, so that they are available for your expressions. The evaluator also recognizes the International System unit prefixes. If 'i' is appended after the prefix, binary prefixes are used, which are based on powers of 1024 instead of powers of 1000. The 'B' postfix multiplies the value by 8, and can be appended after a unit prefix or used alone. This allows using for example 'KB', 'MiB', 'G' and 'B' as number postfix. The list of available International System prefixes follows, with indication of the corresponding powers of 10 and of 2. @table @option @item y 10^-24 / 2^-80 @item z 10^-21 / 2^-70 @item a 10^-18 / 2^-60 @item f 10^-15 / 2^-50 @item p 10^-12 / 2^-40 @item n 10^-9 / 2^-30 @item u 10^-6 / 2^-20 @item m 10^-3 / 2^-10 @item c 10^-2 @item d 10^-1 @item h 10^2 @item k 10^3 / 2^10 @item K 10^3 / 2^10 @item M 10^6 / 2^20 @item G 10^9 / 2^30 @item T 10^12 / 2^40 @item P 10^15 / 2^40 @item E 10^18 / 2^50 @item Z 10^21 / 2^60 @item Y 10^24 / 2^70 @end table @c man end EXPRESSION EVALUATION