7 语法

这个章节介绍采用ffmpeg库和工具时的一些语法和格式要求。

引用与转义(Quoting and escaping)

ffmpeg采用如下的引用和转义机制，除非明确规定，以下规则都适用：

• "'"和"\"分别用于（引用和转义）特殊字符。除了它们可能还有其它特殊字符，但这只在特定的语法中有效。
• 一个特殊字符必须有转义前缀"\"
• 所有的引用字符串都由"'"封闭包含。引号"'"本身不能被引用，所以你可能需要关闭引用或者转义。
• 前导和尾随的空格字符除非专门由引号引用或者转义，否则都会在解析字符串时移除。

注意在使用命令行或者脚本时，你可能需要2级转义，这取决于你shell环境支持的语法。

声明在libavutil/avstring.h中的函数av_get_token被用于任务分析中的引用和转义处理。

ffmpeg源码中的工具tools/ffescape被用于自动处理引用和转义。

语法例子

• 转义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

日期

接受如下的语法:

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

如果值为now表示当前时间

时间是本地时间，除非Z被附加到最后，它表示采用UTC时间。如果年-月-日没有指定就以当前的年-月-日。

持续时间

它有两种表示方式：

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

  HH表示小时数，MM表示分钟数（最多2位数字）SS表示秒数（也最多2位数字），m是SS的小数位值

• [-]S+[.m...]

  S是秒的数值，m是S的小数位值。

两种语法前面都可选'-'号，表示负数持续时间。

持续时间例子

下面均是有效持续时间:

• ‘55’ 表示55秒
• ‘12:03:45’ 表示12小时3分钟45秒
• ‘23.189’ 表示23.189秒

视频尺寸（分辨率）

指定视频源的尺寸大小，它可以是一些表示特定（预设）尺寸的字符串名或者widthxheight（其中width和height都是数字值）的字符串
下面是一些预设的表示尺寸的字符串名及其对应分辨率:

• ‘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

视频帧率

指定视频的帧速率，除了用每秒帧数表示外，还可以用frame_rate_num/frame_rate_den这样的格式字符串表示，此外还有一些预定义的帧率名字符串。
下面就是一些预定义的帧率名及对应的帧率:

• ‘ntsc’ 30000/1001
• ‘pal’ 25/1
• ‘qpal’ 25/1
• ‘sntsc’ 30000/1001
• ‘spal’ 25/1
• ‘film’ 24/1
• ‘ntsc-film’ 24000/1001

  比率

  一个比率值可以是一个表达式或者numerator.denominator一样的含小数值。

注意比率无限值（1/0)或者负数值被认为是有效的，这里你需要摒弃以往的一些看法。

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

颜色/Color

允许采用下面预定义的颜色名或者一个[0x|#]RRGGBB[AA]这样序列的16进制数字值，可以通过@来附加透明度表示，透明度分量（alpha）可以是”0x”后面跟一个16进制数或者0到1之间的十进制字符串，它代表不透明度值（’0x00’或者’0’表示完全透明，’0xFF’或者’1’表示完全不透明），如果没有专门指定透明分量，则默认为’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

通道布局

对于多音频通道的流，一个通道布局可以具体描述其配置情况。为了描述通道布局，ffmpeg采用了一些特殊的语法。

除了可以采用ID标识外，也可以采用下表的预定义:

• ‘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 超重低音

标准的通道布局可以采用如下的定义:

• ‘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
• ‘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
• ‘octagonal’ FL+FR+FC+BL+BR+BC+SL+SR
• ‘downmix’ DL+DR

一个特定的通道布局可以是一组由+或者|连接起来多个值，其中每个值可以是：

• 前面的标准通道布局名，例如’mono’,’stereo’,’4.0’,’quad’,’5.0’等等
• 或者单个命名通道如’FL’,’FR’,’FC’,’LFE’等等
• 多个通道数字序号，使用后缀’c’的十进制，对于利用数字表示的默认通道布局，参考av-get_default_channel_layout说明。
• 通道布局蒙版(mask)，是’0x’起始的16进制，参考在libavutil/channel_layout.h中声明的AV_CH_*宏。

从libavutil版本53开始，尾随’c’的十进制数表示通道变成必须（除非采用16进制的蒙版来表示通道）

参考声明于libavutil/channel_layout.h中的av_get_channel_layout进行深入了解。