FFmpeg 工具文档

目录

1 描述

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

2 语法

本节介绍 FFmpeg 库和工具使用的语法和格式。

2.1 引号和转义

除非另有明确说明,否则 FFmpeg 采用以下引号和转义机制。应用以下规则

  • '’ 和 ‘\’ 是特殊字符(分别用于引号和转义)。除此之外,根据使用转义和引号的特定语法,可能还存在其他特殊字符。
  • 通过在特殊字符前加上 ‘\’ 来对其进行转义。
  • 所有包含在 ‘''’ 之间的字符都会按字面包含在解析的字符串中。引号字符 ‘'’ 本身不能被引用,因此您可能需要关闭引号并对其进行转义。
  • 除非转义或引用,否则前导和尾随空格将从解析的字符串中删除。

请注意,当使用命令行或脚本时,您可能需要添加第二级转义,这取决于所采用的 shell 语言的语法。

定义在 libavutil/avstring.h 中的函数 av_get_token 可用于根据上述规则解析带引号或转义的标记。

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

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 视频尺寸

指定源视频的大小,它可能是 widthxheight 形式的字符串,或者是大小缩写的名称。

以下缩写被识别

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 视频帧率

指定视频的帧率,表示为每秒生成的帧数。它必须是 frame_rate_num/frame_rate_den 格式的字符串、一个整数、一个浮点数或有效的视频帧率缩写。

以下缩写被识别

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 比率

比率可以表示为表达式,或者以 numerator:denominator 的形式表示。

请注意,具有无限 (1/0) 或负值的比率被认为是有效的,因此如果您想排除这些值,则应检查返回值。

可以使用“0:0”字符串表示未定义的值。

2.7 颜色

它可以是下面定义的颜色名称(不区分大小写匹配)或 [0x|#]RRGGBB[AA] 序列,可能后跟 @ 和表示 alpha 分量的字符串。

alpha 分量可以是 "0x" 后跟十六进制数字组成的字符串,也可以是介于 0.0 和 1.0 之间的十进制数,它表示不透明度值(‘0x00’ 或 ‘0.0’ 表示完全透明,‘0xff’ 或 ‘1.0’ 表示完全不透明)。如果未指定 alpha 分量,则假定为 ‘0xff’。

字符串 ‘random’ 将产生随机颜色。

以下是可识别的颜色名称

爱丽丝蓝

0xF0F8FF

古董白

0xFAEBD7

水色

0x00FFFF

海蓝宝石色

0x7FFFD4

天蓝色

0xF0FFFF

米色

0xF5F5DC

瓷白色

0xFFE4C4

黑色

0x000000

杏仁白

0xFFEBCD

蓝色

0x0000FF

蓝紫色

0x8A2BE2

棕色

0xA52A2A

原木色

0xDEB887

军蓝色

0x5F9EA0

黄绿色

0x7FFF00

巧克力色

0xD2691E

珊瑚色

0xFF7F50

矢车菊蓝

0x6495ED

玉米色

0xFFF8DC

深红色

0xDC143C

青色

0x00FFFF

深蓝色

0x00008B

深青色

0x008B8B

深金黄色

0xB8860B

深灰色

0xA9A9A9

深绿色

0x006400

深卡其色

0xBDB76B

深洋红色

0x8B008B

深橄榄绿

0x556B2F

深橙色

0xFF8C00

深兰花色

0x9932CC

深红色

0x8B0000

深鲑鱼色

0xE9967A

深海绿色

0x8FBC8F

深石板蓝色

0x483D8B

深石板灰色

0x2F4F4F

深绿松石色

0x00CED1

深紫色

0x9400D3

深粉红色

0xFF1493

深天蓝色

0x00BFFF

暗灰色

0x696969

道奇蓝

0x1E90FF

耐火砖红

0xB22222

花白色

0xFFFAF0

森林绿

0x228B22

紫红色

0xFF00FF

淡灰色

0xDCDCDC

幽灵白

0xF8F8FF

金色

0xFFD700

金麒麟色

0xDAA520

灰色

0x808080

绿色

0x008000

黄绿色

0xADFF2F

蜜色

0xF0FFF0

热粉红色

0xFF69B4

印度红

0xCD5C5C

靛蓝色

0x4B0082

象牙色

0xFFFFF0

卡其色

0xF0E68C

淡紫色

0xE6E6FA

淡紫红

0xFFF0F5

草绿色

0x7CFC00

柠檬绸色

0xFFFACD

浅蓝色

0xADD8E6

浅珊瑚色

0xF08080

浅青色

0xE0FFFF

浅金黄色

0xFAFAD2

浅绿色

0x90EE90

浅灰色

0xD3D3D3

浅粉红色

0xFFB6C1

浅鲑鱼色

0xFFA07A

浅海绿色

0x20B2AA

浅天蓝色

0x87CEFA

浅石板灰色

0x778899

浅钢蓝色

0xB0C4DE

浅黄色

0xFFFFE0

酸橙色

0x00FF00

酸橙绿

0x32CD32

亚麻色

0xFAF0E6

洋红色

0xFF00FF

栗色

0x800000

中海蓝宝石色

0x66CDAA

中蓝色

0x0000CD

中兰花色

0xBA55D3

中紫色

0x9370D8

中海绿色

0x3CB371

中石板蓝色

0x7B68EE

中春绿色

0x00FA9A

中绿松石色

0x48D1CC

中紫红色

0xC71585

午夜蓝

0x191970

薄荷奶油色

0xF5FFFA

雾玫瑰色

0xFFE4E1

鹿皮色

0xFFE4B5

纳瓦白

0xFFDEAD

海军蓝

0x000080

旧蕾丝色

0xFDF5E6

橄榄色

0x808000

深绿褐色

0x6B8E23

橙色

0xFFA500

橙红色

0xFF4500

兰花色

0xDA70D6

苍麒麟色

0xEEE8AA

苍绿色

0x98FB98

苍绿松石色

0xAFEEEE

苍紫红色

0xD87093

番木瓜色

0xFFEFD5

桃色

0xFFDAB9

秘鲁色

0xCD853F

粉红色

0xFFC0CB

李子色

0xDDA0DD

粉蓝色

0xB0E0E6

紫色

0x800080

红色

0xFF0000

玫瑰棕色

0xBC8F8F

宝蓝色

0x4169E1

马鞍棕色

0x8B4513

鲑鱼色

0xFA8072

沙棕色

0xF4A460

海绿色

0x2E8B57

海贝色

0xFFF5EE

赭色

0xA0522D

银色

0xC0C0C0

天蓝色

0x87CEEB

石板蓝色

0x6A5ACD

石板灰色

0x708090

雪白色

0xFFFAFA

春绿色

0x00FF7F

钢蓝色

0x4682B4

棕褐色

0xD2B48C

水鸭色

0x008080

蓟色

0xD8BFD8

番茄色

0xFF6347

绿松石色

0x40E0D0

紫色

0xEE82EE

小麦色

0xF5DEB3

白色

0xFFFFFF

白烟色

0xF5F5F5

黄色

0xFFFF00

黄绿色

0x9ACD32

2.8 声道布局

通道布局指定多通道音频流中通道的空间分布。为了指定通道布局,FFmpeg 使用了一种特殊的语法。

各个通道通过 id 标识,如下表所示

FL

前左

FR

前右

FC

前中

LFE

低频

BL

后左

BR

后右

FLC

前偏左

FRC

前偏右

BC

后中

SL

侧左

SR

侧右

TC

顶中

TFL

顶部前左

TFC

顶部前中

TFR

顶部前右

TBL

顶部后左

TBC

顶部后中

TBR

顶部后右

DL

混音左

DR

混音右

WL

宽左

WR

宽右

SDL

环绕直达左

SDR

环绕直达右

LFE2

低频 2

可以使用以下标识符指定标准声道布局组成

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

9.1.6

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

hexadecagonal

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

binaural

BIL+BIR

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

自定义声道布局可以指定为以“+”分隔的项的序列。每项可以是

  • 单个声道的名称(例如“FL”,“FR”,“FC”,“LFE”等),每个声道可以选择在“@”之后包含自定义名称(例如“FL@Left”,“FR@Right”,“FC@Center”,“LFE@Low_Frequency”等)

可以使用以下方式指定标准声道布局

  • 单个声道的名称(例如“FL”,“FR”,“FC”,“LFE”等)
  • 标准声道布局的名称(例如“mono”,“stereo”,“4.0”,“quad”,“5.0”等)
  • 声道的数量,以十进制表示,后跟“c”,产生该声道数量的默认声道布局(请参阅函数av_channel_layout_default)。请注意,并非所有声道计数都有默认布局。
  • 声道的数量,以十进制表示,后跟“C”,产生具有指定声道数量的未知声道布局。请注意,并非所有声道布局规范字符串都支持未知声道布局。
  • 声道布局掩码,以十六进制表示,以“0x”开头(请参阅 libavutil/channel_layout.h 中的 AV_CH_* 宏)。

在 libavutil 版本 53 之前,指定声道数量的尾随字符“c”是可选的,但现在是必需的,而声道布局掩码也可以指定为十进制数(当且仅当后面没有跟“c”或“C”时)。

另请参阅libavutil/channel_layout.h中定义的函数av_channel_layout_from_string

3 表达式求值

在评估算术表达式时,FFmpeg 使用内部公式评估器,该评估器通过 libavutil/eval.h 接口实现。

表达式可能包含一元运算符,二元运算符,常量和函数。

可以将两个表达式 expr1expr2 组合以形成另一个表达式“expr1;expr2”。expr1expr2 依次求值,新表达式的值为 expr2 的值。

以下二元运算符可用:+-*/^

以下一元运算符可用:+-

可以使用一些内部变量来存储和加载中间结果。可以使用 ldst 函数访问它们,索引参数从 0 到 9 不等,以指定要访问的内部变量。

以下函数可用

abs(x)

计算 x 的绝对值。

acos(x)

计算 x 的反余弦。

asin(x)

计算 x 的反正弦。

atan(x)

计算 x 的反正切。

atan2(y, x)

计算 y/x 的反正切的主值。

between(x, min, max)

如果 x 大于或等于 min 且小于或等于 max,则返回 1,否则返回 0。

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

计算 xy 的按位与/或运算。

在执行按位运算之前,将 xy 的计算结果转换为整数。

请注意,转换为整数和转换回浮点数都可能失去精度。请注意大数(通常为 2^53 及更大)的意外结果。

ceil(expr)

将表达式 expr 的值向上舍入到最接近的整数。例如,“ceil(1.5)”为“2.0”。

clip(x, min, max)

返回 x 的值,该值被限制在 minmax 之间。

cos(x)

计算 x 的余弦。

cosh(x)

计算 x 的双曲余弦。

eq(x, y)

如果 xy 相等,则返回 1,否则返回 0。

exp(x)

计算 x 的指数(以 e 为底,即欧拉数)。

floor(expr)

将表达式 expr 的值向下舍入到最接近的整数。例如,“floor(-1.5)”为“-2.0”。

gauss(x)

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

gcd(x, y)

返回 xy 的最大公约数。如果 xy 均为 0 或其中一个或两个均小于零,则行为未定义。

gt(x, y)

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

gte(x, y)

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

hypot(x, y)

此函数与具有相同名称的 C 函数类似;它返回“sqrt(x*x + y*y)”,即边长为 xy 的直角三角形的斜边长度,或点 (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)

返回 xy 之间按 z 量进行的线性插值。

log(x)

计算 x 的自然对数。

lt(x, y)

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

lte(x, y)

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

max(x, y)

返回 xy 之间的最大值。

min(x, y)

返回 xy 之间的最小值。

mod(x, y)

计算 x 除以 y 的余数。

not(expr)

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

pow(x, y)

计算 xy 次幂,等效于 "(x)^(y)"。

print(t)
print(t, l)

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

random(idx)

返回 0.0 到 1.0 之间的伪随机值。idx 是用于保存种子/状态的内部变量的索引,该值之前可以使用 st(idx) 存储。

要初始化种子,您需要将种子值作为 64 位无符号整数存储在索引为 idx 的内部变量中。

例如,要将值为 42 的种子存储在索引为 0 的内部变量中并打印一些随机值

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

返回 minmax 之间的区间内的伪随机值。idx 是用于保存种子/状态的内部变量的索引,该值之前可以使用 st(idx) 存储。

要初始化种子,您需要将种子值作为 64 位无符号整数存储在索引为 idx 的内部变量中。

root(expr, max)

查找一个输入值,使得由带有参数 ld(0)expr 表示的函数在 0..max 区间内为 0。

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 处计算泰勒级数,给定一个表示函数在 0 处的 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)

当表达式 cond 为非零时,计算表达式 expr,并返回最后一个 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 文件中列出。

本文档于 2025 年 1 月 21 日 使用 makeinfo 生成。

托管由 telepoint.bg 提供