FFmpeg工具文档

网站翻译由林建有提供支持

1 简介

本文档描述了libavutil库提供的一些通用功能和工具。

2 语法

本节记录了FFmpeg库和工具采用的语法和格式。

2.1 引号和转义

FFmpeg采用以下引用和转义机制，除非明确规定。适用以下规则：

  • ‘'’ 和 ‘\’ 是特殊字符（分别用于引用和转义）。除了它们，根据所采用转义和引用的具体语法，还可能会有其他特殊字符。
  • 通过前缀‘转义特殊字符。\’.
  • 所有括在‘''’之间的字符均以字面形式包含在解析字符串中。引用字符‘'’本身无法被引用，因此您可能需要关闭引用并转义它。
  • 起始和结尾的空格，除非被转义或引用，否则在解析字符串中会被移除。

注意，在使用命令行或脚本时，可能需要增加第二层转义，这取决于所采用的shell语言的语法。

函数av_get_token定义于libavutil/avstring.h可用于解析按照上述定义的规则进行引用或转义的标记。

工具tools/ffescape在FFmpeg源树中可用于自动在脚本中引用或转义字符串。

2.1.1 示例

  • 转义字符串Crime d'Amour包含'特殊字符：
    Crime d\'Amour
  • 上述字符串包含一个引用，因此'在引用时需要转义：
    'Crime d'\''Amour'
  • 通过引用包含起始或结尾的空格：
    '  this string starts and ends with whitespaces  '
  • 转义和引用可以混合使用：
    ' The string '\'string\'' is a string '
  • 要包含字面量‘\’可以使用转义或引用：
    'c:\foo' can be written as c:\\foo

2.2 日期

接受的语法是：

[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
now

如果值为"now"，则采用当前时间。

时间是本地时间，除非添加了Z，表示作为UTC时间解析。 如果未指定年月日部分，则采用当前年月日。

2.3 时间持续

有两种接受的表示时间持续的语法。

[-][HH:]MM:SS[.m...]

HH表示小时数，MM表示分钟数，最多2位数字，SS表示秒数，最多2位数字。末尾的m表示小数值，适用于SS.

或 

[-]S+[.m...][s|ms|us]

S表示秒数，带有可选的小数部分m。可选的字面后缀‘s’, ‘ms’或‘us’表示将值解释为秒、毫秒或微秒。

在两种表达方式中，可选的‘-’表示负持续时间。

2.3.1 示例

以下示例均为有效的时间持续：

‘55’

55秒

‘0.2’

0.2秒

‘200ms’

200毫秒，即0.2秒

‘200000us’

200000微秒，即0.2秒

‘12:03:45’

12小时，03分钟和45秒

‘23.189’

23.189秒

2.4 视频尺寸

指定源视频的尺寸，可以是形式为宽度x高度的字符串，也可以是尺寸的简写名称。

以下缩写被识别：

‘ntsc’

720x480

‘pal’

720x576

‘qntsc’

352x240

‘qpal’

352x288

‘sntsc’

640x480

‘spal’

768x576

‘film’

352x240

‘ntsc-film’

352x240

‘sqcif’

128x96

‘qcif’

176x144

‘cif’

352x288

‘4cif’

704x576

‘16cif’

1408x1152

‘qqvga’

160x120

‘qvga’

320x240

‘vga’

640x480

‘svga’

800x600

‘xga’

1024x768

‘uxga’

1600x1200

‘qxga’

2048x1536

‘sxga’

1280x1024

‘qsxga’

2560x2048

‘hsxga’

5120x4096

‘wvga’

852x480

‘wxga’

1366x768

‘wsxga’

1600x1024

‘wuxga’

1920x1200

‘woxga’

2560x1600

‘wqsxga’

3200x2048

‘wquxga’

3840x2400

‘whsxga’

6400x4096

‘whuxga’

7680x4800

‘cga’

320x200

‘ega’

640x350

‘hd480’

852x480

‘hd720’

1280x720

‘hd1080’

1920x1080

‘2k’

2048x1080

‘2kflat’

1998x1080

‘2kscope’

2048x858

‘4k’

4096x2160

‘4kflat’

3996x2160

‘4kscope’

4096x1716

‘nhd’

640x360

‘hqvga’

240x160

‘wqvga’

400x240

‘fwqvga’

432x240

‘hvga’

480x320

‘qhd’

960x540

‘2kdci’

2048x1080

‘4kdci’

4096x2160

‘uhd2160’

3840x2160

‘uhd4320’

7680x4320

2.5 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 frame_rate_num/frame_rate_den, an integer number, a float number or a valid video frame rate abbreviation.

The following abbreviations are recognized:

‘ntsc’

30000/1001

‘pal’

25/1

‘qntsc’

30000/1001

‘qpal’

25/1

‘sntsc’

30000/1001

‘spal’

25/1

‘film’

24/1

‘ntsc-film’

24000/1001

2.6 Ratio

A ratio can be expressed as an expression, or in the form numerator: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.

2.7 Color

It can be the name of a color as defined below (case insensitive match) or a [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 (‘0x00’ or ‘0.0’ means completely transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha component is not specified then ‘0xff’ is assumed.

The string ‘random’ will result in a random color.

The following names of colors are recognized:

‘AliceBlue’

0xF0F8FF

‘AntiqueWhite’

0xFAEBD7

‘Aqua’

0x00FFFF

‘Aquamarine’

0x7FFFD4

‘Azure’

0xF0FFFF

‘Beige’

0xF5F5DC

‘Bisque’

0xFFE4C4

‘Black’

0x000000

‘BlanchedAlmond’

0xFFEBCD

‘Blue’

0x0000FF

‘BlueViolet’

0x8A2BE2

‘Brown’

0xA52A2A

‘BurlyWood’

0xDEB887

‘CadetBlue’

0x5F9EA0

‘Chartreuse’

0x7FFF00

‘Chocolate’

0xD2691E

‘Coral’

0xFF7F50

‘CornflowerBlue’

0x6495ED

‘Cornsilk’

0xFFF8DC

‘Crimson’

0xDC143C

‘Cyan’

0x00FFFF

‘DarkBlue’

0x00008B

‘DarkCyan’

0x008B8B

‘DarkGoldenRod’

0xB8860B

‘DarkGray’

0xA9A9A9

‘DarkGreen’

0x006400

‘DarkKhaki’

0xBDB76B

‘DarkMagenta’

0x8B008B

‘DarkOliveGreen’

0x556B2F

‘Darkorange’

0xFF8C00

‘DarkOrchid’

0x9932CC

‘DarkRed’

0x8B0000

‘DarkSalmon’

0xE9967A

‘DarkSeaGreen’

0x8FBC8F

‘DarkSlateBlue’

0x483D8B

‘DarkSlateGray’

0x2F4F4F

‘DarkTurquoise’

0x00CED1

‘DarkViolet’

0x9400D3

‘DeepPink’

0xFF1493

‘DeepSkyBlue’

0x00BFFF

‘DimGray’

0x696969

‘DodgerBlue’

0x1E90FF

‘FireBrick’

0xB22222

‘FloralWhite’

0xFFFAF0

‘ForestGreen’

0x228B22

‘Fuchsia’

0xFF00FF

‘Gainsboro’

0xDCDCDC

‘GhostWhite’

0xF8F8FF

‘Gold’

0xFFD700

‘GoldenRod’

0xDAA520

‘Gray’

0x808080

‘Green’

0x008000

‘GreenYellow’

0xADFF2F

‘HoneyDew’

0xF0FFF0

‘HotPink’

0xFF69B4

‘IndianRed’

0xCD5C5C

‘Indigo’

0x4B0082

‘Ivory’

0xFFFFF0

‘Khaki’

0xF0E68C

‘Lavender’

0xE6E6FA

‘LavenderBlush’

0xFFF0F5

‘LawnGreen’

0x7CFC00

‘LemonChiffon’

0xFFFACD

‘LightBlue’

0xADD8E6

‘LightCoral’

0xF08080

‘LightCyan’

0xE0FFFF

‘LightGoldenRodYellow’

0xFAFAD2

‘LightGreen’

0x90EE90

‘LightGrey’

0xD3D3D3

‘LightPink’

0xFFB6C1

‘LightSalmon’

0xFFA07A

‘LightSeaGreen’

0x20B2AA

‘LightSkyBlue’

0x87CEFA

‘LightSlateGray’

0x778899

‘LightSteelBlue’

0xB0C4DE

‘LightYellow’

0xFFFFE0

‘Lime’

0x00FF00

‘LimeGreen’

0x32CD32

‘Linen’

0xFAF0E6

‘Magenta’

0xFF00FF

‘Maroon’

0x800000

‘MediumAquaMarine’

0x66CDAA

‘MediumBlue’

0x0000CD

‘MediumOrchid’

0xBA55D3

‘MediumPurple’

0x9370D8

‘MediumSeaGreen’

0x3CB371

‘MediumSlateBlue’

0x7B68EE

‘MediumSpringGreen’

0x00FA9A

‘MediumTurquoise’

0x48D1CC

‘MediumVioletRed’

0xC71585

‘MidnightBlue’

0x191970

‘MintCream’

0xF5FFFA

‘MistyRose’

0xFFE4E1

‘Moccasin’

0xFFE4B5

‘NavajoWhite’

0xFFDEAD

‘Navy’

0x000080

‘OldLace’

0xFDF5E6

‘Olive’

0x808000

‘OliveDrab’

0x6B8E23

‘Orange’

0xFFA500

‘OrangeRed’

0xFF4500

‘Orchid’

0xDA70D6

‘PaleGoldenRod’

0xEEE8AA

‘PaleGreen’

0x98FB98

‘PaleTurquoise’

0xAFEEEE

‘PaleVioletRed’

0xD87093

‘PapayaWhip’

0xFFEFD5

‘PeachPuff’

0xFFDAB9

‘Peru’

0xCD853F

‘Pink’

0xFFC0CB

‘Plum’

0xDDA0DD

‘PowderBlue’

0xB0E0E6

‘Purple’

0x800080

‘Red’

0xFF0000

‘RosyBrown’

0xBC8F8F

‘RoyalBlue’

0x4169E1

‘SaddleBrown’

0x8B4513

‘Salmon’

0xFA8072

‘SandyBrown’

0xF4A460

‘SeaGreen’

0x2E8B57

‘SeaShell’

0xFFF5EE

‘Sienna’

0xA0522D

‘Silver’

0xC0C0C0

‘SkyBlue’

0x87CEEB

‘SlateBlue’

0x6A5ACD

‘SlateGray’

0x708090

‘Snow’

0xFFFAFA

‘SpringGreen’

0x00FF7F

‘SteelBlue’

0x4682B4

‘Tan’

0xD2B48C

‘Teal’

0x008080

‘Thistle’

0xD8BFD8

‘Tomato’

0xFF6347

‘Turquoise’

0x40E0D0

‘Violet’

0xEE82EE

‘Wheat’

0xF5DEB3

‘White’

0xFFFFFF

‘WhiteSmoke’

0xF5F5F5

‘Yellow’

0xFFFF00

‘YellowGreen’

0x9ACD32

2.8 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:

‘FL’

front left

‘FR’

front right

‘FC’

front center

‘LFE’

low frequency

‘BL’

back left

‘BR’

back right

‘FLC’

front left-of-center

‘FRC’

front right-of-center

‘BC’

back center

‘SL’

side left

‘SR’

side right

‘TC’

top center

‘TFL’

top front left

‘TFC’

top front center

‘TFR’

top front right

‘TBL’

top back left

‘TBC’

top back center

‘TBR’

top back right

‘DL’

downmix left

‘DR’

downmix right

‘WL’

wide left

‘WR’

wide right

‘SDL’

surround direct left

‘SDR’

surround direct right

‘LFE2’

low frequency 2

Standard channel layout compositions can be specified by using the following identifiers:

‘mono’

FC

‘stereo’

FL+FR

‘2.1’

FL+FR+LFE

‘3.0’

FL+FR+FC

‘3.0(back)’

FL+FR+BC

‘4.0’

FL+FR+FC+BC

‘quad’

FL+FR+BL+BR

‘quad(side)’

FL+FR+SL+SR

‘3.1’

FL+FR+FC+LFE

‘5.0’

FL+FR+FC+BL+BR

‘5.0(side)’

FL+FR+FC+SL+SR

‘4.1’

FL+FR+FC+LFE+BC

‘5.1’

FL+FR+FC+LFE+BL+BR

‘5.1(side)’

FL+FR+FC+LFE+SL+SR

‘6.0’

FL+FR+FC+BC+SL+SR

‘6.0(front)’

FL+FR+FLC+FRC+SL+SR

‘3.1.2’

FL+FR+FC+LFE+TFL+TFR

‘hexagonal’

FL+FR+FC+BL+BR+BC

‘6.1’

FL+FR+FC+LFE+BC+SL+SR

‘6.1’

FL+FR+FC+LFE+BL+BR+BC

‘6.1(front)’

FL+FR+LFE+FLC+FRC+SL+SR

‘7.0’

FL+FR+FC+BL+BR+SL+SR

‘7.0(front)’

FL+FR+FC+FLC+FRC+SL+SR

‘7.1’

FL+FR+FC+LFE+BL+BR+SL+SR

‘7.1(wide)’

FL+FR+FC+LFE+BL+BR+FLC+FRC

‘7.1(wide-side)’

FL+FR+FC+LFE+FLC+FRC+SL+SR

‘5.1.2’

FL+FR+FC+LFE+BL+BR+TFL+TFR

‘octagonal’

FL+FR+FC+BL+BR+BC+SL+SR

‘cube’

FL+FR+BL+BR+TFL+TFR+TBL+TBR

‘5.1.4’

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR

‘7.1.2’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR

‘7.1.4’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR

‘7.2.3’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2

‘9.1.4’

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR

‘hexadecagonal’

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR

‘downmix’

DL+DR

‘22.2’

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR

A custom channel layout can be specified as a sequence of terms, separated by ’+’. Each term can be:

  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, ‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.)

A standard channel layout can be specified by the following:

  • the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.)
  • the name of a standard channel layout (e.g. ‘mono’, ‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.)
  • a number of channels, in decimal, followed by ’c’, yielding the default channel layout for that number of channels (see the function av_channel_layout_default). Note that not all channel counts have a default layout.
  • 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.
  • a channel layout mask, in hexadecimal starting with "0x" (see the AV_CH_* macros in libavutil/channel_layout.h.

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 av_channel_layout_from_string defined in libavutil/channel_layout.h.

3 Expression Evaluation

When evaluating an arithmetic expression, FFmpeg uses an internal formula evaluator, implemented through the libavutil/eval.h interface.

An expression may contain unary, binary operators, constants, and functions.

Two expressions expr1 and expr2 can be combined to form another expression "expr1;expr2". expr1 and expr2 are evaluated in turn, and the new expression evaluates to the value of expr2.

The following binary operators are available: +, -, *, /, ^.

The following unary operators are available: +, -.

Some internal variables can be used to store and load intermediary results. They can be accessed using the ld and st functions with an index argument varying from 0 to 9 to specify which internal variable to access.

The following functions are available:

abs(x)

Compute absolute value of x.

acos(x)

Compute arccosine of x.

asin(x)

Compute arcsine of x.

atan(x)

Compute arctangent of x.

atan2(y, x)

Compute principal value of the arc tangent of y/x.

between(x, min, max)

Return 1 if x is greater than or equal to min and lesser than or equal to max, 0 otherwise.

bitand(x, y)
bitor(x, y)

Compute bitwise and/or operation on x and y.

The results of the evaluation of x and 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).

ceil(expr)

Round the value of expression expr upwards to the nearest integer. For example, "ceil(1.5)" is "2.0".

clip(x, min, max)

Return the value of x clipped between min and max.

cos(x)

Compute cosine of x.

cosh(x)

Compute hyperbolic cosine of x.

eq(x, y)

Return 1 if x and y are equivalent, 0 otherwise.

exp(x)

Compute exponential of x (with base e，即欧拉数。

floor(expr)

将表达式的值进行取整expr向下取整到最接近的整数。例如，"floor(-1.5)" 的结果是 "-2.0"。

gauss(x)

计算高斯函数x，对应于exp(-x*x/2) / sqrt(2*PI).

gcd(x, y)

返回x和y的最大公约数。如果x和y都为0，或者任意一个小于0，则行为未定义。

gt(x, y)

如果x大于y，返回1，否则返回0。

gte(x, y)

如果x大于或等于y，返回1，否则返回0。

hypot(x, y)

该函数类似于同名的C函数；它返回 "sqrt(x*x + y*y)"，即长度为x和y的直角三角形的斜边长度，或者点 (x, y) 到原点的距离。

if(x, y)

计算x，如果结果非零则返回y的计算结果，否则返回0。

if(x, y, z)

计算x，如果结果非零则返回y的计算结果，否则返回z.

ifnot(x, y)

计算x，如果结果为零则返回y的计算结果，否则返回0。

ifnot(x, y, z)

计算x，如果结果为零则返回y的计算结果，否则返回z.

isinf(x)

如果x是+/−INFINITY，返回1.0，否则返回0.0。

isnan(x)

如果x是NAN，返回1.0，否则返回0.0。

ld(idx)

加载索引为idx的内部变量的值，该变量之前通过st(idx, expr)存储。 函数返回加载的值。

lerp(x, y, z)

在x和y之间进行线性插值，插值量为z.

log(x)

计算x.

lt(x, y)

如果x小于y，返回1，否则返回0。

lte(x, y)

如果x小于或等于y，返回1，否则返回0。

max(x, y)

返回x和y.

min(x, y)

返回x和y.

mod(x, y)

计算x除以y.

not(expr)

如果expr为零，返回1.0，否则返回0.0。

pow(x, y)

计算x的幂次y，相当于"(x)^(y)".

print(t)
print(t, l)

打印表达式的值t，日志级别为l。如果未指定l，将使用默认日志级别。 返回打印的表达式值。

random(idx)

返回0.0到1.0之间的伪随机数。idx是保存种子/状态的内部变量的索引，该变量可以通过之前存储st(idx).

要初始化种子，需要将种子值作为64位无符号整数存储在索引为idx.

的内部变量中。例如，将种子存储为42，并打印几个伪随机值：0 and print a few random values: 

st(0,42); print(random(0)); print(random(0)); print(random(0))
randomi(idx, min, max)

返回在区间min和max. 之间的伪随机值。是保存种子/状态的内部变量的索引，该变量可以通过之前存储st(idx).

要初始化种子，需要将种子值作为64位无符号整数存储在索引idx.

root(expr, max)

寻找一个输入值，使得由expr表示的函数以参数ld(0)和区间 0..max.

表达式expr必须表示连续函数，否则结果未定义。

ld(0)用于表示函数的输入值，这意味着给定表达式将被多次评估，使用表达式可通过ld(0)访问的各种输入值。当表达式评估为 0时，将返回对应的输入值。

round(expr)

对表达式的值进行四舍五入expr到最接近的整数。例如，"round(1.5)"是"2.0"。

sgn(x)

计算x.

sin(x)

的符号。x.

sinh(x)

的正弦值。x.

sqrt(expr)

的双曲正弦值。expr的平方根。这相当于"(expr)^.5".

squish(x)

计算表达式1/(1 + exp(4*x)).

st(idx, expr)

存储表达式expr的值到一个内部变量中。idx指定要存储的变量索引，范围从0到9。函数返回存储在内部变量中的值。

存储的值可以通过ld(var).

检索。 注意：变量目前在表达式之间不可共享。

tan(x)

计算x.

tanh(x)

的正切值。x.

taylor(expr, x)
taylor(expr, x, idx)

计算给定x的泰勒级数，基于表达表示ld(idx)某一阶导数值的表达式。

如果级数不收敛，则结果未定义。

ld(idx)用来表示导数阶数，这意味着给定的表达式将被多次评估，使用表达式可通过expr访问的各种输入值。ld(idx)如果idx未指定，则假定为0。

注意，当你有关于 y 的导数值，而不是关于 0 时，可以使用taylor(expr, x-y)。

time(0)

返回当前（壁钟时间）时间，以秒为单位。

trunc(expr)

对表达式的值进行向零取整expr到最接近整数。例如，"trunc(-1.5)"是"-1.0"。

while(cond, expr)

计算表达式expr当表达式cond的值非零时，返回最后一个expr计算的结果或如果cond始终为假，返回 NAN。

以下常量可用：

PI

单位圆面积，约为3.14

E

exp(1)（欧拉数），约为2.718

PHI

黄金分割比值 (1+sqrt(5))/2，约为1.618

假设表达式具有非零值时被认为是"真"，注意：

*类似于 AND

+类似于 OR

例如构造：

if (A AND B) then C

等效于：

if(A*B, C)

在您的C代码中，您可以扩展一元和二元函数的列表，并定义可识别的常数，以便它们可供您的表达式使用。

评估器还可识别国际单位制前缀。如果前缀后附加'i'，则使用二进制前缀，基于1024的幂而非1000的幂。 'B'后缀将值乘以8，可以附加在单位前缀之后，也可以单独使用。这使得您可以使用例如'KB'、'MiB'、'G'和'B'作为数字后缀。

以下是可用国际单位制前缀的列表，并指出相应的10的幂和2的幂。

y

10^-24 / 2^-80

z

10^-21 / 2^-70

a

10^-18 / 2^-60

f

10^-15 / 2^-50

p

10^-12 / 2^-40

n

10^-9 / 2^-30

u

10^-6 / 2^-20

m

10^-3 / 2^-10

c

10^-2

d

10^-1

h

10^2

k

10^3 / 2^10

K

10^3 / 2^10

M

10^6 / 2^20

G

10^9 / 2^30

T

10^12 / 2^40

P

10^15 / 2^50

E

10^18 / 2^60

Z

10^21 / 2^70

Y

10^24 / 2^80

4 参考资料

ffmpeg, ffplay, ffprobe, libavutil

5 作者

FFmpeg 开发者。

有关作者的详细信息，请查看项目的 Git 历史 （https://git.ffmpeg.org/ffmpeg），例如通过在FFmpeg源码目录中键入以下命令git log或浏览以下在线存储库https://git.ffmpeg.org/ffmpeg.

特定组件的维护者在源代码树中列出文件MAINTAINERS中。

本文档通过makeinfo.

主机由telepoint.bg 提供。