FFmpeg 工具文档

千里马-horse2025-12-10 16:44

目录

[1. 描述](#1. 描述)

[2. 语法](#2. 语法)

[2.1 引用与转义](#2.1 引用与转义)

[2.1.1 示例](#2.1.1 示例)

[2.2 日期](#2.2 日期)

[2.3 时间长度](#2.3 时间长度)

[2.3.1 示例](#2.3.1 示例)

[2.4 视频尺寸](#2.4 视频尺寸)

[2.5 视频帧率](#2.5 视频帧率)

[2.6 比率](#2.6 比率)

[2.7 颜色](#2.7 颜色)

[Alpha 通道说明](#Alpha 通道说明)

特殊颜色

支持的颜色名称及对应值

[2.8 声道布局](#2.8 声道布局)

单个声道标识

标准声道布局组合

自定义声道布局

版本兼容说明

[3. 表达式求值](#3. 表达式求值)

基本规则

运算符

二元运算符

一元运算符

内部变量

函数列表

常量

逻辑运算

扩展能力

单位前缀

单位前缀对应表

1. 描述

本文档介绍 libavutil 库提供的一些通用特性和工具。

2. 语法

本节说明 FFmpeg 库和工具所采用的语法和格式。

2.1 引用与转义

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

  • ''' 和 '\' 是特殊字符（分别用于引用和转义）。此外，根据转义和引用所使用的具体语法，可能还存在其他特殊字符。
  • 特殊字符可通过在其前面添加 '\' 进行转义。
  • 包含在 '''' 之间的所有字符均按原样包含在解析后的字符串中。引用字符 ''' 本身无法被引用，因此可能需要关闭引用并对其进行转义。
  • 除非经过转义或引用，否则解析后的字符串将移除前导和尾随空格。
  • 注意，在使用命令行或脚本时，可能需要添加第二层转义，这取决于所采用的 Shell 语言的语法。

libavutil/avstring.h 中定义的 av_get_token 函数可用于解析按照上述规则引用或转义的令牌。

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

2.1.1 示例

转义包含特殊字符 ''' 的字符串 Crime d'Amour：

cpp 复制代码 
Crime d\'Amour

上述字符串包含引号，因此在引用时需要对 ''' 进行转义：

复制代码 
'Crime d'\''Amour'

通过引用包含前导或尾随空格：

复制代码 
'  this string starts and ends with whitespaces  '

转义和引用可以混合使用：

复制代码 
' The string '\'string\'' is a string '

要包含字面意义上的 '\'，可以使用转义或引用：

cpp 复制代码 
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 时间长度

表示时间长度支持两种语法格式：

cpp 复制代码 
[-][HH:]MM:SS[.m...]
  • HH 表示小时数，MM 表示分钟数（最多 2 位数字），SS 表示秒数（最多 2 位数字）。
  • 末尾的 m 表示 SS 的小数部分。
cpp 复制代码 
[-]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 通道说明
  • Alpha 通道值可为：
    • "0x" 后跟十六进制数
    • 0.0 到 1.0 之间的十进制数（表示不透明度：'0x00' 或 '0.0' 表示完全透明，'0xff' 或 '1.0' 表示完全不透明）。
  • 若未指定 Alpha 通道，则默认值为 '0xff'。
特殊颜色
  • 字符串 'random' 表示随机颜色。
支持的颜色名称及对应值
颜色名称 十六进制值
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 声道布局

声道布局指定多声道音频流中声道的空间分布。FFmpeg 使用特殊语法指定声道布局。

单个声道标识
声道标识 说明
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 第二低频声道
标准声道布局组合
布局标识 包含声道组合
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 / 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' 等），可在 '@' 后添加自定义名称（如 'FL@Left'、'FR@Right' 等）。
  • 标准声道布局名称（如 'mono'、'stereo' 等）。
  • 十进制数字 + '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 接口实现。

基本规则

  • 表达式可包含一元运算符、二元运算符、常量和函数。
  • 两个表达式 expr1 和 expr2 可组合为新表达式 "expr1;expr2"，按顺序求值，结果为 expr2 的值。

运算符

二元运算符

+（加）、-（减）、*（乘）、/（除）、^（幂）

一元运算符

+（正）、-（负）

内部变量

可通过 ld 和 st 函数访问内部变量（索引 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) 对 x 和 y 执行按位与运算（先转换为整数，可能丢失精度）
bitor(x, y) 对 x 和 y 执行按位或运算（先转换为整数，可能丢失精度）
ceil(expr) 向上取整（例：ceil (1.5) = 2.0）
clip(x, min, max) 将 x 限制在 [min, max] 范围内
cos(x) 计算 x 的余弦值
cosh(x) 计算 x 的双曲余弦值
eq(x, y) 若 x 与 y 相等返回 1，否则返回 0
exp(x) 计算 e 的 x 次方（e 为自然常数）
floor(expr) 向下取整（例：floor (-1.5) = -2.0）
gauss(x) 计算高斯函数：exp (-xx/2) / sqrt(2PI)
gcd(x, y) 计算 x 和 y 的最大公约数（x、y 均为 0 或存在负数时行为未定义）
gt(x, y) 若 x > y 返回 1，否则返回 0
gte(x, y) 若 x >= y 返回 1，否则返回 0
hypot(x, y) 计算直角三角形斜边长度：sqrt (xx + yy)
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 存储）
lerp(x, y, z) 按 z 比例在 x 和 y 之间线性插值
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) 打印 t 的值（使用默认日志级别），返回打印的值
print(t, l) 按日志级别 l 打印 t 的值，返回打印的值
random(idx) 返回 0.0-1.0 之间的伪随机数（idx 为存储种子 / 状态的内部变量索引，需先初始化种子）
randomi(idx, min, max) 返回 [min, max] 范围内的伪随机数（idx 为种子存储索引，需先初始化种子）
root(expr, max) 在 0..max 区间内查找使 expr（以 ld (0) 为参数）等于 0 的输入值（expr 需为连续函数）
round(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），返回存储的值
tan(x) 计算 x 的正切值
tanh(x) 计算 x 的双曲正切值
taylor(expr, x) 在 x 处计算泰勒级数（expr 表示 ld (0) 阶导数在 0 点的值，未收敛时结果未定义）
taylor(expr, x, idx) 在 x 处计算泰勒级数（idx 指定导数阶数的内部变量索引，默认 0）
time(0) 返回当前系统时间（秒数）
trunc(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 的幂），后缀 '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/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
相关推荐
一点晖光11 小时前
ffmpeg合成的视频在ios浏览器不能播放的问题
ffmpeg·音视频
天黑请闭眼11 小时前
linux：ffmpeg服务安装
linux·ffmpeg
小c君tt11 小时前
FFmpeg音视频-库使用2
qt·ffmpeg·音视频
一点都不方女士12 小时前
Windows系统提示“找不到ffmpeg.dll”？3种下载修复指南
windows·ffmpeg·dll·命令行·动态链接库·运行库
一点晖光13 小时前
ffmpeg压缩图片和视频
ffmpeg·音视频·图片处理
小c君tt13 小时前
FFmpeg库函数使用流程
qt·ffmpeg
小尧嵌入式13 小时前
在windows上安装ffmpeg及新版ffmpeg命令
c++·windows·算法·ffmpeg
别动哪条鱼13 小时前
AVFrame的data数组数据结构详解
网络·数据结构·ffmpeg
小c君tt13 小时前
FFmpeg在QT中的使用3
开发语言·qt·ffmpeg
热门推荐
01GitHub 镜像站点02【超详细教程】手把手教你从微软官网免费下载Windows 10官方原版ISO镜像（2025最新版）03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04UV安装并设置国内源05BongoCat - 跨平台键盘猫动画工具06Linux下V2Ray安装配置指南07React CVE-2025-55182漏洞排查与修复指南08本地部署阿里最新开源的Z-Image09从入门到实战：Gemini 3 使用指南速览10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）