FFmpeg 滤镜文档

1 描述

本文档介绍 libavfilter 库提供的滤镜、源（source）和汇（sink）。

2 滤镜处理简介

FFmpeg 中的滤镜处理由 libavfilter 库实现。

在 libavfilter 中，一个滤镜可以有多个输入和多个输出。为了说明可以实现哪些效果，来看下面这个 filtergraph。

                [main]
input --> split ---------------------> overlay --> output
            |                             ^
            |[tmp]                  [flip]|
            +-----> crop --> vflip -------+

这个 filtergraph 将输入流拆分为两条流，然后让其中一条流依次经过 crop 滤镜和 vflip 滤镜处理，再与另一条流叠加合并。可以用下面的命令实现这一效果：

ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT

其结果是视频的上半部分会被镜像映射到输出视频的下半部分。

同一条线性链中的滤镜用逗号分隔，不同的线性链之间用分号分隔。在这个示例中，crop,vflip 属于同一条线性链，split 和 overlay 则分别位于另一条链中。线性链的连接点用方括号中的名称标注。示例中，split 滤镜生成两个输出，分别关联到标签 [main] 和 [tmp]。

split 的第二个输出（标注为 [tmp]）所对应的流会经过 crop 滤镜处理，裁去视频的下半部分，然后再做垂直翻转。overlay 滤镜以 split 滤镜未经改动的第一个输出（标注为 [main]）作为输入，将 crop,vflip 滤镜链生成的输出叠加到其下半部分。

有些滤镜的输入是一组参数：这些参数写在滤镜名和一个等号之后，彼此之间用冒号分隔。

存在所谓的源滤镜，它们没有音频/视频输入；也存在汇滤镜，它们没有音频/视频输出。

3 graph2dot

FFmpeg 工具目录中包含的 graph2dot 程序可用来解析 filtergraph 描述，并输出对应的 dot 语言文本表示。

执行下面的命令：

graph2dot -h

即可查看 graph2dot 的用法。

之后可以把 dot 描述传给 dot 程序（属于 graphviz 程序套件），从而得到 filtergraph 的图形化表示。

例如，下面这一系列命令：

echo GRAPH_DESCRIPTION | \
tools/graph2dot -o graph.tmp && \
dot -Tpng graph.tmp -o graph.png && \
display graph.png

可用来生成并显示表示 GRAPH_DESCRIPTION 字符串所描述图的图像。注意，这个字符串必须是一个完整的自包含图，其输入和输出都要显式定义。例如，如果命令行形式如下：

ffmpeg -i infile -vf scale=640:360 outfile

那么 GRAPH_DESCRIPTION 字符串就需要写成如下形式：

nullsrc,scale=640:360,nullsink

你可能还需要设置 nullsrc 的参数，并添加一个 format 滤镜以模拟特定的输入文件。

4 Filtergraph 描述

filtergraph 是由若干相连滤镜组成的有向图。它可以包含环路，一对滤镜之间也可以有多条链路。每条链路一侧有一个输入端口，连接到提供输入的滤镜；另一侧有一个输出端口，连接到接收输出的滤镜。

filtergraph 中的每个滤镜都是应用程序中注册的某个滤镜类的实例，该类定义了滤镜的功能以及输入、输出端口的数量。

没有输入端口的滤镜称为“源”，没有输出端口的滤镜称为“汇”。

4.1 Filtergraph 语法

filtergraph 有一种文本表示形式，ffmpeg 的 -filter/-vf/-af 及 -filter_complex 选项、ffplay 的 -vf/-af 选项，以及 libavfilter/avfilter.h 中定义的 avfilter_graph_parse_ptr() 函数都能识别这种形式。

filterchain 由一系列相连的滤镜组成，每个滤镜都与序列中前一个滤镜相连。filterchain 用以“,”分隔的滤镜描述列表来表示。

filtergraph 由一系列 filterchain 组成。这一系列 filterchain 用以“;”分隔的 filterchain 描述列表来表示。

滤镜用下面形式的字符串来表示：[in_link_1]...[in_link_N]filter_name@id=arguments[out_link_1]...[out_link_M]

filter_name 是所描述滤镜作为实例所属滤镜类的名称，必须是程序中已注册的某个滤镜类的名称，其后可以任选地跟上 "@id"。滤镜类的名称之后可以任选地跟上字符串 "=arguments"。

arguments 是包含用于初始化该滤镜实例的参数的字符串，可以是以下两种形式之一：

以“:”分隔的 key=value 对列表。
以“:”分隔的 value 列表。这种情况下，各个键会被视为按声明顺序对应的选项名。例如 fade 滤镜按顺序声明了 type、start_frame、nb_frames 这三个选项。那么参数列表 in:0:30 表示把值 in 赋给选项 type，把 0 赋给 start_frame，把 30 赋给 nb_frames。
以“:”分隔的、直接给出的 value 与长形式 key=value 对混合而成的列表。直接给出的 value 必须放在 key=value 对之前，并遵循前一点相同的顺序约束。后续的 key=value 对可以按任意喜欢的顺序设置。

如果选项值本身是一组条目（例如 format 滤镜接受的是 pixel format 的列表），列表中的各项通常用“|”分隔。

参数列表可以用字符“'”作为起止标记进行引用（quote），并用字符“\”对引用文本内部的字符进行转义；否则，参数字符串在遇到下一个特殊字符（属于集合“[]=;,”）时即视为结束。

ffmpeg CLI 工具中实现了一种特殊语法，可以从文件加载选项值。做法是在选项名前加一个斜杠“/”，随后给出的值会被解释为实际值所在的路径。例如：

ffmpeg -i <INPUT> -vf drawtext=/text=/tmp/some_text <OUTPUT>

这样会从 /tmp/some_text 加载要绘制的文本。希望实现类似功能的 API 使用者，应结合 avfilter_graph_segment_*() 函数族与自定义的 IO 代码来实现。

滤镜的名称和参数前后可以任选地加上一组链路标签（link label）。链路标签可以为一条链路命名，并将其关联到某个滤镜的输出或输入端口。前置的标签 in_link_1 ... in_link_N 关联到滤镜的输入端口，后置的标签 out_link_1 ... out_link_M 关联到输出端口。

当 filtergraph 中出现两个同名的链路标签时，就会在对应的输入端口和输出端口之间建立一条链路。

如果某个输出端口没有标注标签，默认情况下它会被链接到 filterchain 中下一个滤镜的第一个未标注标签的输入端口。例如，在下面这条 filterchain 中：

nullsrc, split[L1], [L2]overlay, nullsink

split 滤镜实例有两个输出端口，overlay 滤镜实例有两个输入端口。split 的第一个输出端口标注为 "L1"，overlay 的第一个输入端口标注为 "L2"，split 的第二个输出端口则链接到 overlay 的第二个输入端口，这两者都未标注标签。

在滤镜描述中，如果第一个滤镜的输入标签未指定，则默认视为 "in"；如果最后一个滤镜的输出标签未指定，则默认视为 "out"。

在一条完整的 filterchain 中，所有未标注标签的滤镜输入、输出端口都必须被连接。如果一个 filtergraph 中所有 filterchain 的所有滤镜输入、输出端口都已连接，则认为该 filtergraph 有效。

filtergraph 规范中用于分隔各个记号的前导和尾随空白（空格、制表符或换行符）会被忽略。也就是说，可以用空行和空格来提升 filtergraph 的可读性。

例如，下面这个 filtergraph：

testsrc,split[L1],hflip[L2];[L1][L2] hstack

可以写成如下形式：

testsrc,
split [L1], hflip [L2];

[L1][L2] hstack

在需要进行格式转换的地方，Libavfilter 会自动插入 scale 滤镜。可以通过在 filtergraph 描述前加上 sws_flags=flags;，为这些自动插入的缩放器（scaler）指定 swscale 标志。

下面是 filtergraph 语法的 BNF 描述：

NAME             ::= sequence of alphanumeric characters and '_'
FILTER_NAME      ::= NAME["@"NAME]
LINKLABEL        ::= "[" NAME "]"
LINKLABELS       ::= LINKLABEL [LINKLABELS]
FILTER_ARGUMENTS ::= sequence of chars (possibly quoted)
FILTER           ::= [LINKLABELS] FILTER_NAME ["=" FILTER_ARGUMENTS] [LINKLABELS]
FILTERCHAIN      ::= FILTER [,FILTERCHAIN]
FILTERGRAPH      ::= [sws_flags=flags;] FILTERCHAIN [;FILTERGRAPH]

4.2 关于 filtergraph 转义的说明

组合 filtergraph 描述涉及多个层级的转义。关于所采用转义流程的更多信息，参见 (ffmpeg-utils)the "Quoting and escaping" section in the ffmpeg-utils(1) manual。

第一层转义影响每个滤镜选项值的内容，其中可能包含用于分隔各值的特殊字符 :，或转义字符 \' 之一。

第二层转义影响整个滤镜描述，其中可能包含转义字符 \'，或 filtergraph 描述所使用的特殊字符 [],;。

最后，在 shell 命令行中指定 filtergraph 时，还需要对其中包含的 shell 特殊字符再进行第三层转义。

例如，考虑下面这个要嵌入 drawtext 滤镜描述 text 值中的字符串：

this is a 'string': may contain one, or more, special characters

这个字符串包含特殊转义字符 ' 和特殊字符 :，因此需要按如下方式转义：

text=this is a \'string\'\: may contain one, or more, special characters

当把这段滤镜描述嵌入 filtergraph 描述时，还需要第二层转义，以转义所有 filtergraph 特殊字符。因此上面的示例就变成了：

drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters

（注意，除了 \' 这个转义特殊字符之外，, 也需要转义）。

最后，在把 filtergraph 描述写进 shell 命令时，还需要根据所用 shell 的转义规则再做一层额外的转义。例如，假设 \ 是特殊字符，需要用另一个 \ 来转义，那么前面的字符串最终会变成：

-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"

为了在使用接受滤镜规范作为输入的命令行工具时避免这种繁琐的转义，建议尽量避免在 shell 中直接书写滤镜或选项的规范。

例如对于 drawtext 滤镜，可能更适合用 textfile 选项代替 text 来指定要渲染的文本。

5 时间线编辑

有些滤镜支持通用的 enable 选项。对于支持 timeline editing 的滤镜，可以给这个选项设置一个表达式，该表达式会在把帧送入滤镜之前被求值。如果求值结果非零，滤镜就会被启用；否则该帧会保持不变，直接送往 filtergraph 中的下一个滤镜。

该表达式接受以下取值：

‘t’

以秒为单位表示的时间戳；如果输入时间戳未知则为 NAN

‘n’

输入帧的序号，从 0 开始

‘pos’

输入帧在文件中的位置，未知时为 NAN；已弃用，请勿使用

‘w’ ‘h’

如果是视频，则为输入帧的宽度和高度

此外，这些滤镜还支持一个 enable 命令，可用来重新定义该表达式。

和其他滤镜处理选项一样，enable 选项也遵循相同的规则。

例如，要让 blur 滤镜（smartblur）在第 10 秒到第 3 分钟之间生效，并让 curves 滤镜从第 3 秒开始生效，可以这样写：

smartblur = enable='between(t,10,3*60)',
curves    = enable='gte(t,3)' : preset=cross_process

可以用 ffmpeg -filters 查看哪些滤镜支持 timeline。

6 通过命令在运行时修改选项

有些选项可以在滤镜运行期间通过命令来修改。这些选项会在 ffmpeg -h filter= 的输出中标注为 ’T’。命令的名称就是选项的名称，参数就是新的值。

7 具有多个输入的滤镜的选项（framesync）

一些具有多个输入的滤镜支持一组共同的选项。这些选项只能按名称设置，不能使用简写形式。

eof_action

在副输入上遇到 EOF 时采取的动作，接受以下值之一：

repeat

重复最后一帧（默认值）。

endall

结束两条流。

pass

原样传递主输入。

shortest

若设为 1，则在最短的输入结束时强制终止输出。默认值为 0。

repeatlast

如果设为 1，则强制将副流的最后一帧延长到主流结束为止。设为 0 会禁用此行为。默认值为 1。

ts_sync_mode

根据副输入的时间戳来同步各条流的严格程度，接受以下值之一：

default

在副输入中，取时间戳不晚于（更小或相等）主输入帧时间戳、且与之最接近的那一帧。

nearest

在副输入中，取时间戳与主输入帧时间戳绝对值最接近的那一帧。

8 音频滤镜

在配置 FFmpeg 构建时，可以用 --disable-filters 禁用任意现有滤镜。configure 的输出会显示你的构建中包含哪些音频滤镜。

下面是当前可用音频滤镜的说明。

8.1 aap

使用第二条音频流，对第一条音频流应用仿射投影（Affine Projection）算法。

这种自适应滤镜用于基于多个输入音频样本估计未知音频。仿射投影算法可以在计算复杂度与收敛速度之间做出取舍。

接受的选项说明如下。

order

设置滤镜阶数。

projection

设置投影阶数。

设置滤镜的 mu。

delta

设置用于初始化内部协方差矩阵的系数。

out_mode

设置滤镜的输出样本。接受以下值：

传递第一个输入。

传递第二个输入。

传递期望的第二个输入与误差信号估计值之间的差值。

传递第一个输入与误差信号估计值之间的差值。

传递误差信号的估计采样。

默认值为 o。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

8.2 acompressor

压缩器（compressor）主要用来压缩信号的动态范围。尤其是现代音乐，为了提升整体响度，大多以较高的压缩比进行压缩。这样做是为了最大限度地吸引听众的注意力，让声音更“饱满”，为音轨带来更多“力量”。如果信号压缩过度，之后听起来可能会显得沉闷、“发死”，也可能出现“泵浦（pumping）”现象（这既可能是一种强有力的效果，也可能彻底毁掉一段音轨）。恰到好处的压缩是获得专业音质的关键，也是混音与母带处理中的高深技艺。由于其设置颇为复杂，可能需要很长时间才能找到这种效果恰当的分寸感。

压缩的做法是：检测超过所选 threshold（阈值）电平的音量，并按 ratio 设置的系数将其压低。举例来说，如果把阈值设为 -12dB，而信号达到 -6dB，那么在 2:1 的压缩比下，结果信号会是 -9dB。由于对信号进行精确操作会导致波形失真，可以让这种压低在时间上逐步展开，这是通过设置“Attack”和“Release”实现的。attack 决定信号超过阈值后需要经过多长时间才会开始出现压低，release 则设置信号低于阈值后需要经过多长时间才会再次减弱压低。比所选 attack 时间更短的信号不会受到影响。信号总体的压低量之后可以用 makeup 设置来补偿。例如，把信号峰值压低约 6dB，再把 makeup 提升到相同的量，最终得到的信号会比原始信号响一倍。为了让进入压缩状态更柔和，knee 会在所选分贝范围内，让阈值处原本尖锐的拐点变得平滑。

该滤镜接受以下选项：

level_in

设置输入增益。默认值为 1。范围为 0.015625 到 64。

mode

设置压缩器的工作模式，可以是 upward 或 downward。默认值为 downward。

threshold

如果流的信号超过这个电平，就会影响增益压低的程度。默认值为 0.125。范围为 0.00097563 到 1。

ratio

设置信号被压低所依据的比率。1:2 表示如果电平比阈值高出 4dB，压低之后就只会高出 2dB。默认值为 2。范围为 1 到 20。

attack

信号超过阈值后，经过多少毫秒才开始出现增益压低。默认值为 20。范围为 0.01 到 2000。

release

信号低于阈值后，经过多少毫秒压低量才会再次减小。默认值为 250。范围为 0.01 到 9000。

makeup

设置处理后信号将被放大多少。默认值为 1。范围为 1 到 64。

knee

让阈值周围原本尖锐的拐点变得平滑，从而更柔和地进入增益压低。默认值为 2.82843。范围为 1 到 8。

link

选择由输入流所有声道的 average（平均）电平，还是由输入流中更响的（maximum，最大）声道来影响压低程度。默认值为 average。

detection

在 peak 情况下取精确信号，在 rms 情况下取 RMS 值。默认值为 rms，通常效果更平滑。

mix

输出中使用压缩后信号的比例。默认值为 1。范围为 0 到 1。

8.2.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.3 acontrast

简单的音频动态范围压缩/扩展滤镜。

该滤镜接受以下选项：

contrast

设置对比度。默认值为 33。允许范围为 0 到 100。

8.4 acopy

将输入音频源原样不变地复制到输出。这主要用于测试目的。

8.5 acrossfade

将一条输入音频流交叉淡化（cross fade）到另一条输入音频流。交叉淡化会在第一条流末尾附近，在指定的时长内进行。

该滤镜接受以下选项：

inputs, n

指定要交叉淡化的输入数量。交叉淡化多个输入时，各输入会依次拼接并交叉淡化，方式与 concat 滤镜类似。默认值为 2。

nb_samples, ns

指定交叉淡化效果持续的样本数。交叉淡化效果结束时，第一路输入音频会完全变为静音。默认值为 44100。

duration, d

指定交叉淡化效果的时长。所接受的语法参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。默认情况下，时长由 nb_samples 决定。如果设置了这个选项，就会用它代替 nb_samples。

overlap, o

第一条流的结尾是否应与第二条流的开头重叠。默认启用。

curve1

设置第一条流交叉淡化过渡所用的曲线。

curve2

设置第二条流交叉淡化过渡所用的曲线。

可用曲线类型的说明参见 afade 滤镜的说明。

8.5.1 示例

从一路输入交叉淡化到另一路输入：

ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac

从一路输入交叉淡化到另一路输入，但不重叠：

ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac

拼接多路输入，各输入之间进行交叉淡化：

    ffmpeg -i first.flac -i second.flac -i third.flac -filter_complex acrossfade=n=3 output.flac

8.6 acrossover

将音频流拆分为多个频段。

该滤镜将音频流拆分为两个或更多频率范围。把所有流重新叠加起来会得到一个平坦的输出。

该滤镜接受以下选项：

split

设置分频点。这些值必须为正数且依次递增。

order

设置每个频段拆分所用的滤镜阶数。它控制的是滤镜的滚降（roll-off），即滤镜传递函数的陡峭程度。可用取值如下：

‘2nd’

每倍频程 12 dB。

‘4th’

每倍频程 24 dB。

‘6th’

每倍频程 36 dB。

‘8th’

每倍频程 48 dB。

‘10th’

每倍频程 60 dB。

‘12th’

每倍频程 72 dB。

‘14th’

每倍频程 84 dB。

‘16th’

每倍频程 96 dB。

‘18th’

每倍频程 108 dB。

‘20th’

每倍频程 120 dB。

默认值为 4th。

level

设置输入增益电平。允许范围为 0 到 1。默认值为 1。

gains

设置每个频段的输出增益。默认值对所有频段都是 1。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

默认值为 auto。

8.6.1 示例

以 1500 Hz 的分频点，把输入音频流拆分为两个频段（低频段和高频段），每个频段各自成为一条独立的流：
```
ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav
```

与上面相同，但使用更高的滤镜阶数：

ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav

与上面相同，但另外加上一个中间频段（1500 到 8000 之间的频率）：

ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav

8.7 acrusher

降低音频的位分辨率。

这是一个功能增强的比特粉碎器（bit crusher）滤镜。比特粉碎器用来在听感上降低音频信号采样所用的位数。它其实完全不会改变位深度（bit depth），只是制造出相应的效果。位深度被降低后的素材听起来更粗糙、更“数字化”。这个滤镜甚至可以圆整到连续值，而不是离散的位深度。此外它还带有一个 D/C 偏移，会使信号的下半部分和上半部分产生不同的粉碎效果。抗混叠（Anti-Aliasing）设置能产生更“柔和”的粉碎音效。

这个滤镜的另一个特点是对数模式。这项设置会把位之间的距离从线性改为对数。其结果是粉碎效果听起来“自然”得多，例如不会对低电平信号产生门限（gate）效应。人耳的感知本身是对数式的，因此这种粉碎方式听起来舒服得多。对数粉碎同样可以进行抗锯齿处理。

该滤镜接受以下选项：

level_in

设置输入电平。

level_out

设置输出电平。

bits

设置位缩减量。

mix

设置混合量。

mode

可以是线性 lin 或对数 log。

设置 DC。

设置抗混叠。

samples

设置样本缩减量。

lfo

启用 LFO。默认禁用。

lforange

设置 LFO 范围。

lforate

设置 LFO 速率。

8.7.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.8 acue

将音频滤镜处理延迟到指定的挂钟（wallclock）时间戳。参见 cue 滤镜。

8.9 adeclick

从输入音频中去除脉冲噪声。

被检测为脉冲噪声的样本会用自回归建模得到的插值样本替换。

window, w

以毫秒为单位设置窗口大小。允许范围为 10 到 100。默认值为 55 毫秒。这决定了一次处理的窗口大小。

overlap, o

以窗口大小的百分比设置窗口重叠量。允许范围为 50 到 95。默认值为 75%。将其设为很高的值会提升脉冲噪声的去除效果，但会使整个处理过程慢得多。

arorder, a

以窗口大小的百分比设置自回归阶数。允许范围为 0 到 25。默认值为 2%。这个选项还会影响利用相邻优质样本进行插值所得样本的质量。

threshold, t

设置阈值。允许范围为 1 到 100。默认值为 2。它控制要去除的脉冲噪声的强度。值越低，被检测为脉冲噪声的样本就越多。

burst, b

以窗口大小的百分比设置突发融合量。允许范围为 0 到 10。默认值为 2。如果两个被检测为噪声的样本间隔小于这个值，那么这两个样本之间的样本也会被检测为噪声。

method, m

设置重叠方式。

可接受的值有：

add, a

选择重叠相加（overlap-add）方式。这种方式下，即便是未经过插值的样本也会有轻微变化。

save, s

选择重叠保存（overlap-save）方式。未经过插值的样本保持不变。

默认值为 a。

8.10 adeclip

从输入音频中去除削波（clip）样本。

被检测为削波的样本会用自回归建模得到的插值样本替换。

window, w

以毫秒为单位设置窗口大小。允许范围为 10 到 100。默认值为 55 毫秒。这决定了一次处理的窗口大小。

overlap, o

以窗口大小的百分比设置窗口重叠量。允许范围为 50 到 95。默认值为 75%。

arorder, a

以窗口大小的百分比设置自回归阶数。允许范围为 0 到 25。默认值为 8%。这个选项还会影响利用相邻优质样本进行插值所得样本的质量。

threshold, t

设置阈值。允许范围为 1 到 100。默认值为 10。值越高，削波检测就越不敏感。

hsize, n

设置用于检测削波的直方图大小。允许范围为 100 到 9999。默认值为 1000。值越高，削波检测就越不敏感。

method, m

设置重叠方式。

可接受的值有：

add, a

选择重叠相加（overlap-add）方式。这种方式下，即便是未经过插值的样本也会有轻微变化。

save, s

选择重叠保存（overlap-save）方式。未经过插值的样本保持不变。

默认值为 a。

8.11 adecorrelate

对输入音频流应用去相关（decorrelation）处理。

该滤镜接受以下选项：

stages

设置滤镜处理的去相关阶数。允许范围为 1 到 16。默认值为 6。

seed

设置用于在各声道间设置延迟的随机数种子。

8.12 adelay

延迟一个或多个音频声道。

被延迟声道的样本会用静音填充。

该滤镜接受以下选项：

delays

以“|”分隔的列表形式，为每个声道设置延迟量（毫秒）。未被使用的延迟值会被静默忽略。如果给出的延迟数量少于声道数量，其余声道将不会被延迟。如果想按精确的样本数延迟，请在数值后加上“S”。如果想改为按秒延迟，请在数值后加上“s”。

all

对其余所有声道使用最后设置的延迟值。默认禁用。启用此选项会改变选项 delays 的解释方式。

8.12.1 示例

将第 1 声道延迟 1.5 秒，第 3 声道延迟 0.5 秒，第 2 声道（以及可能存在的其他任何声道）保持不变。
```
adelay=1500|0|500
```
将第 2 声道延迟 500 个样本，第 3 声道延迟 700 个样本，第 1 声道（以及可能存在的其他任何声道）保持不变。
```
adelay=0|500S|700S
```
将所有声道延迟相同数量的样本：
```
adelay=delays=64S:all=1
```

8.13 adenorm

通过加入极低电平的噪声来修正音频中的非规格化数（denormal）。

这个滤镜应放在任何可能产生非规格化数的滤镜之前。

下面是所接受参数的说明。

level

以 dB 为单位设置所加噪声的电平。默认值为 -351。允许范围为 -451 到 -90。

type

设置所加噪声的类型。

加入 DC 信号。

加入 AC 信号。

square

加入方波信号。

pulse

加入脉冲信号。

默认值为 dc。

8.13.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.14 aderivative, aintegral

计算音频流的微分/积分。

依次应用这两个滤镜可得到原始音频。

8.15 adrc

对输入音频流应用频谱动态范围控制器滤镜。

接受的选项说明如下。

transfer

设置传递函数表达式。

该表达式可以包含以下常量：

当前声道编号

当前样本编号

nb_channels

声道数

以秒为单位表示的时间戳

采样率

当前频率的功率值，单位为 dB

当前频率，单位为 Hz

默认值为 p。

attack

以毫秒为单位设置 attack。默认值为 50 毫秒。允许范围为 1 到 1000 毫秒。

release

以毫秒为单位设置 release。默认值为 100 毫秒。允许范围为 5 到 2000 毫秒。

channels

设置要过滤的声道，默认过滤音频流中的 all（全部）声道。

8.15.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.15.2 示例

以 -50 dB 的阈值和 1:6 的比率，对所有频率应用频谱压缩：
```
adrc=transfer='if(gt(p,-50),-50+(p-(-50))/6,p)':attack=50:release=100
```

与上面相同，但比率为 1:2，且仅过滤前中置声道：

adrc=transfer='if(gt(p,-50),-50+(p-(-50))/2,p)':attack=50:release=100:channels=FC

以 -85 dB 的阈值，用较短的 attack 时间和 release 时间，对所有频率应用频谱噪声门：
```
adrc=transfer='if(lte(p,-85),p-800,p)':attack=1:release=5
```
以 -10 dB 的阈值和 1:2 的比率，对所有频率应用频谱扩展：
```
adrc=transfer='if(lt(p,-10),-10+(p-(-10))*2,p)':attack=50:release=100
```
以 2 ms 的 attack 和 10 ms 的 release，对所有频率应用最大 -60 dB 的限幅：
```
adrc=transfer='min(p,-60)':attack=2:release=10
```

8.16 adynamicequalizer

对输入音频流应用动态均衡。

接受的选项说明如下。

threshold

设置用于触发均衡的检测阈值。阈值检测使用检测滤波器。默认值为 0。允许范围为 0 到 100。

dfrequency

以 Hz 为单位设置检测滤镜用于触发均衡的检测频率。默认值为 1000 Hz。允许范围为 2 到 1000000 Hz。

dqfactor

设置检测滤镜用于触发均衡的检测谐振系数。默认值为 1。允许范围为 0.001 到 1000。

tfrequency

设置均衡滤波器的目标频率。默认值为 1000 Hz。允许范围为 2 到 1000000 Hz。

tqfactor

设置目标均衡滤镜的目标谐振系数。默认值为 1。允许范围为 0.001 到 1000。

attack

设置均衡开始前，检测到的信号需要高于检测阈值的毫秒数。默认值为 20。允许范围为 1 到 2000。

release

设置均衡结束前，检测到的信号需要低于检测阈值的毫秒数。默认值为 200。允许范围为 1 到 2000。

ratio

设置提升均衡增益所依据的比率。默认值为 1。允许范围为 0 到 30。

makeup

设置提升均衡增益所用的 makeup 偏移量。默认值为 0。允许范围为 0 到 100。

range

设置允许的最大衰减/提升量。默认值为 50。允许范围为 1 到 200。

mode

设置滤镜的工作模式，可以是以下之一：

‘listen’

仅输出被分离出的检测信号。

‘cutbelow’

衰减检测阈值以下的频率。

‘cutabove’

衰减检测阈值以上的频率。

‘boostbelow’

提升检测阈值以下的频率。

‘boostabove’

提升检测阈值以上的频率。

默认模式为 ‘cutbelow’。

dftype

设置检测滤波器的类型，可以是以下之一：

‘bandpass’ ‘lowpass’ ‘highpass’ ‘peak’

默认类型为 ‘bandpass’。

tftype

设置目标滤波器的类型，可以是以下之一：

‘bell’ ‘lowshelf’ ‘highshelf’

默认类型为 ‘bell’。

auto

自动从检测滤镜采集阈值。默认为 ‘disabled’。此选项有助于在输入音频流的特定时间段内检测阈值，此时选项值会在运行时改变。

可用值如下：

‘disabled’

禁用自动采集的阈值。

‘off’

停止选取阈值。

‘on’

开始选取阈值。

‘adaptive’

通过计算滑动窗口熵，自适应地选取阈值。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

8.16.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.17 adynamicsmooth

对输入音频流应用动态平滑。

接受的选项说明如下。

sensitivity

设置对频率波动的敏感度。默认值为 2。允许范围为 0 到 1e+06。

basefreq

设置用于平滑的基准频率。默认值为 22050。允许范围为 2 到 1e+06。

8.17.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.18 aecho

对输入音频应用回声效果。

回声是反射声，说话或喊叫时会在山间（有时也包括大型建筑物之间）自然产生；数字回声效果模拟了这种现象，常用于丰富单件乐器或人声的音色。原始信号与反射声之间的时间差就是 delay，反射信号的响度就是 decay。多个回声可以有不同的延迟和衰减。

下面是所接受参数的说明。

in_gain

设置反射信号的输入增益。默认值为 0.6。

out_gain

设置反射信号的输出增益。默认值为 0.3。

delays

以毫秒为单位设置原始信号与反射声之间的时间间隔列表，用 ’|’ 分隔。每个 delay 允许的范围为 (0 - 90000.0]。默认值为 1000。

decays

设置反射信号响度的列表，用 ’|’ 分隔。每个 decay 允许的范围为 (0 - 1.0]。默认值为 0.5。

8.18.1 示例

让听感上仿佛有两倍于实际演奏的乐器数量：
```
aecho=0.8:0.88:60:0.4
```
如果延迟非常短，听起来就像（金属质感的）机器人在演奏音乐：
```
aecho=0.8:0.88:6:0.4
```
更长的延迟听起来就像山间的露天音乐会：
```
aecho=0.8:0.9:1000:0.3
```
与上面相同，但多了一座山：
```
aecho=0.8:0.9:1000|1800:0.3|0.25
```

8.19 aemphasis

音频加重滤镜使用不同的滤镜曲线，生成或还原直接取自黑胶唱片或经过加重处理的 CD 的素材。例如，要把音乐录制到黑胶唱片上，必须先用滤镜改变信号，以弥补这种录制介质的缺点。播放该素材时，则必须应用反向滤镜来还原频率响应的失真。

该滤镜接受以下选项：

level_in

设置输入增益。

level_out

设置输出增益。

mode

设置滤镜模式。若要还原素材，请使用 reproduction 模式，否则使用 production 模式。默认模式为 reproduction。

type

设置滤镜类型，用于选择介质。可以是以下之一：

col

选择 Columbia。

emi

选择 EMI。

bsi

选择 BSI (78RPM)。

riaa

选择 RIAA。

选择 Compact Disc (CD)。

50fm

选择 50µs (FM)。

75fm

选择 75µs (FM)。

50kf

选择 50µs (FM-KF)。

75kf

选择 75µs (FM-KF)。

8.19.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.20 aeval

根据指定的表达式修改音频信号。

该滤镜接受一个或多个表达式（每个声道一个），这些表达式会被求值并用于修改对应的音频信号。

它接受以下参数：

exprs

设置用 ’|’ 分隔的表达式列表，每个声道对应一个表达式。如果输入声道数大于表达式数量，剩余的输出声道将使用最后指定的表达式。

channel_layout, c

设置输出声道布局。如果未指定，声道布局由表达式的数量决定。如果设置为 ‘same’，则默认使用与输入相同的声道布局。

exprs 中的每个表达式都可以包含以下常量和函数：

当前表达式的声道编号

被求值样本的编号，从 0 开始

采样率

被求值样本的时间，以秒为单位

nb_in_channels nb_out_channels

输入和输出的声道数量

val(CH)

编号为 CH 的输入声道的值

注意：该滤镜速度较慢。如需更快的处理，应使用专用滤镜。

8.20.1 示例

音量减半：
```
aeval=val(ch)/2:c=same
```
反转第二声道的相位：
```
aeval=val(0)|-val(1)
```

8.21 aexciter

激励器用于产生原始信号中不存在的高音。做法是对信号产生范围受限的谐波失真，并将其叠加到原始信号中。激励器不会像均衡器那样单纯提升较高的频率，而是提升音频信号的高端，从而产生更“清脆”或更“明亮”的声音。

该滤镜接受以下选项：

level_in

设置处理信号之前的输入电平。允许范围为 0 到 64。默认值为 1。

level_out

设置处理信号之后的输出电平。允许范围为 0 到 64。默认值为 1。

amount

设置叠加到原始信号中的谐波量。允许范围为 0 到 64。默认值为 1。

drive

设置新生成谐波的量。允许范围为 0.1 到 10。默认值为 8.5。

blend

设置新生成谐波的倍频程。允许范围为 -10 到 10。默认值为 0。

freq

以 Hz 为单位设置生成谐波的下限频率。允许范围为 2000 到 12000 Hz。默认值为 7500 Hz。

ceil

设置生成谐波的上限频率。允许范围为 9999 到 20000 Hz。如果值低于 10000 Hz，则不施加上限。

listen

静音原始信号，仅输出叠加的谐波。默认禁用。

8.21.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.22 afade

对输入音频应用淡入/淡出效果。

下面是所接受参数的说明。

type, t

指定效果类型，可以是 in（表示淡入）或 out（表示淡出效果）。默认值为 in。

start_sample, ss

指定开始应用淡化效果的起始样本编号。默认值为 0。

nb_samples, ns

指定淡化效果持续的样本数。淡入效果结束时，输出音频的音量将与输入音频相同；淡出过渡结束时，输出音频将变为静音。默认值为 44100。

start_time, st

指定淡化效果的开始时间。默认值为 0。该值必须以时间长度的形式指定；可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。如果设置了该选项，就会用它代替 start_sample。

duration, d

指定淡化效果的时长。可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。淡入效果结束时，输出音频的音量将与输入音频相同；淡出过渡结束时，输出音频将变为静音。默认情况下，时长由 nb_samples 决定。如果设置了该选项，就会用它代替 nb_samples。

curve

设置淡化过渡所用的曲线。

可接受的值有：

tri

选择三角形、线性斜率（默认）

qsin

选择四分之一正弦波

hsin

选择二分之一正弦波

esin

选择指数正弦波

log

选择对数

ipar

选择反转抛物线

qua

选择二次

cub

选择三次

squ

选择平方根

cbr

选择立方根

par

选择抛物线

exp

选择指数

iqsin

选择反转的四分之一正弦波

ihsin

选择反转的二分之一正弦波

dese

选择双指数座（double-exponential seat）

desi

选择双指数 sigmoid（double-exponential sigmoid）

losi

选择逻辑斯谛函数（logistic sigmoid）

sinc

选择正弦基数函数（sinc）

isinc

选择反转的正弦基数函数

quat

选择四次

quatr

选择四次方根

qsin2

选择四分之一正弦波的平方

hsin2

选择二分之一正弦波的平方

nofade

不应用淡化

silence

设置淡入的初始增益或淡出的最终增益。默认值为 0.0。

unity

设置淡出的初始增益或淡入的最终增益。默认值为 1.0。

8.22.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.22.2 示例

对音频的前 15 秒做淡入：
```
afade=t=in:ss=0:d=15
```
对 900 秒音频的最后 25 秒做淡出：
```
afade=t=out:st=875:d=25
```

8.23 afftdn

使用 FFT 对音频样本进行降噪。

下面是所接受参数的说明。

noise_reduction, nr

以 dB 为单位设置降噪量，允许范围为 0.01 到 97。默认值为 12 dB。

noise_floor, nf

以 dB 为单位设置噪声基底，允许范围为 -80 到 -20。默认值为 -50 dB。

noise_type, nt

设置噪声类型。

可接受的值有：

white, w

选择白噪声。

vinyl, v

选择黑胶噪声。

shellac, s

选择虫胶噪声。

custom, c

选择由 bn 选项定义的自定义噪声。

默认值为白噪声。

band_noise, bn

为 15 个频带中的每一个设置自定义频带噪声配置，频带之间用 ’ ’ 或 ’|’ 分隔。

residual_floor, rf

以 dB 为单位设置残差基底，允许范围为 -80 到 -20。默认值为 -38 dB。

track_noise, tn

启用噪声基底追踪。默认禁用。启用后，噪声基底会自动调整。

track_residual, tr

启用残差追踪。默认禁用。

output_mode, om

设置输出模式。

可接受的值有：

input, i

原样传递输入。

output, o

传递滤除噪声后的信号。

noise, n

仅传递噪声。

默认值为 output。

adaptivity, ad

设置适应性系数，用于控制每个频段增益调整的适应速度。值为 0 时可实现即时适应，值越大反应越慢。允许范围为 0 到 1。默认值为 0.5。

floor_offset, fo

设置噪声基底偏移系数。该选项用于调整应用于所测得噪声基底的偏移量，仅在启用噪声基底追踪时才生效。允许范围为 -2.0 到 2.0。默认值为 1.0。

noise_link, nl

设置用于多声道音频的噪声链接方式。

可接受的值有：

none

使用各声道原本的噪声基底。

min

使用所有声道中测得的最小噪声基底。

max

使用所有声道中测得的最大噪声基底。

average

使用所有声道测得噪声基底的平均值。

默认值为 min。

band_multiplier, bm

设置频带乘数系数，用于控制频带在频段上展开的程度。允许范围为 0.2 到 5。默认值为 1.25。

sample_noise, sn

切换是否从输入音频中采集并测量噪声配置。

可接受的值有：

start, begin

开始采集样本噪声。

stop, end

停止采集样本噪声，并测量新的噪声频带配置。

默认值为 none。

gain_smooth, gs

设置增益平滑的空间半径，用于平滑应用于每个频段的增益。有助于减少随机的音乐噪声伪影。值越大，增益平滑程度越高。允许范围为 0 到 50。默认值为 0。

8.23.1 命令

该滤镜支持将以上部分选项作为命令使用。

8.23.2 示例

将白噪声降低 10dB，并使用先前测得的 -40dB 噪声基底：
```
afftdn=nr=10:nf=-40
```
将白噪声降低 10dB，同时将初始噪声基底设为 -80dB，并启用噪声基底的自动追踪，使其在处理过程中逐渐变化：
```
afftdn=nr=10:nf=-80:tn=1
```
将噪声降低 20dB，使用 -40dB 的噪声基底，并使用命令采集输入音频前 0.4 秒的噪声配置：
```
asendcmd=0.0 afftdn sn start,asendcmd=0.4 afftdn sn stop,afftdn=nr=20:nf=-40
```

8.24 afftfilt

对频域中的采样值应用任意表达式。

real

为每个独立声道设置频域实部表达式，各声道之间用 ’|’ 分隔。默认值为 "re"。如果输入声道数多于表达式数，多出的输出声道将使用最后一个指定的表达式。

imag

为每个独立声道设置频域虚部表达式，各声道之间用 ’|’ 分隔。默认值为 "im"。

real 和 imag 中的表达式可以包含以下常量和函数：

采样率

当前频点编号

可用频点数

当前表达式的声道号

chs

声道数

pts

当前帧的 pts

当前声道当前频点的实部

当前声道当前频点的虚部

real(b, ch)

返回位置 (bin,channel) 处频点实部的值

imag(b, ch)

返回位置 (bin,channel) 处频点虚部的值

win_size

设置窗口大小。允许的范围为 16 到 131072。默认值为 4096

win_func

设置窗口函数。

可接受的值有：

‘rect’ ‘bartlett’ ‘hann, hanning’ ‘hamming’ ‘blackman’ ‘welch’ ‘flattop’ ‘bharris’ ‘bnuttall’ ‘bhann’ ‘sine’ ‘nuttall’ ‘lanczos’ ‘gauss’ ‘tukey’ ‘dolph’ ‘cauchy’ ‘parzen’ ‘poisson’ ‘bohman’ ‘kaiser’

默认值为 hann。

overlap

设置窗口重叠。如果设置为 1，将自动选择所选窗口函数推荐的重叠值。默认值为 0.75。

8.24.1 示例

使音频中几乎只保留低频：

afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"

应用机器人化效果：

afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"

应用低语效果：

afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8"

应用相位偏移：

afftfilt="real=re*cos(1)-im*sin(1):imag=re*sin(1)+im*cos(1)"

8.25 afir

应用任意的有限脉冲响应（FIR）滤波器。

该滤镜设计用于应用长达 60 秒的长 FIR 滤波器。

它可用作数字分频滤波器、房间均衡、串音消除、波场合成、声音定位（auralization）、环境声学（ambiophonics）、全景声（ambisonics）和空间化的组件。

该滤镜使用第一路以外的流作为 FIR 系数。如果非第一路流只有单个声道，则该声道将用于第一路流的所有输入声道；否则，非第一路流的声道数必须与第一路流的声道数相同。

它接受以下参数：

dry

设置干信号增益。用于设置输入增益。

wet

设置湿信号增益。用于设置最终输出增益。

length

设置脉冲响应滤波器的长度。默认值为 1，表示处理整个 IR。

gtype

此选项已弃用，不起任何作用。

irnorm

设置滤波前应用于 IR 系数的范数。允许的范围为 -1 到 2。IR 系数会使用该选项设置计算出的向量范数进行归一化。对于负值，不计算范数，IR 系数完全不做修改。默认值为 1。

irlink

对于多声道 IR，如果将该选项设置为 true，所有 IR 声道都会按 irnorm 选项设置的、在所有 IR 声道系数中测得的最大增益进行归一化。禁用时，每个 IR 声道内的所有 IR 系数会独立归一化。默认值为 true。

irgain

设置滤波前应用于 IR 系数的增益。允许的范围为 0 到 1。该增益会在 irnorm 选项应用的任何增益之后再应用。

irfmt

设置 IR 流的格式。可以是 mono 或 input。默认值为 input。

maxir

以秒为单位设置允许的最大脉冲响应滤波器时长。默认值为 30 秒。允许的范围为 0.1 到 60 秒。

response

此选项已弃用，不起任何作用。

channel

此选项已弃用，不起任何作用。

size

此选项已弃用，不起任何作用。

rate

此选项已弃用，不起任何作用。

minp

设置用于卷积的最小分区大小。默认值为 8192。允许的范围为 1 到 65536。较小的值会以更高的 CPU 占用为代价降低延迟。

maxp

设置用于卷积的最大分区大小。默认值为 8192。允许的范围为 8 到 65536。较小的值可能会增加 CPU 占用。

nbirs

设置运行时可切换的输入脉冲响应流的数量。允许的范围为 1 到 32。默认值为 1。

设置用于卷积的 IR 流，从 0 开始，必须始终小于 nbirs 选项指定的值。默认值为 0。该选项可在运行时通过命令更改。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

默认值是 auto。

irload

设置何时加载 IR 流。可以是 init 或 access。前者在初始化时加载并准备好所有 IR，后者在首次访问某个特定 IR 时才加载一次。默认值为 init。

8.25.1 示例

将混响应用于流，使用单声道 IR 文件作为第二个输入，使用 ffmpeg 的完整命令为：
```
ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
```
给定输入的立体声流，以及左右声道各自的立体声脉冲响应，脉冲响应文件名分别为 l_ir.wav 和 r_ir.wav，应用真立体声处理，并设置 irnorm 选项的值：
```
"pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irnorm=1.2,pan=stereo|FL<c0+c2|FR<c1+c3"
```

与上例类似，但将 irgain 显式设置为估计值，并禁用 irnorm：

"pan=4C|c0=FL|c1=FL|c2=FR|c3=FR[a];amovie=l_ir.wav[LIR];amovie=r_ir.wav[RIR];[LIR][RIR]amerge[ir];[a][ir]afir=irfmt=input:irgain=-5dB:irnom=-1,pan=stereo|FL<c0+c2|FR<c1+c3"

8.26 aformat

为输入音频设置输出格式约束。框架会协商出最合适的格式以尽量减少转换。

它接受以下参数：

sample_fmts, f

以 ’|’ 分隔的所需 sample format 列表。

sample_rates, r

以 ’|’ 分隔的所需采样率列表。

channel_layouts, cl

以 ’|’ 分隔的所需声道布局列表。

所需语法请参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Channel Layout 一节。

如果省略某个参数，则允许所有值。

将输出强制为无符号 8 位或有符号 16 位立体声

aformat=sample_fmts=u8|s16:channel_layouts=stereo

8.27 afreqshift

对输入音频采样应用频移。

该滤镜接受以下选项：

shift

指定频移量。允许的范围为 -INT_MAX 到 INT_MAX。默认值为 0.0。

level

设置应用于最终输出的输出增益。允许的范围为 0.0 到 1.0。默认值为 1.0。

order

设置滤波使用的滤波器阶数。允许的范围为 1 到 16。默认值为 8。

8.27.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.28 afwtdn

使用小波从输入采样中降低宽带噪声。

接受的选项说明如下。

sigma

设置噪声 sigma，允许的范围为 0 到 1。默认值为 0。该选项控制对输入采样施加的降噪强度。设置该选项最实用的方式是通过分贝值，例如 -45dB。

levels

设置小波分解的层数。允许的范围为 1 到 12。默认值为 10。设置得过低会使降噪性能明显变差。

wavet

设置用于分解输入帧的小波类型。它们按系数数量从少到多排列。系数越多，滤波速度越慢，但总体质量越好。可用的小波有：

‘sym2’ ‘sym4’ ‘rbior68’ ‘deb10’ ‘sym10’ ‘coif5’ ‘bl3’ percent

设置完全降噪的百分比。允许的范围为 0 到 100。默认值为 85，即部分降噪。

profile

启用后，第一个输入帧将用作噪声轮廓。如果第一帧的采样中包含非噪声内容，性能会明显变差。

adaptive

启用后，会分析输入帧中是否存在噪声。如果以较高概率检测到噪声，该帧的轮廓将用于处理后续帧，直到检测到新的噪声帧为止。

samples

以采样数设置单帧的大小。允许的范围为 512 到 65536。默认帧大小为 8192 个采样。

softness

设置阈值处理函数内部应用的柔和度。允许的范围为 0 到 10。默认柔和度为 1。

8.28.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.29 agate

噪声门主要用于降低信号中较小的部分。这种信号处理方式可以减少有用信号之间令人不快的噪声。

门限处理的方式是：检测音量是否低于选定的电平阈值，并按 ratio 设置的系数将其降低。噪声基底通过 range 设置。由于对信号的精确操控会导致波形失真，因此可以让衰减随时间平滑地进行，方法是设置 attack 和 release。

attack 决定信号需要低于阈值多长时间才会开始发生衰减，release 设置信号需要高于阈值多长时间才会使衰减再次减弱。短于所选 attack 时间的信号将保持不变。

level_in

设置滤波前的输入电平。默认值为 1。允许的范围为 0.015625 到 64。

mode

设置工作模式。可以是 upward 或 downward。默认值为 downward。设置为 upward 模式时，信号中较大的部分会被放大，从而向上扩展动态范围；否则在 downward 模式下，信号中较小的部分会被降低。

range

设置信号低于阈值时的增益衰减电平。默认值为 0.06125。允许的范围为 0 到 1。将其设置为 0 会禁用衰减，此时滤镜的行为类似扩展器。

threshold

如果信号升高到超过该电平，增益衰减就会解除。默认值为 0.125。允许的范围为 0 到 1。

ratio

设置信号被衰减的比率。默认值为 2。允许的范围为 1 到 9000。

attack

信号需要高于阈值多少毫秒，增益衰减才会停止。默认值为 20 毫秒。允许的范围为 0.01 到 9000。

release

信号需要低于阈值多少毫秒，衰减才会再次增大。默认值为 250 毫秒。允许的范围为 0.01 到 9000。

makeup

设置处理后信号的放大量。默认值为 1。允许的范围为 1 到 64。

knee

对阈值附近的尖锐拐点进行圆滑处理，使增益衰减的过渡更加柔和。默认值为 2.828427125。允许的范围为 1 到 8。

detection

选择检测时取精确信号还是取类 RMS 信号。默认值为 rms。可以是 peak 或 rms。

link

选择由所有声道的平均电平还是由更响的声道来影响衰减。默认值为 average。可以是 average 或 maximum。

8.29.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.30 aiir

应用任意的无限脉冲响应（IIR）滤波器。

它接受以下参数：

zeros, z

设置 B/分子/零点/反射系数。

poles, p

设置 A/分母/极点/梯形系数。

gains, k

设置各声道的增益。

dry_gain

设置输入增益。

wet_gain

设置输出增益。

format, f

设置系数格式。

‘ll’

格子-梯形函数

‘sf’

模拟传递函数

‘tf’

数字传递函数

‘zp’

Z 平面零点/极点，直角坐标（默认）

‘pr’

Z 平面零点/极点，极坐标（弧度）

‘pd’

Z 平面零点/极点，极坐标（度）

‘sp’

S 平面零点/极点

process, r

设置处理类型。

‘d’

直接处理

‘s’

串行处理

‘p’

并行处理

precision, e

设置滤波精度。

‘dbl’

双精度浮点（默认）

‘flt’

单精度浮点

‘i32’

32 位整数

‘i16’

16 位整数

normalize, n

归一化滤波器系数，默认启用。启用后会将 DC 处的幅度响应归一化为 0dB。

mix

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

response

在附加的视频流中显示 IR 的频率响应，幅度（洋红色）、相位（绿色）和群延迟（黄色）。默认禁用。

channel

设置显示哪个 IR 声道的频率响应。默认显示第一个声道。该选项仅在启用 response 时使用。

size

设置视频流的大小。该选项仅在启用 response 时使用。

tf 和 sf 格式的系数以空格分隔，并按升序排列。

zp 格式的系数以空格分隔，系数的顺序无关紧要。zp 格式的系数是带虚数单位 i 的复数。

可以为每个声道提供不同的系数和增益，此时用 ’|’ 分隔各系数或增益。剩余的所有声道将使用最后提供的系数。

8.30.1 示例

针对 48000 Hz 采样率，在约 5000Hz 处应用 2 极椭圆陷波：

aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d

与上例相同，但使用 zp 格式：

aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s

使用模拟传递函数格式，应用 3 阶模拟归一化巴特沃斯低通滤波器：
```
aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
```

8.31 alimiter

限幅器可防止输入信号上升超过所需的阈值。该限幅器使用前瞻（lookahead）技术来防止信号失真。这意味着信号处理后会有一个小延迟。请注意，产生的延迟就是你设置的 attack 时间。

该滤镜接受以下选项：

level_in

设置输入增益。默认值为 1。

level_out

设置输出增益。默认值为 1。

limit

不允许高于该电平的信号通过限幅器。默认值为 1。

attack

限幅器将在这段时间（毫秒）内达到其衰减电平。默认值为 5 毫秒。

release

在这段毫秒数内从限幅恢复到 1.0 的衰减。默认值为 50 毫秒。

asc

当始终需要增益衰减时，ASC 会负责将衰减释放到一个平均衰减电平，而不是在释放时间内衰减到 0。

asc_level

选择释放时间受 ASC 影响的程度，0 表示释放时间几乎不变，1 则会产生更长的释放时间。

level

自动调整输出信号电平。默认启用。启用后会将音频重新归一化为 0dB。

latency

补偿因使用由 attack 参数设置的前瞻缓冲区而引入的延迟。同时会在流到达 EOF 时刷新前瞻缓冲区中有效的音频数据。

根据所选的设置，建议在应用该滤镜之前先用 aresample 将输入上采样 2 倍或 4 倍。

8.32 allpass

应用具有中心频率（单位为 Hz）frequency、滤波器宽度 width 的双极点全通滤波器。全通滤波器会改变音频的频率-相位关系，而不改变其频率-幅度关系。

该滤镜接受以下选项：

frequency, f

以 Hz 为单位设置频率。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

以 width_type 单位指定滤波器的带宽。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

order, o

设置滤波器阶数，可以是 1 或 2。默认值为 2。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

8.32.1 命令

该滤镜支持以下命令：

frequency, f

更改 allpass 的 frequency。命令的语法为: "frequency"

width_type, t

更改 allpass 的 width_type。命令的语法为: "width_type"

width, w

更改 allpass 的 width。命令的语法为: "width"

mix, m

更改 allpass 的 mix。命令的语法为: "mix"

8.33 aloop

循环播放音频采样。

该滤镜接受以下选项：

loop

设置循环次数。将该值设置为 -1 会导致无限循环。默认值为 0。

size

设置最大采样数。默认值为 0。

start

设置循环的第一个采样。默认值为 0。

time

以秒为单位设置循环开始的时间。仅当名为 start 的选项设置为 -1 时才使用。

8.34 amerge

将两路或更多路音频流合并为单一的多声道流。

所有输入必须具有相同的采样率和格式。

如果输入的时长不同，输出将随最短的输入结束。

该滤镜接受以下选项：

inputs

设置输入数量。默认值为 2。

layout_mode

该选项控制如何确定输出声道布局，以及合并时是否重新排列音频声道。

legacy

这是该滤镜历来的行为方式，因此是默认值。

如果各输入的声道布局已知且互不重叠，因而是兼容的，则输出的声道布局会相应设置，并按需重新排列声道。如果各输入的声道布局有重叠、部分未知，或使用了诸如 ambisonics 之类的特殊声道布局，则输出将依次包含第一个输入的所有声道，接着是第二个输入的所有声道，输出的声道布局将是对应总声道数的默认值。

例如，如果第一个输入为 2.1（FL+FR+LF），第二个输入为 FC+BL+BR，则输出将为 5.1，声道顺序如下：a1、a2、b1、a3、b2、b3（a1 是第一个输入的第一个声道，b1 是第二个输入的第一个声道）。

另一方面，如果两个输入都是立体声，输出声道将按默认顺序 a1、a2、b1、b2 排列，声道布局会被任意设置为 4.0，这可能符合预期，也可能不符合。

reset

该模式会忽略输入的声道布局，不进行声道重排。输出将依次包含第一个输入的所有声道，接着是第二个输入的所有声道，以此类推。

输出声道布局将只指定总声道数。

normal

该模式会保留输入声道的名称和指定信息，不进行声道重排。输出将依次包含第一个输入的所有声道，接着是第二个输入的所有声道，以此类推。

8.34.1 示例

将两个单声道文件合并为一个立体声流：

amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge

假设 input.mkv 中有 1 路视频流和 6 路音频流，进行多路合并：

ffmpeg -i input.mkv -filter_complex "[0:1][0:2][0:3][0:4][0:5][0:6] amerge=inputs=6" -c:a pcm_s16le output.mkv

8.35 amix

将多路音频输入混合为单一输出。

请注意，该滤镜仅支持 float 采样（amerge 和 pan 音频滤镜支持多种格式）。如果 amix 的输入是整数采样，将自动插入 aresample 以执行到 float 采样的转换。

它接受以下参数：

inputs

输入数量。如果未指定，默认值为 2。

duration

如何确定流的结束。

longest

最长输入的时长。（默认）

shortest

最短输入的时长。

first

第一个输入的时长。

dropout_transition

某路输入流结束时，用于音量重新归一化的过渡时间（秒）。默认值为 2 秒。

weights

以空格分隔的一串数字指定每路输入音频流的权重。如果指定的权重数少于输入数，最后一个权重会分配给其余的输入。每路输入的默认权重为 1。

normalize

始终缩放输入，而不仅仅是对采样求和。如果禁用该选项，在该滤镜处理前后如果输入未归一化，请注意可能会发生严重的削波。默认启用。

8.35.1 示例

此示例将 3 路输入音频流混合为一个输出，其时长与第一个输入相同，断流过渡时间为 3 秒：
```
ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
```
此示例将一路人声和一路音乐输入音频流混合为一个输出，其时长与最长的输入相同。音乐的权重为人声的四分之一，且输入未归一化：
```
ffmpeg -i VOCALS -i MUSIC -filter_complex amix=inputs=2:duration=longest:dropout_transition=0:weights="1 0.25":normalize=0 OUTPUT
```

8.35.2 命令

该滤镜支持以下命令：

weights normalize

语法与同名选项相同。

8.36 amultiply

将第一个音频流与第二个音频流相乘，并将结果存储到输出音频流中。相乘的方式是将第一个流的每个采样与第二个流相同位置的采样相乘。

通过这种逐元素相乘，可以产生振幅淡入淡出和振幅调制。

8.37 anequalizer

面向各声道的高阶参数多频段均衡器。

它接受以下参数：

params

该选项字符串的格式为："cchn f=cf w=w g=g t=f | ..."。各均衡器频段以 ’|’ 分隔。

chn

设置要应用均衡的声道编号。如果输入没有该声道，则忽略该条目。

设置频段的中心频率。如果输入没有该频率，则忽略该条目。

以赫兹为单位设置频段宽度。

以 dB 为单位设置频段增益。

设置频段的滤波器类型，可选，可以是：

‘0’

巴特沃斯，此为默认值。

‘1’

切比雪夫 1 型。

‘2’

切比雪夫 2 型。

curves

启用此选项后，anequalizer 的频率响应会显示在视频流中。

size

设置视频流的大小。仅当启用 curves 选项时才有用。

mgain

设置将显示的最大增益。仅当启用 curves 选项时才有用。将此值设置为合理数值后，就能够显示由彼此过于接近的相邻频段（两者同时启用时会产生更高增益）所导出的增益。

fscale

设置在视频输出中绘制频率响应时使用的频率刻度。可以是 linear（线性）或 logarithmic（对数）。默认值为 logarithmic。

colors

设置将在视频流中显示的各声道曲线的颜色。这是一个以空格或 ’|’ 分隔的颜色名称列表。无法识别或缺失的颜色将替换为白色。

8.37.1 示例

使用切比雪夫 1 型滤波器，将前 2 个声道中心频率 200Hz、宽度 100 Hz 的增益降低 10：
```
anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
```

8.37.2 命令

该滤镜支持以下命令：

change

更改现有的滤镜参数。命令的语法为："fN|f=freq|w=width|g=gain"

fN 为现有的滤波器编号，从 0 开始；如果不存在这样的滤波器，则返回错误。freq 用于设置新的频率参数。width 用于以赫兹为单位设置新的宽度参数。gain 用于以 dB 为单位设置新的增益参数。

使用 asendcmd 的完整滤镜调用可能如下所示：asendcmd=c=’4.0 anequalizer change 0|f=200|w=50|g=1’,anequalizer=...

8.38 anlmdn

使用非局部均值（Non-Local Means）算法降低音频采样中的宽带噪声。

每个采样都会通过查找具有相似上下文的其他采样来进行调整。这种上下文相似度是通过比较大小为 p 的周边区块（patch）来定义的。区块的搜索范围是采样周围半径为 r 的区域。

该滤镜接受以下选项：

strength, s

设置降噪强度。允许的范围为 0.00001 到 10000。默认值为 0.00001。

patch, p

设置区块半径的时长。允许的范围为 1 到 100 毫秒。默认值为 2 毫秒。

research, r

设置搜索半径的时长。允许的范围为 2 到 300 毫秒。默认值为 6 毫秒。

output, o

设置输出模式。

可接受的值有：

原样传递输入。

传递已滤除噪声的音频。

仅传递噪声。

默认值为 o。

smooth, m

设置平滑系数。默认值为 11。允许的范围为 1 到 1000。

8.38.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.39 anlmf, anlms

使用第二个音频流，对第一个音频流应用 Normalized Least-Mean-(Squares|Fourth) 算法。

该自适应滤波器通过寻找能使误差信号（期望的第二个输入音频流与作为实际信号的第一个输入音频流之间的差）达到最小均方的滤波器系数，来模拟所需的滤波器。

接受的选项说明如下。

order

设置滤波器阶数。

设置滤波器的 mu。

eps

设置滤波器的 eps。

leakage

设置滤波器的 leakage。

out_mode

可接受的值有：

传递第一个输入。

传递第二个输入。

传递期望的第二个输入与误差信号估计值之间的差值。

传递第一个输入与误差信号估计值之间的差值。

传递误差信号的估计采样。

默认值为 o。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

8.39.1 示例

此滤镜的众多用途之一是降噪：用延迟了固定量的相同采样对输入音频进行滤波，立体声音频的一个示例如下：
```
asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
```

8.39.2 命令

该滤镜支持与选项相同的命令，order 选项除外。

8.40 anull

将音频源原样传递到输出。

8.41 apad

用静音填充音频流的末尾。

此滤镜可与 ffmpeg 的 -shortest 结合使用，将音频流延长到与视频流相同的长度。

接受的选项说明如下。

packet_size

设置静音数据包的大小。默认值为 4096。

pad_len

设置要添加到末尾的静音采样数。达到该值后，流将终止。此选项与 whole_len 互斥。

whole_len

设置输出音频流中采样总数的最小值。如果该值大于输入音频的长度，则会在末尾添加静音，直到达到该值为止。此选项与 pad_len 互斥。

pad_dur

指定要添加的静音采样的时长。受支持的语法请参阅 ffmpeg-utils(1) 手册中的「(ffmpeg-utils)Time duration」一节。仅当设置为非负值时才会使用。

whole_dur

指定输出音频流中的最小总时长。受支持的语法请参阅 ffmpeg-utils(1) 手册中的「(ffmpeg-utils)Time duration」一节。仅当设置为非负值时才会使用。如果该值大于输入音频的长度，则会在末尾添加静音，直到达到该值为止。此选项与 pad_dur 互斥

如果 pad_len、whole_len、pad_dur、whole_dur 这几个选项都未设置，滤镜就会无限地向输入流末尾添加静音。

请注意，在 ffmpeg 4.4 及更早版本中，将 pad_dur 或 whole_dur 设置为 0 同样会导致滤镜无限添加静音。

8.41.1 示例

在输入的末尾添加 1024 个采样的静音：
```
apad=pad_len=1024
```
确保音频输出至少包含 10000 个采样，必要时用静音填充输入：
```
apad=whole_len=10000
```
使用 ffmpeg 用静音填充音频输入，从而在使用 shortest 选项时，让视频流始终成为最短的流，并在输出文件中被转换到末尾：
```
ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
```

8.42 aphaser

为输入音频添加移相效果。

移相滤波器会在频谱中产生一系列波峰和波谷。波峰和波谷的位置会被调制，使其随时间变化，从而产生扫描效果。

下面是所接受参数的说明。

in_gain

设置输入增益。默认值为 0.4。

out_gain

设置输出增益。默认值为 0.74。

delay

以毫秒为单位设置延迟。默认值为 3.0。

decay

设置衰减。默认值为 0.4。

speed

以 Hz 为单位设置调制速度。默认值为 0.5。

type

设置调制类型。默认值为 triangular。

可接受的值有：

‘triangular, t’ ‘sinusoidal, s’

8.43 aphaseshift

对输入音频采样应用相移。

该滤镜接受以下选项：

shift

指定相移。允许的范围为 -1.0 到 1.0。默认值为 0.0。

level

设置应用于最终输出的输出增益。允许的范围为 0.0 到 1.0。默认值为 1.0。

order

设置滤波使用的滤波器阶数。允许的范围为 1 到 16。默认值为 8。

8.43.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.44 apsnr

测量音频峰值信噪比（Peak Signal-to-Noise Ratio）。

此滤镜接受两路音频流作为输入，并输出第一路音频流。结果会在任一输入结束时按声道以 dB 输出。

8.45 apsyclip

对输入音频流应用心理声学限幅器（Psychoacoustic clipper）。

该滤镜接受以下选项：

level_in

设置输入增益。默认值为 1。范围为 [0.015625 - 64]。

level_out

设置输出增益。默认值为 1。范围为 [0.015625 - 64]。

clip

设置开始削波的值。默认值为 0dBFS，即 1。

diff

仅输出差值采样，便于听出引入的失真。默认禁用。

adaptive

设置所应用的自适应失真强度。默认值为 0.5。允许的范围为 0 到 1。

iterations

设置心理声学限幅器的迭代次数。允许的范围为 1 到 20。默认值为 10。

level

自动调整输出信号电平。默认禁用。启用后会将音频重新归一化为 0dBFS。

8.45.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.46 apulsator

音频脉动器（pulsator）介于自动摇移器（autopanner）和颤音效果（tremolo）之间，不过它也能产生一些有趣的立体声效果。脉动器会根据波形和相位各不相同的 LFO（低频振荡器），改变左右声道的音量。此滤镜能够定义左右声道之间的偏移量。偏移量为 0 表示两个 LFO 的波形完全一致，此时左右声道的变化幅度相同，效果即为传统的颤音。偏移量为 50% 表示右声道的波形恰好发生相位反转（即向后偏移了大约频率的一半），此时脉动器的作用就像自动摇移器。偏移量为 1 时，两条曲线会再次一致。介于两者之间的任何设置，都会使相位偏移在各阶段间无缝移动，并用正弦波和三角波产生某种“旁通”声音。偏移量越接近 1（从 0.5 开始），信号从左声道传到右声道的速度就越快。

该滤镜接受以下选项：

level_in

设置输入增益。默认值为 1。范围为 [0.015625 - 64]。

level_out

设置输出增益。默认值为 1。范围为 [0.015625 - 64]。

mode

设置 LFO 使用的波形形状。可以是 sine、triangle、square、sawup 或 sawdown 之一。默认值为 sine。

amount

设置调制量。定义原始信号受 LFO 影响的程度。

offset_l

设置左声道偏移量。默认值为 0。允许的范围为 [0 - 1]。

offset_r

设置右声道偏移量。默认值为 0.5。允许的范围为 [0 - 1]。

width

设置脉冲宽度。默认值为 1。允许的范围为 [0 - 2]。

timing

设置计时模式。可以是 bpm、ms 或 hz 之一。默认值为 hz。

bpm

设置 bpm。默认值为 120。允许的范围为 [30 - 300]。仅当 timing 设置为 bpm 时才使用。

设置 ms。默认值为 500。允许的范围为 [10 - 2000]。仅当 timing 设置为 ms 时才使用。

以 Hz 为单位设置频率。默认值为 2。允许的范围为 [0.01 - 100]。仅当 timing 设置为 hz 时才使用。

8.47 aresample

使用 libswresample 库将输入音频重采样为指定的参数。如果未指定任何参数，滤镜会在输入和输出之间自动转换。

此滤镜还能够拉伸/压缩音频数据以匹配时间戳，或者插入静音/裁剪音频以匹配时间戳，也可以两者结合，或者两者都不做。

此滤镜接受 [sample_rate:]resampler_options 语法，其中 sample_rate 表示采样率，resampler_options 是以 ":" 分隔的 key=value 对列表。支持选项的完整列表请参阅 ffmpeg-resampler(1) 手册中的「(ffmpeg-resampler)Resampler Options」一节。

8.47.1 示例

将输入音频重采样为 44100Hz：
```
aresample=44100
```
将采样拉伸/压缩以匹配给定的时间戳，每秒最多补偿 1000 个采样：
```
aresample=async=1000
```

8.48 areverse

反向播放音频片段。

警告：此滤镜需要用内存缓冲整个片段，因此建议先进行截取。

8.48.1 示例

取片段的前 5 秒并反向播放。
```
atrim=end=5,areverse
```

8.49 arls

使用第二个音频流，对第一个音频流应用递归最小二乘（Recursive Least Squares）算法。

该自适应滤波器通过递归地寻找能使误差信号（期望的第二个输入音频流与作为实际信号的第一个输入音频流之间的差）的加权线性最小二乘代价函数最小化的滤波器系数，来模拟所需的滤波器。

接受的选项说明如下。

order

设置滤波器阶数。

lambda

设置遗忘因子。

delta

设置用于初始化内部协方差矩阵的系数。

out_mode

设置滤波器的输出采样。可接受以下值：

传递第一个输入。

传递第二个输入。

传递期望的第二个输入与误差信号估计值之间的差值。

传递第一个输入与误差信号估计值之间的差值。

传递误差信号的估计采样。

默认值为 o。

precision

设置处理样本时使用的精度。

auto

根据其他滤镜自动选择内部 sample format。

float

始终使用单精度浮点 sample format。

double

始终使用双精度浮点 sample format。

8.50 arnndn

使用循环神经网络（Recurrent Neural Networks）降低语音中的噪声。

此滤镜接受以下选项：

model, m

设置要加载的训练模型文件。此选项始终为必填项。

mix

设置将滤波后的采样混入最终输出的比例。允许的范围为 -1 到 1。默认值为 1。负值有特殊含义，用于设置在最终滤波输出中保留多少经过滤波处理的噪声。将此选项设置为 -1，可以听到从输入信号中移除的实际噪声。

8.50.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.51 asdr

测量音频信号失真比（Signal-to-Distortion Ratio）。

此滤镜接受两路音频流作为输入，并输出第一路音频流。结果会在任一输入结束时按声道以 dB 输出。

8.52 asetnsamples

设置每个输出音频帧的采样数。

最后一个输出数据包可能包含不同数量的采样，因为当输入音频发出结束信号时，滤镜会刷新所有剩余的采样。

该滤镜接受以下选项：

nb_out_samples, n

设置每个输出音频帧的帧数。此数值指的是 每个声道 的采样数。默认值为 1024。

pad, p

如果设置为 1，滤镜会用零填充最后一个音频帧，使其包含与之前帧相同数量的采样。默认值为 1。

例如，要将每帧的采样数设置为 1234 并禁用最后一帧的填充，可使用：

asetnsamples=n=1234:p=0

8.53 asetrate

在不改变 PCM 数据的情况下设置采样率。这会导致速度和音调发生变化。

该滤镜接受以下选项：

sample_rate, r

设置输出采样率。默认值为 44100 Hz。

8.54 ashowinfo

为每个输入音频帧显示一行，其中包含各种信息。输入音频不会被修改。

显示的行包含一系列 key:value 形式的键/值对。

输出中会显示以下值：

输入帧的（连续）编号，从 0 开始。

pts

输入帧的 presentation timestamp，以时间基为单位；时间基取决于滤镜的输入 pad，通常为 1/sample_rate。

pts_time

输入帧的 presentation timestamp，以秒为单位。

fmt

sample format。

chlayout

声道布局。

rate

该音频帧的采样率。

nb_samples

该帧中（每个声道）的采样数。

checksum

音频数据的 Adler-32 校验和（以十六进制显示）。对于平面（planar）音频，数据会被视为将所有平面拼接在一起。

plane_checksums

各数据平面的 Adler-32 校验和列表。

8.55 asisdr

测量音频尺度不变信号失真比（Scaled-Invariant Signal-to-Distortion Ratio）。

此滤镜接受两路音频流作为输入，并输出第一路音频流。结果会在任一输入结束时按声道以 dB 输出。

8.56 asoftclip

对音频应用软削波（soft clipping）。

软削波是一种失真效果，它使信号的幅度沿着平滑的曲线饱和，而不是像硬削波（hard-clipping）那样急剧削平。

此滤镜接受以下选项：

type

设置软削波的类型。

可接受的值有：

hard tanh atan cubic exp alg quintic sin erf threshold

设置开始削波的阈值。默认值为 0dB，即 1。

output

设置应用于输出的增益。默认值为 0dB，即 1。

param

设置控制 sigmoid 函数的附加参数。

oversample

设置过采样系数。

8.56.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.57 aspectralstats

显示音频声道的频域统计信息。统计数据会针对每个音频声道和每个音频帧进行计算，并作为元数据存储。

它接受以下选项：

win_size

以采样数设置窗口长度。默认值为 2048。允许的范围为 32 到 65536。

win_func

设置窗口函数。

可接受的值有：

默认值为 hann。

overlap

设置窗口重叠。允许的范围为 0 到 1。默认值为 0.5。

measure

选择要测量的参数。元数据键可用作标志，默认值为 all，表示测量所有内容。none 会禁用所有测量。

各元数据键的列表如下：

mean variance centroid spread skewness kurtosis entropy flatness crest flux slope decrease rolloff

8.58 asr

自动语音识别（Automatic Speech Recognition）。

此滤镜使用 PocketSphinx 进行语音识别。要启用此滤镜的编译，需要使用 --enable-pocketsphinx 配置 FFmpeg。

它接受以下选项：

rate

设置输入音频的采样率。默认值为 16000。此值需要与语音模型匹配，否则会导致效果不佳。

hmm

设置包含声学模型文件的目录。

dict

设置发音词典。

设置语言模型文件。

lmctl

设置语言模型集合。

lmname

设置要使用的语言模型。

logfn

设置日志消息的输出位置。

此滤镜会将识别到的语音导出为帧元数据 lavfi.asr.text。

8.59 astats

显示音频声道的时域统计信息。针对每个音频声道计算并显示统计信息，如适用也会给出整体数值。

它接受以下选项：

length

峰值和谷值的均方根（RMS）测量所用的短窗口长度，以秒为单位。默认值为 0.05（50 毫秒）。允许范围为 [0 - 10]。

metadata

设置元数据注入。所有元数据键都带有 lavfi.astats.X 前缀，其中 X 是从 1 开始的声道编号，或者字符串 Overall。默认禁用。

每个声道可用的键为：Bit_depth Crest_factor DC_offset Dynamic_range Entropy Flat_factor Max_difference Max_level Mean_difference Min_difference Min_level Noise_floor Noise_floor_count Number_of_Infs Number_of_NaNs Number_of_denormals Peak_count Abs_Peak_count Peak_level RMS_difference RMS_peak RMS_trough Zero_crossings Zero_crossings_rate

Overall 的键为：Bit_depth DC_offset Entropy Flat_factor Max_difference Max_level Mean_difference Min_difference Min_level Noise_floor Noise_floor_count Number_of_Infs Number_of_NaNs Number_of_denormals Number_of_samples Peak_count Abs_Peak_count Peak_level RMS_difference RMS_level RMS_peak RMS_trough

例如，完整的键类似于 lavfi.astats.1.DC_offset 或 lavfi.astats.Overall.Peak_count。

各键的说明见下文。

reset

设置累积统计在重置前所计算的帧数。默认禁用。

measure_perchannel

选择按声道测量的参数。元数据键可用作标志，默认值为 all，即测量所有内容。none 会禁用所有按声道的测量。

measure_overall

选择整体测量的参数。元数据键可用作标志，默认值为 all，即测量所有内容。none 会禁用所有整体测量。

各测量键的说明如下：

none

不测量

all

测量所有内容

Bit_depth

音频整体的位深度，即每个样本使用的位数

Crest_factor

峰值与 RMS 电平的标准比值（注意：不是以 dB 表示）

DC_offset

相对零点的平均幅度偏移

Dynamic_range

以 dB 为单位测得的音频动态范围

Entropy

整段音频测得的熵值，接近 1.0 的熵值通常在白噪声中测得

Flat_factor

信号在其峰值电平（即 Min_level 或 Max_level）处的平坦度（即连续多个样本取相同值）

Max_difference

相邻两个样本之间的最大差值

Max_level

最大样本电平

Mean_difference

相邻两个样本之间的平均差值，即每对相邻样本差值的平均数

Min_difference

相邻两个样本之间的最小差值

Min_level

最小样本电平

Noise_floor

在短窗口内以 dBFS 测得的局部峰值最小值

Noise_floor_count

信号达到 Noise floor 的次数（不是样本数）

Number_of_Infs

取值为无穷大的样本数

Number_of_NaNs

取值为 NaN（非数）的样本数

Number_of_denormals

取值为次正规数（subnormal）的样本数

Number_of_samples

样本数

Peak_count

信号达到 Min_level 或 Max_level 的次数（不是样本数）

Abs_Peak_count

从信号中取得的绝对值样本，达到 Min_level 和 Max_level 中较大绝对值的次数

Peak_level

以 dBFS 测得的标准峰值电平

RMS_difference

相邻两个样本之间的均方根（RMS）差值

RMS_level

以 dBFS 测得的标准 RMS 电平

RMS_peak RMS_trough

在短窗口内测得的 RMS 电平峰值和谷值，以 dBFS 为单位。

Zero crossings

波形穿过零电平轴的点数

Zero crossings rate

过零次数与音频样本数之比

8.60 asubboost

提升超低音频率。

该滤镜接受以下选项：

dry

设置干信号增益，即保留多少原始信号。允许范围为 0 到 1。默认值为 1.0。

wet

设置湿信号增益，即保留多少已滤波信号。允许范围为 0 到 1。默认值为 1.0。

boost

设置最大提升系数。允许范围为 1 到 12。默认值为 2。

decay

设置延迟线的衰减增益值。允许范围为 0 到 1。默认值为 0.0。

feedback

设置延迟线的反馈增益值。允许范围为 0 到 1。默认值为 0.9。

cutoff

以赫兹为单位设置截止频率。允许范围为 50 到 900。默认值为 100。

slope

设置截止频率的斜率量。允许范围为 0.0001 到 1。默认值为 0.5。

delay

设置延迟。允许范围为 1 到 100。默认值为 20。

channels

设置要处理的声道。默认值为所有可用声道。

8.60.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.61 asubcut

衰减超低音频率。

此滤镜允许设置比 highpass 滤镜更陡峭的自定义滚降，因此能够更多地衰减阻带内的频率成分。

该滤镜接受以下选项：

cutoff

以赫兹为单位设置截止频率。允许范围为 2 到 200。默认值为 20。

order

设置滤镜阶数。可用值为 3 到 20。默认值为 10。

level

设置输入增益电平。允许范围为 0 到 1。默认值为 1。

8.61.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.62 asupercut

衰减超高频。

该滤镜接受以下选项：

cutoff

以赫兹为单位设置截止频率。允许范围为 20000 到 192000。默认值为 20000。

order

设置滤镜阶数。可用值为 3 到 20。默认值为 10。

level

设置输入增益电平。允许范围为 0 到 1。默认值为 1。

8.62.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.63 asuperpass

应用高阶巴特沃斯带通滤波器。

该滤镜接受以下选项：

centerf

以赫兹为单位设置中心频率。允许范围为 2 到 999999。默认值为 1000。

order

设置滤镜阶数。可用值为 4 到 20。默认值为 4。

qfactor

设置 Q 因子。允许范围为 0.01 到 100。默认值为 1。

level

设置输入增益电平。允许范围为 0 到 2。默认值为 1。

8.63.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.64 asuperstop

应用高阶巴特沃斯带阻滤波器。

该滤镜接受以下选项：

centerf

以赫兹为单位设置中心频率。允许范围为 2 到 999999。默认值为 1000。

order

设置滤镜阶数。可用值为 4 到 20。默认值为 4。

qfactor

设置 Q 因子。允许范围为 0.01 到 100。默认值为 1。

level

设置输入增益电平。允许范围为 0 到 2。默认值为 1。

8.64.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.65 atempo

调整音频速度。

该滤镜恰好接受一个参数，即音频速度。若未指定，则滤镜假定标称速度为 1.0。速度必须在 [0.5, 100.0] 范围内。

请注意，当速度大于 2 时，滤镜会跳过部分样本而不是将其混合。如果出于某种原因这是一个问题，也可以将多个 atempo 实例首尾相连，以获得所需的乘积速度。

8.65.1 示例

将音频减速到 80% 速度：
```
atempo=0.8
```
将音频加速到 300% 速度：
```
atempo=3
```
通过首尾相连两个 atempo 实例，将音频加速到 300% 速度：
```
atempo=sqrt(3),atempo=sqrt(3)
```

8.65.2 命令

该滤镜支持以下命令：

tempo

更改滤镜的速度缩放系数。命令的语法为："tempo"

8.66 atilt

对音频流应用频谱倾斜滤镜。

该滤镜对任意指定频段应用任意的频谱滚降斜率。

该滤镜接受以下选项：

freq

以 Hz 为单位设置倾斜的中心频率。默认值为 10000 Hz。

slope

设置倾斜的斜率方向。默认值为 0。允许范围为 -1 到 1。

width

设置倾斜的宽度。默认值为 1000。允许范围为 100 到 10000。

order

设置倾斜滤镜的阶数。

level

设置输入音量电平。允许范围为 0 到 4。默认值为 1。

8.66.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.67 atrim

截取输入，使输出仅包含输入的一段连续子部分。

它接受以下参数：

start

要保留区段的开始时间戳（以秒为单位）。即时间戳为 start 的音频样本将是输出中的第一个样本。

end

指定将被丢弃的第一个音频样本的时间，即时间戳为 end 的样本的前一个样本将是输出中的最后一个样本。

start_pts

与 start 相同，只是此选项以样本而非秒为单位设置开始时间戳。

end_pts

与 end 相同，只是此选项以样本而非秒为单位设置结束时间戳。

duration

输出的最大时长（以秒为单位）。

start_sample

应输出的第一个样本的编号。

end_sample

应丢弃的第一个样本的编号。

start、end、duration 以时间长度规范表示；参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Time duration 一节。

请注意，前两组 start/end 选项以及 duration 选项参照的是帧时间戳，而 _sample 选项只是简单地统计通过滤镜的样本数。因此，当时间戳错误、不精确或不是从零开始时，start/end_pts 和 start/end_sample 会给出不同的结果。另请注意，此滤镜不会修改时间戳。如果希望输出时间戳从零开始，请在 atrim 滤镜之后插入 asetpts 滤镜。

如果设置了多个 start 或 end 选项，此滤镜会尝试贪婪地保留匹配至少一个指定约束的所有样本。若只想保留同时满足所有约束的部分，请将多个 atrim 滤镜连接起来。

默认设置会保留全部输入。因此可以只设置 end 的值，从而保留指定时间之前的所有内容。

示例：

丢弃除输入第二分钟以外的所有内容：
```
ffmpeg -i INPUT -af atrim=60:120
```

仅保留前 1000 个样本：

ffmpeg -i INPUT -af atrim=end_sample=1000

8.68 axcorrelate

计算两路输入音频流之间的归一化加窗互相关。

得到的样本值始终介于 -1 到 1 之间（含端点）。如果结果为 1，表示在所选区间内两路输入样本高度相关。结果为 0 表示完全不相关。如果结果为 -1，表示两路输入样本反相，即彼此抵消。

该滤镜接受以下选项：

size

设置计算互相关的区间大小。默认值为 256。允许范围为 2 到 131072。

algo

设置互相关算法。可以是 slow、fast 或 best。默认值为 best。fast 算法假定任意给定区间内的均值始终为零，因此所需计算量少得多。这一般并不成立，但对典型音频流是有效的。

8.68.1 示例

计算立体声音频流中各声道之间的相关性：

ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav

8.69 bandpass

应用中心频率为 frequency、（3dB 点）带宽为 width 的双极点巴特沃斯带通滤波器。csg 选项会选择恒定裙边增益（skirt gain，此时峰值增益 = Q），而非默认的恒定 0dB 峰值增益。滤波器的滚降为每倍频程 6dB（每十倍频程 20dB）。

该滤镜接受以下选项：

frequency, f

设置滤波器的中心频率。默认值为 3000。

csg

设置为 1 时使用恒定裙边增益。默认值为 0。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

以 width_type 单位指定滤波器的带宽。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

设置用于反向 IIR 处理的块大小。如果将此值设置得足够大（大于脉冲响应截断至接近零值时的长度），滤波将变为线性相位；否则如果不够大，则只会产生令人不快的伪影。

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.69.1 命令

该滤镜支持以下命令：

frequency, f

更改 bandpass 的 frequency。命令的语法为："frequency"

width_type, t

更改 bandpass 的 width_type。命令的语法为："width_type"

width, w

更改 bandpass 的 width。命令的语法为："width"

mix, m

更改 bandpass 的 mix。命令的语法为："mix"

8.70 bandreject

应用中心频率为 frequency、（3dB 点）带宽为 width 的双极点巴特沃斯带阻滤波器。滤波器的滚降为每倍频程 6dB（每十倍频程 20dB）。

该滤镜接受以下选项：

frequency, f

设置滤波器的中心频率。默认值为 3000。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

以 width_type 单位指定滤波器的带宽。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.70.1 命令

该滤镜支持以下命令：

frequency, f

更改 bandreject 的 frequency。命令的语法为："frequency"

width_type, t

更改 bandreject 的 width_type。命令的语法为："width_type"

width, w

更改 bandreject 的 width。命令的语法为："width"

mix, m

更改 bandreject 的 mix。命令的语法为："mix"

8.71 bass, lowshelf

使用响应类似标准 hi-fi 音调控制的双极点搁架式滤波器，提升或削减音频的低音（较低）频率。这也称为搁架式均衡（EQ）。

该滤镜接受以下选项：

gain, g

给出 0 Hz 处的增益。其有效范围大约为 -20（大幅削减）到 +20（大幅提升）。使用正增益时请注意削波。

frequency, f

设置滤波器的中心频率，从而可用于扩大或缩小要提升或削减的频率范围。默认值为 100 Hz。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

决定滤波器搁架过渡的陡峭程度。

poles, p

设置极点数。默认值为 2。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.71.1 命令

该滤镜支持以下命令：

frequency, f

更改 bass 的 frequency。命令的语法为："frequency"

width_type, t

更改 bass 的 width_type。命令的语法为："width_type"

width, w

更改 bass 的 width。命令的语法为："width"

gain, g

更改 bass 的 gain。命令的语法为："gain"

mix, m

更改 bass 的 mix。命令的语法为："mix"

8.72 biquad

使用给定的系数应用 biquad IIR 滤镜。其中 b0、b1、b2 和 a0、a1、a2 分别为分子和分母系数，channels, c 用于指定要处理的声道，默认处理所有可用声道。

8.72.1 命令

该滤镜支持以下命令：

a0 a1 a2 b0 b1 b2

更改 biquad 参数。命令的语法为："value"

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.73 bs2b

Bauer 立体声转双耳（binaural）转换，可改善立体声录音在耳机上的听感。

要启用该滤镜的编译，需要在 configure FFmpeg 时加上 --enable-libbs2b。

它接受以下参数：

profile

预定义的串音（crossfeed）等级。

default

默认等级（fcut=700, feed=50）。

cmoy

Chu Moy 电路（fcut=700, feed=60）。

jmeier

Jan Meier 电路（fcut=650, feed=95）。

fcut

截止频率（以 Hz 为单位）。

feed

馈送电平（以 Hz 为单位）。

8.74 channelmap

将输入声道重新映射到新的位置。

它接受以下参数：

map

将声道从输入映射到输出。参数是以 ’|’ 分隔的映射列表，每个元素采用 in_channel-out_channel 或 in_channel 的形式。in_channel 可以是输入声道的名称（例如 FL 表示左前声道），也可以是它在输入声道布局中的索引。out_channel 是输出声道的名称，或它在输出声道布局中的索引。若未给出 out_channel，则隐式地视为一个索引，从零开始，每次映射递增 1。不允许混用不同类型的映射，否则会导致解析错误。

channel_layout

输出流的声道布局。若未指定，滤镜将根据 out_channel 的名称或映射的数量进行猜测。猜测得到的布局不一定会按照映射的顺序包含各个声道。

若不存在任何映射，滤镜会隐式地将输入声道映射到输出声道，并保留索引。

8.74.1 示例

例如，假设输入是一个 5.1+下混（downmix）的 MOV 文件：
```
ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
```

将根据输入的下混声道创建一个标记为立体声的输出 WAV 文件。

修复按 AAC 原生声道顺序错误编码的 5.1 WAV：

ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav

8.75 channelsplit

将输入音频流中的每个声道拆分为单独的输出流。

它接受以下参数：

channel_layout

输入流的声道布局。默认值为 "stereo"。

channels

描述要作为单独输出流提取的声道的声道布局，或使用 "all" 将每个输入声道都提取为单独的流。默认值为 "all"。

选择输入声道布局中不存在的声道将导致错误。

8.75.1 示例

例如，假设输入是一个立体声 MP3 文件：

ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv

将创建一个包含两条音频流的输出 Matroska 文件，一条只包含左声道，另一条只包含右声道。

将一个 5.1 WAV 文件拆分为按声道分别存放的文件：

ffmpeg -i in.wav -filter_complex
'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
side_right.wav

仅从 5.1 WAV 文件中提取 LFE 声道：

ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
-map '[LFE]' lfe.wav

8.76 chorus

为音频添加合唱效果。

可以让单个人声听起来像合唱，但也可以应用于乐器演奏。

合唱效果类似于带有短延迟的回声效果，但回声的延迟是恒定的，而合唱则使用正弦波或三角波调制使延迟发生变化。调制深度定义了调制后的延迟相对于原始延迟提前或滞后播放的范围。因此延迟的声音听起来或慢或快，即延迟的声音会围绕原始声音产生音高波动，就像合唱中部分人声略微跑调一样。

它接受以下参数：

in_gain

设置输入增益。默认值为 0.4。

out_gain

设置输出增益。默认值为 0.4。

delays

设置延迟。典型的延迟约为 40ms 到 60ms。

decays

设置衰减。

speeds

设置速度。

depths

设置深度。

8.76.1 示例

单个延迟：
```
chorus=0.7:0.9:55:0.4:0.25:2
```

两个延迟：

chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3

使用三个延迟获得更丰满的合唱效果：

chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3

8.77 compand

压缩或扩展音频的动态范围。

它接受以下参数：

attacks decays

以秒为单位的时间列表，用于对每个声道计算输入信号瞬时电平的平均值以确定其音量。attacks 指音量增大，decays 指音量减小。在大多数情况下，起音时间（对音频变大出现的响应）应比衰减时间短，因为人耳对突然的大声音比对突然的小声音更敏感。attack 的典型值为 0.3 秒，decay 的典型值为 0.8 秒。若指定的 attacks 和 decays 数量少于声道数，则最后设置的 attack/decay 将用于剩余的所有声道。

points

传递函数的点列表，以相对于最大可能信号振幅的 dB 值指定。每个关键点列表必须使用以下语法定义：x0/y0|x1/y1|x2/y2|.... 或 x0/y0 x1/y1 x2/y2 ....

输入值必须严格递增，但传递函数不必单调上升。系统假定存在点 0/0，但可以（通过 0/out-dBn）覆盖它。传递函数的典型值为 -70/-70|-60/-20|1/0。

soft-knee

以 dB 为单位设置所有连接点的曲线半径。默认值为 0.01。

gain

以 dB 为单位设置应用于传递函数所有点上的附加增益。这样便于轻松调整整体增益。默认值为 0。

volume

以 dB 为单位设置滤波开始时每个声道假定的初始音量。这使用户可以先提供一个标称电平，从而例如避免在压扩（companding）开始运作之前对初始信号电平施加过大的增益。对于开始时较安静的音频，典型值为 -90 dB。默认值为 0。

delay

以秒为单位设置延迟。输入音频会立即被分析，但音频在送入音量调整器之前会被延迟。指定一个大致等于 attack/decay 时间的延迟，可让滤镜有效地以预测模式而非反应模式运行。默认值为 0。

8.77.1 示例

制作同时包含安静与响亮段落、适合在嘈杂环境中收听的音乐：
```
compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
```

另一个示例，针对包含耳语和爆炸声部分的音频：

    compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0

当噪声电平低于信号时使用的噪声门：

compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1

另一个噪声门示例，这次是噪声电平高于信号的情况（在某种程度上类似于静噪 squelch）：
```
compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
```

从 -6dB 开始的 2:1 压缩：

compand=points=-80/-80|-6/-6|0/-3.8|20/3.5

从 -9dB 开始的 2:1 压缩：

compand=points=-80/-80|-9/-9|0/-5.3|20/2.9

从 -12dB 开始的 2:1 压缩：

compand=points=-80/-80|-12/-12|0/-6.8|20/1.9

从 -18dB 开始的 2:1 压缩：

compand=points=-80/-80|-18/-18|0/-9.8|20/0.7

从 -15dB 开始的 3:1 压缩：

compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2

压缩器/门限：

compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6

扩展器：

compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3

-6dB 的硬限幅器：

compand=attacks=0:points=-80/-80|-6/-6|20/-6

-12dB 的硬限幅器：

compand=attacks=0:points=-80/-80|-12/-12|20/-12

-35 dB 的硬噪声门：

compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20

软限幅器：

compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8

8.78 compensationdelay

Compensation Delay Line（补偿延迟线）是一种基于距离度量的延迟，用于补偿麦克风或扬声器位置的差异。

例如，你用放置在不同位置的两支麦克风录制吉他。由于在正常条件下声波波前的速度是固定的，麦克风的相位会因其位置和相互配置而不同。当这些麦克风处于同相（同步）状态时，可以获得最佳的混音效果。请注意，麦克风之间约 30 cm 的距离会使一支麦克风以与另一支反相的方式捕捉信号，这会使最终的混音听起来发闷。该滤镜通过为每条麦克风轨道添加不同的延迟并使其同步，来帮助解决相位问题。

以一条轨道为基准，将其他轨道逐一与之同步时可获得最佳效果。请记住，同步/延迟的容差也取决于采样率，采样率越高，容差越大。

该滤镜接受以下参数：

以毫米为单位设置距离。这是用于精细调整的补偿距离。默认值为 0。

以厘米为单位设置距离。这是用于收紧距离设置的补偿距离。默认值为 0。

以米为单位设置距离。这是用于粗略距离设置的补偿距离。默认值为 0。

dry

设置 dry 量，即未处理（dry）信号的量。默认值为 0。

wet

设置 wet 量，即已处理（wet）信号的量。默认值为 1。

temp

以摄氏度设置温度。这是环境的温度。默认值为 20。

8.78.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.79 crossfeed

应用耳机串音（crossfeed）滤镜。

串音（crossfeed）是将立体声录音的左右声道进行混合的处理过程，主要用于减弱低频的极端立体声分离感。

其目的是为听者带来更接近扬声器听感的声音。

该滤镜接受以下选项：

strength

设置串音强度。默认值为 0.2。允许范围为 0 到 1。这会为立体声像的侧向部分设置低架滤波器的增益。默认值为 -6dB。strength 设为 1 时允许的最大值为 -30db。

range

设置声场宽度。默认值为 0.5。允许范围为 0 到 1。这会设置低架滤波器的截止频率。默认截止频率约为 1550 Hz。当 range 设为 1 时，截止频率设为 2100 Hz。

slope

设置低架滤波器的曲线斜率。默认值为 0.5。允许范围为 0.01 到 1。

level_in

设置输入增益。默认值为 0.9。

level_out

设置输出增益。默认值为 1。

block_size

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.79.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.80 crystalizer

用于音频锐化的简单算法。

该滤镜会线性地增大各音频采样点之间的差异。

该滤镜接受以下选项：

设置效果强度（默认：2.0）。取值范围为 -10.0 到 0（声音不变）再到 10.0（最大效果）之间。要反向滤波，请使用负值。

启用削波（clipping）。默认启用。

8.80.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.81 dcshift

对音频应用直流（DC）偏移。

这对于从音频中去除直流偏移（可能是由录音链中的硬件问题造成的）很有用。直流偏移的影响是降低余量（headroom），从而降低音量。可以使用 astats 滤镜来判断信号是否存在直流偏移。

shift

设置直流偏移量，允许范围为 [-1, 1]。它表示对音频进行偏移的幅度。

limitergain

可选。其值应远小于 1（例如 0.05 或 0.02），用于防止削波。

8.82 deesser

对音频采样应用去齿音（de-essing）处理。

设置触发去齿音处理的强度。允许范围为 0 到 1。默认值为 0。

设置对声音高音部分的压低（ducking）量。允许范围为 0 到 1。默认值为 0.5。

去齿音时保留多少原始频率内容。允许范围为 0 到 1。默认值为 0.5。

设置输出模式。

可接受的值有：

原样传递输入。

输出滤除齿音（ess）后的信号。

仅输出齿音（ess）成分。

默认值为 o。

8.83 dialoguenhance

增强立体声音频中的对白。

该滤镜接受立体声输入并产生环绕声（3.0）声道输出。新生成的前置中央声道包含了原本存在于两个立体声声道中、经过增强的对白语音。该滤镜输出的前左和前右声道与立体声输入中的相同。

该滤镜接受以下选项：

original

设置要保留在前置中央声道输出中的原始中央成分系数。允许范围为 0 到 1。默认值为 1。

enhance

设置加入前置中央声道输出中的对白增强系数。允许范围为 0 到 3。默认值为 1。

voice

设置语音检测系数。允许范围为 2 到 32。默认值为 2。

8.83.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.84 drmeter

测量音频的动态范围。

DR 值达到 14 及以上见于动态感很强的素材。DR 值在 8 到 13 之间见于过渡性的素材。而低于 8 的则动态范围很差，压缩程度很高。

该滤镜接受以下选项：

length

以秒为单位设置窗口长度，用于将音频分割为等长的片段。默认值为 3 秒。

8.85 dynaudnorm

动态音频归一化器（Dynamic Audio Normalizer）。

该滤镜会对输入音频施加一定量的增益，以将其峰值幅度提升到目标电平（例如 0 dBFS）。不过，与更“简单”的归一化算法不同，Dynamic Audio Normalizer 会针对输入音频动态地重新调整增益系数。这样一来，可以对音频中“安静”的部分施加额外的增益，同时避免让“响亮”的部分产生失真或削波。换句话说：Dynamic Audio Normalizer 会将安静段落与响亮段落的音量“拉平”，即把各段落的音量都调整到相同的目标电平。但请注意，Dynamic Audio Normalizer 是在不使用“动态范围压缩”的情况下实现这一目标的，音频文件中每个段落内部的动态范围会被 100% 保留。

framelen, f

以毫秒为单位设置帧长，范围为 10 到 8000 毫秒，默认值为 500 毫秒。Dynamic Audio Normalizer 会将输入音频切分为称为“帧”的小块来处理，这是必要的，因为峰值幅度对单个采样值而言没有意义，而需要针对连续的一段采样值来确定峰值幅度。“标准”归一化器只会直接使用整个文件的峰值幅度，而 Dynamic Audio Normalizer 则针对每一帧单独确定峰值幅度。帧长以毫秒指定，默认情况下 Dynamic Audio Normalizer 使用 500 毫秒的帧长，经证明这对大多数文件都能取得良好效果。请注意，以采样点数表示的精确帧长，会根据各输入音频文件自身的采样率自动确定。

gausssize, g

设置高斯滤波器的窗口大小，范围为 3 到 301，且必须为奇数，默认值为 31。Dynamic Audio Normalizer 中最重要的参数或许就是高斯平滑滤波器的 window size（窗口大小）。滤波器的窗口大小以帧为单位指定，并以当前帧为中心。为简化起见，该值必须为奇数，因此默认值 31 会将当前帧连同其前面的 15 帧和后面的 15 帧一并纳入考虑。使用更大的窗口会带来更强的平滑效果，从而使增益变化更小，也就是增益适应更慢；反之，使用更小的窗口会带来更弱的平滑效果，从而使增益变化更大，也就是增益适应更快。换句话说，该值越大，Dynamic Audio Normalizer 的行为就越接近“传统”归一化滤镜；反之，该值越小，它的行为就越接近动态范围压缩器。

peak, p

设置目标峰值，用于指定归一化后的音频输入所允许的最高幅度电平。该滤镜会尝试尽可能接近目标峰值幅度，同时也确保归一化后的信号绝不会超过该峰值幅度。一帧的最大局部增益系数直接由目标峰值幅度决定。默认值为 0.95，因而会留出 5% 的余量*。不建议将该值设置得更高。

maxgain, m

设置最大增益系数，范围为 1.0 到 100.0，默认值为 10.0。Dynamic Audio Normalizer 会为每个输入帧确定可能的最大（局部）增益系数，即不会导致削波或失真的最大增益系数。最大增益系数由该帧振幅最高的采样点决定。不过，Dynamic Audio Normalizer 还会通过一个预先设置的（全局）最大增益系数，对每帧的最大增益系数加以限制，这是为了避免在“静音”或近乎静音的帧中出现过大的增益系数。默认情况下最大增益系数为 10.0，对大多数输入来说默认值已经足够，通常不建议调高该值；不过对于整体音量水平极低的输入，可能有必要允许更高的增益系数。但请注意，Dynamic Audio Normalizer 并不会简单地应用“硬性”阈值（即将超过阈值的值直接截断），而是会应用一个“S 形（sigmoid）”阈值函数，这样增益系数会平滑地趋近阈值，但绝不会超过该值。

targetrms, r

设置目标 RMS，范围为 0.0 到 1.0，默认值为 0.0（禁用）。默认情况下，Dynamic Audio Normalizer 执行的是“峰值”归一化，即每一帧的最大局部增益系数（仅）由该帧振幅最高的采样点决定，这样可以在不超过最大信号电平（即不产生削波）的前提下尽可能放大采样值。不过，Dynamic Audio Normalizer 也可以选择性地考虑该帧的均方根（简称 RMS）。在电气工程中，RMS 常用于衡量随时间变化的信号的功率，因此人们认为 RMS 比单纯观察信号峰值幅度更能近似“感知响度”。因此，将所有帧调整到恒定的 RMS 值，就能建立起统一的“感知响度”。如果指定了目标 RMS 值，帧的局部增益系数就会被定义为恰好能得到该 RMS 值的系数。不过请注意，为防止削波，最大局部增益系数仍然受该帧振幅最高采样点的限制。

coupling, n

启用声道耦合。默认启用。默认情况下，Dynamic Audio Normalizer 会以相同的量放大所有声道，这意味着所有声道都会使用同一个增益系数，即可能的最大增益系数由“最响”的声道决定。不过，在某些录音中，各声道的音量可能并不均衡，例如某个声道可能比其他声道“更安静”。在这种情况下，可以使用该选项禁用声道耦合。这样一来，增益系数会针对每个声道独立确定，仅取决于该声道自身振幅最高的采样点，从而有助于统一各声道的音量。

correctdc, c

启用直流偏置校正。默认禁用。（时域中的）音频信号是一系列采样值。在 Dynamic Audio Normalizer 中，这些采样值以 -1.0 到 1.0 的范围表示，与原始输入格式无关。通常，音频信号，即“波形”，应当以零点为中心，也就是说，若计算文件内或单帧内所有采样值的平均值，结果应为 0.0，或至少非常接近该值。但是，如果平均值明显偏离 0.0（无论偏向正方向还是负方向），这种情况就称为直流偏置或直流偏移。由于直流偏置显然是不希望出现的，Dynamic Audio Normalizer 提供了可选的直流偏置校正功能。启用直流偏置校正后，Dynamic Audio Normalizer 会求出每个输入帧的平均值，即“直流校正”偏移量，并从该帧的所有采样值中减去该值，从而确保这些采样值再次以 0.0 为中心。此外，为了避免帧边界处出现“断层”，直流校正偏移值会在相邻帧之间平滑插值。

altboundary, b

启用备用边界模式。默认禁用。Dynamic Audio Normalizer 会考虑每一帧周围一定范围的相邻帧，其中既包括前面的帧，也包括后面的帧。但对于位于音频文件最开头和最末尾的“边界”帧而言，并非所有相邻帧都可用：具体来说，音频文件最开始的若干帧没有前面的帧可用，同样，最后的若干帧也没有后面的帧可用。于是就产生了一个问题：对于“边界”区域中缺失的帧，应假定使用怎样的增益系数？Dynamic Audio Normalizer 实现了两种模式来处理这种情况。默认的边界模式会为缺失的帧假定增益系数恰好为 1.0，从而分别在输入的开头和结尾形成平滑的“淡入”和“淡出”效果。

compress, s

设置压缩系数，范围为 0.0 到 30.0，默认值为 0.0。默认情况下，Dynamic Audio Normalizer 不会应用“传统”压缩，这意味着信号峰值不会被削减，因而每个局部邻域内的完整动态范围都会被保留。不过，在某些情况下，可能需要将 Dynamic Audio Normalizer 的归一化算法与更“传统”的压缩结合使用。为此，Dynamic Audio Normalizer 提供了可选的压缩（阈值处理）功能。仅当压缩功能被启用时，所有输入帧才会在实际归一化处理之前先经过一个软拐点阈值函数处理。简单来说，该阈值函数会削减振幅超过特定阈值的所有采样值。不过，Dynamic Audio Normalizer 并不会简单地应用固定的阈值，而是会针对每一帧单独调整阈值。一般而言，参数越小压缩越强，反之亦然。不建议使用低于 3.0 的值，因为可能出现可闻的失真。

threshold, t

设置目标阈值，用于指定将被归一化的音频输入所允许的最低幅度电平。如果输入帧的音量高于该值，该帧就会被归一化；否则该帧可能完全不会被归一化。默认值设为 0，意味着所有输入帧都会被归一化。该选项主要在不希望放大数字噪声时有用。

channels, h

指定要处理的声道，默认处理所有可用声道。

overlap, o

指定帧的重叠量。设为 0（默认值）时不进行帧重叠。使用大于 0 且小于 1 的值，会带来不那么保守的增益调整，就像将 framelen 选项设为较小值时那样；若 framelen 选项的值针对非零重叠做了相应补偿，则与重叠为 0 的情况相比，增益调整在时间上会更加平滑。

curve, v

指定计算施加到各帧的增益时所使用的峰值映射曲线表达式。输出帧的最大增益仍会受到该滤镜前面提到的其他选项的限制。

该表达式可以包含以下常量：

当前声道编号

当前采样点编号

nb_channels

声道数

以秒表示的时间戳

采样率

当前帧的峰值

8.85.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.86 earwax

使音频在耳机上更易于聆听。

该滤镜会为 44.1kHz 立体声（即音频 CD 格式）音频添加“提示”，使得在耳机上聆听时，立体声声像会从听者头内（耳机的标准听感）移动到听者前方外侧（扬声器的标准听感）。

移植自 SoX。

8.87 equalizer

应用一个双极峰化均衡（EQ）滤镜。使用该滤镜，可以提升或降低所选频率及其附近的信号电平，而（与带通和带阻滤镜不同）其他所有频率的电平保持不变。

为了产生复杂的均衡曲线，该滤镜可以多次给出，每次使用不同的中心频率。

该滤镜接受以下选项：

frequency, f

以 Hz 设置滤镜的中心频率。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

以 width_type 单位指定滤波器的带宽。

gain, g

以 dB 设置所需的增益或衰减。使用正增益时请注意削波。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.87.1 示例

在 1000 Hz 处衰减 10 dB，带宽为 200 Hz：
```
equalizer=f=1000:t=h:width=200:g=-10
```
以 Q 1 在 1000 Hz 处应用 2 dB 增益，并以 Q 2 在 100 Hz 处衰减 5 dB：
```
equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
```

8.87.2 命令

该滤镜支持以下命令：

frequency, f

更改 equalizer 的 frequency。命令的语法为："frequency"

width_type, t

更改 equalizer 的 width_type。命令的语法为："width_type"

width, w

更改 equalizer 的 width。命令的语法为："width"

gain, g

更改 equalizer 的 gain。命令的语法为："gain"

mix, m

更改 equalizer 的 mix。命令的语法为："mix"

8.88 extrastereo

线性地增大左右声道之间的差异，从而为回放增添一种“现场”效果。

该滤镜接受以下选项：

设置差异系数（默认：2.5）。0.0 表示单声道（两声道的平均值），1.0 时声音保持不变，-1.0 时左右声道将互换。

启用削波。默认启用。

8.88.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.89 firequalizer

使用任意频率响应进行 FIR 均衡。

该滤镜接受以下选项：

gain

以 dB 为单位设置增益曲线表达式。该表达式可以包含以下变量：

计算得到的频率

采样率

声道编号；禁用多声道评估时设为 0

chid

声道 ID，参见 libavutil/channel_layout.h；禁用多声道评估时设为第一个声道的 ID

chs

声道数

chlayout

channel_layout，参见 libavutil/channel_layout.h

以及以下函数：

gain_interpolate(f)

根据 gain_entry 在频率 f 处插值增益

cubic_interpolate(f)

与 gain_interpolate 相同，但更平滑

该选项也可用作命令。默认值为 gain_interpolate(f)。

gain_entry

为 gain_interpolate 函数设置增益条目。该表达式可以包含以下函数：

entry(f, g)

在频率 f 处存储值为 g 的增益条目

该选项也可用作命令。

delay

以秒为单位设置滤镜延迟。值越大越精确。默认值为 0.01。

accuracy

以 Hz 为单位设置滤镜精度。值越小越精确。默认值为 5。

wfunc

设置窗函数。可接受的值有：

rectangular

矩形窗，适用于增益曲线已经平滑的情况

hann

汉宁窗（默认）

hamming

海明窗

blackman

布莱克曼窗

nuttall3

三项连续一阶导数纳托尔窗

mnuttall3

最小三项不连续纳托尔窗

nuttall

四项连续一阶导数纳托尔窗

bnuttall

最小四项不连续纳托尔窗（布莱克曼-纳托尔窗）

bharris

布莱克曼-哈里斯窗

tukey

图基窗

fixed

启用后，使用固定数量的音频采样点。这可在使用较大延迟进行滤波时提升速度。默认禁用。

multi

对增益启用多声道评估。默认禁用。

zero_phase

通过减去时间戳来补偿延迟，从而启用零相位模式。默认禁用。

scale

设置增益使用的刻度。可接受的值有：

linlin

线性频率，线性增益

linlog

线性频率，对数（dB）增益（默认）

loglin

对数频率（以 20 Hz 为 0 的倍频程刻度），线性增益

loglog

对数频率，对数增益

dumpfile

设置用于转储的文件，适用于 gnuplot。

dumpscale

设置 dumpfile 使用的刻度。可接受的值与 scale 选项相同。默认值为 linlog。

fft2

启用基于复数 FFT 的双声道卷积。这可显著提升速度。默认禁用。

min_phase

启用最小相位脉冲响应。默认禁用。

8.89.1 示例

1000 Hz 处的低通：

firequalizer=gain='if(lt(f,1000), 0, -INF)'

使用 gain_entry 实现 1000 Hz 处的低通：

firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'

自定义均衡：

firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'

使用零相位补偿延迟的更大延迟：

firequalizer=delay=0.1:fixed=on:zero_phase=on

左声道低通，右声道高通：

firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on

8.90 flanger

对音频应用镶边（flanging）效果。

该滤镜接受以下选项：

delay

以毫秒为单位设置基础延迟。范围为 0 到 30。默认值为 0。

depth

以毫秒为单位设置附加扫描延迟。范围为 0 到 10。默认值为 2。

regen

设置再生百分比（延迟信号反馈）。范围为 -95 到 95。默认值为 0。

width

设置与原始信号混合的延迟信号百分比。范围为 0 到 100。默认值为 71。

speed

设置每秒扫描次数（Hz）。范围为 0.1 到 10。默认值为 0.5。

shape

设置扫描波形，可以是 triangular（三角波）或 sinusoidal（正弦波）。默认值为 sinusoidal。

phase

为多声道设置扫描波的百分比相移。范围为 0 到 100。默认值为 25。

interp

设置延迟线插值方式，linear（线性）或 quadratic（二次）。默认值为 linear。

8.91 haas

对音频应用 Haas 效果。

请注意，这对单声道信号应用最为合理。将此滤镜应用于单声道信号可赋予其一定的方向感，并扩展其立体声像。

该滤镜接受以下选项：

level_in

设置输入电平。默认值为 1，即 0dB

level_out

设置输出电平。默认值为 1，即 0dB。

side_gain

设置应用于信号侧部分的增益。默认值为 1。

middle_source

设置中置声源的种类。可以是以下之一：

‘left’

选择左声道。

‘right’

选择右声道。

‘mid’

选择立体声像中间部分的信号。

‘side’

选择立体声像侧部分的信号。

middle_phase

改变中置相位。默认禁用。

left_delay

设置左声道延迟。默认值为 2.05 毫秒。

left_balance

设置左声道平衡。默认值为 -1。

left_gain

设置左声道增益。默认值为 1。

left_phase

改变左声道相位。默认禁用。

right_delay

设置右声道延迟。默认值为 2.12 毫秒。

right_balance

设置右声道平衡。默认值为 1。

right_gain

设置右声道增益。默认值为 1。

right_phase

改变右声道相位。默认启用。

8.92 hdcd

解码 High Definition Compatible Digital（HDCD）数据。嵌入 HDCD 编码的 16 位 PCM 流会被扩展为 20 位 PCM 流。

该滤镜支持 HDCD 的 Peak Extend 和 Low-level Gain Adjustment 特性，并检测 Transient Filter 标志。

ffmpeg -i HDCD16.flac -af hdcd OUT24.flac

在 wav 中使用该滤镜时，请注意 wav 的默认编码为 16 位，因此生成的 20 位流会被截断回 16 位。要获得 24 位 PCM 输出，请在该滤镜之后使用类似 -acodec pcm_s24le 的选项。

ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav

该滤镜接受以下选项：

disable_autoconvert

禁用滤镜图中的任何自动格式转换或重采样。

process_stereo

将立体声声道一起处理。如果 target_gain 在各声道之间不一致，则视为无效，并使用最后一个有效的 target_gain。

cdt_ms

以毫秒为单位设置代码检测计时器周期。

force_pe

即使未发出 PE 信号，也始终将超过 -3dBFS 的峰值进行扩展。

analyze_mode

将音频替换为纯音，并调整振幅以指示解码过程中的某个特定方面。输出文件可以在音频编辑器中与原始文件一起加载，以辅助分析。

可以使用 analyze_mode=pe:force_pe=true 来查看所有高于 PE 电平的采样点。

可用的模式有：

‘0, off’

禁用

‘1, lle’

每个采样点的增益调整电平

‘2, pe’

发生峰值扩展的采样点

‘3, cdt’

代码检测计时器处于活动状态的采样点

‘4, tgm’

各声道之间 target gain 不匹配的采样点

8.93 headphone

应用头部相关传输函数（HRTF），在用户周围创建虚拟扬声器，以便通过耳机进行双耳听音。HRIR 通过额外的流提供，每个声道需要一个立体声输入流。

该滤镜接受以下选项：

map

设置用于卷积的输入流映射。该参数是一个以 ’|’ 分隔的声道名称列表，按作为滤镜额外流输入给出的顺序排列。这同时指定了输入流的数量。输入流的数量不得少于第一个流的声道数加一。

gain

设置应用于音频的增益。值以 dB 为单位。默认值为 0。

type

设置处理类型。可以是 time 或 freq。time 表示在时域处理音频，速度较慢；freq 表示在频域处理音频，速度较快。默认值为 freq。

lfe

为 LFE 声道设置自定义增益。值以 dB 为单位。默认值为 0。

size

以采样点数设置一次处理的帧大小。默认值为 1024。允许的范围是 1024 到 96000。

hrir

设置 hrir 流的格式。默认值为 stereo。可选值为 multich。若设为 stereo，附加流的数量应大于或等于第一个输入流的输入声道数，且每个附加流的声道数都应为立体声（2 声道）。若设为 multich，附加流的数量应恰好为一个，且该附加流的输入声道数应等于或大于第一个输入流声道数的两倍。

8.93.1 示例

使用 wav 文件作为系数、通过 amovie 滤镜实现 7.1 下混的完整示例，每个 amovie 滤镜使用包含 IR 系数的立体声文件作为输入。这些文件给出了每个虚拟扬声器位置对应的系数：

ffmpeg -i input.wav
-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
output.wav

同样使用 wav 文件作为系数、通过 amovie 滤镜实现 7.1 下混的完整示例，但这次采用 multich 的 hrir 格式：

ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
output.wav

8.94 highpass

应用一个具有 3dB 点频率的高通滤波器。该滤波器可以是单极点，或双极点（默认）。滤波器的滚降为每极点每倍频程 6dB（每极点每十倍频程 20dB）。

该滤镜接受以下选项：

frequency, f

以 Hz 为单位设置频率。默认值为 3000。

poles, p

设置极点数。默认值为 2。

width_type, t

设置指定滤波器带宽的方法。

Q 值

倍频程

斜率

kHz

width, w

以 width_type 的单位指定滤镜的带宽。仅适用于双极点滤镜。默认值为 0.707q，对应巴特沃斯响应。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.94.1 命令

该滤镜支持以下命令：

frequency, f

更改高通频率。命令的语法为 : "frequency"

width_type, t

更改高通的 width_type。命令的语法为 : "width_type"

width, w

更改高通的 width。命令的语法为 : "width"

mix, m

更改高通的 mix。命令的语法为 : "mix"

8.95 join

将多个输入流合并为一个多声道流。

它接受以下参数：

inputs

输入流的数量。默认值为 2。

channel_layout

期望的输出声道布局。默认值为 stereo。

map

将输入的声道映射到输出。该参数是一个以 ’|’ 分隔的映射列表，每项采用 input_idx.in_channel-out_channel 的形式。input_idx 是输入流从 0 开始的索引。in_channel 可以是输入声道的名称（例如前左声道为 FL），也可以是它在指定输入流中的索引。out_channel 是输出声道的名称。

当映射未被显式指定时，该滤镜会尝试猜测映射。其做法是先尝试查找一个未使用的匹配输入声道，若失败则选取第一个未使用的输入声道。

合并 3 个输入（已正确设置声道布局）：

ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT

从 6 个单声道流构建 5.1 输出：

ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
'join=inputs=6:channel_layout=5.1:map=0.0-FL|1.0-FR|2.0-FC|3.0-SL|4.0-SR|5.0-LFE'
out

8.96 ladspa

加载一个 LADSPA（Linux Audio Developer’s Simple Plugin API）插件。

要启用该滤镜的编译，需要使用 --enable-ladspa 配置 FFmpeg。

file, f

指定要加载的 LADSPA 插件库的名称。如果定义了环境变量 LADSPA_PATH，则会在 LADSPA_PATH 中以冒号分隔的列表所指定的各个目录中搜索 LADSPA 插件；否则会在标准 LADSPA 路径中搜索，顺序如下：HOME/.ladspa/lib/、/usr/local/lib/ladspa/、/usr/lib/ladspa/。

plugin, p

指定库中的插件。有些库只包含一个插件，而有些则包含多个。如果未设置该项，滤镜将列出指定库中所有可用的插件。

controls, c

sample_rate, s

指定采样率，默认值为 44100。仅在插件没有输入时使用。

nb_samples, n

设置每个输出帧中每个声道的采样点数，默认值为 1024。仅在插件没有输入时使用。

duration, d

设置源音频的最小持续时间。关于可接受的语法，请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。请注意，由于生成的音频总是在一个完整帧的末尾被截断，实际持续时间可能大于指定值。如果未指定，或指定的持续时间为负值，则音频将被视为无限生成。仅在插件没有输入时使用。

latency, l

启用延迟补偿，默认禁用。仅在插件有输入时使用。

8.96.1 示例

列出 amp（LADSPA 示例插件）库中所有可用的插件：
```
ladspa=file=amp
```
列出 VCF 库中 vcf_notch 插件的所有可用 control 及其有效范围：
```
ladspa=f=vcf:p=vcf_notch:c=help
```
使用 Computer Music Toolkit（CMT）插件库模拟低质量音频设备：
```
ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
```
使用 TAP-plugins（Tom’s Audio Processing plugins）为音频添加混响：
```
ladspa=file=tap_reverb:tap_reverb
```

生成振幅为 0.2 的白噪声：

ladspa=file=cmt:noise_source_white:c=c0=.2

使用 C* Audio Plugin Suite（CAPS）库中的插件 C* Click - Metronome 生成每分钟 20 次的咔嗒声：
```
ladspa=file=caps:Click:c=c1=20'
```
应用 C* Eq10X2 - Stereo 10-band equaliser 效果：
```
ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
```
使用 Steve Harris 的 SWH Plugins 合集中的 fast lookahead limiter 将音量提升 20dB：
```
ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
```
使用 Steve Harris 的 SWH Plugins 合集中的 Multiband EQ 衰减低频：
```
ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
```
使用 C* Audio Plugin Suite（CAPS）库中的 Narrower 缩小立体声像：
```
ladspa=caps:Narrower
```
另一种白噪声，这次使用 C* Audio Plugin Suite（CAPS）库：
```
ladspa=caps:White:.2
```
使用 C* Audio Plugin Suite（CAPS）库生成一些分形噪声：
```
ladspa=caps:Fractal:c=c1=1
```
使用 VLevel 插件进行动态音量归一化：
```
ladspa=vlevel-ladspa:vlevel_mono
```

8.96.2 命令

该滤镜支持以下命令：

修改第 N 个 control 的值。

如果指定的值无效，则会被忽略，并保留此前的值。

8.97 loudnorm

EBU R128 响度归一化。包含动态和线性两种归一化模式。支持单遍（直播流、文件）和双遍（文件）两种模式。该算法可以针对 IL、LRA 和最大真实峰值进行处理。在动态模式下，为了准确检测真实峰值，音频流会被上采样至 192 kHz。要显式设置输出采样率，请使用 -ar 选项或 aresample 滤镜。

该滤镜接受以下选项：

I, i

设置综合响度目标。范围为 -70.0 到 -5.0。默认值为 -24.0。

LRA, lra

设置响度范围目标。范围为 1.0 到 50.0。默认值为 7.0。

TP, tp

设置最大真实峰值。范围为 -9.0 到 +0.0。默认值为 -2.0。

measured_I, measured_i

输入文件的实测 IL。范围为 -99.0 到 +0.0。

measured_LRA, measured_lra

输入文件的实测 LRA。范围为 0.0 到 99.0。

measured_TP, measured_tp

输入文件的实测真实峰值。范围为 -99.0 到 +99.0。

measured_thresh

输入文件的实测阈值。范围为 -99.0 到 +0.0。

offset

设置偏移增益。增益在真实峰值限制器之前应用。范围为 -99.0 到 +99.0。默认值为 +0.0。

linear

通过对源音频进行线性缩放来实现归一化。必须同时指定 measured_I、measured_LRA、measured_TP 和 measured_thresh。目标 LRA 不应低于源 LRA，且综合响度的变化不应导致真实峰值超过目标 TP。如果不满足这些条件中的任何一个，归一化模式将回退为动态模式。可选值为 true 或 false。默认值为 true。

dual_mono

将单声道输入文件视为“双单声道”（dual-mono）处理。如果单声道文件打算在立体声系统上播放，其 EBU R128 测量值在听感上将是不准确的。设为 true 时，该选项会补偿此影响。多声道输入文件不受此选项影响。可选值为 true 或 false。默认值为 false。

print_format

设置统计信息的打印格式。可选值为 summary、json 或 none。默认值为 none。

stats_file

将统计信息写入指定文件。格式由 print_format 控制，且必须设置该项。指定 - 可写入标准输出。默认未设置。

8.98 lowpass

应用一个具有 3dB 点频率的低通滤波器。该滤镜可以是单极点或双极点（默认）。滤波器的滚降为每极点每倍频程 6dB（每极点每十倍频程 20dB）。

该滤镜接受以下选项：

frequency, f

以 Hz 为单位设置频率。默认值为 500。

poles, p

设置极点数。默认值为 2。

width_type, t

设置指定滤波器带宽的方法。

Q 值

倍频程

斜率

kHz

width, w

以 width_type 的单位指定滤镜的带宽。仅适用于双极点滤镜。默认值为 0.707q，对应巴特沃斯响应。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.98.1 示例

仅对 LFE 声道进行低通滤波，如果不存在 LFE 声道则不做任何操作：
```
lowpass=c=LFE
```

8.98.2 命令

该滤镜支持以下命令：

frequency, f

更改低通的频率。命令的语法为： "frequency"

width_type, t

更改低通的 width_type。命令的语法为： "width_type"

width, w

更改低通的 width。命令的语法为： "width"

mix, m

更改低通的 mix。命令的语法为： "mix"

8.99 lv2

加载 LV2（LADSPA Version 2）插件。

要启用该滤镜的编译，需要在 configure FFmpeg 时加上 --enable-lv2。

plugin, p

指定插件 URI。可能需要转义 ’:’。

controls, c

设置以 ’|’ 分隔的 controls 列表，这是决定所加载插件行为的零个或多个浮点值（例如延迟、阈值或增益）。如果将 controls 设置为 help，会打印出所有可用的 control 及其有效范围。

sample_rate, s

指定采样率，默认值为 44100。仅当插件的输入数为 0 时才使用。

nb_samples, n

设置每个输出帧中每个声道的采样数，默认值为 1024。仅当插件的输入数为 0 时才使用。

duration, d

设置生成音源的最小时长。可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。请注意，由于生成的音频总是在完整帧的末尾处被切断，实际时长可能会比指定的时长更长。如果未指定该时长，或者指定的时长为负值，则音频将被视为无限生成。仅当插件的输入数为 0 时才使用。

8.99.1 示例

应用 Calf 的低音增强插件：

lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2

应用 Calf 的 vinyl 插件：

lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5

应用 ArtyFX 的 bit crusher 插件：

lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3

8.99.2 命令

该滤镜支持将插件导出的所有选项作为命令使用。

8.100 mcompand

对音频的动态范围进行多频段压缩或扩展。

输入音频使用 4 阶 Linkwitz-Riley IIR 划分为多个频段。这类似于扬声器的分频器，在没有压扩器动作时会得到平坦的频率响应。

它接受以下参数：

args

此选项的语法为：attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... 关于各项内容的说明，请参阅 compand 滤镜的文档。

8.101 pan

以特定的增益电平混合各声道。该滤镜接受输出声道布局，其后跟随一组声道定义。

该滤镜也可用于高效地重新映射音频流的声道。

该滤镜接受形式为 "l|outdef|outdef|..." 的参数

输出声道布局或声道数量

outdef

输出声道规格，形式为 "out_name=[gain]in_name[(+-)[gain]in_name...]"

out_name

要定义的输出声道，可以是声道名称（FL、FR 等）或声道编号（c0、c1 等）

gain

该声道的乘法系数，1 表示音量保持不变

in_name

要使用的输入声道，详情参见 out_name；不能混用具名和编号的输入声道

如果将声道规格中的 ‘=’ 替换为 ‘<’，则该规格的增益会被重新归一化，使总和为 1，从而避免削波噪声。

8.101.1 混合示例

例如，如果要将立体声下混为单声道，同时为左声道使用更大的系数：

pan=1c|c0=0.9*c0+0.1*c1

一种自定义的下混到立体声的方式，可自动适用于 3、4、5 和 7 声道的环绕声：

pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR

注意，ffmpeg 内置了默认的下混（以及上混）系统，除非有非常特殊的需求，否则应优先使用该系统（参见 "-ac" 选项）。

8.101.2 重新映射示例

声道的重新映射仅在以下情况下才有效：

增益系数为 0 或 1，
每个输出声道只有一个输入，

如果同时满足这些条件，滤镜会通知用户（"Pure channel mapping detected"），并使用经过优化的无损方法进行重新映射。

例如，如果有一个 5.1 声源，希望通过丢弃多余的声道得到立体声音频流：

pan="stereo| c0=FL | c1=FR"

对于同一声源，也可以在保留输入声道布局的同时交换左前声道和右前声道：

pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"

如果输入是立体声音频流，可以按如下方式静音左前声道（同时仍保留立体声声道布局）：

pan="stereo|c1=c1"

同样以立体声音频流作为输入，可以将右声道同时复制到左前和右前声道：

pan="stereo| c0=FR | c1=FR"

8.102 replaygain

ReplayGain 扫描滤镜。该滤镜接收一路音频流作为输入，并原样输出。滤镜处理结束时会显示 track_gain 和 track_peak。

该滤镜接受以下导出的只读选项：

track_gain

流结束时导出的音轨增益，单位为 dB。

track_peak

流结束时导出的音轨峰值。

8.103 resample

转换音频的 sample format、采样率和声道布局。该滤镜不适合直接使用。

8.104 rubberband

使用 librubberband 进行时间伸缩和音高变换。

要启用该滤镜的编译，需要在 configure FFmpeg 时加上 --enable-librubberband。

该滤镜接受以下选项：

tempo

设置速度缩放系数。

pitch

设置音高缩放系数。

transients

设置瞬态检测器。可选值有：

crisp mixed smooth detector

设置检测器。可选值有：

compound percussive soft phase

设置相位。可选值有：

laminar independent window

设置处理窗口大小。可选值有：

standard short long smoothing

设置平滑。可选值有：

off on formant

在变调时启用共振峰保持。可选值有：

shifted preserved pitchq

设置音高质量。可选值有：

quality speed consistency channels

设置声道。可选值有：

apart together

8.104.1 命令

该滤镜支持以下命令：

tempo

更改滤镜的速度缩放系数。命令的语法为： "tempo"

pitch

更改滤镜的音高缩放系数。命令的语法为： "pitch"

8.105 sidechaincompress

该滤镜的行为类似普通压缩器，但能够利用第二路输入信号来压缩检测到的信号。它需要两路输入流，并返回一路输出流。第一路输入流会根据第二路流的信号进行处理。经过滤波的信号随后可以在后续处理阶段被其他滤镜进一步处理。参见 pan 和 amerge 滤镜。

该滤镜接受以下选项：

level_in

设置输入增益。默认值为 1。范围为 0.015625 到 64。

mode

设置压缩器的工作模式。可以是 upward 或 downward。默认值为 downward。

threshold

如果第二路流的信号超过该电平，就会影响第一路流的增益衰减。默认值为 0.125。范围为 0.00097563 到 1。

ratio

设置信号被衰减的比率。1:2 表示如果电平比阈值高出 4dB，衰减后就只比阈值高出 2dB。默认值为 2。范围为 1 到 20。

attack

信号需要高于阈值多少毫秒，增益衰减才会开始。默认值为 20。范围为 0.01 到 2000。

release

信号需要低于阈值多少毫秒，衰减才会重新减弱。默认值为 250。范围为 0.01 到 9000。

makeup

设置处理后信号被放大的量。默认值为 1。范围为 1 到 64。

knee

对阈值附近的尖锐拐点进行圆滑处理，使增益衰减的过渡更加柔和。默认值为 2.82843。范围为 1 到 8。

link

选择由侧链流所有声道的 average（平均）电平，还是由侧链流中更响的（maximum）声道来影响衰减。默认值为 average。

detection

在 peak 模式下取精确信号，在 rms 模式下取 RMS 信号。默认值为 rms，该模式总体更平滑。

level_sc

设置侧链增益。默认值为 1。范围为 0.015625 到 64。

mix

输出中使用多少压缩后的信号。默认值为 1。范围为 0 到 1。

8.105.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.105.2 示例

接收 2 路音频输入的完整 ffmpeg 示例：第 1 路输入根据第 2 路输入的信号进行压缩，随后将压缩后的信号与第 2 路输入合并：
```
ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
```

8.106 sidechaingate

侧链噪声门的行为类似普通的（宽带）噪声门，但能够在将检测到的信号送入增益衰减阶段之前先对其进行滤波。通常，噪声门会使用全频段信号来检测超过阈值的电平。例如：如果从侧链信号中切除所有低频，那么噪声门只有在高频不足时才会降低音轨的音量。利用这种技术，可以减少原声鼓的共鸣，或去除失真强烈的吉他闷音的“隆隆声”。它需要两路输入流，并返回一路输出流。第一路输入流会根据第二路流的信号进行处理。

该滤镜接受以下选项：

level_in

设置滤波前的输入电平。默认值为 1。允许的范围为 0.015625 到 64。

mode

设置工作模式。可以是 upward 或 downward。默认值为 downward。设置为 upward 模式时，信号中较高的部分会被放大，从而向上扩展动态范围；否则在 downward 模式下，信号中较低的部分会被衰减。

range

设置信号低于阈值时的增益衰减电平。默认值为 0.06125。允许的范围为 0 到 1。将其设置为 0 会禁用衰减，此时滤镜的行为类似扩展器。

threshold

如果信号升高到超过该电平，增益衰减就会解除。默认值为 0.125。允许的范围为 0 到 1。

ratio

设置信号被衰减的比率。默认值为 2。允许的范围为 1 到 9000。

attack

信号需要高于阈值多少毫秒，增益衰减才会停止。默认值为 20 毫秒。允许的范围为 0.01 到 9000。

release

信号需要低于阈值多少毫秒，衰减才会再次增大。默认值为 250 毫秒。允许的范围为 0.01 到 9000。

makeup

设置处理后信号的放大量。默认值为 1。允许的范围为 1 到 64。

knee

对阈值附近的尖锐拐点进行圆滑处理，使增益衰减的过渡更加柔和。默认值为 2.828427125。允许的范围为 1 到 8。

detection

选择检测时取精确信号还是取类 RMS 信号。默认值为 rms。可以是 peak 或 rms。

link

选择由所有声道的平均电平还是由更响的声道来影响衰减。默认值为 average。可以是 average 或 maximum。

level_sc

设置侧链增益。默认值为 1。范围为 0.015625 到 64。

8.106.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.107 silencedetect

检测音频流中的静音。

当该滤镜检测到输入音频音量在不短于最小检测噪声时长的时间内，一直小于或等于噪声容差值时，就会记录一条消息。

打印出的时间和时长以秒为单位表示。lavfi.silence_start 或 lavfi.silence_start.X 元数据键会设置在时间戳达到或超过检测时长的第一帧上，其中包含静音第一帧的时间戳。

lavfi.silence_duration 或 lavfi.silence_duration.X，以及 lavfi.silence_end 或 lavfi.silence_end.X 元数据键会设置在静音之后的第一帧上。如果启用了 mono，各声道会被单独评估，此时会使用带 .X 后缀的键，其中 X 对应声道号。

该滤镜接受以下选项：

noise, n

设置噪声容差。可以用 dB 指定（即在指定值后加上 "dB"），也可以用振幅比指定。默认值为 -60dB，即 0.001。

duration, d

设置触发通知所需的静音时长（默认值为 2 秒）。可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。

mono, m

分别处理各声道，而不是合并处理。默认情况下禁用。

8.107.1 示例

以 -50dB 的噪声容差检测 5 秒的静音：
```
silencedetect=n=-50dB:d=5
```
使用 ffmpeg 以 0.0001 的噪声容差检测 silence.mp3 中静音的完整示例：
```
ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
```

8.108 silenceremove

去除音频开头、中间或结尾处的静音。

该滤镜接受以下选项：

start_periods

该值用于指示是否应裁剪音频开头的静音。值为 0 表示不裁剪开头的静音。指定非零值时，会一直裁剪音频，直到找到非静音为止。通常，从音频开头裁剪静音时 start_periods 应为 1，但也可以设置为更大的值，以裁剪掉直到出现指定次数非静音区间为止的所有音频。默认值为 0。

start_duration

指定必须检测到多长时间的非静音，才会停止裁剪音频。增大该时长，可以将突发噪声也当作静音裁剪掉。默认值为 0。

start_threshold

该值指示应将何种采样值视为静音。对于数字音频，0 通常就够用了，但对于从模拟设备录制的音频，可能需要提高该值以计入背景噪声。可以用 dB 指定（即在指定值后加上 "dB"），也可以用振幅比指定。默认值为 0。

start_silence

指定裁剪后在开头保留的静音最大时长。默认值为 0，相当于裁剪掉所有被检测为静音的采样。

start_mode

指定多声道音频开头处静音结束的检测模式。可以是 any 或 all。默认值为 any。使用 any 时，只要任意声道的任意采样被检测为非静音，就会触发音频流开头静音裁剪的结束。使用 all 时，只有当每个声道的每个采样都被检测为非静音，才会触发音频流开头静音裁剪的结束，用途有限。

stop_periods

设置从音频末尾裁剪静音的次数。指定正值时，会在找到指定的静音区间后裁剪音频。要去除文件中间的静音，可将 stop_periods 指定为负值。此时该值会被当作正值处理，用于指示效果应按 stop_periods 指定的次数重新开始处理，因而适合去除音频中间的静音区间。默认值为 0。

stop_duration

指定在停止复制音频之前必须存在的静音时长。指定更长的时长，可以让想要保留的静音留在音频中。默认值为 0。

stop_threshold

与 start_threshold 相同，但用于从音频末尾裁剪静音。可以用 dB 指定（即在指定值后加上 "dB"），也可以用振幅比指定。默认值为 0。

stop_silence

指定裁剪后在末尾保留的静音最大时长。默认值为 0，相当于裁剪掉所有被检测为静音的采样。

stop_mode

指定多声道音频开头之后静音开始的检测模式。可以是 any 或 all。默认值为 all。使用 any 时，只要任意声道的任意采样被检测为静音，就会触发音频流开头之后静音裁剪的开始，用途有限。使用 all 时，只有当每个声道的每个采样都被检测为静音，才会触发音频流开头之后静音裁剪的开始。

detection

设置静音的检测方式。

avg

移动窗口内采样绝对值的平均值。

rms

移动窗口内采样绝对值的均方根。

peak

移动窗口内采样绝对值的最大值。

median

移动窗口内采样绝对值的中位数。

ptp

移动窗口内采样最大峰值与最小峰值之差的绝对值。

dev

移动窗口内采样值的标准差。

默认值为 rms。

window

以秒为单位设置时长，用于计算静音检测窗口的采样数大小。使用 0 会实际上禁用任何窗口处理，静音检测时每个声道只使用单个采样。此时可能还需要将 start_silence 和/或 stop_silence 设置为非零值，同时也将 start_duration 和/或 stop_duration 设置为非零值。默认值为 0.02。允许的范围为 0 到 10。

timestamp

设置每个输出音频帧时间戳的处理模式。

write

全面重写时间戳，仅为第一个输出帧保留起始时间。

copy

未被丢弃的帧保持与输入音频帧相同的时间戳。

默认值为 write。

8.108.1 示例

以下示例展示了如何使用该滤镜，来开始一段不包含通常发生在按下录制按钮与表演开始之间那段延迟的录音：
```
silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
```
裁剪音频中从开头到结尾遇到的所有超过 1 秒的静音：
```
silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
```
使用峰值检测，裁剪音频中从开头到结尾所有的数字静音采样，前提是音频中存在超过 0 个数字静音采样，且在流中所有声道的相同位置都检测到数字静音：
```
silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
```
裁剪音频中从开头到结尾每隔一个遇到的静音区间，前提是每个静音区间中的静音超过 1 秒：
```
silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB
```

与上面类似，但从每个被裁剪的区间中最多保留 0.5 秒的静音：

silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5

与上面类似，但从音频开头最多保留 1.5 秒的静音：

silenceremove=stop_periods=-2:stop_duration=1:stop_threshold=-90dB:stop_silence=0.5:start_periods=1:start_duration=1:start_silence=1.5:stop_threshold=-90dB

8.108.2 命令

该滤镜支持将以上部分选项作为命令使用。

8.109 sofalizer

SOFAlizer 使用头相关传输函数（HRTF）在用户周围生成虚拟扬声器，以便通过耳机进行双耳聆听（最多支持 9 声道的音频格式）。HRTF 存储在 SOFA 文件中（相关数据库参见 http://www.sofacoustics.org/）。SOFAlizer 由奥地利科学院声学研究所（ARI）开发。

要启用该滤镜的编译，需要在 configure FFmpeg 时加上 --enable-libmysofa。

该滤镜接受以下选项：

sofa

设置用于渲染的 SOFA 文件。

gain

设置应用于音频的增益。值以 dB 为单位。默认值为 0。

rotation

以度为单位设置虚拟扬声器的旋转角度。默认值为 0。

elevation

以度为单位设置虚拟扬声器的仰角。默认值为 0。

radius

以米为单位设置使用近场 HRTF 时扬声器与听者之间的距离。默认值为 1。

type

设置处理类型。可以是 time 或 freq。time 在时域中处理音频，速度较慢；freq 在频域中处理音频，速度较快。默认值为 freq。

speakers

自定义设置虚拟扬声器的位置。该选项的语法为： [| |...]。每个虚拟扬声器用一个简短的声道名后接以度为单位的方位角和仰角来描述。各虚拟扬声器的描述之间用 ’|’ 分隔。例如，要覆盖左前和右前声道的位置，可使用：’speakers=FL 45 15|FR 345 15’。包含无法识别的声道名的描述会被忽略。

lfegain

自定义设置 LFE 声道的增益。值以 dB 为单位。默认值为 0。

framesize

以采样数自定义设置帧大小。默认值为 1024。允许的范围为 1024 到 96000。仅当 ‘type’ 选项设置为 freq 时才使用。

normalize

导入 SOFA 文件时是否对所有 IR 进行归一化。默认情况下已启用。

interpolate

在精确位置不匹配时，是否对最近的 IR 与相邻 IR 进行插值。默认情况下已禁用。

minphase

加载 SOFA 文件时对所有 IR 进行最小相位化。默认情况下已禁用。

anglestep

设置邻近搜索的角度步长。仅当 interpolate 选项启用时才使用。

radstep

设置邻近搜索的半径步长。仅当 interpolate 选项启用时才使用。

8.109.1 示例

使用 ClubFritz6 sofa 文件：

sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1

使用 ClubFritz12 sofa 文件，采用更大的半径和小幅旋转：

sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5

与上面类似，但为左前、右前、左后和右后自定义了扬声器位置，同时也自定义了增益：
```
"sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
```

8.110 speechnorm

Speech Normalizer（语音归一化器）。

该滤镜会根据阈值对音频采样的每个半周期（局部一组全部高于零或全部低于零、且位于两个最近零交叉点之间的采样）进行扩展或压缩，从而使音频在以下选项控制的条件下达到目标峰值。

该滤镜接受以下选项：

peak, p

设置扩展的目标峰值。此值指定归一化后的输入音频所允许的最高绝对振幅电平。默认值为 0.95。允许的范围为 0.0 到 1.0。

expansion, e

设置最大扩展系数。允许的范围为 1.0 到 50.0。默认值为 2.0。该选项控制采样局部半周期的最大扩展量。最大扩展量应使局部峰值达到目标峰值但绝不超过它，且新旧峰值之比不超过该选项的值。

compression, c

设置最大压缩系数。允许的范围为 1.0 到 50.0。默认值为 2.0。该选项控制采样局部半周期的最大压缩量。该选项仅在 threshold 选项设置为大于 0.0 的值时才会使用；在这种情况下，当局部峰值低于或等于 threshold 设置的值时，属于该峰值所在半周期的所有采样都会按当前压缩系数进行压缩。

threshold, t

设置阈值。默认值为 0.0。允许的范围为 0.0 到 1.0。该选项指定哪些半周期的采样会被压缩，哪些会被扩展。局部峰值低于或等于该选项值的半周期采样会按当前压缩系数压缩；否则，若高于阈值，则会按扩展系数进行扩展，使其能达到目标峰值但绝不超过它。

raise, r

设置每个采样半周期扩展系数的提升量。默认值为 0.001。允许的范围为 0.0 到 1.0。这控制着每个新半周期扩展系数提升的速度，直到达到 expansion 的值为止。将该选项设置得过高可能会导致失真。

fall, f

设置每个采样半周期压缩系数的提升量。默认值为 0.001。允许的范围为 0.0 到 1.0。这控制着每个新半周期压缩系数提升的速度，直到达到 compression 的值为止。

channels, h

指定要滤波的声道，默认情况下会滤波所有可用声道。

invert, i

启用反转滤波，默认情况下禁用。这会反转对 threshold 选项的解读方式。启用后，局部峰值低于或等于 threshold 选项的采样半周期会被扩展，否则会被压缩。

link, l

在计算应用于各滤波声道采样的增益时联动各声道，默认情况下禁用。禁用时，各滤波声道的增益计算相互独立；启用该选项后，则会为每个滤波声道使用所有可能增益中的最小值。

rms, m

设置扩展的目标 RMS 值。此值指定归一化后的输入音频所允许的最高 RMS 电平。默认值为 0.0，即禁用状态。允许的范围为 0.0 到 1.0。

8.110.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.110.2 示例

微弱而缓慢的放大：
```
speechnorm=e=3:r=0.00001:l=1
```
适中而缓慢的放大：
```
speechnorm=e=6.25:r=0.00001:l=1
```
强烈而快速的放大：
```
speechnorm=e=12.5:r=0.0001:l=1
```
非常强烈而快速的放大：
```
speechnorm=e=25:r=0.0001:l=1
```
极端而快速的放大：
```
speechnorm=e=50:r=0.0001:l=1
```

8.111 stereotools

该滤镜提供了一些便捷的工具来处理立体声信号，可在控制参数的同时将 M/S 立体声录音转换为 L/R 信号，或扩展主轨的立体声声像。

该滤镜接受以下选项：

level_in

为两个声道设置滤波前的输入电平。默认值为 1。允许的范围为 0.015625 到 64。

level_out

为两个声道设置滤波后的输出电平。默认值为 1。允许的范围为 0.015625 到 64。

balance_in

设置两个声道之间的输入平衡。默认值为 0。允许的范围为 -1 到 1。

balance_out

设置两个声道之间的输出平衡。默认值为 0。允许的范围为 -1 到 1。

softclip

启用软削波。这会产生模拟失真，而不是生硬的数字 0dB 削波。默认情况下禁用。

mutel

静音左声道。默认情况下禁用。

muter

静音右声道。默认情况下禁用。

phasel

改变左声道的相位。默认情况下禁用。

phaser

改变右声道的相位。默认情况下禁用。

mode

设置立体声模式。可用值有：

‘lr>lr’

Left/Right 转换为 Left/Right，这是默认值。

‘lr>ms’

Left/Right 转换为 Mid/Side。

‘ms>lr’

Mid/Side 转换为 Left/Right。

‘lr>ll’

Left/Right 转换为 Left/Left。

‘lr>rr’

Left/Right 转换为 Right/Right。

‘lr>l+r’

Left/Right 转换为 Left + Right。

‘lr>rl’

Left/Right 转换为 Right/Left。

‘ms>ll’

Mid/Side 转换为 Left/Left。

‘ms>rr’

Mid/Side 转换为 Right/Right。

‘ms>rl’

Mid/Side 转换为 Right/Left。

‘lr>l-r’

Left/Right 转换为 Left - Right。

slev

设置侧信号的电平。默认值为 1。允许的范围为 0.015625 到 64。

sbal

设置侧信号的平衡。默认值为 0。允许的范围为 -1 到 1。

mlev

设置中间信号的电平。默认值为 1。允许的范围为 0.015625 到 64。

mpan

设置中间信号的声像。默认值为 0。允许的范围为 -1 到 1。

base

在单声道和反转声道之间设置立体声基准。默认值为 0。允许的范围为 -1 到 1。

delay

以毫秒为单位设置延迟，即左声道相对右声道延迟多少，反之亦然。默认值为 0。允许的范围为 -20 到 20。

sclevel

设置 S/C 电平。默认值为 1。允许的范围为 1 到 100。

phase

以度为单位设置立体声相位。默认值为 0。允许的范围为 0 到 360。

bmode_in, bmode_out

设置 balance_in/balance_out 选项的平衡模式。

可以是以下之一：

‘balance’

经典平衡模式。每次衰减一个声道。增益最高提升到 1。

‘amplitude’

与上面的经典模式类似，但增益最高提升到 2。

‘power’

等功率分配，范围为 -6dB 到 +6dB。

8.111.1 命令

该滤镜支持将以上所有选项作为命令使用。

8.111.2 示例

应用类似卡拉 OK 的效果：
```
stereotools=mlev=0.015625
```
将 M/S 信号转换为 L/R：
```
"stereotools=mode=ms>lr"
```

8.112 stereowiden

此滤镜通过抑制两个声道共有的信号，并将左声道的信号延迟到右声道（反之亦然），从而增强立体声效果、拓宽立体声感。

该滤镜接受以下选项：

delay

左声道信号延迟到右声道（反之亦然）的时间，单位为毫秒。默认为 20 毫秒。

feedback

延迟信号进入右声道（反之亦然）的增益量。会给左声道信号在右声道输出（反之亦然）中带来延迟效果，从而产生拓宽感。默认为 0.3。

crossfeed

将左声道以反相方式交叉馈送到右声道。这有助于抑制单声道成分。若该值为 1，将抵消两个声道共有的全部信号。默认为 0.3。

drymix

设置原始声道输入信号的电平。默认为 0.8。

8.112.1 命令

此滤镜支持除 delay 之外的上述所有选项作为命令。

8.113 superequalizer

应用 18 段均衡器。

该滤镜接受以下选项：

设置 65Hz 频段的增益。

设置 92Hz 频段的增益。

设置 131Hz 频段的增益。

设置 185Hz 频段的增益。

设置 262Hz 频段的增益。

设置 370Hz 频段的增益。

设置 523Hz 频段的增益。

设置 740Hz 频段的增益。

设置 1047Hz 频段的增益。

10b

设置 1480Hz 频段的增益。

11b

设置 2093Hz 频段的增益。

12b

设置 2960Hz 频段的增益。

13b

设置 4186Hz 频段的增益。

14b

设置 5920Hz 频段的增益。

15b

设置 8372Hz 频段的增益。

16b

设置 11840Hz 频段的增益。

17b

设置 16744Hz 频段的增益。

18b

设置 20000Hz 频段的增益。

8.114 surround

应用音频环绕上混滤镜。

此滤镜可从音频流生成多声道输出。

该滤镜接受以下选项：

chl_out

设置输出声道布局。默认为 5.1。

所需语法请参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Channel Layout 一节。

chl_in

设置输入声道布局。默认为立体声。

所需语法请参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Channel Layout 一节。

level_in

设置输入音量电平。默认为 1。

level_out

设置输出音量电平。默认为 1。

lfe

如果输出声道布局包含 LFE 声道，则启用其输出。默认启用。

lfe_low

设置 LFE 低截止频率。默认为 128 Hz。

lfe_high

设置 LFE 高截止频率。默认为 256 Hz。

lfe_mode

设置 LFE 模式，可为 add 或 sub。默认为 add。在 add 模式下，LFE 声道由输入音频生成并加入输出。在 sub 模式下，LFE 声道同样由输入音频生成并加入输出，但同时会从所有非 LFE 输出声道中减去输出 LFE 声道。

smooth

设置时间平滑强度，用于在变换立体声音频时逐步改变各系数。允许范围为 0.0 到 1.0。当 focus 选项的值大于 0.0 时，有助于提升输出质量。默认为 0.0。只有此范围内、且不含边界的值才有效。

angle

设置立体声环绕变换的角度。允许范围为 0 到 360。默认为 90。

focus

设置立体声环绕变换的焦点。允许范围为 -1 到 1。默认为 0。

fc_in

设置前中置声道输入音量。默认为 1。

fc_out

设置前中置声道输出音量。默认为 1。

fl_in

设置前左声道输入音量。默认为 1。

fl_out

设置前左声道输出音量。默认为 1。

fr_in

设置前右声道输入音量。默认为 1。

fr_out

设置前右声道输出音量。默认为 1。

sl_in

设置侧左声道输入音量。默认为 1。

sl_out

设置侧左声道输出音量。默认为 1。

sr_in

设置侧右声道输入音量。默认为 1。

sr_out

设置侧右声道输出音量。默认为 1。

bl_in

设置后左声道输入音量。默认为 1。

bl_out

设置后左声道输出音量。默认为 1。

br_in

设置后右声道输入音量。默认为 1。

br_out

设置后右声道输出音量。默认为 1。

bc_in

设置后中置声道输入音量。默认为 1。

bc_out

设置后中置声道输出音量。默认为 1。

lfe_in

设置 LFE 输入音量。默认为 1。

lfe_out

设置 LFE 输出音量。默认为 1。

allx

设置所有声道在 X 轴方向上的立体声像展开使用量。允许范围为 -1 到 15。默认此值为负值 -1，即不使用。

ally

设置所有声道在 Y 轴方向上的立体声像展开使用量。允许范围为 -1 到 15。默认此值为负值 -1，即不使用。

fcx, flx, frx, blx, brx, slx, srx, bcx

设置各声道在 X 轴方向上的立体声像展开使用量。允许范围为 0.06 到 15。默认此值为 0.5。

fcy, fly, fry, bly, bry, sly, sry, bcy

设置各声道在 Y 轴方向上的立体声像展开使用量。允许范围为 0.06 到 15。默认此值为 0.5。

win_size

设置窗口大小。允许范围为 1024 到 65536。默认大小为 4096。

win_func

设置窗口函数。

可接受的值有：

默认值为 hann。

overlap

设置窗口重叠量。若设为 1，将选取所选窗口函数推荐的重叠量。默认为 0.5。

8.115 tiltshelf

使用一个响应类似标准 hi-fi 音调控制的双极搁架式滤波器，提升或削减音频的低频，同时削减或提升高频。这也称为搁架式均衡（EQ）。

该滤镜接受以下选项：

gain, g

给出 0 Hz 处的增益。其有效范围大约为 -20（大幅削减）到 +20（大幅提升）。使用正增益时请注意削波。

frequency, f

设置滤波器的中心频率，从而可用于扩大或缩小要提升或削减的频率范围。默认值为 3000 Hz。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

决定滤波器搁架过渡的陡峭程度。

poles, p

设置极点数。默认值为 2。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.115.1 命令

此滤镜支持部分选项作为命令。

8.116 treble, highshelf

使用一个响应类似标准 hi-fi 音调控制的双极搁架式滤波器，提升或削减音频的高音（高频）。这也称为搁架式均衡（EQ）。

该滤镜接受以下选项：

gain, g

给出约 22 kHz 与奈奎斯特频率二者中较低者处的增益。其有效范围大约为 -20（大幅削减）到 +20（大幅提升）。使用正增益时请注意削波。

frequency, f

设置滤波器的中心频率，从而可用于扩大或缩小要提升或削减的频率范围。默认值为 3000 Hz。

width_type, t

设置指定滤波器带宽的方法。

Q 因子

倍频程

斜率

kHz

width, w

决定滤波器搁架过渡的陡峭程度。

poles, p

设置极点数。默认值为 2。

mix, m

输出中使用经滤波信号的比例。默认值为 1。范围为 0 到 1。

channels, c

指定要滤波的声道，默认对所有可用声道进行滤波。

normalize, n

对 biquad 系数进行归一化，默认禁用。启用后会将直流（DC）处的幅度响应归一化到 0dB。

transform, a

设置 IIR 滤波器的变换类型。

di dii tdi tdii latt svf zdf precision, r

设置滤波精度。

auto

根据环绕声滤镜自动选择 sample format。

s16

始终使用有符号 16 位。

s32

始终使用有符号 32 位。

f32

始终使用 32 位浮点。

f64

始终使用 64 位浮点。

block_size, b

请注意，设置为非零值时，滤镜延迟将恰好为这么多个采样点。

8.116.1 命令

该滤镜支持以下命令：

frequency, f

更改高音的频率。命令的语法为: "frequency"

width_type, t

更改高音的 width_type。命令的语法为: "width_type"

width, w

更改高音的 width。命令的语法为: "width"

gain, g

更改高音的增益。命令的语法为: "gain"

mix, m

更改高音的 mix。命令的语法为: "mix"

8.117 tremolo

正弦波幅度调制。

该滤镜接受以下选项：

调制频率，单位为赫兹。次谐波范围（20 Hz 或以下）的调制频率会产生颤音（tremolo）效果。将调制频率指定为高于 20 Hz 时，此滤镜也可用作环形调制器。范围为 0.1 - 20000.0。默认值为 5.0 Hz。

以百分比表示的调制深度。范围为 0.0 - 1.0。默认值为 0.5。

8.118 vibrato

正弦波相位调制。

该滤镜接受以下选项：

调制频率，单位为赫兹。范围为 0.1 - 20000.0。默认值为 5.0 Hz。

以百分比表示的调制深度。范围为 0.0 - 1.0。默认值为 0.5。

8.119 virtualbass

应用音频虚拟低音（Virtual Bass）滤镜。

此滤镜接受立体声输入，并生成带 LFE（2.1）声道的立体声输出。新生成的 LFE 声道包含从两个立体声声道中得到的增强虚拟低音。此滤镜按立体声输入原样输出前左和前右声道，不做更改。

该滤镜接受以下选项：

cutoff

设置虚拟低音的截止频率。默认值为 250 Hz。允许范围为 100 到 500 Hz。

strength

设置虚拟低音的强度。允许范围为 0.5 到 3。默认值为 3。

8.120 volume

调整输入音频的音量。

它接受以下参数：

volume

设置音频音量表达式。

输出值会被裁剪到最大值。

输出音频音量由以下关系给出：

output_volume = volume * input_volume

volume 的默认值为 "1.0"。

precision

此参数表示数学精度。

它决定允许哪些输入 sample format，进而影响音量缩放的精度。

fixed

8 位定点；这会将输入 sample format 限制为 U8、S16 和 S32。

float

32 位浮点；这会将输入 sample format 限制为 FLT。（默认）

double

64 位浮点；这会将输入 sample format 限制为 DBL。

replaygain

选择在输入帧中遇到 ReplayGain 附加数据时的行为。

drop

移除 ReplayGain 附加数据，忽略其内容（默认）。

ignore

忽略 ReplayGain 附加数据，但将其保留在帧中。

track

若存在轨道增益（track gain），优先使用它。

album

若存在专辑增益（album gain），优先使用它。

replaygain_preamp

应用于所选 replaygain 增益的前置放大增益，单位为 dB。

replaygain_preamp 的默认值为 0.0。

replaygain_noclip

通过限制所应用的增益来防止削波。

replaygain_noclip 的默认值为 1。

eval

设置何时对音量表达式求值。

可接受的值有：

‘once’

仅在滤镜初始化时，或在发送 ‘volume’ 命令时，对表达式求值一次

‘frame’

对每个到来的帧求值

默认值为 ‘once’。

音量表达式可包含以下参数。

帧编号（从零开始）

nb_channels

声道数

nb_consumed_samples

滤镜已消耗的采样数

nb_samples

当前帧中的采样数

pos

文件中原始帧的位置；已弃用，请勿使用

pts

帧的 PTS

sample_rate

采样率

startpts

流起始处的 PTS

startt

流起始处的时间

帧的时间

时间戳的时间基

volume

最后设置的音量值

请注意，当 eval 设为 ‘once’ 时，仅 sample_rate 和 tb 变量可用，其余所有变量都将求值为 NAN。

8.120.1 命令

该滤镜支持以下命令：

volume

修改音量表达式。此命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

8.120.2 示例

将输入音频的音量减半：

volume=volume=0.5
volume=volume=1/2
volume=volume=-6.0206dB

在以上所有示例中，volume 这个命名键均可省略，例如可以这样写：

    volume=0.5

使用定点精度将输入音频功率提高 6 分贝：
```
volume=volume=6dB:precision=fixed
```
在时间 10 之后，以 5 秒的衰减周期使音量淡出：
```
volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
```

8.121 volumedetect

检测输入视频的音量。

此滤镜没有参数。它仅支持 16 位有符号整数采样，因此在需要时会对输入进行转换。到达输入流末尾时，会在日志中打印有关音量的统计信息。

具体来说，它会显示平均音量（均方根）、最大音量（按每个采样计算），以及已记录音量值的直方图起始部分（从最大值到累计 1/1000 的采样）。

所有音量均以相对于最大 PCM 值的分贝表示。

8.121.1 示例

以下是输出的摘录：

[Parsed_volumedetect_0  0xa23120] mean_volume: -27 dB
[Parsed_volumedetect_0  0xa23120] max_volume: -4 dB
[Parsed_volumedetect_0  0xa23120] histogram_4db: 6
[Parsed_volumedetect_0  0xa23120] histogram_5db: 62
[Parsed_volumedetect_0  0xa23120] histogram_6db: 286
[Parsed_volumedetect_0  0xa23120] histogram_7db: 1042
[Parsed_volumedetect_0  0xa23120] histogram_8db: 2551
[Parsed_volumedetect_0  0xa23120] histogram_9db: 4609
[Parsed_volumedetect_0  0xa23120] histogram_10db: 8409

这意味着：

均方能量约为 -27 dB，即 10^-2.7。
最大的采样为 -4 dB，更准确地说是介于 -4 dB 与 -5 dB 之间。
有 6 个采样为 -4 dB，62 个为 -5 dB，286 个为 -6 dB，依此类推。

换言之，将音量提高 +4 dB 不会导致任何削波，提高 +5 dB 则会导致 6 个采样出现削波，依此类推。

8.122 whisper

它使用 OpenAI 的 Whisper 模型运行自动语音识别。

它需要 whisper.cpp 库 (https://github.com/ggml-org/whisper.cpp) 作为前提条件。安装该库后，可以使用以下命令启用：./configure --enable-whisper。

该滤镜具有以下选项：

model

已下载的 whisper.cpp 模型的文件路径（必需）。

language

用于转录的语言（自动检测使用 ’auto’）。默认值："auto"

translate

启用后，会将转录内容从源语言翻译为英语。启用此选项需要使用多语言模型。默认值："false"

queue

在使用 whisper 处理音频之前，可排入该滤镜队列等待处理的最大大小。使用较小的值时，音频流会被更频繁地处理，但转录质量会降低，所需的处理能力也会更高。使用较大的值（例如 10-20 秒）时，可以用更少的 CPU（就像使用 whisper-cli 工具那样）获得更准确的结果，但转录延迟会更高，因此不适合处理实时流。可以考虑将 vad_model 选项与较大的 queue 值搭配使用。默认值："3"

use_gpu

是否应启用 GPU 支持。默认值："true"

gpu_device

要使用的 GPU 设备索引。默认值："0"

destination

如果设置了该项，转录输出会被发送到指定的文件或 URL（使用某种 FFmpeg AVIO 协议）；否则，输出会以 info 消息的形式记录到日志中。输出还会被写入 "lavfi.whisper.text" 帧元数据中。如果目标是文件且该文件已存在，将会被覆盖。

format

目标格式字符串，可以是 "text"（只会将转录得到的文本发送到目标）、"srt"（字幕格式）或 "json"。默认值："text"

max_len

以字符数表示的段最大长度。设置为大于 0 的值时，转录段会按单词拆分，以不超过该长度。这对于生成行较短的字幕很有用。默认值："0"

vad_model

VAD 模型文件的路径。设置后，滤镜会加载一个额外的语音活动检测（voice activity detection）模块 (https://github.com/snakers4/silero-vad)，用于对音频队列进行分段；使用该选项时，请设置一个从 whisper.cpp 仓库获取的有效路径（例如 "../whisper.cpp/models/ggml-silero-v5.1.2.bin"），并将 queue 参数增大到更高的值（例如 20）。

vad_threshold

要使用的 VAD 阈值。默认值："0.5"

vad_min_speech_duration

VAD 判定为语音的最小持续时间。默认值："0.1"

vad_min_silence_duration

VAD 判定为静音的最小持续时间。默认值："0.5"

8.122.1 示例

运行转录并生成 srt 文件：

ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
:language=en\
:queue=3\
:destination=output.srt\
:format=srt" -f null -

运行转录，并将输出以 JSON 格式发送到 HTTP 服务：

ffmpeg -i input.mp4 -vn -af "whisper=model=../whisper.cpp/models/ggml-base.en.bin\
:language=en\
:queue=3\
:destination=http\\://localhost\\:3000\
:format=json' -f null -

使用 VAD 选项转录麦克风输入：

ffmpeg -loglevel warning -f pulse -i default \
-af 'highpass=f=200,lowpass=f=3000,whisper=model=../whisper.cpp/models/ggml-medium.bin\
:language=en\
:queue=10\
:destination=-\
:format=json\
:vad_model=../whisper.cpp/models/ggml-silero-v5.1.2.bin' -f null -

9 音频源

下面是当前可用音频源的说明。

9.1 abuffer

缓冲音频帧，并使其可供滤镜链使用。

该源主要用于程序化使用，特别是通过 libavfilter/buffersrc.h 中定义的接口使用。

它接受以下参数：

time_base

提交帧的时间戳所使用的时间基。它必须是浮点数，或者是分子/分母的形式。

sample_rate

输入音频缓冲区的采样率。

sample_fmt

输入音频缓冲区的 sample format。可以是 sample format 名称，也可以是 libavutil/samplefmt.h 中 enum AVSampleFormat 里对应的整数表示

channel_layout

输入音频缓冲区的声道布局。可以是 libavutil/channel_layout.c 中 channel_layout_map 里的声道布局名称，也可以是 libavutil/channel_layout.h 中 AV_CH_LAYOUT_* 宏对应的整数表示

channels

输入音频缓冲区的声道数。如果同时指定了 channels 和 channel_layout，两者必须一致。

9.1.1 示例

abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo

将指示该源接受 44100Hz 的平面 16 位有符号立体声。由于名为 "s16p" 的 sample format 对应数字 6，"stereo" 声道布局对应值 0x3，因此这等价于：

abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3

9.2 aevalsrc

生成由表达式指定的音频信号。

该源接受一个或多个输入表达式（每个声道一个），这些表达式会被求值并用于生成相应的音频信号。

该源接受以下选项：

exprs

为每个声道分别设置以 ’|’ 分隔的表达式列表。如果未指定 channel_layout 选项，所选的声道布局取决于提供的表达式数量。否则，最后一个指定的表达式会应用于剩余的输出声道。

channel_layout, c

设置声道布局。指定布局中的声道数必须等于指定表达式的数量。

duration, d

设置生成音频的最短时长。可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。注意，最终时长可能大于指定的时长，因为生成的音频总是在一个完整帧的末尾处被截断。

如果未指定该值，或指定的时长为负数，则音频将被视为无限期生成。

nb_samples, n

设置每个输出帧中每个声道的采样数，默认值为 1024。

sample_rate, s

指定采样率，默认值为 44100。

exprs 中的每个表达式可以包含以下常量：

被求值采样点的编号，从 0 开始

被求值采样点的时间，以秒为单位，从 0 开始

采样率

9.2.1 示例

生成静音：
```
aevalsrc=0
```
生成频率为 440 Hz 的正弦信号，并将采样率设置为 8000 Hz：
```
aevalsrc="sin(440*2*PI*t):s=8000"
```
生成双声道信号，显式指定声道布局（前中置 + 后中置）：
```
aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
```
生成白噪声：
```
aevalsrc="-2+random(0)"
```

生成调幅信号：

aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"

在 360 Hz 载波上生成 2.5 Hz 的双耳节拍：

aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"

9.3 afdelaysrc

生成分数延迟 FIR 系数。

生成的流可与 afir 滤镜配合使用，对音频信号滤波。

该滤镜接受以下选项：

delay, d

设置分数延迟。默认为 0。

sample_rate, r

设置采样率，默认为 44100。

nb_samples, n

设置每帧的采样数。默认为 1024。

taps, t

设置输出音频流中滤波器系数的数量。默认值为 0。

channel_layout, c

指定声道布局，可以是表示声道布局的字符串。channel_layout 的默认值是 "stereo"。

9.4 afireqsrc

生成 FIR 均衡器系数。

生成的流可与 afir 滤镜配合使用，对音频信号滤波。

该滤镜接受以下选项：

preset, p

设置均衡器预设。默认预设为 flat。

可用的预设有：

‘custom’ ‘flat’ ‘acoustic’ ‘bass’ ‘beats’ ‘classic’ ‘clear’ ‘deep bass’ ‘dubstep’ ‘electronic’ ‘hard-style’ ‘hip-hop’ ‘jazz’ ‘metal’ ‘movie’ ‘pop’ ‘r&b’ ‘rock’ ‘vocal booster’ gains, g

为每个频段设置自定义增益。仅当 preset 选项设置为 custom 时才会使用。各增益值以空白分隔，均以 dBFS 为单位设置。默认为 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0。

bands, b

设置自定义均衡器增益所对应的自定义频段。这些值必须严格递增。仅当 preset 选项设置为 custom 时才会使用。各频段值以空白分隔，每个频段表示以 Hz 为单位的频率。默认为 25 40 63 100 160 250 400 630 1000 1600 2500 4000 6300 10000 16000 24000。

taps, t

设置输出音频流中滤波器系数的数量。默认值为 4096。

sample_rate, r

设置输出音频流的采样率，默认为 44100。

nb_samples, n

设置输出音频流中每帧的采样数。默认为 1024。

interp, i

设置 FIR 均衡器系数的插值方法。可以是 linear 或 cubic。

phase, h

设置 FIR 滤波器的相位类型。可以是 linear 或 min（最小相位）。默认是最小相位滤波器。

9.5 afirsrc

使用频率采样法生成 FIR 系数。

生成的流可与 afir 滤镜配合使用，对音频信号滤波。

该滤镜接受以下选项：

taps, t

设置输出音频流中滤波器系数的数量。默认值为 1025。

frequency, f

设置用于确定幅度和相位的频率点。这些值必须非递减排列，第一个元素必须为 0，最后一个元素必须为 1。各元素以空白分隔。

magnitude, m

为 frequency 设置的每个频率点设置幅度值。数值的数量必须与频率点的数量相同。各值以空白分隔。

phase, p

为 frequency 设置的每个频率点设置相位值。数值的数量必须与频率点的数量相同。各值以空白分隔。

sample_rate, r

设置采样率，默认为 44100。

nb_samples, n

设置每帧的采样数。默认为 1024。

win_func, w

设置窗函数。默认为 blackman。

9.6 anullsrc

空音频源，返回未经处理的音频帧。它主要用作模板，以及用于分析/调试工具，或作为忽略输入数据的滤镜的源（例如 sox synth 滤镜）。

该源接受以下选项：

channel_layout, cl

指定声道布局，可以是整数，也可以是表示声道布局的字符串。channel_layout 的默认值是 "stereo"。

字符串与声道布局值之间的映射关系请查看 libavutil/channel_layout.c 中 channel_layout_map 的定义。

sample_rate, r

指定采样率，默认值为 44100。

nb_samples, n

设置每个所请求帧的采样数。

duration, d

设置生成音频的时长。可接受的语法请参见 (ffmpeg-utils)the Time duration section in the ffmpeg-utils(1) manual。

如果未指定该值，或指定的时长为负数，则音频将被视为无限期生成。

9.6.1 示例

将采样率设置为 48000 Hz，声道布局设置为 AV_CH_LAYOUT_MONO。
```
anullsrc=r=48000:cl=4
```
用更直观的语法执行相同的操作：
```
anullsrc=r=48000:cl=mono
```

所有参数都需要显式定义。

9.7 flite

使用 libflite 库合成语音。

要启用该滤镜的编译，需要使用 --enable-libflite 配置 FFmpeg。

请注意，2.0 之前版本的 flite 库不是线程安全的。

该滤镜接受以下选项：

list_voices

如果设置为 1，会列出可用语音的名称并立即退出。默认值为 0。

nb_samples, n

设置每帧的最大采样数。默认值为 512。

textfile

设置包含待朗读文本的文件名。

text

设置要朗读的文本。

voice, v

设置用于语音合成的声音。默认值为 kal。另请参见 list_voices 选项。

9.7.1 示例

从文件 speech.txt 读取文本，并使用标准 flite 声音进行合成：
```
flite=textfile=speech.txt
```

读取指定的文本并选择 slt 声音：

flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt

向 ffmpeg 输入文本：

ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt

使用 flite 和 lavfi 设备，让 ffplay 朗读指定的文本：

ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'

关于 libflite 的更多信息，请查看：http://www.festvox.org/flite/

9.8 anoisesrc

生成噪声音频信号。

该滤镜接受以下选项：

sample_rate, r

指定采样率。默认值为 48000 Hz。

amplitude, a

指定生成音频流的振幅（0.0 - 1.0）。默认值为 1.0。

duration, d

指定生成音频流的时长。不指定该选项会生成长度无限的噪声。

color, colour, c

指定噪声的颜色。可用的噪声颜色有 white、pink、brown、blue、violet 和 velvet。默认颜色为 white。

seed, s

指定用于设置 PRNG 种子的值。

nb_samples, n

设置每个输出帧的采样数，默认为 1024。

density

设置 velvet 噪声发生器的密度（0.0 - 1.0），默认为 0.05。

9.8.1 示例

生成 60 秒的 pink 噪声，采样率为 44.1 kHz，振幅为 0.5：
```
anoisesrc=d=60:c=pink:r=44100:a=0.5
```

9.9 hilbert

生成奇数抽头的希尔伯特变换 FIR 系数。

生成的流可与 afir 滤镜配合使用，将信号相移 90 度。

这在许多矩阵编码方案中使用，也用于生成解析信号。该过程通常写作乘以虚数单位 i（或 j）。

该滤镜接受以下选项：

sample_rate, s

设置采样率，默认为 44100。

taps, t

设置 FIR 滤波器的长度，默认为 22051。

nb_samples, n

设置每帧的采样数。

win_func, w

设置生成 FIR 系数时使用的窗函数。

9.10 sinc

生成 sinc 凯泽窗低通、高通、带通或带阻 FIR 系数。

生成的流可与 afir 滤镜配合使用，对音频信号滤波。

该滤镜接受以下选项：

sample_rate, r

设置采样率，默认为 44100。

nb_samples, n

设置每帧的采样数。默认为 1024。

设置高通频率。默认为 0。

设置低通频率。默认为 0。如果高通频率低于低通频率，且低通频率高于 0，则滤镜会生成带通滤波器系数，否则生成带阻滤波器系数。

phase

设置滤波器的相位响应。默认为 50。允许的范围是 0 到 100。

beta

设置凯泽窗的 beta 值。

att

设置阻带衰减。默认为 120dB，允许的范围是 40 到 180 dB。

round

启用舍入，默认禁用。

hptaps

设置高通滤波器的抽头数。

lptaps

设置低通滤波器的抽头数。

9.11 sine

生成振幅为 1/8 的正弦波音频信号。

该音频信号是逐位精确的。

该滤镜接受以下选项：

frequency, f

设置载波频率。默认为 440 Hz。

beep_factor, b

启用每秒一次的周期性提示音，其频率为载波频率的 beep_factor 倍。默认为 0，表示禁用提示音。

sample_rate, r

指定采样率，默认为 44100。

duration, d

指定生成音频流的时长。

samples_per_frame

设置每个输出帧的采样数。

该表达式可以包含以下常量：

输出音频帧的（顺序）编号，从 0 开始。

pts

输出音频帧的 PTS（Presentation TimeStamp），以 TB 为单位表示。

输出音频帧的 PTS，以秒为单位表示。

输出音频帧的时间基。

默认为 1024。

9.11.1 示例

生成简单的 440 Hz 正弦波：
```
sine
```

生成 220 Hz 正弦波，每秒带一次 880 Hz 提示音，持续 5 秒：

sine=220:4:d=5
sine=f=220:b=4:d=5
sine=frequency=220:beep_factor=4:duration=5

按照 1602,1601,1602,1601,1602 的 NTSC 模式生成 1 kHz 正弦波：

sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'

10 音频汇

下面是当前可用音频汇的说明。

10.1 abuffersink

缓冲音频帧，并使其在滤镜链末端可用。

该汇主要用于程序化使用，特别是通过 libavfilter/buffersink.h 中定义的接口或选项系统。

它接受一个指向 AVABufferSinkContext 结构体的指针，该结构体定义了输入缓冲区的格式，需作为 opaque 参数传给 avfilter_init_filter 以进行初始化。

10.2 anullsink

空音频汇；对输入音频不做任何处理。它主要用作模板，以及用于分析/调试工具。

11 视频滤镜

在配置 FFmpeg 构建时，可以用 --disable-filters 禁用任意现有滤镜。configure 的输出会显示你的构建中包含哪些视频滤镜。

下面是当前可用视频滤镜的说明。

11.1 addroi

在视频帧中标记感兴趣区域。

帧数据会原样透传，但会在帧上附加元数据，标明可能影响后续编码行为的感兴趣区域。多次应用该滤镜即可标记多个区域。

区域距帧左边缘的距离，以像素为单位。

区域距帧上边缘的距离，以像素为单位。

区域宽度，以像素为单位。

区域高度，以像素为单位。

参数 x、y、w 和 h 均为表达式，可以包含以下变量：

输入帧的宽度。

输入帧的高度。

qoffset

在该区域内应用的量化偏移。

该值必须是 -1 到 +1 范围内的实数。值为零表示不改变质量。负值要求更高的质量（更少的量化），而正值要求更低的质量（更多的量化）。

该范围经过校准，使极值表示可能的最大偏移——如果帧的其余部分以尽可能最差的质量编码，偏移为 -1 则表示该区域无论如何都应以尽可能最好的质量编码。中间值则以某种取决于 codec 的方式进行插值。

例如，在 10 位 H.264 中，量化参数的取值范围为 -12 到 51。一个典型的 qoffset 值 -1/10 表示该区域应以比帧其余部分好大约十分之一全范围的 QP 进行编码。也就是说，如果帧的大部分以约 30 的 QP 编码，该区域将获得约 24 的 QP（偏移量约为 -1/10 * (51 - -12) = -6.3）。极值 -1 则表示无论帧其余部分如何处理，该区域都应以尽可能最好的质量编码，也就是应以 QP -12 编码。

clear

如果设置为 true，会在添加新区域之前，移除帧上已标记的所有现有感兴趣区域。

11.1.1 示例

将帧的中心四分之一区域标记为感兴趣区域。
```
addroi=iw/4:ih/4:iw/2:ih/2:-1/10
```
将帧左边缘 100 像素宽的区域标记为非常不感兴趣（以远低于帧其余部分的质量进行编码）。
```
addroi=0:0:100:ih:+1/5
```

11.2 alphaextract

从输入中提取 alpha 分量，作为灰度视频输出。这在与 alphamerge 滤镜配合使用时特别有用。

11.3 alphamerge

使用第二路输入的灰度值添加或替换主输入的 alpha 分量。这是为了配合 alphaextract 使用，以便在不支持 alpha 通道的格式中传输或存储带有 alpha 的帧序列。

例如，要从普通的 YUV 编码视频和一个由 alphaextract 生成的独立视频中重建完整帧，可以这样使用：

movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]

11.4 amplify

放大当前像素与相邻帧中相同像素位置的像素之间的差异。

此滤镜接受以下选项：

radius

设置帧半径。默认为 2。允许的范围是 1 到 63。例如半径为 3 会让滤镜计算 7 帧的平均值。

factor

设置放大差异的系数。默认为 2。允许的范围是 0 到 65535。

threshold

设置差异放大的阈值。任何大于或等于该值的差异都不会改变源像素。默认为 10。允许的范围是 0 到 65535。

tolerance

设置差异放大的容差。任何小于该值的差异都不会改变源像素。默认为 0。允许的范围是 0 到 65535。

low

设置改变源像素的下限。默认为 65535。允许的范围是 0 到 65535。该选项控制可使源像素值减小的最大可能值。

high

设置改变源像素的上限。默认为 65535。允许的范围是 0 到 65535。该选项控制可使源像素值增大的最大可能值。

planes

设置要滤波的平面。默认为 all。允许的范围是 0 到 15。

11.4.1 命令

该滤镜支持以下与同名选项对应的命令：

factor threshold tolerance low high planes

11.5 ass

与 subtitles 滤镜相同，区别在于它不需要 libavcodec 和 libavformat 即可工作。但另一方面，它仅限于 ASS（Advanced Substation Alpha）字幕文件。

该滤镜接受来自 subtitles 滤镜的 filename/f、original_size、fontsdir 和 alpha，此外还有以下选项：

shaping

设置整形引擎。

可用值如下：

‘auto’

默认的 libass 整形引擎，是当前可用中最好的。

‘simple’

快速且与字体无关的整形器，只能进行替换。

‘complex’

使用 OpenType 进行替换和定位的较慢整形器。要正确渲染阿拉伯文、希伯来文、天城文和泰文等复杂文字，需要用到它。需要 libass 使用 HarfBuzz 构建。

默认为 auto。

11.6 atadenoise

对视频输入应用自适应时间平均降噪（Adaptive Temporal Averaging Denoiser）。

该滤镜接受以下选项：

设置第 1 个平面的阈值 A。默认值为 0.02，有效范围为 0 到 0.3。

设置第 1 个平面的阈值 B。默认值为 0.04，有效范围为 0 到 5。

设置第 2 个平面的阈值 A。默认值为 0.02，有效范围为 0 到 0.3。

设置第 2 个平面的阈值 B。默认值为 0.04，有效范围为 0 到 5。

设置第 3 个平面的阈值 A。默认值为 0.02，有效范围为 0 到 0.3。

设置第 3 个平面的阈值 B。默认值为 0.04，有效范围为 0 到 5。

阈值 A 用于对输入信号的剧烈变化做出反应，阈值 B 用于对输入信号的持续变化做出反应。

设置滤镜用于平均的帧数。默认值为 9，必须是 [5, 129] 范围内的奇数。

设置滤镜平均时使用的帧平面。默认值为 all。

设置滤镜用于平均的算法变体。默认值为表示并行的 p，也可以设置为表示串行的 s。

并行方式可能比串行更快，反之则从不成立。并行方式会在首次出现超过阈值的变化时提前终止，而串行方式则会继续处理另一侧的帧，只要这些帧等于或低于阈值。

0s 1s 2s

设置第 1、第 2、第 3 个平面的 sigma。默认值为 32767，有效范围为 0 到 32767。此选项控制 size 定义的半径内每个像素的权重，默认值意味着每个像素的权重相同。将此选项设为 0 会实际上禁用滤镜处理。

11.6.1 命令

除选项 s 外，该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

11.7 avgblur

应用平均模糊滤镜。

该滤镜接受以下选项：

sizeX

设置水平半径大小。

planes

设置要过滤的平面。默认情况下会过滤所有平面。

sizeY

设置垂直半径大小，若为零则与 sizeX 相同。默认值为 0。

11.7.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.8 backgroundkey

将静态背景转为透明。

该滤镜接受以下选项：

threshold

场景切换检测的阈值。

similarity

与背景的相似度百分比。

blend

设置不相似像素的混合量。

11.8.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.9 bbox

计算输入帧亮度平面中非黑色像素的边界框。

该滤镜计算包含所有亮度值大于允许最小值的像素的边界框，描述该边界框的参数会输出到滤镜日志中。

该滤镜接受以下选项：

min_val

设置最小亮度值。默认值为 16。

11.9.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.10 bilateral

应用双边滤镜，在保留边缘的同时进行空间平滑处理。

该滤镜接受以下选项：

sigmaS

设置用于计算空间权重的高斯函数 sigma。允许的范围为 0 到 512。默认值为 0.1。

sigmaR

设置用于计算值域权重的高斯函数 sigma。允许的范围为 0 到 1。默认值为 0.1。

planes

设置要过滤的平面。默认仅第一个。

11.10.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.11 bitplanenoise

显示并测量位平面噪声。

该滤镜接受以下选项：

bitplane

设置要分析的平面。默认值为 1。

filter

从上面设置的 bitplane 中过滤掉噪声像素。默认禁用。

11.12 blackdetect, blackdetect_vulkan

检测（几乎）完全黑屏的视频区间，可用于检测章节切换、广告或无效录制内容。

该滤镜会将检测分析结果同时输出到日志和帧元数据中。如果找到时长不小于指定最小值的黑屏片段，会以 info 级别向日志输出一行包含起止时间戳及时长的信息；此外，还会为每一帧以 debug 级别输出一行日志，显示该帧检测到的黑屏程度。

该滤镜还会为黑屏片段的第一帧附加键为 lavfi.black_start 的元数据，并为黑屏片段结束后的第一帧附加键为 lavfi.black_end 的元数据，值为该帧的时间戳。无论指定的最小时长为何，都会添加此元数据。

该滤镜接受以下选项：

black_min_duration, d

设置检测到的黑屏最小持续时间（以秒为单位）。必须是非负浮点数。

默认值为 2.0。

picture_black_ratio_th, pic_th

设置将画面判定为“黑”的阈值，表示以下比率的最小值：

nb_black_pixels / nb_pixels

当比率达到该值时即判定画面为黑。默认值为 0.98。

pixel_black_th, pix_th

设置将像素判定为“黑”的阈值。

该阈值表示像素被判定为“黑”所对应的最大亮度值，所提供的值会依据以下公式进行缩放：

absolute_threshold = luma_minimum_value + pixel_black_th * luma_range_size

luma_range_size 和 luma_minimum_value 取决于输入视频格式：YUV 全范围格式下范围为 [0-255]，YUV 非全范围格式下范围为 [16-235]。

默认值为 0.10。

alpha

若为 true，则检查 alpha 通道而非亮度通道，检测的是（几乎）透明的帧，而不是几乎全黑的帧。

默认值为禁用。

以下示例将像素最大阈值设为最小值，并仅检测时长 2 秒及以上的黑屏区间：

blackdetect=d=2:pix_th=0.00

11.13 blackframe

检测（几乎）完全黑屏的帧，可用于检测章节切换或广告。输出行包含检测到的帧号、黑屏百分比、文件中的位置（未知时为 -1）以及以秒为单位的时间戳。

要显示输出行，需要将 loglevel 至少设置为 AV_LOG_INFO。

该滤镜会导出帧元数据 lavfi.blackframe.pblack，其值表示画面中低于阈值的像素所占的百分比。

它接受以下参数：

amount

需要低于阈值的像素所占的百分比，默认值为 98。

threshold, thresh

像素值低于该阈值即被视为黑色，默认值为 32。

11.14 blend

将两个视频帧相互混合。

blend 滤镜接收两路输入流并输出一路流，第一路输入为“顶”层，第二路输入为“底”层。默认情况下，当时长最长的输入结束时，输出也随之结束。

tblend（时间混合，time blend）滤镜从单个流中取两个连续帧，输出将新帧混合叠加到旧帧之上所得的结果。

接受的选项说明如下。

c0_mode c1_mode c2_mode c3_mode all_mode

为特定像素分量（all_mode 情况下为所有像素分量）设置混合模式。默认值为 normal。

分量模式可用的取值如下：

‘addition’ ‘and’ ‘average’ ‘bleach’ ‘burn’ ‘darken’ ‘difference’ ‘divide’ ‘dodge’ ‘exclusion’ ‘extremity’ ‘freeze’ ‘geometric’ ‘glow’ ‘grainextract’ ‘grainmerge’ ‘hardlight’ ‘hardmix’ ‘hardoverlay’ ‘harmonic’ ‘heat’ ‘interpolate’ ‘lighten’ ‘linearlight’ ‘multiply’ ‘multiply128’ ‘negation’ ‘normal’ ‘or’ ‘overlay’ ‘phoenix’ ‘pinlight’ ‘reflect’ ‘screen’ ‘softdifference’ ‘softlight’ ‘stain’ ‘subtract’ ‘vividlight’ ‘xor’ c0_opacity c1_opacity c2_opacity c3_opacity all_opacity

为特定像素分量（all_opacity 情况下为所有像素分量）设置混合不透明度，仅在与像素分量混合模式配合使用时有效。

c0_expr c1_expr c2_expr c3_expr all_expr

为特定像素分量（all_expr 情况下为所有像素分量）设置混合表达式。注意，若设置了此项，相关的模式选项将被忽略。

表达式可以使用以下变量：

被过滤帧的序号，从 0 开始。

X Y

当前采样点的坐标

W H

当前被过滤平面的宽度和高度

SW SH

被过滤平面的宽度和高度缩放比例，即当前平面尺寸与亮度平面尺寸之比。例如对于 yuv420p 帧，亮度平面的值为 1,1，色度平面的值为 0.5,0.5。

当前帧的时间，以秒为单位。

TOP, A

第一个视频帧（顶层）在当前位置的像素分量值。

BOTTOM, B

第二个视频帧（底层）在当前位置的像素分量值。

blend 滤镜还支持 framesync 选项。

11.14.1 示例

在前 10 秒内实现从底层到顶层的过渡：

blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'

实现从顶层到底层的线性水平过渡：
```
blend=all_expr='A*(X/W)+B*(1-X/W)'
```

应用 1x1 棋盘格效果：

blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'

应用从左侧显现（uncover left）效果：
```
blend=all_expr='if(gte(N*SW+X,W),A,B)'
```
应用从下方显现（uncover down）效果：
```
blend=all_expr='if(gte(Y-N*SH,0),A,B)'
```

应用从左上方显现（uncover up-left）效果：

blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'

沿对角线分割视频，两侧分别显示顶层和底层：
```
blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
```
显示当前帧与前一帧之间的差异：
```
tblend=all_mode=grainextract
```

11.14.2 命令

此滤镜支持与选项相同的命令。

11.15 blockdetect

在不改变输入帧的情况下判定帧的块效应（blockiness）。

基于 Remco Muijs 和 Ihor Kirenko 的 "A no-reference blocking artifact measure for adaptive video processing." 2005 13th European signal processing conference。

该滤镜接受以下选项：

period_min period_max

设置用于确定像素网格（周期）的最小值和最大值。默认值为 [3,24]。

planes

设置要过滤的平面。默认仅第一个。

11.15.1 示例

确定第一个平面的块效应程度，并在 [8,32] 范围内搜索周期：
```
blockdetect=period_min=8:period_max=32:planes=1
```

11.16 blurdetect

在不改变输入帧的情况下判定帧的模糊程度（blurriness）。

基于 Marziliano, Pina 等人的 "A no-reference perceptual blur metric."，支持基于块的简化处理。

该滤镜接受以下选项：

low high

设置 Canny 阈值算法所用的低阈值和高阈值。

高阈值用于选取“强”边缘像素，随后通过 8 连通将其与低阈值选取的“弱”边缘像素相连。

低阈值和高阈值必须选自 [0,1] 范围，且 low 应小于或等于 high。

low 的默认值为 20/255，high 的默认值为 50/255。

radius

定义在边缘像素周围搜索局部极大值的半径。

block_pct

仅针对最显著的块（以百分比给出）确定模糊程度。

block_width

确定宽度为 block_width 的块的模糊程度。如果设置为小于 1 的值，则不使用分块，无论 block_height 为何，都会将整幅图像作为一个整体处理。

block_height

确定高度为 block_height 的块的模糊程度。如果设置为小于 1 的值，则不使用分块，无论 block_width 为何，都会将整幅图像作为一个整体处理。

planes

设置要过滤的平面。默认仅第一个。

11.16.1 示例

确定最显著的 32x32 块中 80% 的模糊程度：

blurdetect=block_width=32:block_height=32:block_pct=80

11.17 bm3d

使用块匹配三维（Block-Matching 3D）算法对帧进行降噪。

该滤镜接受以下选项。

sigma

设置降噪强度。默认值为 1，允许的范围为 0 到 999.9。降噪算法对 sigma 非常敏感，请根据片源进行调整。

block

设置局部块（patch）大小，用于设置二维尺寸。

bstep

设置处理块时的滑动步长。默认值为 4，允许的范围为 1 到 64。值越小可处理的参考块越多，速度也越慢。

group

设置第三维上相似块的最大数量。默认值为 1，设为 1 时不进行块匹配。值越大，单个分组中可包含的块越多。允许的范围为 1 到 256。

range

设置块匹配搜索的半径。默认值为 9，允许的范围为 1 到 INT32_MAX。

mstep

设置块匹配两个搜索位置之间的步长。默认值为 1，允许的范围为 1 到 64。值越小速度越慢。

thmse

设置块匹配均方误差的阈值。有效范围为 0 到 INT32_MAX。

hdthr

设置三维变换域中硬阈值处理的阈值参数。值越大，频域中的硬阈值滤波效果越强。

estim

设置滤波估计模式，可以是 basic 或 final。默认值为 basic。

ref

若启用，滤镜将使用第 2 路流进行块匹配。当 estim 选项的值为 basic 时默认禁用，当 estim 的值为 final 时始终启用。

planes

设置要过滤的平面。默认是除 alpha 外的所有可用平面。

11.17.1 示例

使用 bm3d 进行基础滤波：

bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic

与上面相同，但仅过滤亮度：

bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1

与上面相同，但使用两种估计模式：

split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1

与上面相同，但改用 nlmeans 滤镜进行预滤波：

split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1

11.18 boxblur

对输入视频应用方框模糊（boxblur）算法。

它接受以下参数：

luma_radius, lr luma_power, lp chroma_radius, cr chroma_power, cp alpha_radius, ar alpha_power, ap

接受的选项说明如下。

luma_radius, lr chroma_radius, cr alpha_radius, ar

为用于模糊对应输入平面的方框半径（以像素为单位）设置表达式。

半径值必须是非负数，且对亮度平面和 alpha 平面不得大于表达式 min(w,h)/2 的值，对色度平面不得大于 min(cw,ch)/2 的值。

luma_radius 的默认值为 "2"。若未指定，chroma_radius 和 alpha_radius 默认取 luma_radius 所设置的对应值。

表达式可以包含以下常量：

w h

输入的宽度和高度（以像素为单位）。

cw ch

输入色度图像的宽度和高度（以像素为单位）。

hsub vsub

水平和垂直方向的色度二次采样值。例如，对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

luma_power, lp chroma_power, cp alpha_power, ap

指定 boxblur 滤镜对相应平面的应用次数。

luma_power 的默认值为 2。若未指定，chroma_power 和 alpha_power 默认取 luma_power 所设置的对应值。

值为 0 将禁用该效果。

11.18.1 示例

应用 boxblur 滤镜，将亮度、色度和 alpha 半径均设为 2：
```
boxblur=luma_radius=2:luma_power=1
boxblur=2:1
```
将亮度半径设为 2，alpha 和色度半径设为 0：
```
boxblur=2:1:cr=0:ar=0
```

将亮度和色度半径设为视频尺寸的一个分数：

boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1

11.19 bwdif

对输入视频进行去隔行处理（“bwdif” 即 “Bob Weaver Deinterlacing Filter” 的缩写）。

基于 yadif 并结合 w3fdif 与三次插值算法的运动自适应去隔行。它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

0, send_frame

每个帧输出一帧。

1, send_field

每个场输出一帧。

默认值为 send_field。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

0, tff

假定顶场在前。

1, bff

假定底场在前。

-1, auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

0, all

对所有帧去隔行。

1, interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

11.20 ccrepack

重新打包 CEA-708 隐藏字幕（closed captioning）附加数据

该滤镜修复了商业 encoder 中因上游 CEA-708 负载格式错误而出现的各种问题，具体包括元组数量不正确（目标 FPS 对应的 cc_count 有误）以及元组顺序不正确（即 CEA-608 元组未位于负载的最前面几项）。

11.21 cas

对视频流应用对比度自适应锐化（Contrast Adaptive Sharpen）滤镜。

该滤镜接受以下选项：

strength

设置锐化强度。默认值为 0。

planes

设置要过滤的平面。默认值为过滤除 alpha 平面外的所有平面。

11.21.1 命令

此滤镜支持与选项相同的命令。

11.22 chromahold

移除除某一种颜色外所有颜色的色彩信息。

该滤镜接受以下选项：

color

不会被替换为中性色度的颜色。

similarity

与上述颜色的相似度百分比。0.01 仅匹配完全相同的键控颜色，1.0 则匹配所有颜色。

blend

混合百分比。0.0 会使像素要么完全变灰，要么完全不变灰；数值越大，保留的色彩越多。

yuv

表示传入的颜色已经是 YUV 而非 RGB。

启用此项后，像 "green" 或 "red" 这样的字面颜色名将不再有意义。可以借此以十六进制数字传入精确的 YUV 值。

11.22.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.23 chromakey

YUV 色彩空间的色彩/色度键控。

该滤镜接受以下选项：

color

将被替换为透明的颜色。

similarity

与键控颜色的相似度百分比。

0.01 仅匹配完全相同的键控颜色，1.0 则匹配所有颜色。

blend

混合百分比。

0.0 会使像素要么完全透明，要么完全不透明。

数值越大，像素越呈现半透明；像素颜色与键控颜色越相似，透明度就越高。

yuv

表示传入的颜色已经是 YUV 而非 RGB。

启用此项后，像 "green" 或 "red" 这样的字面颜色名将不再有意义。可以借此以十六进制数字传入精确的 YUV 值。

11.23.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.23.2 示例

使输入图像中的每个绿色像素变为透明：
```
ffmpeg -i input.png -vf chromakey=green out.png
```

将绿幕视频叠加到静态黑色背景之上。

ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv

11.24 chromanr

降低色度噪声。

该滤镜接受以下选项：

thres

设置色度值求平均的阈值。当前像素与相邻像素的 Y、U、V 像素分量绝对差之和低于该阈值时才会参与平均。亮度分量保持不变并直接复制到输出。默认值为 30，允许的范围为 1 到 200。

sizew

设置用于求平均的矩形的水平半径。允许的范围为 1 到 100，默认值为 5。

sizeh

设置用于求平均的矩形的垂直半径。允许的范围为 1 到 100，默认值为 5。

stepw

设置求平均时的水平步长。默认值为 1，允许的范围为 1 到 50。主要用于加快滤波速度。

steph

设置求平均时的垂直步长。默认值为 1，允许的范围为 1 到 50。主要用于加快滤波速度。

threy

设置色度值求平均所用的 Y 阈值，用于更精细地控制当前像素与相邻像素 Y 分量之间允许的最大差值。默认值为 200，允许的范围为 1 到 200。

threu

设置色度值求平均所用的 U 阈值，用于更精细地控制当前像素与相邻像素 U 分量之间允许的最大差值。默认值为 200，允许的范围为 1 到 200。

threv

设置色度值求平均所用的 V 阈值，用于更精细地控制当前像素与相邻像素 V 分量之间允许的最大差值。默认值为 200，允许的范围为 1 到 200。

distance

设置计算中使用的距离类型。

‘manhattan’

绝对差。

‘euclidean’

差值的平方。

默认距离类型为 manhattan。

11.24.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

11.25 chromashift

水平和/或垂直偏移色度像素。

该滤镜接受以下选项：

cbh

设置色度蓝水平偏移的量。

cbv

设置色度蓝垂直偏移的量。

crh

设置色度红水平偏移的量。

crv

设置色度红垂直偏移的量。

edge

设置边缘模式，可以是 smear、default 或 warp。

11.25.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.26 ciescope

显示 CIE 色度图，并在图上叠加像素。

该滤镜接受以下选项：

system

设置色彩系统。

‘ntsc, 470m’ ‘ebu, 470bg’ ‘smpte’ ‘240m’ ‘apple’ ‘widergb’ ‘cie1931’ ‘rec709, hdtv’ ‘uhdtv, rec2020’ ‘dcip3’ cie

设置 CIE 系统。

‘xyy’ ‘ucs’ ‘luv’ gamuts

设置要绘制的色域。

可用值请参见 system 选项。

size, s

设置 ciescope 的大小，默认为 512。

intensity, i

设置将输入像素值映射到 CIE 图时使用的强度。

contrast

设置绘制超出当前色彩系统色域范围的舌形区域颜色时所用的对比度。

corrgamma

校正该图上显示的伽马值，默认启用。

showwhite

在 CIE 图上显示白点，默认禁用。

gamma

设置输入伽马值。仅在 XYZ 输入色彩空间下使用。

fill

用 CIE 颜色填充。默认启用。

11.27 codecview

可视化部分 codec 导出的信息。

部分 codec 可以借助侧数据等方式通过帧导出信息。例如，一些基于 MPEG 的 codec 会通过 codec 的 flags2 选项中的 export_mvs 标志导出运动矢量。

该滤镜接受以下选项：

block

使用亮度平面显示块划分结构。

设置要可视化的运动矢量。

mv 可用的标志如下：

‘pf’

P 帧的前向预测运动矢量

‘bf’

B 帧的前向预测运动矢量

‘bb’

B 帧的后向预测运动矢量

使用色度平面显示量化参数。

mv_type, mvt

设置要可视化的运动矢量类型。除非通过 frame_type 选项另行指定，否则包含所有帧的运动矢量。

mv_type 可用的标志如下：

‘fp’

前向预测运动矢量

‘bp’

后向预测运动矢量

frame_type, ft

设置要可视化其运动矢量的帧类型。

frame_type 可用的标志如下：

‘if’

帧内编码帧（I 帧）

‘pf’

预测帧（P 帧）

‘bf’

双向预测帧（B 帧）

11.27.1 示例

使用 ffplay 可视化所有帧的前向预测运动矢量：

ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp

使用 ffplay 可视化 P 帧和 B 帧的多方向运动矢量：

ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb

11.28 colorbalance

修改输入帧中三原色（红、绿、蓝）的强度。

该滤镜允许在阴影、中间调或高光区域调整输入帧的红青、绿品红或蓝黄平衡。

调整值为正时，平衡偏向原色；为负时，偏向补色。

该滤镜接受以下选项：

rs gs bs

调整红、绿、蓝的阴影（最暗的像素）。

rm gm bm

调整红、绿、蓝的中间调（中等亮度的像素）。

rh gh bh

调整红、绿、蓝的高光（最亮的像素）。

选项允许的范围是 [-1.0, 1.0]。默认值为 0。

更改色彩平衡时保持明度。默认禁用。

11.28.1 示例

为阴影添加红色偏色：
```
colorbalance=rs=.3
```

11.28.2 命令

该滤镜支持将以上所有选项作为命令使用。

11.29 colorcontrast

调整 RGB 分量之间的色彩对比度。

该滤镜接受以下选项：

设置红青对比度。默认值为 0.0。允许的范围是 -1.0 到 1.0。

设置绿品红对比度。默认值为 0.0。允许的范围是 -1.0 到 1.0。

设置蓝黄对比度。默认值为 0.0。允许的范围是 -1.0 到 1.0。

rcw gmw byw

设置 rc、gm、by 各选项值的权重。默认值为 0.0。允许的范围是 0.0 到 1.0。如果所有权重均为 0.0，则禁用滤镜处理。

设置保持明度的程度。默认值为 0.0。允许的范围是 0.0 到 1.0。

11.29.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.30 colorcorrect

有选择地调整黑色和白色的色彩白平衡。该滤镜在 YUV 色彩空间中处理。

该滤镜接受以下选项：

设置红色阴影点。允许的范围是 -1.0 到 1.0。默认值为 0。

设置蓝色阴影点。允许的范围是 -1.0 到 1.0。默认值为 0。

设置红色高光点。允许的范围是 -1.0 到 1.0。默认值为 0。

设置蓝色高光点。允许的范围是 -1.0 到 1.0。默认值为 0。

saturation

设置饱和度的量。允许的范围是 -3.0 到 3.0。默认值为 1。

analyze

如果设置为 manual 以外的值，将分析每一帧，并使用推导出的参数处理输出帧。

可接受的值有：

‘manual’ ‘average’ ‘minmax’ ‘median’

默认值为 manual。

11.30.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.31 colorchannelmixer

通过重新混合颜色通道来调整视频输入帧。

该滤镜通过将同一像素中其他通道相关联的值相加来修改某个颜色通道。例如，如果要修改的值是红色，则输出值为：

red=red*rr + blue*rb + green*rg + alpha*ra

该滤镜接受以下选项：

rr rg rb ra

调整输入的红、绿、蓝、alpha 通道对输出红通道的贡献。默认值 rr 为 1，rg、rb、ra 为 0。

gr gg gb ga

调整输入的红、绿、蓝、alpha 通道对输出绿通道的贡献。默认值 gg 为 1，gr、gb、ga 为 0。

br bg bb ba

调整输入的红、绿、蓝、alpha 通道对输出蓝通道的贡献。默认值 bb 为 1，br、bg、ba 为 0。

ar ag ab aa

调整输入的红、绿、蓝、alpha 通道对输出 alpha 通道的贡献。默认值 aa 为 1，ar、ag、ab 为 0。

选项允许的范围是 [-2.0, 2.0]。

设置色彩保持模式。可接受的值如下：

‘none’

禁用色彩保持，这是默认值。

‘lum’

保持亮度。

‘max’

保持 RGB 三元组的最大值。

‘avg’

保持 RGB 三元组的平均值。

‘sum’

保持 RGB 三元组的总和值。

‘nrm’

保持 RGB 三元组的归一化值。

‘pwr’

保持 RGB 三元组的幂值。

设置更改颜色时的色彩保持量。允许的范围是 [0.0, 1.0]。默认值为 0.0，即禁用。

11.31.1 示例

将源转换为灰度：

colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3

模拟棕褐色调：

colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131

11.31.2 命令

该滤镜支持将以上所有选项作为命令使用。

11.32 colordetect

分析视频帧以确定有效值范围和 alpha 模式。

该滤镜接受以下选项：

mode

要检测的属性集合。不可用的属性（例如没有 alpha 通道的输入图像的 alpha 模式）会被自动忽略。

接受以下标志的组合：

‘color_range’

检测源是否包含超出 limited（MPEG）范围的亮度像素，这表示该源是 full range 的 YUV 源。

‘alpha_mode’

检测源是否包含高于 alpha 通道值的色彩值，这表示 alpha 通道是独立的（straight，直通），而非预乘的。同时检测 alpha 平面是否完全不透明。

‘all’

启用上述所有属性的检测。这是默认值。

11.33 colorize

在视频流上叠加一种纯色。

该滤镜接受以下选项：

hue

设置颜色的色相。允许的范围是 0 到 360。默认值为 0。

saturation

设置颜色的饱和度。允许的范围是 0 到 1。默认值为 0.5。

lightness

设置颜色的明度。允许的范围是 0 到 1。默认值为 0.5。

mix

设置源明度的混合比例。默认设置为 1.0。允许的范围是 0.0 到 1.0。

11.33.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.34 colorkey

RGB 色彩空间的色键处理。该滤镜作用于 8 位 RGB 格式的帧，将落在关键色相似度半径内的每个像素的 alpha 分量设置为 0。半径外像素的 alpha 值取决于 blend 选项的值。

该滤镜接受以下选项：

color

设置将 alpha 设为 0（完全透明）的颜色。参见 ffmpeg-utils 手册中的 “Color” 一节。默认值为 black。

similarity

设置以关键色为中心的半径，在该半径内其他颜色也具有完全透明度。计算得到的距离与关键色和像素颜色的 RGB 值在 3D 空间中的单位分数距离有关。范围是 0.01 到 1.0。0.01 表示仅匹配精确关键色周围极小的半径，而 1.0 表示匹配所有颜色。默认值为 0.01。

blend

设置落在相似度半径之外的像素的 alpha 值的计算方式。0.0 会使像素完全透明或完全不透明。值越大，像素越呈半透明状态，且像素颜色与关键色越相近，透明度越高。范围是 0.0 到 1.0。默认值为 0.0。

11.34.1 示例

使输入图像中的每个绿色像素变为透明：
```
ffmpeg -i input.png -vf colorkey=green out.png
```

将绿幕视频叠加到静态背景图像之上。

ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv

11.34.2 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.35 colorhold

移除除某一特定颜色外所有 RGB 颜色的颜色信息。

该滤镜接受以下选项：

color

不会被替换为中性灰色的颜色。

similarity

与上述颜色的相似度百分比。0.01 仅匹配精确的关键色，而 1.0 匹配所有颜色。

blend

混合百分比。0.0 会使像素完全变灰。值越大，保留的颜色越多。

11.35.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.36 colorlevels

使用色阶调整视频输入帧。

该滤镜接受以下选项：

rimin gimin bimin aimin

调整红、绿、蓝、alpha 的输入黑点。选项允许的范围是 [-1.0, 1.0]。默认值为 0。

rimax gimax bimax aimax

调整红、绿、蓝、alpha 的输入白点。选项允许的范围是 [-1.0, 1.0]。默认值为 1。

输入色阶用于提亮高光（明亮色调）、加暗阴影（暗色调），以及改变明暗色调的平衡。

romin gomin bomin aomin

调整红、绿、蓝、alpha 的输出黑点。选项允许的范围是 [0, 1.0]。默认值为 0。

romax gomax bomax aomax

调整红、绿、蓝、alpha 的输出白点。选项允许的范围是 [0, 1.0]。默认值为 1。

输出色阶允许手动选择受限的输出色阶范围。

preserve

设置色彩保持模式。可接受的值如下：

‘none’

禁用色彩保持，这是默认值。

‘lum’

保持亮度。

‘max’

保持 RGB 三元组的最大值。

‘avg’

保持 RGB 三元组的平均值。

‘sum’

保持 RGB 三元组的总和值。

‘nrm’

保持 RGB 三元组的归一化值。

‘pwr’

保持 RGB 三元组的幂值。

11.36.1 示例

使视频输出变暗：

colorlevels=rimin=0.058:gimin=0.058:bimin=0.058

增加对比度：

colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96

使视频输出变亮：

colorlevels=rimax=0.902:gimax=0.902:bimax=0.902

增加亮度：

colorlevels=romin=0.5:gomin=0.5:bomin=0.5

11.36.2 命令

该滤镜支持将以上所有选项作为命令使用。

11.37 colormap

将自定义颜色映射应用于视频流。

该滤镜需要三个输入视频流。第一个流是将要被滤镜处理的视频流。第二个和第三个视频流指定用于源颜色到目标颜色映射的颜色色块。

该滤镜接受以下选项：

patch_size

以像素为单位设置源和目标视频流的色块大小。

nb_patches

设置从源和目标视频流中使用的色块的最大数量。默认值为附加视频流中可用的色块数量。允许的最大色块数量是 64。

type

设置用于目标颜色的调整方式。可以是 relative 或 absolute。默认值为 absolute。

kernel

设置用于测量映射颜色之间色差的核函数。

可接受的值如下：

‘euclidean’ ‘weuclidean’

默认值为 euclidean。

11.38 colormatrix

转换色彩矩阵。

该滤镜接受以下选项：

src dst

指定源和目标色彩矩阵。两个值都必须指定。

可接受的值如下：

‘bt709’

BT.709

‘fcc’

FCC

‘bt601’

BT.601

‘bt470’

BT.470

‘bt470bg’

BT.470BG

‘smpte170m’

SMPTE-170M

‘smpte240m’

SMPTE-240M

‘bt2020’

BT.2020

例如，要从 BT.601 转换为 SMPTE-240M，可使用以下命令：

colormatrix=bt601:smpte240m

11.39 colorspace

转换色彩空间、传递特性或原色。输入视频的尺寸必须为偶数。

该滤镜接受以下选项：

all

一次性指定所有颜色属性。

可接受的值如下：

‘bt470m’

BT.470M

‘bt470bg’

BT.470BG

‘bt601-6-525’

BT.601-6 525

‘bt601-6-625’

BT.601-6 625

‘bt709’

BT.709

‘smpte170m’

SMPTE-170M

‘smpte240m’

SMPTE-240M

‘bt2020’

BT.2020

space

指定输出色彩空间。

可接受的值如下：

‘bt709’

BT.709

‘fcc’

FCC

‘bt470bg’

BT.470BG 或 BT.601-6 625

‘smpte170m’

SMPTE-170M 或 BT.601-6 525

‘smpte240m’

SMPTE-240M

‘ycgco’

YCgCo

‘bt2020ncl’

非恒定亮度的 BT.2020

trc

指定输出传递特性。

可接受的值如下：

‘bt709’

BT.709

‘bt470m’

BT.470M

‘bt470bg’

BT.470BG

‘gamma22’

恒定伽马 2.2

‘gamma28’

恒定伽马 2.8

‘smpte170m’

SMPTE-170M、BT.601-6 625 或 BT.601-6 525

‘smpte240m’

SMPTE-240M

‘srgb’

SRGB

‘iec61966-2-1’

iec61966-2-1

‘iec61966-2-4’

iec61966-2-4

‘xvycc’

xvycc

‘bt2020-10’

面向 10 位内容的 BT.2020

‘bt2020-12’

面向 12 位内容的 BT.2020

primaries

指定输出原色。

可接受的值如下：

‘bt709’

BT.709

‘bt470m’

BT.470M

‘bt470bg’

BT.470BG 或 BT.601-6 625

‘smpte170m’

SMPTE-170M 或 BT.601-6 525

‘smpte240m’

SMPTE-240M

‘film’

film

‘smpte431’

SMPTE-431

‘smpte432’

SMPTE-432

‘bt2020’

BT.2020

‘jedec-p22’

JEDEC P22 荧光体

range

指定输出色彩范围。

可接受的值如下：

‘tv’

TV（受限）范围

‘mpeg’

MPEG（受限）范围

‘pc’

PC（完整）范围

‘jpeg’

JPEG（完整）范围

format

指定输出色彩格式。

可接受的值如下：

‘yuv420p’

YUV 4:2:0 平面格式 8 位

‘yuv420p10’

YUV 4:2:0 平面格式 10 位

‘yuv420p12’

YUV 4:2:0 平面格式 12 位

‘yuv422p’

YUV 4:2:2 平面格式 8 位

‘yuv422p10’

YUV 4:2:2 平面格式 10 位

‘yuv422p12’

YUV 4:2:2 平面格式 12 位

‘yuv444p’

YUV 4:4:4 平面格式 8 位

‘yuv444p10’

YUV 4:4:4 平面格式 10 位

‘yuv444p12’

YUV 4:4:4 平面格式 12 位

fast

执行快速转换，跳过伽马/原色校正。这样可以显著降低 CPU 占用，但在数学上并不精确。若要获得与 colormatrix 滤镜生成的输出兼容的结果，请使用 fast=1。

dither

指定抖动模式。

可接受的值如下：

‘none’

不抖动

‘fsb’

Floyd-Steinberg 抖动

wpadapt

白点适应模式。

可接受的值如下：

‘bradford’

Bradford 白点适应

‘vonkries’

von Kries 白点适应

‘identity’

恒等白点适应（即无白点适应）

clipgamut

控制如何裁剪因色彩空间转换而产生的超出色域范围的颜色。

可接受的值如下：

‘none’

不裁剪超出色域范围的颜色。

‘rgb’

在构建伽马传递 LUT 时，将 RGB 值裁剪到 [0, 1] 范围内。

iall

一次性覆盖所有输入属性。可接受的值与 all 相同。

ispace

覆盖输入色彩空间。可接受的值与 space 相同。

iprimaries

覆盖输入原色。可接受的值与 primaries 相同。

itrc

覆盖输入传递特性。可接受的值与 trc 相同。

irange

覆盖输入色彩范围。可接受的值与 range 相同。

该滤镜会将传递特性、色彩空间和原色转换为指定的用户值。若未指定输出值，则会根据 "all" 属性设置默认值；若该属性也未指定，滤镜将记录一条错误。输出色彩范围和格式默认与输入色彩范围和格式相同。输入的传递特性、色彩空间、原色和色彩范围应当在输入数据上设置；如果缺少其中任何一项，滤镜将记录一条错误，且不执行转换。

例如，要将输入转换为 SMPTE-240M，可使用以下命令：

colorspace=smpte240m

11.40 colortemperature

调整视频中的色温，以模拟环境色温的变化。

该滤镜接受以下选项：

temperature

以开尔文为单位设置色温。允许范围为 1000 到 40000，默认值为 6500 K。

mix

设置与滤镜处理后输出的混合程度。允许范围为 0 到 1，默认值为 1。

设置保留明度的程度。允许范围为 0 到 1，默认值为 0。

11.40.1 命令

此滤镜支持与选项相同的命令。

11.41 convolution

应用 3x3、5x5、7x7 或水平/垂直方向最多 49 个元素的卷积。

该滤镜接受以下选项：

0m 1m 2m 3m

为每个平面设置矩阵。方形模式下，矩阵为 9、25 或 49 个带符号整数组成的序列；行模式下，矩阵为 1 到 49 个（奇数个）带符号整数组成的序列。

0rdiv 1rdiv 2rdiv 3rdiv

为每个平面设置计算值的乘数。如果未设置或为 0，则为所有矩阵元素之和的倒数（1/sum）。

0bias 1bias 2bias 3bias

为每个平面设置偏置。该值会被加到乘法结果上，可用于使整体图像变亮或变暗。默认值为 0.0。

0mode 1mode 2mode 3mode

为每个平面设置矩阵模式。可以是 square、row 或 column。默认值为 square。

11.41.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.41.2 示例

应用锐化：

convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"

应用模糊：

convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"

应用边缘增强：

convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"

应用边缘检测：

convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"

应用包含对角线的拉普拉斯边缘检测器：

convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0"

应用浮雕效果：

convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"

11.42 convolve

以第二条流作为脉冲，在频域对视频流应用二维卷积。

该滤镜接受以下选项：

planes

设置要处理的平面。

impulse

设置要处理哪些脉冲视频帧，可以是 first 或 all。默认值为 all。

convolve 滤镜还支持 framesync 选项。

11.43 copy

将输入视频源原样复制到输出。这主要用于测试目的。

11.44 coreimage

在 OSX 上使用 Apple 的 CoreImage API，通过 GPU 进行视频滤镜处理。

硬件加速基于 OpenGL 上下文。通常这意味着处理由视频硬件完成。不过，也存在基于软件的 OpenGL 实现，因此无法保证一定由硬件处理，这取决于具体的 OSX 版本。

Apple 提供了许多滤镜和图像生成器，各自附带种类繁多的选项。引用滤镜时必须同时指定其名称和选项。

coreimage 滤镜接受以下选项：

list_filters

列出所有可用的滤镜和生成器，以及各自的选项、可能的最小值和最大值，以及默认值。

list_filters=true

filter

通过各自的名称和选项指定全部滤镜。使用 list_filters 确定所有有效的滤镜名称和选项。数值型选项以 float 值指定，并会自动限制在各自的取值范围内。向量和颜色选项须以空格分隔的 float 值列表指定。字符必须转义。特殊选项名 default 可用于让滤镜使用默认选项。

必须指定 default 或至少一个滤镜选项。省略的选项均使用其默认值。滤镜字符串的语法如下：

filter=<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...][#<NAME>@<OPTION>=<VALUE>[@<OPTION>=<VALUE>][@...]][#...]

output_rect

指定一个矩形区域，滤镜链的输出会被复制到输入图像的该区域内。该区域以空格分隔的 float 值列表给出：

output_rect=x\ y\ width\ height

如果未给出，则输出矩形等于输入图像的尺寸。输出矩形会在输入图像的边界处自动裁剪。每个分量都可以使用负值。

output_rect=25\ 25\ 100\ 100

可以将多个滤镜串联起来进行连续处理，而无需 GPU-HOST 传输，从而实现复杂滤镜链的快速处理。目前仅支持零个输入图像（生成器）或恰好一个输入图像（滤镜）及一个输出图像的滤镜。此外，转场滤镜尚不能按预期方式使用。

根据各自滤镜内核的不同，某些滤镜生成的输出图像会带有额外的填充。系统会自动移除该填充，以确保滤镜输出与输入图像尺寸相同。

对于图像生成器，输出图像的尺寸分别由滤镜链中前一个输出图像，或整个滤镜链的输入图像决定。生成器不会使用该图像的像素信息来生成输出，但生成的输出会叠加到该图像上，从而部分或完全覆盖输出图像。

coreimagesrc 视频源可用于生成直接输入滤镜链的输入图像。使用该视频源后，无需再通过其他视频源或输入视频来提供输入图像。

11.44.1 示例

列出所有可用的滤镜：
```
coreimage=list_filters=true
```
使用 CIBoxBlur 滤镜及其默认选项模糊图像：
```
coreimage=filter=CIBoxBlur@default
```
使用滤镜链，CISepiaTone 使用默认值，CIVignetteEffect 的中心设为 100x100、半径设为 50 像素：
```
coreimage=filter=CIBoxBlur@default#CIVignetteEffect@inputCenter=100\ 100@inputRadius=50
```

使用 nullsrc 和 CIQRCodeGenerator 为 FFmpeg 主页生成二维码，以下是针对 Apple 标准 bash shell 完整转义后的命令行：

ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png

11.45 corr

获取两个输入视频之间的相关性。

此滤镜接受两个输入视频。

要使该滤镜正常工作，两个输入视频必须具有相同的分辨率和 pixel format。此外，该滤镜假定两个输入具有相同的帧数，并逐帧比较。

得到的各分量相关性，以及平均值、最小值和最大值，会通过日志系统输出。

该滤镜会将每帧计算得到的相关性存储在帧元数据中。

该滤镜还支持 framesync 选项。

在下面的示例中，正在处理的输入文件 main.mpg 会与参考文件 ref.mpg 比较。

ffmpeg -i main.mpg -i ref.mpg -lavfi corr -f null -

11.46 cover_rect

覆盖一个矩形对象

它接受以下选项：

cover

可选的覆盖图像的文件路径，须为 yuv420 格式。

mode

设置覆盖模式。

可接受的值有：

‘cover’

使用提供的图像覆盖它

‘blur’

通过对周围像素插值来覆盖它

默认值为 blur。

11.46.1 示例

使用 ffmpeg，用提供的图像覆盖给定视频中的矩形对象：

ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv

11.47 crop

将输入视频裁剪为指定的尺寸。

它接受以下参数：

w, out_w

输出视频的宽度。默认值为 iw。该表达式仅在滤镜配置期间求值一次，或在发送 ‘w’ 或 ‘out_w’ 命令时求值。

h, out_h

输出视频的高度。默认值为 ih。该表达式仅在滤镜配置期间求值一次，或在发送 ‘h’ 或 ‘out_h’ 命令时求值。

输出视频左边缘在输入视频中的水平位置。默认值为 (in_w-out_w)/2。该表达式按帧求值。

输出视频上边缘在输入视频中的垂直位置。默认值为 (in_h-out_h)/2。该表达式按帧求值。

keep_aspect

如果设为 1，将通过更改输出的采样宽高比，强制使输出的显示宽高比与输入相同。默认值为 0。

exact

启用精确裁剪。启用后，经过二次采样的视频会按照指定的精确宽度/高度/x/y 裁剪，而不会被舍入为最接近的较小值。默认值为 0。

out_w、out_h、x、y 参数是包含以下常量的表达式：

x y

x 和 y 的计算值。它们在每个新帧都会被求值。

in_w in_h

输入的宽度和高度。

iw ih

与 in_w 和 in_h 相同。

out_w out_h

输出（裁剪后）的宽度和高度。

ow oh

与 out_w 和 out_h 相同。

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，与 (iw / ih) * sar 相同

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

输入帧的编号，从 0 开始。

pos

输入帧在文件中的位置，未知时为 NAN；已弃用，请勿使用

以秒表示的时间戳。如果输入时间戳未知，则为 NAN。

out_w 的表达式可以依赖 out_h 的值，out_h 的表达式也可以依赖 out_w，但两者都不能依赖 x 和 y，因为 x 和 y 是在 out_w 和 out_h 之后求值的。

x 和 y 参数指定输出（未裁剪）区域左上角位置的表达式。它们按帧求值。如果求得的值无效，则会被近似为最接近的有效值。

x 的表达式可以依赖 y，y 的表达式也可以依赖 x。

11.47.1 示例

在位置 (12,34) 裁剪尺寸为 100x100 的区域。
```
crop=100:100:12:34
```

使用命名选项，上面的示例变为：

    crop=w=100:h=100:x=12:y=34

裁剪尺寸为 100x100 的中央输入区域：
```
crop=100:100
```
裁剪尺寸为输入视频 2/3 的中央输入区域：
```
crop=2/3*in_w:2/3*in_h
```
裁剪输入视频的中央正方形区域：
```
crop=out_w=in_h
crop=in_h
```
划定一个矩形，其左上角位于位置 100:100，右下角对应输入图像的右下角。
```
crop=in_w-100:in_h-100:100:100
```
从左右边缘各裁剪 10 像素，从上下边缘各裁剪 20 像素
```
crop=in_w-2*10:in_h-2*20
```
只保留输入图像右下角的四分之一：
```
crop=in_w/2:in_h/2:in_w/2:in_h/2
```
裁剪高度以获得黄金比例：
```
crop=in_w:1/PHI*in_w
```

应用震颤效果：

crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)

根据时间戳应用不规则的摄像机效果：

crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)

根据 y 的值设置 x：
```
crop=in_w/2:in_h/2:y:10+10*sin(n/10)
```

11.47.2 命令

该滤镜支持以下命令：

w, out_w h, out_h x y

设置输出视频的宽度/高度，以及在输入视频中的水平/垂直位置。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.48 cropdetect

自动检测裁剪尺寸。

它会计算所需的裁剪参数，并通过日志系统输出推荐的参数。检测到的尺寸对应于输入视频中根据 mode 判定的非黑色区域或视频区域。

它接受以下参数：

mode

根据 mode 的不同，裁剪检测的依据可以是周围像素的单纯黑色值，也可以是运动矢量与边缘像素的组合。

‘black’

检测环绕在播放视频周围的黑色像素。如需精细控制，请使用 limit 选项。

‘mvedges’

通过视频内部的运动矢量，并扫描通常构成播放视频边界的边缘像素，来检测正在播放的视频。

limit

设置较高的黑色值阈值，可选范围从无（0）到全部（对于基于 8 位的格式为 255）。大于该设置值的强度值将被视为非黑色。默认值为 24。也可以指定 0.0 到 1.0 之间的值，该值会根据 pixel format 的位深度缩放。

round

宽度/高度应能被其整除的值。默认值为 16\。偏移量会自动调整以使视频居中。使用 2 可只得到偶数尺寸（4:2:2 视频需要）。编码为大多数视频 codec 时，16 是最佳选择。

skip

设置跳过评估的起始帧数。默认值为 2。范围为 0 到 INT_MAX。

reset_count, reset

设置一个计数器，用于确定经过多少帧后 cropdetect 会重置此前检测到的最大视频区域，并重新开始检测当前的最优裁剪区域。默认值为 0。

当频道台标使视频区域失真时，这会很有用。0 表示“从不重置”，返回播放期间遇到的最大区域。

mv_threshold

以像素为单位设置运动检测的阈值。默认值为 8。

low high

设置 Canny 阈值算法所用的低阈值和高阈值。

高阈值用于选取“强”边缘像素，随后通过 8 连通将其与低阈值选取的“弱”边缘像素相连。

低阈值和高阈值必须选自 [0,1] 范围，且 low 应小于或等于 high。

low 的默认值为 5/255，high 的默认值为 15/255。

11.48.1 示例

查找被黑边包围的视频区域：

ffmpeg -i file.mp4 -vf cropdetect,metadata=mode=print -f null -

查找嵌入的视频区域，预先生成运动矢量：

ffmpeg -i file.mp4 -vf mestimate,cropdetect=mode=mvedges,metadata=mode=print -f null -

查找嵌入的视频区域，使用来自 decoder 的运动矢量：

ffmpeg -flags2 +export_mvs -i file.mp4 -vf cropdetect=mode=mvedges,metadata=mode=print -f null -

11.48.2 命令

该滤镜支持以下命令：

limit

该命令接受与对应选项相同的语法。如果指定的表达式无效，则保持当前值不变。

11.49 cue

将视频滤镜处理延迟到给定的实时时钟（wallclock）时间戳。该滤镜首先放行 preroll 数量的帧，然后最多缓冲 buffer 数量的帧并等待 cue。到达 cue 后，会转发已缓冲的帧，以及此后从输入进入的所有帧。

该滤镜可用于同步多个 ffmpeg 进程的输出，适用于 decklink 等实时输出设备。通过在滤镜链中加入延迟并预先缓冲帧，进程可以在到达目标实时时钟时间戳后几乎立即将数据传递给输出。

无法保证完美的帧精度，但对某些使用场景而言，结果已经足够好。

cue

以微秒为单位的 UNIX 时间戳形式表示的 cue 时间戳。默认值为 0。

preroll

以 preroll 形式放行的内容时长，以秒表示。默认值为 0。

buffer

在等待 cue 之前缓冲内容的最长时长，以秒表示。默认值为 0。

11.50 curves

使用曲线调整颜色。

该滤镜类似于 Adobe Photoshop 和 GIMP 的曲线工具。每个分量（红、绿、蓝）的值由 N 个关键点定义，这些关键点通过一条平滑曲线相互连接。x 轴表示输入帧的像素值，y 轴表示要为输出帧设置的新像素值。

默认情况下，分量曲线由 (0;0) 和 (1;1) 两个点定义。这会形成一条直线，其中每个原始像素值都被“调整”为其自身的值，也就是说图像不会发生变化。

该滤镜允许你重新定义这两个点并添加更多点。系统会定义一条新曲线，平滑地经过所有这些新坐标。新定义的点必须在 x 轴上严格递增，且其 x、y 值必须位于 [0;1] 区间内。曲线的形成方式取决于 interp 选项（默认为 natural），使用自然三次样条插值或单调三次样条插值。natural 样条通常能生成更平滑的曲线，而单调（pchip）样条则保证指定点之间的过渡是单调的。如果计算出的曲线超出了向量空间范围，相应的值会被裁剪。

该滤镜接受以下选项：

preset

从可用的颜色预设中选择一个。该选项可以与 r、g、b 参数一起使用；在这种情况下，后指定的选项优先于预设值。可用的预设有：

‘none’ ‘color_negative’ ‘cross_process’ ‘darker’ ‘increase_contrast’ ‘lighter’ ‘linear_contrast’ ‘medium_contrast’ ‘negative’ ‘strong_contrast’ ‘vintage’

默认值为 none。

master, m

设置主（master）关键点。这些点会定义第二遍映射，有时称为“亮度”或“值”映射。由于其作用类似于后处理 LUT，因此可以与 r、g、b 或 all 一起使用。

red, r

设置红色分量的关键点。

green, g

设置绿色分量的关键点。

blue, b

设置蓝色分量的关键点。

all

设置所有分量（不包括 master）的关键点。可以与其他关键点分量选项一起使用；在这种情况下，未设置的分量会回退到此 all 设置。

psfile

指定要从中导入设置的 Photoshop 曲线文件（.acv）。

plot

将曲线的 Gnuplot 脚本保存到指定文件中。

interp

指定插值的类型。可用的算法有：

‘natural’

自然三次样条，使用二阶连续可微的分段三次多项式。

‘pchip’

单调三次样条，使用分段三次 Hermite 插值多项式（PCHIP）。

为避免某些 filtergraph 语法冲突，每个关键点列表都必须使用以下语法定义：x0/y0 x1/y1 x2/y2 ...。

11.50.1 命令

此滤镜支持与选项相同的命令。

11.50.2 示例

略微提高蓝色的中间调：
```
curves=blue='0/0 0.5/0.58 1/1'
```

复古效果：

curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8'

这里我们为每个分量得到以下坐标：

red

(0;0.11) (0.42;0.51) (1;0.95)

green

(0;0) (0.50;0.48) (1;1)

blue

(0;0.22) (0.49;0.44) (1;0.80)

上面的示例也可以通过对应的内置预设实现：
```
curves=preset=vintage
```
或者更简单地：
```
curves=vintage
```

使用一个 Photoshop 预设，并重新定义绿色分量的点：

curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'

使用 ffmpeg 和 gnuplot 查看 cross_process 配置文件的曲线：

ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
gnuplot -p /tmp/curves.plt

11.51 datascope

视频数据分析滤镜。

该滤镜显示视频局部区域的十六进制像素值。

该滤镜接受以下选项：

size, s

设置输出视频的尺寸。

设置获取像素的 x 偏移量。

设置获取像素的 y 偏移量。

mode

设置显示模式，可以是以下值之一：

‘mono’

在黑色背景上以白色绘制十六进制像素值。

‘color’

在黑色背景上以输入视频的像素颜色绘制十六进制像素值。

‘color2’

在从输入视频取样得到的彩色背景上绘制十六进制像素值，文字颜色的选取方式确保始终清晰可见。

axis

在视频的左侧和顶部绘制行号和列号。

opacity

设置背景不透明度。

format

设置显示的数值格式。可以是 hex 或 dec。默认值为 hex。

components

设置要显示的像素分量。默认情况下会显示所有像素分量。

11.51.1 命令

该滤镜支持与选项相同的命令，但不包括 size 选项。

11.52 dblur

应用方向性模糊滤镜。

该滤镜接受以下选项：

angle

设置方向性模糊的角度。默认值为 45。

radius

设置方向性模糊的半径。默认值为 5。

planes

设置要过滤的平面。默认情况下会过滤所有平面。

11.52.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.53 dctdnoiz

使用 2D DCT（频域滤波）对帧去噪。

该滤镜并非为实时处理而设计。

该滤镜接受以下选项：

sigma, s

设置噪声 sigma 常数。

该 sigma 定义了 3 * sigma 的硬阈值；低于此阈值的每个 DCT 系数（绝对值）都会被丢弃。

如果需要更高级的滤波方式，请参阅 expr。

默认值为 0。

overlap

设置每个块重叠的像素数。由于该滤镜可能较慢，你可能希望降低此值，但代价是滤镜效果变差，并有产生各种伪影的风险。

如果重叠值不允许处理整个输入宽度或高度，将显示警告，且相应的边界不会被去噪。

默认值为 blocksize-1，这是可能的最佳设置。

expr, e

设置系数因子表达式。

对于 DCT 块的每个系数，该表达式都会被求值，作为该系数的乘数值。

如果设置了此选项，则会忽略 sigma 选项。

系数的绝对值可以通过变量 c 访问。

使用位数设置块大小。1<<n 定义了块大小，即所处理块的宽度和高度。

默认值为 3（8x8），可以提高到 4 以获得 16x16 的块大小。请注意，更改此设置会对处理速度产生很大影响。此外，更大的块大小并不一定意味着更好的去噪效果。

11.53.1 示例

使用 sigma 为 4.5 应用降噪：

dctdnoiz=4.5

使用表达式系统也可以实现相同的操作：

dctdnoiz=e='gte(c, 4.5*3)'

使用 16x16 的块大小进行强力降噪：

dctdnoiz=15:n=4

11.54 deband

从输入视频中去除条带伪影。其原理是用参考像素的平均值替换条带化的像素。

该滤镜接受以下选项：

1thr 2thr 3thr 4thr

设置每个平面的条带检测阈值。默认为 0.02。有效范围为 0.00003 到 0.5。如果当前像素与参考像素的差值小于阈值，则视为条带化。

range, r

条带检测范围，单位为像素。默认为 16。如果为正值，将使用 0 到设置值范围内的随机数；如果为负值，则使用其绝对值本身。该范围定义了当前像素周围四个像素构成的正方形。

direction, d

设置用于比较四个像素所依据的方向，单位为弧度。如果为正值，将从 0 到设置方向之间选取随机方向；如果为负值，则直接选取其绝对值。例如方向为 0、-PI 或 -2*PI 弧度时，只选取同一行上的像素，-PI/2 则只选取同一列上的像素。

blur, b

如果启用，当前像素将与周围四个像素的平均值进行比较。默认启用。如果禁用，当前像素将与周围四个像素分别比较；只有当与周围四个像素的差值全部小于阈值时，该像素才会被视为条带化。

coupling, c

如果启用，仅当所有像素分量都被判定为条带化时（即所有颜色分量都触发了条带检测阈值），当前像素才会被改变。默认禁用。

11.54.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.55 deblock

从输入视频中去除块效应伪影。

该滤镜接受以下选项：

filter

设置滤镜类型，可以是 weak 或 strong。默认为 strong。它控制应用哪种去块方式。

block

设置块的大小，允许范围为 4 到 512。默认为 8。

alpha beta gamma delta

设置块效应检测阈值。允许范围为 0 到 1。默认值分别为：alpha 为 0.098，其余为 0.05。使用更高的阈值可以提供更强的去块效果。alpha 用于控制块的精确边界处的阈值检测。其余选项控制边界附近的阈值检测，分别对应下/上或左/右方向。将其中任意一个设置为 0 都会禁用去块。

planes

设置要滤波的平面。默认对所有可用平面进行滤波。

11.55.1 示例

使用 weak 滤镜、块大小为 4 像素进行去块。
```
deblock=filter=weak:block=4
```
使用 strong 滤镜、块大小为 4 像素，并使用自定义阈值来对更多边界进行去块。
```
deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
```

与上面类似，但只对第一个平面进行滤波。

deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1

与上面类似，但只对第二个和第三个平面进行滤波。

deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6

11.55.2 命令

该滤镜支持将以上所有选项作为命令使用。

11.56 decimate

按固定间隔丢弃重复的帧。

该滤镜接受以下选项：

cycle

设置从中丢弃一帧的帧数。将其设为 N 意味着每 N 帧为一组，其中一帧会被丢弃。默认为 5。

dupthresh

设置重复检测的阈值。如果某一帧的差异度量值小于或等于该值，则将其判定为重复帧。默认为 1.1

scthresh

设置场景切换阈值。默认为 15。

blockx blocky

设置用于度量计算的 x 轴和 y 轴块大小。块越大，噪声抑制效果越好，但对细微运动的检测效果越差。必须是 2 的幂。默认为 32。

ppsrc

将主输入标记为预处理输入，并启用干净源输入流。这样可以在保持帧选择无损的同时，使用各种滤镜对输入进行预处理以辅助度量计算。设置为 1 时，第一条流为预处理输入，第二条流为用于选取保留帧的干净源。默认为 0。

chroma

设置度量计算中是否考虑色度。默认为 1。

mixed

设置输入是否只有部分内容需要被去重。默认为 false。若启用，视频输出流将采用可变帧率。

11.57 deconvolve

以第二条流作为脉冲，在频域中对视频流进行二维反卷积。

该滤镜接受以下选项：

planes

设置要处理的平面。

impulse

设置要处理哪些脉冲视频帧，可以是 first 或 all。默认为 all。

noise

设置进行除法运算时的噪声。默认为 0.0000001。当宽度和高度不相等且不是 2 的幂，或者进行卷积之前的流本身含有噪声时，此选项会很有用。

deconvolve 滤镜还支持 framesync 选项。

11.58 dedot

减少视频中的交叉亮度（点爬行）和交叉色度（彩虹纹）。

它接受以下选项：

设置工作模式，可以组合使用 dotcrawl（用于减少交叉亮度）和/或 rainbows（用于减少交叉色度）。

设置空间亮度阈值。值越低，交叉亮度的减少效果越强。

设置时间亮度的容差。值越高，交叉亮度的减少效果越强。

设置色度时间变化的容差。值越高，交叉色度的减少效果越强。

设置时间色度阈值。值越低，交叉色度的减少效果越强。

11.59 deflate

对视频应用 deflate（收缩）效果。

该滤镜会用局部（3x3）平均值替换像素，该平均值只考虑低于该像素的值。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量，默认值为 65535。若为 0，则该平面将保持不变。

11.59.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.60 deflicker

去除帧间的时间性亮度波动。

它接受以下选项：

size, s

以帧数设置移动平均滤波器的大小。默认为 5。允许范围为 2 到 129。

mode, m

设置用于平滑时间性亮度波动的平均模式。

可用值如下：

‘am’

算术平均

‘gm’

几何平均

‘hm’

调和平均

‘qm’

平方平均

‘cm’

立方平均

‘pm’

幂平均

‘median’

中值

bypass

不实际修改帧。仅需要元数据时会很有用。

11.61 deinterlace_d3d12

使用 D3D12 硬件加速视频处理对输入视频进行去隔行。

该滤镜使用 DirectX 12 Video Processor 在 GPU 上执行去隔行，支持简单的 bob 和驱动定义的高级（运动自适应）算法。要求输入采用 d3d12 硬件 pixel format。

该滤镜会根据需要自动向硬件查询所需的时间参考帧数量，并管理一个帧队列来提供这些帧。

它接受以下选项：

method

去隔行方法。接受以下值之一：

‘default’

选择硬件上可用的最佳去隔行方法。如果驱动支持 custom，则使用该方法；否则回退到 bob。这是默认值。

‘bob’

bob 去隔行。每个场都独立缩放到完整帧高度。简单快速，但在有运动的内容上可能产生明显的 bob 伪影。

‘custom’

驱动定义的高级去隔行。具体算法因硬件而异，通常采用运动自适应技术并结合时间参考帧以获得更高质量。

默认值为 default。

mode

指定隔行模式。接受以下值之一：

‘frame’

每帧发送一帧。输出帧率等于输入帧率。这是默认值。

‘field’

每场发送一帧。输出帧率是输入帧率的两倍。

默认值为 frame。

deint

指定要去隔行的帧。接受以下值之一：

‘all’

对所有帧进行去隔行。这是默认值。

‘interlaced’

只对标记为隔行的帧进行去隔行；逐行帧将原样通过。

默认值为 all。

11.61.1 示例

使用软件解码和硬件上可用的最佳去隔行方法对隔行视频进行去隔行：

ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
       -vf "format=nv12,hwupload,deinterlace_d3d12=method=default,hwdownload,format=nv12" \
       -c:v libx264 -crf 18 output.mp4

使用 bob 方法以场速率（帧率的两倍）进行去隔行，并采用硬件解码（完整 d3d12 管线）：

ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.ts \
       -vf "deinterlace_d3d12=method=bob:mode=field" \
       -c:v h264_d3d12va output.mp4

只对隔行帧进行去隔行，逐行帧原样通过：

ffmpeg -init_hw_device d3d12va=d3d12 -filter_hw_device d3d12 -i input.ts \
       -vf "format=nv12,hwupload,deinterlace_d3d12=deint=interlaced,hwdownload,format=nv12" \
       -c:v libx264 -crf 18 output.mp4

11.62 dejudder

去除部分隔行的电视电影转换素材所产生的抖动。

抖动可能由 pullup 滤镜等引入。如果原始素材是部分经过电视电影转换的内容，那么 pullup,dejudder 的输出将是可变帧率。这可能会改变容器中记录的帧率。除此之外，该滤镜不会影响恒定帧率的视频。

该滤镜提供的选项如下：

cycle

指定抖动重复出现的窗口长度。

接受任意大于 1 的整数。常用的取值如下：

‘4’

如果原始素材是从 24fps 电视电影转换到 30fps（胶片转 NTSC）。

‘5’

如果原始素材是从 25fps 电视电影转换到 30fps（PAL 转 NTSC）。

‘20’

如果两者混合。

默认值为 ‘4’。

11.63 delogo

通过对周围像素进行简单插值来消除电视台台标。只需设置一个覆盖台标的矩形，它就会消失（有时也会出现更难看的东西——效果因情况而异）。

它接受以下参数：

x y

指定台标左上角的坐标。必须指定。

w h

指定要清除的台标的宽度和高度。必须指定。

show

设置为 1 时，屏幕上会绘制一个绿色矩形，以便更容易找到正确的 x、y、w、h 参数。默认值为 0。

该矩形绘制在将被（部分）替换为插值的最外层像素上。矩形外部各方向紧邻的下一个像素的值将用于计算矩形内部的插值像素值。

11.63.1 示例

设置一个矩形，覆盖左上角坐标为 0,0、大小为 100x77 的区域：
```
delogo=x=0:y=0:w=100:h=77
```

11.64 derain

通过应用基于卷积神经网络的 derain 方法，去除输入图像/视频中的雨。支持的模型如下：

Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN)。参见 http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf。

训练脚本以及模型生成脚本可以在 https://github.com/XueweiMeng/derain_filter.git 仓库中找到。

该滤镜接受以下选项：

filter_type

指定要使用的滤镜。该选项接受以下值：

‘derain’

derain 滤镜。要执行 derain 滤镜，需要使用 derain 模型。

‘dehaze’

dehaze 滤镜。要执行 dehaze 滤镜，需要使用 dehaze 模型。

默认值为 ‘derain’。

dnn_backend

指定用于模型加载和执行的 DNN 后端。该选项接受以下值：

‘tensorflow’

TensorFlow 后端。要启用该后端，需要安装 TensorFlow for C 库（参见 https://www.tensorflow.org/install/lang_c），并使用 --enable-libtensorflow 配置 FFmpeg

model

设置指定网络架构及其参数的模型文件路径。请注意，不同的后端使用不同的文件格式。TensorFlow 只能加载其自身格式的文件。

要获得完整功能（例如异步执行），请使用 dnn_processing 滤镜。

11.65 deshake

尝试修正水平和/或垂直方向上的微小位移变化。该滤镜有助于消除因手持摄像机、碰到三脚架、在交通工具上移动等原因造成的相机抖动。

该滤镜接受以下选项：

x y w h

指定一个矩形区域，用于限制运动向量的搜索范围。如果需要，可以将运动向量的搜索限制在由左上角坐标、宽度和高度定义的帧内矩形区域中。这些参数与 drawbox 滤镜的含义相同，可以用 drawbox 来可视化边界框的位置。

当画面内被摄体的同时运动可能被运动向量搜索误判为相机运动时，此选项很有用。

如果 x、y、w、h 中的任意一个或全部设为 -1，则使用整个帧。这样就可以在不为运动向量搜索指定边界框的情况下设置后续选项。

默认值 - 搜索整个帧。

rx ry

指定 x 和 y 方向上的最大运动范围，取值范围为 0-64 像素。默认为 16。

edge

指定如何为帧边缘的空白处生成像素。可用的值如下：

‘blank, 0’

在空白处填充零值

‘original, 1’

在空白处使用原始图像

‘clamp, 2’

在空白处使用拉伸的边缘像素值

‘mirror, 3’

在空白处使用镜像的边缘像素

默认值为 ‘mirror’。

blocksize

指定用于运动搜索的块大小。范围为 4-128 像素，默认为 8。

contrast

指定块的对比度阈值。只有对比度（最亮像素与最暗像素之差）超过指定值的块才会被考虑。范围为 1-255，默认为 125。

指定搜索策略。可用的值如下：

‘exhaustive, 0’

设置为全面搜索

‘less, 1’

设置为非全面搜索。

默认值为 ‘exhaustive’。

filename

如果设置，运动搜索的详细日志将写入指定的文件。

11.66 despill

去除由绿幕或蓝幕反射色造成的前景色的不必要污染。

此滤镜接受以下选项：

type

设置要使用的 despill 类型。

mix

设置 spillmap 的生成方式。

expand

设置要去除多少残留的溢色。

red

控制溢色区域中红色的量。

green

控制溢色区域中绿色的量。对于绿幕，应设为 -1。

blue

控制溢色区域中蓝色的量。对于蓝幕，应设为 -1。

brightness

控制溢色区域的亮度，同时保留颜色。

alpha

修改由生成的 spillmap 得到的 alpha。

11.66.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.67 detelecine

对视频应用与电视电影转换过程完全相反的操作。它需要使用 pattern 选项指定一个预定义图案，该图案必须与传给 telecine 滤镜的图案相同。

此滤镜接受以下选项：

first_field

‘top, t’

顶场优先

‘bottom, b’

底场优先。默认值为 top。

pattern

一个表示要应用的下拉图案的数字字符串。默认值为 23。

start_frame

一个数字，表示第一帧相对于电视电影转换图案的位置。当流被截断时可使用此选项。默认值为 0。

11.68 dilation

对视频应用膨胀（dilation）效果。

该滤镜会用局部（3x3）最大值替换像素。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量，默认值为 65535。若为 0，则该平面将保持不变。

coordinates

指定要参考的像素的标志。默认值为 255，即使用全部八个像素。

标志与局部 3x3 坐标的对应关系如下：

1 2 3 4 5 6 7 8

11.68.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.69 displace

根据第二个和第三个输入流对像素进行位移。

它接受三个输入流并输出一个流：第一个输入是源，第二个和第三个输入是位移图。

第二个输入指定沿 x 轴对像素进行多少位移，第三个输入指定沿 y 轴对像素进行多少位移。如果某个位移图流结束，将使用该位移图的最后一帧。

请注意，位移图一旦生成，就可以反复重复使用。

接受的选项说明如下。

edge

设置超出范围的像素的位移行为。

可用值如下：

‘blank’

缺失的像素将替换为黑色像素。

‘smear’

相邻像素将向外扩展以替换缺失的像素。

‘wrap’

超出范围的像素将被环绕，指向另一侧的像素。

‘mirror’

超出范围的像素将替换为镜像像素。

默认为 ‘smear’。

11.69.1 示例

为 hd720 尺寸的 rgb 输入视频添加波纹效果：

ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT

为 hd720 尺寸的 rgb 输入视频添加波浪效果：

ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT

11.70 dnn_classify

使用深度神经网络基于边界框进行分类。

该滤镜接受以下选项：

dnn_backend

指定用于模型加载和执行的 DNN 后端。该选项目前只接受 openvino，之后会加入 tensorflow 后端。

model

设置指定网络架构及其参数的模型文件路径。请注意，不同的后端使用不同的文件格式。

input

设置 dnn 网络的输入名称。

output

设置 dnn 网络的输出名称。

confidence

设置置信度阈值（默认值：0.5）。

labels

设置指定标签 id 与名称对应关系的标签文件路径。每个标签名称单独占一行，行尾空格和空行会被跳过。第一行是标签 id 0 的名称，第二行是标签 id 1 的名称，依此类推。如果未提供标签文件，则将标签 id 本身当作名称。

backend_configs

设置要传给后端的配置。

对于 tensorflow 后端，可以通过 sess_config 选项设置其配置，请使用 tools/python/tf_sess_config.py 获取适合你系统的配置。

11.71 dnn_detect

使用深度神经网络进行目标检测。

该滤镜接受以下选项：

dnn_backend

指定用于模型加载和执行的 DNN 后端。该选项目前只接受 openvino，之后会加入 tensorflow 后端。

model

设置指定网络架构及其参数的模型文件路径。请注意，不同的后端使用不同的文件格式。

input

设置 dnn 网络的输入名称。

output

设置 dnn 网络的输出名称。

confidence

设置置信度阈值（默认值：0.5）。

labels

设置指定标签 id 与名称对应关系的标签文件路径。每个标签名称单独占一行，行尾空格和空行会被跳过。第一行是标签 id 0 的名称（通常为 ’background’），第二行是标签 id 1 的名称，依此类推。如果未提供标签文件，则将标签 id 本身当作名称。

backend_configs

设置要传给后端的配置。要使用异步执行，请设置 async（默认：已设置）。如果后端不支持异步，则回退到同步执行。

11.72 dnn_processing

使用深度神经网络进行图像处理。它需要与另一个滤镜配合使用，该滤镜负责将帧的 pixel format 转换为 dnn 网络所需的格式。

该滤镜接受以下选项：

dnn_backend

指定用于模型加载和执行的 DNN 后端。该选项接受以下值：

‘tensorflow’

TensorFlow 后端。要启用该后端，需要安装 TensorFlow for C 库（参见 https://www.tensorflow.org/install/lang_c），并使用 --enable-libtensorflow 配置 FFmpeg

‘openvino’

OpenVINO 后端。要启用该后端，需要构建并安装 OpenVINO for C 库（参见 https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md），并使用 --enable-libopenvino 配置 FFmpeg（如果头文件和库未安装到系统路径中，可能还需要 –extra-cflags=-I... –extra-ldflags=-L...）

‘torch’

Libtorch 后端。要启用该后端，需要构建并安装用于 C++ 的 Libtorch 库。请下载 cxx11 ABI 版本（参见 https://pytorch.org/get-started/locally），并使用 --enable-libtorch --extra-cflags=-I/libtorch_root/libtorch/include --extra-cflags=-I/libtorch_root/libtorch/include/torch/csrc/api/include --extra-ldflags=-L/libtorch_root/libtorch/lib/ 配置 FFmpeg

‘onnx’

ONNX Runtime 后端。要启用该后端，需要安装 ONNX Runtime 库（参见 https://onnxruntime.ai/），并使用 --enable-libonnxruntime 配置 FFmpeg。

当前的 ONNX Runtime 后端要求输入和输出张量为 4 维、采用 NCHW 布局，且元素类型为 32 位浮点数（ONNX FLOAT）；使用整数或其他元素类型（例如 UINT8）的模型不受支持，会在加载时被拒绝。目前尚不支持使用 NHWC 布局或其他维数的模型。仅支持单输入模型；后端在运行模型时只绑定一个输入张量。

对于 ONNX Runtime 后端，input 和 output 选项是可选的；如果省略，后端会从会话中解析张量名称。

ONNX Runtime 后端使用单个推理请求同步运行推理。因此，共享的 async 和 nireq 选项对 dnn_backend=onnx 没有影响：无论其取值如何，推理始终以同步方式运行。

model

设置指定网络架构及其参数的模型文件路径。请注意，不同的后端使用不同的文件格式。TensorFlow、OpenVINO、Libtorch 和 ONNX Runtime 后端都只能加载各自对应格式的文件。

input

设置 dnn 网络的输入名称。TensorFlow 后端为必需项；ONNX Runtime 后端为可选项。

output

设置 dnn 网络的输出名称。TensorFlow 后端为必需项；ONNX Runtime 后端为可选项。

backend_configs

设置要传给后端的配置。要使用异步执行，请设置 async（默认：已设置）。如果后端不支持异步，则回退到同步执行。

对于 tensorflow 后端，可以通过 sess_config 选项设置其配置，请使用 tools/python/tf_sess_config.py 获取适合你系统的 TensorFlow 后端配置。

device

设置运行模型所用的设备。对于 ONNX Runtime 后端，此项用于选择执行提供程序：cpu（默认）、cuda（NVIDIA GPU）、dml（DirectML，仅限 Windows）或 vitisai（AMD Ryzen AI NPU）。

device_id

设置 GPU 执行提供程序（例如 cuda 或 dml）在 ONNX Runtime 后端中使用的设备索引。默认为 0。

threads_per_operation

仅适用于 ONNX Runtime 后端。设置在使用 device=cpu 运行时，每个 ONNX Runtime 算子所使用的 CPU 线程数。默认为 0（让 ONNX Runtime 自动选择）。对 GPU/NPU 提供程序没有影响。

11.72.1 示例

使用 can.pb 去除 rgb24 帧中的雨迹（参见 derain 滤镜）：

./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg

对 yuv420p 帧（支持平面 YUV 格式）使用 srcnn.pb 处理 Y 通道（参见 sr 滤镜）：

./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg

对格式为 yuv420p 的帧（支持平面 YUV 格式），使用会改变帧尺寸的 espcn.pb 处理 Y 通道（参见 sr 滤镜）；请使用 tools/python/tf_sess_config.py 获取适合你系统的 TensorFlow 后端配置。
```
./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y:backend_configs=sess_config=0x10022805320e09cdccccccccccec3f20012a01303801 -y tmp.espcn.jpg
```

11.73 drawbox

在输入图像上绘制一个彩色矩形。

它接受以下参数：

x y

指定矩形左上角坐标的表达式。默认值为 0。

width, w height, h

指定矩形宽度和高度的表达式；若为 0，则解释为输入的宽度和高度。默认值为 0。

color, c

指定要绘制的矩形颜色。关于此选项的通用语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。若使用特殊值 invert，矩形边缘的颜色将与反转亮度后的视频相同。

thickness, t

设置矩形边缘粗细的表达式。值为 fill 时将创建一个填充的矩形。默认值为 3。

可接受的常量列表见下文。

replace

适用于输入带 alpha 的情况。值为 1 时，绘制的矩形像素将覆盖视频的颜色和 alpha 像素。默认值为 0，此时矩形会合成到输入上，视频的 alpha 保持不变。

x、y、w、h、t 参数是包含以下常量的表达式：

dar

输入的显示宽高比，等同于 (w / h) * sar。

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

in_h, ih in_w, iw

输入的宽度和高度。

sar

输入的样本宽高比。

x y

绘制矩形的 x、y 偏移坐标。

w h

绘制矩形的宽度和高度。

box_source

如果想使用 side data 中检测边界框（detection bboxes）内的框数据，可将 box source 设置为 side_data_detection_bboxes。

如果设置了 box_source，则 x、y、width、height 将被忽略，并继续使用 side data 中检测边界框内的框数据。因此，如果不确定 box source，请不要使用此参数。

绘制矩形的粗细。

这些常量使 x、y、w、h、t 表达式可以相互引用，因此你可以指定例如 y=x/dar 或 h=w/dar。

11.73.1 示例

沿输入图像边缘绘制黑色矩形：
```
drawbox
```
绘制颜色为红色、不透明度为 50% 的矩形：
```
drawbox=10:20:200:60:red@0.5
```

上例也可以写作：

    drawbox=x=10:y=20:w=200:h=60:color=red@0.5

用粉色填充矩形：

drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill

绘制一个 2 像素宽、红色、比例为 2.40:1 的遮罩：

drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red

11.73.2 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.74 drawgraph

使用输入视频的元数据绘制图表。

它接受以下参数：

设置第 1 个帧元数据键，用于取值以绘制图表。

fg1

设置第 1 个前景色表达式。

设置第 2 个帧元数据键，用于取值以绘制图表。

fg2

设置第 2 个前景色表达式。

设置第 3 个帧元数据键，用于取值以绘制图表。

fg3

设置第 3 个前景色表达式。

设置第 4 个帧元数据键，用于取值以绘制图表。

fg4

设置第 4 个前景色表达式。

min

设置元数据值的最小值。

max

设置元数据值的最大值。

设置图表的背景色。默认值为白色。

mode

设置图表模式。

mode 可用的值为：

‘bar’ ‘dot’ ‘line’

默认值为 line。

slide

设置滑动模式。

slide 可用的值为：

‘frame’

到达右边界时绘制新的帧。

‘replace’

用新的列替换旧的列。

‘scroll’

从右向左滚动。

‘rscroll’

从左向右滚动。

‘picture’

绘制单张图像。

默认值为 frame。

size

设置图表视频的尺寸。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Video size” 一节。默认值为 900x256。

rate, r

设置输出帧率。默认值为 25。

前景色表达式可以使用以下变量：

MIN

元数据值的最小值。

MAX

元数据值的最大值。

VAL

当前元数据键的值。

颜色以 0xAABBGGRR 的形式定义。

使用 signalstats 滤镜元数据的示例：

signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255

使用 ebur128 滤镜元数据的示例：

ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5

11.75 drawgrid

在输入图像上绘制网格。

它接受以下参数：

x y

指定网格交点某一点坐标（用于配置偏移量）的表达式。两者默认值均为 0。

width, w height, h

指定网格单元宽度和高度的表达式；若为 0，则分别解释为输入的宽度和高度减去 thickness，从而使图像被网格框住。默认值为 0。

color, c

指定网格的颜色。关于此选项的通用语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。若使用特殊值 invert，网格的颜色将与反转亮度后的视频相同。

thickness, t

设置网格线粗细的表达式。默认值为 1。

可接受的常量列表见下文。

replace

适用于输入带 alpha 的情况。值为 1 时，绘制的网格像素将覆盖视频的颜色和 alpha 像素。默认值为 0，此时网格会合成到输入上，视频的 alpha 保持不变。

x、y、w、h、t 参数是包含以下常量的表达式：

dar

输入的显示宽高比，等同于 (w / h) * sar。

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

in_h, ih in_w, iw

输入的网格单元宽度和高度。

sar

输入的样本宽高比。

x y

网格交点某一点的 x、y 坐标（用于配置偏移量）。

w h

绘制单元的宽度和高度。

绘制单元的粗细。

这些常量使 x、y、w、h、t 表达式可以相互引用，因此你可以指定例如 y=x/dar 或 h=w/dar。

11.75.1 示例

绘制单元格为 100x100 像素、粗细为 2 像素、颜色为红色、不透明度为 50% 的网格：
```
drawgrid=width=100:height=100:thickness=2:color=red@0.5
```
绘制不透明度为 50% 的白色 3x3 网格：
```
drawgrid=w=iw/3:h=ih/3:t=2:c=white@0.5
```

11.75.2 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.76 drawtext

使用 libfreetype 库，在视频上绘制文本字符串或指定文件中的文本。

要启用此滤镜的编译，需要在配置 FFmpeg 时加上 --enable-libfreetype 和 --enable-libharfbuzz。要启用默认字体回退和 font 选项，需要加上 --enable-libfontconfig 配置 FFmpeg。要启用 text_shaping 选项，需要加上 --enable-libfribidi 配置 FFmpeg。

11.76.1 语法

它接受以下参数：

box

用于使用背景色在文本周围绘制矩形。值必须为 1（启用）或 0（禁用）。box 的默认值为 0。

boxborderw

设置使用 boxcolor 在矩形周围绘制的边框宽度。值必须按以下格式之一指定：

boxborderw=10 将所有边框的宽度设置为 10
boxborderw=10|20 将上下边框的宽度设置为 10，左右边框的宽度设置为 20
boxborderw=10|20|30 将上边框的宽度设置为 10，下边框的宽度设置为 30，左右边框的宽度设置为 20
boxborderw=10|20|30|40 将边框宽度设置为 10（上）、20（右）、30（下）、40（左）

boxborderw 的默认值为 "0"。

boxcolor

用于在文本周围绘制矩形的颜色。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。

boxcolor 的默认值为 "white"。

line_spacing

以像素为单位设置行间距。line_spacing 的默认值为 0。

text_align

设置文本相对于矩形边界的垂直和水平对齐方式。值是若干标志的组合：一个表示垂直对齐（T=顶部，M=居中，B=底部），一个表示水平对齐（L=左，C=居中，R=右）。请注意，制表符仅在水平左对齐时受支持。

y_align

指定 y 值的参照对象。可用的值为：

text 第一行文本中最高字形的顶端置于 y 处
baseline 第一行文本的基线置于 y 处
font 第一行文本的基线置于 y 加上字体度量中定义的 ascent（以像素为单位）之处

y_align 的默认值为 "text"，以保持向后兼容。

borderw

设置使用 bordercolor 在文本周围绘制的边框宽度。borderw 的默认值为 0。

bordercolor

设置用于在文本周围绘制边框的颜色。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。

bordercolor 的默认值为 "black"。

expansion

选择文本的展开方式。可以是 none、strftime（已弃用）或 normal（默认）之一。详情见下文的“文本展开”一节。

basetime

设置计数的起始时间。值以微秒为单位。仅在已弃用的 strftime 展开模式下适用。要在 normal 展开模式下模拟同样的效果，可使用 pts 函数，将起始时间（以秒为单位）作为第二个参数传入。

fix_bounds

若为真，则检查并修正文本坐标以避免裁切。

fontcolor

用于绘制字体的颜色。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。

fontcolor 的默认值为 "black"。

fontcolor_expr

以与 text 相同的方式展开、用于获得动态 fontcolor 值的字符串。默认情况下此选项为空值且不会被处理。设置此选项后，将覆盖 fontcolor 选项。

font

用于绘制文本的字体族。默认是 Sans。

fontfile

用于绘制文本的字体文件。必须包含路径。如果 fontconfig 支持被禁用，则此参数为必需。

alpha

应用 alpha 混合绘制文本。值可以是 0.0 到 1.0 之间的数字。该表达式同样接受 x、y 变量。默认值为 1。另见 fontcolor_expr。

fontsize

用于绘制文本的字体大小。fontsize 的默认值为 16。

text_shaping

若设置为 1，则在绘制前尝试对文本进行 shaping（例如反转从右到左书写文本的顺序，并连接阿拉伯字符）。否则，按原样绘制文本。默认为 1（如果支持）。

ft_load_flags

用于加载字体的标志。

这些标志对应 libfreetype 所支持的相应标志，是以下值的组合：

default no_scale no_hinting render no_bitmap vertical_layout force_autohint crop_bitmap pedantic ignore_global_advance_width no_recurse ignore_transform monochrome linear_design no_autohint

默认值为 "default"。

更多信息请参阅 libfreetype 的 FT_LOAD_* 标志文档。

shadowcolor

用于在绘制的文本背后绘制阴影的颜色。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。

shadowcolor 的默认值为 "black"。

boxw

设置在文本周围绘制的矩形宽度。boxw 的默认值会自动计算以匹配文本宽度

boxh

设置在文本周围绘制的矩形高度。boxh 的默认值会自动计算以匹配文本高度

shadowx shadowy

文本阴影位置相对于文本位置的 x、y 偏移量。可以是正值或负值。两者的默认值均为 "0"。

start_number

n/frame_num 变量的起始帧号。默认值为 "0"。

tabsize

用于渲染制表符的空格数。默认值为 4。

timecode

以 "hh:mm:ss[:;.]ff" 格式设置初始时间码的表示形式。可以搭配 text 参数使用，也可以不搭配使用。必须指定 timecode_rate 选项。

timecode_rate, rate, r

设置时间码的帧率（仅用于 timecode）。值将被舍入为最接近的整数。最小值为 "1"。帧率为 30 和 60 时支持丢帧时间码。

tc24hmax

若设置为 1，则 timecode 选项的输出将在 24 小时处回绕。默认值为 0（禁用）。

text

要绘制的文本字符串。文本必须是 UTF-8 编码字符的序列。如果没有通过 textfile 参数指定文件，则此参数为必需。

textfile

包含要绘制文本的文本文件。文本必须是 UTF-8 编码字符的序列。

如果没有通过 text 参数指定文本字符串，则此参数为必需。

如果同时指定了 text 和 textfile，则会抛出错误。

text_source

如果想使用 side data 中检测边界框内的文本数据，应将 text source 设置为 side_data_detection_bboxes。

如果设置了 text source，则 text 和 textfile 将被忽略，并继续使用 side data 中检测边界框内的文本数据。因此，如果不确定 text source，请不要使用此参数。

reload

textfile 将按指定的帧间隔重新加载。请确保以原子方式更新 textfile，否则可能会被部分读取，甚至读取失败。范围为 0 到 INT_MAX。默认值为 0。

x y

指定文本在视频帧内绘制偏移量的表达式。它们相对于输出图像的顶部/左侧边界。

x 和 y 的默认值为 "0"。

可接受的常量和函数列表见下文。

x 和 y 参数是包含以下常量和函数的表达式：

dar

输入的显示宽高比，与 (w / h) * sar 相同

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

line_h, lh

每行文本的高度

main_h, h, H

输入的高度

main_w, w, W

输入的宽度

max_glyph_a, ascent

对于所有渲染的字形，从基线到用于放置字形轮廓点的最高（上方）网格坐标之间的最大距离。由于网格的朝向使 Y 轴向上，因此这是一个正值。

max_glyph_d, descent

对于所有渲染的字形，从基线到用于放置字形轮廓点的最低网格坐标之间的最大距离。由于网格的朝向使 Y 轴向上，因此这是一个负值。

max_glyph_h

最大字形高度，即渲染文本中所包含的所有字形的最大高度，等同于 ascent - descent。

max_glyph_w

最大字形宽度，即渲染文本中所包含的所有字形的最大宽度

font_a

字体度量中定义的 ascent 大小

font_d

字体度量中定义的 descent 大小

top_a

第一行文本字形的最大 ascender

bottom_d

最后一行文本字形的最大 descender

输入帧的编号，从 0 开始

rand(min, max)

返回一个介于 min 和 max 之间的随机数

sar

输入的样本宽高比。

以秒为单位表示的时间戳；如果输入时间戳未知则为 NAN

text_h, th

渲染文本的高度

text_w, tw

渲染文本的宽度

x y

绘制文本的 x、y 偏移坐标。

这些参数使 x 和 y 表达式可以相互引用，因此你可以指定例如 y=x/dar。

pict_type

当前帧图像类型的单字符描述。

pkt_pos

当前数据包在输入文件或流中的位置（以字节为单位，从输入起始处计算）。值为 -1 表示此信息不可用。

duration

当前数据包的时长（以秒为单位）。

pkt_size

当前数据包的大小（以字节为单位）。

11.76.2 文本展开

若 expansion 设置为 strftime，滤镜会识别所提供文本中 C 语言 strftime 函数所接受的序列，并据此展开。请查阅 strftime 的文档。此功能已弃用，建议改用配合 gmtime 或 localtime 展开函数的 normal 展开方式。

若 expansion 设置为 none，则原样输出文本。

若 expansion 设置为 normal（默认值），则使用以下展开机制。

反斜杠字符 ‘\’ 后跟任意字符时，总是展开为第二个字符。

形如 %{...} 的序列会被展开。花括号之间的文本是函数名，其后可能跟着以 ’:’ 分隔的参数。如果参数中包含特殊字符或分隔符（’:’ 或 ’}’），应对其进行转义。

请注意，作为滤镜参数字符串中 text 选项的值、以及作为 filtergraph 描述中的滤镜参数，它们可能也需要被转义，此外可能还需要为 shell 转义，这样最多可达四层转义；使用 textfile 选项配合文本文件可以避免这些问题。

可用的函数如下：

expr, e

表达式求值的结果。

它必须接受一个参数，指定要求值的表达式，该表达式接受与 x、y 值相同的常量和函数。请注意，并非所有常量都能使用，例如在求值表达式时文本大小尚未确定，因此常量 text_w 和 text_h 的值将是未定义的。

expr_int_format, eif

对表达式的值求值，并以格式化整数的形式输出。

第一个参数是要求值的表达式，与 expr 函数相同。第二个参数指定输出格式，可用的值为 ‘x’、‘X’、‘d’、‘u’，其处理方式与 printf 函数完全相同。第三个参数是可选的，用于设置输出所占的位数，可用于在左侧填充零。

gmtime

滤镜运行时刻，以 UTC 表示。可以接受一个参数：C 语言 strftime 函数的格式字符串。此格式字符串经过扩展，支持变量 %[1-6]N，用于输出秒的小数部分，可任意指定输出的位数。

localtime

滤镜运行时刻，以本地时区表示。可以接受一个参数：C 语言 strftime 函数的格式字符串。此格式字符串经过扩展，支持变量 %[1-6]N，用于输出秒的小数部分，可任意指定输出的位数。

metadata

帧元数据。接受一个或两个参数。

第一个参数是必需的，用于指定元数据键。

第二个参数是可选的，用于指定默认值，在找不到元数据键或其为空时使用。

可以通过运行 ffprobe -show_frames 打印出的各帧小节中，查看以 TAG 开头的条目来确定可用的元数据。

在通向 drawtext 滤镜的各滤镜中生成的字符串元数据同样可用。

n, frame_num

帧编号，从 0 开始。

pict_type

当前图像类型的单字符描述。

pts

当前帧的时间戳。最多可接受三个参数。

第一个参数是时间戳的格式；默认为 flt，即以微秒精度的十进制数表示的秒数；hms 表示格式化为 [-]HH:MM:SS.mmm、精确到毫秒的时间戳；gmtime 表示将帧的时间戳格式化为 UTC 时间；localtime 表示将帧的时间戳格式化为本地时区时间。

第二个参数是加到时间戳上的偏移量。

若格式设置为 hms，可提供第三个参数 24HH，以 24 小时制（00-23）表示格式化时间戳中的小时部分。

若格式设置为 localtime 或 gmtime，可提供第三个参数：C 语言 strftime 函数的格式字符串。默认使用 YYYY-MM-DD HH:MM:SS 格式。

11.76.3 命令

此滤镜支持通过命令更改参数：

reinit

更改现有的滤镜参数。

参数的语法与滤镜调用时相同，例如

fontsize=56:fontcolor=green:text='Hello World'

搭配 sendcmd 的完整滤镜调用形式如下：

sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'

如果整个参数无法被解析或作为有效值应用，则滤镜将继续使用其现有参数。

以下选项同样支持作为命令使用：

x
y
alpha
fontsize
fontcolor
boxcolor
bordercolor
shadowcolor
box
boxw
boxh
boxborderw
line_spacing
text_align
shadowx
shadowy
borderw

11.76.4 示例

使用字体 FreeSerif 绘制 "Test Text"，可选参数均使用默认值。

drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"

使用大小为 24 的字体 FreeSerif，在位置 x=100、y=50（从屏幕左上角计算）绘制 ’Test Text’，文本为黄色，周围带有红色矩形。文本和矩形的不透明度均为 20%。
```
drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
          x=100: y=50: fontsize=24: fontcolor=yellow@0.2: box=1: boxcolor=red@0.2"
```

请注意，如果参数列表中不使用空格，则不必加双引号。

在视频帧中央显示文本：

drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"

在随机位置显示文本，每 30 秒切换到一个新位置：

drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)"

在视频帧的最后一行显示一行从右向左滑动的文本。假定文件 LONG_LINE 只包含不带换行符的单独一行。
```
drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
```
从帧底部之外开始显示文件 CREDITS 的内容，并向上滚动。
```
drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
```

在输入视频的中央绘制单个绿色字母 "g"。字形基线置于屏幕高度的一半处。

drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"

每 3 秒显示 1 秒的文本：

drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"

使用 fontconfig 设置字体。请注意，冒号需要转义。

drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'

绘制 "Test Text"，字体大小取决于视频的高度。

drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"

输出实时编码的日期（参见 C 语言 strftime 函数的文档）：
```
drawtext='fontfile=FreeSans.ttf:text=%{localtime\:%a %b %d %Y}'
```

显示淡入淡出（出现/消失）的文本：

#!/bin/sh
DS=1.0 # display start
DE=10.0 # display end
FID=1.5 # fade in duration
FOD=5 # fade out duration
ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 }"

水平对齐多段独立的文本。请注意，max_glyph_a 和 fontsize 的值都包含在 y 偏移量之中。

drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a

如果存在特殊的 lavf.image2dec.source_basename 元数据，则将其绘制到每一帧上；否则绘制字符串 "NA"。请注意，image2 demuxer 必须设置选项 -export_path_metadata 1，这些特殊的元数据字段才能供滤镜使用。
```
drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%{metadata\:lavf.image2dec.source_basename\:NA}':x=10:y=10"
```

关于 libfreetype 的更多信息，请查看：http://www.freetype.org/。

关于 fontconfig 的更多信息，请查看：http://freedesktop.org/software/fontconfig/fontconfig-user.html。

关于 libfribidi 的更多信息，请查看：http://fribidi.org/。

关于 libharfbuzz 的更多信息，请查看：https://github.com/harfbuzz/harfbuzz。

11.77 drawvg

通过执行以名为 VGS（Vector Graphics Script）的自定义语言编写的脚本，在视频帧上绘制矢量图形。

该语言的文档参见 (drawvg-reference)drawvg - Language Reference。带渲染示例的参考版本可在作者的站点查看。

图形使用 cario 2D graphics library 渲染。

要启用此滤镜的编译，需要在配置 FFmpeg 时加上 --enable-cairo。

11.77.1 参数

必须设置 script 或 file 其中之一。

s, script

用于绘制图形的脚本源代码。

file

要加载的脚本源代码所在文件的路径。

11.77.2 Pixel Formats

由于 Cairo 只支持 RGB 图像，如果输入视频是其他格式（例如 YUV 4:2:0），在执行脚本前会先把视频转换为与 Cairo 兼容的格式。之后，需要使用 format 滤镜或 -pix_fmt 选项，将其转换为输出所需的格式。

11.77.3 示例

绘制椭圆的轮廓。

ffmpeg -i input.webm \
    -vf 'drawvg=ellipse (w/2) (h/2) (w/3) (h/3) stroke' \
    -pix_fmt yuv420p \
    output.webm

在帧的正中央绘制一个旋转的正方形。

drawvg 使用的脚本位于文件 draw.vgs 中：

    translate (w/2) (h/2)
    rotate t
    rect -100 -100 200 200
    setcolor red@0.5
    fill

然后：

    ffmpeg -i input.webm -vf 'drawvg=file=draw.vgs,format=yuv420p' output.webm

11.78 edgedetect

检测并绘制边缘。此滤镜使用 Canny 边缘检测算法。

该滤镜接受以下选项：

low high

设置 Canny 阈值算法所用的低阈值和高阈值。

高阈值用于选取“强”边缘像素，随后通过 8 连通将其与低阈值选取的“弱”边缘像素相连。

低阈值和高阈值必须选自 [0,1] 范围，且 low 应小于或等于 high。

low 的默认值为 20/255，high 的默认值为 50/255。

mode

定义绘制模式。

‘wires’

在黑色背景上绘制白色/灰色线条。

‘colormix’

混合颜色以产生绘画/卡通效果。

‘canny’

对所有选中的通道应用 Canny 边缘检测。

默认值为 wires。

planes

选择要滤波的通道。默认情况下会滤波所有可用通道。

11.78.1 示例

使用自定义的滞后阈值参数进行标准边缘检测：
```
edgedetect=low=0.1:high=0.4
```
不做阈值处理的绘画效果：
```
edgedetect=mode=colormix:high=0
```

11.79 elbg

使用 ELBG（Enhanced LBG）算法应用色调分离效果。

对每一帧输入图像，滤镜会在给定码本长度（即输出中不同颜色的数量）的情况下，计算从输入到输出的最优映射。

此滤镜接受以下选项。

codebook_length, l

设置码本长度。该值必须是正整数，表示输出中不同颜色的数量。默认值为 256。

nb_steps, n

设置计算最优映射时应用的最大迭代次数。值越大，结果越好，但计算时间也越长。默认值为 1。

seed, s

设置随机种子，必须是 0 到 UINT32_MAX 之间的整数。如果未指定，或显式设置为 -1，滤镜会尽力使用一个较好的随机种子。

pal8

设置 pal8 输出 pixel format。码本长度大于 256 时此选项不起作用。默认禁用。

use_alpha

在量化计算中包含 alpha 值。可用于创建带有多级 alpha 平滑混合的调色板化输出图像（例如 PNG8）。

11.80 entropy

测量视频帧各颜色通道直方图的灰度熵。

它接受以下参数：

mode

可以是 normal 或 diff。默认是 normal。

diff 模式测量直方图差值的熵，即相邻直方图值之间的绝对差。

11.81 epx

应用为像素艺术设计的 EPX 放大滤镜。

它接受以下选项：

设置缩放倍数：2xEPX 用 2，3xEPX 用 3。默认是 3。

11.82 eq

设置亮度、对比度、饱和度以及近似的伽马调整。

该滤镜接受以下选项：

contrast

设置对比度表达式。值必须是 -1000.0 到 1000.0 范围内的浮点值。默认值为 "1"。

brightness

设置亮度表达式。值必须是 -1.0 到 1.0 范围内的浮点值。默认值为 "0"。

saturation

设置饱和度表达式。值必须是 0.0 到 3.0 范围内的浮点数。默认值为 "1"。

gamma

设置伽马表达式。值必须是 0.1 到 10.0 范围内的浮点数。默认值为 "1"。

gamma_r

设置红色的伽马表达式。值必须是 0.1 到 10.0 范围内的浮点数。默认值为 "1"。

gamma_g

设置绿色的伽马表达式。值必须是 0.1 到 10.0 范围内的浮点数。默认值为 "1"。

gamma_b

设置蓝色的伽马表达式。值必须是 0.1 到 10.0 范围内的浮点数。默认值为 "1"。

gamma_weight

设置伽马权重表达式。可用于减弱高伽马值对明亮图像区域的影响，例如防止其被过度放大而变成纯白。值必须是 0.0 到 1.0 范围内的浮点数。0.0 会将伽马校正完全关闭，1.0 则保留其全部强度。默认是 "1"。

eval

设置何时对亮度、对比度、饱和度和伽马表达式求值。

可接受的值有：

‘init’

仅在滤镜初始化期间或处理命令时对表达式求值一次。

‘frame’

对每个输入帧都求值表达式

默认值为 ‘init’。

这些表达式接受以下参数：

输入帧的帧号，从 0 开始计数

pos

输入文件中对应数据包的字节位置，如果未指定则为 NAN；已弃用，请勿使用

输入视频的帧率，如果输入帧率未知则为 NAN

以秒为单位表示的时间戳；如果输入时间戳未知则为 NAN

11.82.1 命令

此滤镜支持以下命令：

contrast

设置对比度表达式。

brightness

设置亮度表达式。

saturation

设置饱和度表达式。

gamma

设置伽马表达式。

gamma_r

设置 gamma_r 表达式。

gamma_g

设置 gamma_g 表达式。

gamma_b

设置 gamma_b 表达式。

gamma_weight

设置 gamma_weight 表达式。

该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.83 erosion

对视频应用腐蚀（erosion）效果。

此滤镜用局部（3x3）最小值替换像素。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量，默认值为 65535。若为 0，则该平面将保持不变。

coordinates

指定要参考的像素的标志。默认是 255，即使用全部八个像素。

标志与局部 3x3 坐标的对应关系如下：

1 2 3 4 5 6 7 8

11.83.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.84 estdif

对输入视频去隔行（"estdif" 是 "Edge Slope Tracing Deinterlacing Filter" 的缩写）。

这是一个仅在空间维度上工作的滤镜，使用边缘斜率追踪算法插值缺失的行。它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

frame

每个帧输出一帧。

field

每个场输出一帧。

默认值是 field。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

tff

假定顶场在前。

bff

假定底场在前。

auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

all

对所有帧去隔行。

interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

rslope

指定边缘斜率追踪的搜索半径。默认值是 1。允许范围是 1 到 15。

redge

指定最佳边缘匹配的搜索半径。默认值是 2。允许范围是 0 到 15。

ecost

指定边缘匹配的边缘代价。默认值是 2。允许范围是 0 到 50。

mcost

指定边缘匹配的中间代价。默认值是 1。允许范围是 0 到 50。

dcost

指定边缘匹配的距离代价。默认值是 1。允许范围是 0 到 50。

interp

指定使用的插值方式。默认是 4 点插值。它接受以下值之一：

两点插值。

四点插值。

六点插值。

11.84.1 命令

此滤镜支持与选项相同的命令。

11.85 exposure

调整视频流的曝光。

该滤镜接受以下选项：

exposure

以 EV 为单位设置曝光校正值。允许范围是 -3.0 到 3.0 EV。默认值是 0 EV。

black

设置黑位校正值。允许范围是 -1.0 到 1.0。默认值是 0。

11.85.1 命令

此滤镜支持与选项相同的命令。

11.86 extractplanes

从输入视频流中提取颜色通道分量，输出为独立的灰度视频流。

该滤镜接受以下选项：

planes

设置要提取的通道。

planes 可用的值有：

‘y’ ‘u’ ‘v’ ‘a’ ‘r’ ‘g’ ‘b’

选择输入中不可用的通道会导致错误。也就是说，不能同时选择 r、g、b 通道和 y、u、v 通道。

11.86.1 示例

从输入视频帧中提取亮度、u 和 v 颜色通道分量，输出为 3 个灰度视频：

ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi

11.87 fade

对输入视频应用淡入/淡出效果。

它接受以下参数：

type, t

效果类型可以是淡入的 "in"，也可以是淡出的 "out"。默认是 in。

start_frame, s

指定开始应用淡化效果的帧编号。默认是 0。

nb_frames, n

淡化效果持续的帧数。淡入效果结束时，输出视频将与输入视频具有相同的强度。淡出过渡结束时，输出视频将被填充为所选颜色。默认是 25。

alpha

如果设为 1，且输入存在 alpha 通道，则只淡化 alpha 通道。默认值是 0。

start_time, st

以秒指定开始应用淡化效果的帧的时间戳。如果同时指定了 start_frame 和 start_time，淡化将从较晚的一个开始。默认是 0。

duration, d

淡化效果必须持续的秒数。淡入效果结束时输出视频将与输入视频具有相同的强度，淡出过渡结束时输出视频将被填充为所选颜色。如果同时指定了 duration 和 nb_frames，则使用 duration。默认是 0（默认使用 nb_frames）。

color, c

指定淡化的颜色。默认是 "black"。

11.87.1 示例

对视频的前 30 帧做淡入：
```
fade=in:0:30
```

上面的命令等价于：

    fade=t=in:s=0:n=30

对一个 200 帧视频的最后 45 帧做淡出：

fade=out:155:45
fade=type=out:start_frame=155:nb_frames=45

对一个 1000 帧视频的前 25 帧做淡入，最后 25 帧做淡出：
```
fade=in:0:25, fade=out:975:25
```
让前 5 帧变为黄色，然后在第 5-24 帧淡入：
```
fade=in:5:20:color=yellow
```
在视频的前 25 帧对 alpha 做淡入：
```
fade=in:0:25:alpha=1
```
让前 5.5 秒变黑，然后用 0.5 秒淡入：
```
fade=t=in:st=5.5:d=0.5
```

11.88 feedback

应用反馈视频滤镜。

此滤镜将裁剪后的输入帧传给第 2 个输出。从那里可以用其他视频滤镜对其滤波。当滤镜从第 2 个输入收到帧后，该帧会合成到第 1 个输入的原始帧之上，并传给第 1 个输出。

典型用法是只对帧的一部分滤波。

该滤镜接受以下选项：

x y

设置裁剪区域的左上角位置。

w h

设置裁剪区域的大小。

11.88.1 示例

用 gblur 滤镜只对视频帧左上角大小为 100x100 的矩形部分做模糊。
```
[in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]gblur=8[blurin]
```

用 drawbox 滤镜在视频帧左上角大小为 100x100 的部分画一个黑色方框。

[in][blurin]feedback=x=0:y=0:w=100:h=100[out][blurout];[blurout]drawbox=x=0:y=0:w=100:h=100:t=100[blurin]

用 pixelize 滤镜对视频帧中大小为 100x100 的矩形部分做马赛克化。

[in][blurin]feedback=x=320:y=240:w=100:h=100[out][blurout];[blurout]pixelize[blurin]

11.89 fftdnoiz

使用 3D FFT（频域滤波）对帧去噪。

该滤镜接受以下选项：

sigma

设置噪声 sigma 常量。此值决定降噪强度。默认值是 1。允许范围是 0 到 30。使用很高的 sigma 配合较低的重叠度可能会产生块状伪影。

amount

设置降噪量。默认情况下会降低所有检测到的噪声。默认值是 1。允许范围是 0 到 1。

block

以像素为单位设置块的大小。默认是 32，可设置为 8 到 256。

overlap

设置块的重叠度。默认是 0.5。允许范围是 0.2 到 0.8。

method

设置降噪方法。默认是 wiener，也可以是 hard。

设置用于降噪的前序帧数量。默认为 0。

设置用于降噪的后续帧数量。默认为 0。

planes

设置要滤波的通道，默认是除 alpha 之外的所有可用通道。

11.90 fftfilt

对频域中的采样值应用任意表达式。

dc_Y

调整图像亮度通道的 dc 值（增益）。此滤镜接受 0 到 1000 范围内的整数值。默认值设为 0。

dc_U

调整图像第 1 色度通道的 dc 值（增益）。此滤镜接受 0 到 1000 范围内的整数值。默认值设为 0。

dc_V

调整图像第 2 色度通道的 dc 值（增益）。此滤镜接受 0 到 1000 范围内的整数值。默认值设为 0。

weight_Y

设置亮度通道的频域权重表达式。

weight_U

设置第 1 色度通道的频域权重表达式。

weight_V

设置第 2 色度通道的频域权重表达式。

eval

设置何时对表达式求值。

可接受的值有：

‘init’

仅在滤镜初始化期间对表达式求值一次。

‘frame’

对每个输入帧都求值表达式。

默认值为 ‘init’。

此滤镜接受以下变量：

X Y

当前采样点的坐标。

W H

图像的宽度和高度。

输入帧的编号，从 0 开始。

WS HS

用于水平和垂直处理的 FFT 数组大小。

11.90.1 示例

高通：

fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'

低通：

fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'

锐化：

fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'

模糊：

fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'

11.91 field

使用跨距运算从隔行图像中提取单个场，以避免浪费 CPU 时间。输出帧会被标记为非隔行。

该滤镜接受以下选项：

type

指定提取顶场（值为 0 或 top）还是底场（值为 1 或 bottom）。

11.92 fieldhint

按提示文件中以数字形式给出的信息，从前后帧复制顶场和底场，从而创建新帧。

hint

设置包含提示的文件：绝对/相对帧编号。

片段中每一帧都必须对应一行。每行必须包含以逗号分隔的两个数字，后面可以选择性地跟 - 或 +。文件中每行给出的数字，在 absolute 模式下不能超出 [N-1,N+1]（N 为当前帧编号）范围，在 relative 模式下不能超出 [-1, 1] 范围。第一个数字表示从哪一帧取顶场，第二个数字表示从哪一帧取底场。

如果可选地跟 +，输出帧将被标记为隔行；如果跟 -，输出帧将被标记为逐行；否则将与输入帧标记相同。如果可选地跟 t，输出帧只使用顶场；如果是 b，则只使用底场。如果某行以 # 或 ; 开头，该行会被跳过。

mode

可以是 absolute、relative 或 pattern。默认是 absolute。pattern 模式与 relative 模式相同，只是在文件最后一条记录处，如果还有更多帧需要处理但 hint 文件已经用完，则会回到开头继续读取。

relative 模式下 hint 文件开头几行的示例：

0,0 - # first frame
1,0 - # second frame, use third's frame top field and second's frame bottom field
1,0 - # third frame, use fourth's frame top field and third's frame bottom field
1,0 -
0,0 -
0,0 -
1,0 -
1,0 -
1,0 -
0,0 -
0,0 -
1,0 -
1,0 -
1,0 -
0,0 -

11.93 fieldmatch

用于逆电视电影转换（inverse telecine）的场匹配滤镜。目的是从经过电视电影转换的流中重建逐行帧。此滤镜不会丢弃重复帧，因此要实现完整的逆电视电影转换，需要在 filtergraph 中在 fieldmatch 之后接上像 decimate 这样的抽取滤镜。

之所以将场匹配与抽取分离，主要是为了便于在两者之间插入一个去隔行滤镜作为回退方案。如果片源中混有电视电影转换内容和真正的隔行内容，fieldmatch 将无法匹配隔行部分的场。但这些残留的梳齿帧会被标记为隔行，因此可以在抽取之前由 yadif 之类的后续滤镜去隔行。

除了各种配置选项之外，fieldmatch 还可以接受一个通过 ppsrc 选项启用的可选第 2 输入流。启用后，帧的重建将基于这个第 2 输入流的场和帧来完成。这样可以先预处理第 1 输入，以帮助滤镜的各种算法工作，同时（在场匹配正确的前提下）保持输出无损。通常，一个能感知场的降噪器，或亮度/对比度调整会有所帮助。

请注意，此滤镜使用的算法与 TIVTC/TFM（AviSynth 项目）以及 VIVTC/VFM（VapourSynth 项目）相同。后者是 TFM 的轻量克隆，fieldmatch 正是基于它实现的。虽然语义和用法非常接近，但部分行为和选项名称可能有所不同。

decimate 滤镜目前只能处理恒定帧率的输入。如果你的输入混有电视电影转换内容（30fps）和帧率较低（如 24fps）的逐行内容，可使用下面的滤镜链生成所需的恒定帧率流：dejudder,fps=30000/1001,fieldmatch,decimate。

该滤镜接受以下选项：

order

指定输入流所假定的场顺序。可用的值有：

‘auto’

自动检测奇偶性（使用 FFmpeg 内部的奇偶性值）。

‘bff’

假定底场在前。

‘tff’

假定顶场在前。

请注意，有时并不建议信任流所宣称的奇偶性。

默认值是 auto。

mode

设置要使用的匹配模式或策略。pc 模式最为安全，因为它在可能的情况下不会冒因重复帧而产生卡顿的风险，但如果存在不良剪辑点或混合场，即使实际存在良好的匹配，它也可能最终输出梳齿帧。另一方面，pcn_ub 模式在产生卡顿方面风险最高，但只要存在良好的帧，几乎总能找到。其他值在产生卡顿、重复帧的风险，以及在存在不良剪辑点、孤立场、混合场等区段中找到良好匹配的能力方面，都介于 pc 和 pcn_ub 之间。

关于 p/c/n/u/b 的更多细节，请参见 p/c/n/u/b meaning 一节。

可用值如下：

‘pc’

双向匹配（p/c）

‘pc_n’

双向匹配，若仍有梳齿则尝试第 3 次匹配（p/c + n）

‘pc_u’

双向匹配，若仍有梳齿则尝试（相同顺序的）第 3 次匹配（p/c + u）

‘pc_n_ub’

双向匹配，若仍有梳齿则尝试第 3 次匹配，若依然有梳齿则再尝试第 4/5 次匹配（p/c + n + u/b）

‘pcn’

三向匹配（p/c/n）

‘pcn_ub’

三向匹配，若最初的 3 次匹配都被判定为梳齿，则尝试第 4/5 次匹配（p/c/n + u/b）

末尾括号中标出的是在假定 order=tff（且 field 为 auto 或 top）时，该模式所使用的匹配组合。

就速度而言，pc 模式迄今为止最快，pcn_ub 最慢。

默认值是 pc_n。

ppsrc

将主输入流标记为已预处理的输入，并启用第二个输入流作为提取场的干净来源。更多细节请参见滤镜的介绍部分。它类似于 VFM/TFM 的 clip2 功能。

默认值是 0（禁用）。

field

设置用于匹配的来源场。除非在使用 order 相同的值时遇到匹配失败，否则建议将其设置为与 order 相同的值。在某些情况下，改变用于匹配的场会对匹配性能产生较大影响。可用的值有：

‘auto’

自动（与 order 相同的值）。

‘bottom’

从底场匹配。

‘top’

从顶场匹配。

默认值是 auto。

mchroma

设置匹配比较时是否考虑色度。大多数情况下建议保持启用。只有当片源存在严重的色度问题（如明显的彩虹纹或其他伪影）时，才应将其设为 0。将其设为 0 也可以以牺牲一定精度为代价来提升速度。

默认值是 1。

y0 y1

这两个值定义了一个排除带，将 y0 与 y1 之间的行排除在场匹配判定之外。排除带可用于忽略字幕、Logo 或其他可能干扰匹配的内容。y0 设置起始扫描行，y1 设置结束扫描行；y0 与 y1 之间（包括 y0 和 y1 本身）的所有行都会被忽略。将 y0 和 y1 设为相同的值可禁用此功能。y0 和 y1 的默认值是 0。

scthresh

以亮度通道最大变化量的百分比形式设置场景切换检测阈值。较好的值在 [8.0, 14.0] 范围内。场景切换检测只有在 combmatch=sc 时才有意义。scthresh 的取值范围是 [0.0, 100.0]。

默认值是 12.0。

combmatch

当 combatch 不为 none 时，fieldmatch 在决定最终采用哪个匹配时会考虑各匹配的梳齿分数。可用的值有：

‘none’

不基于梳齿分数决定最终匹配。

‘sc’

仅在检测到场景切换时才使用梳齿分数。

‘full’

始终使用梳齿分数。

默认是 sc。

combdbg

强制 fieldmatch 为特定匹配计算梳齿指标并打印出来。此设置在 TFM/VFM 术语中称为 micout。可用的值有：

‘none’

不强制计算。

‘pcn’

强制计算 p/c/n。

‘pcnub’

强制计算 p/c/n/u/b。

默认值是 none。

cthresh

这是用于梳齿帧检测的区域梳齿阈值。它本质上控制梳齿现象必须达到多“强”或多“明显”才会被检测到。值越大，梳齿必须越明显才会被判定；值越小，梳齿即使不太明显或不太强也会被检测到。有效设置范围是 -1（每个像素都会被判定为梳齿）到 255（没有像素会被判定为梳齿）。这本质上是一个像素差值。较好的范围是 [8, 12]。

默认值是 9。

chroma

设置在梳齿帧判定中是否考虑色度。只有当片源存在色度问题（如彩虹纹等）导致启用色度时梳齿帧检测出问题，才应禁用此项。实际上，使用 chroma=0 通常更可靠，除非片源中存在仅色度上的梳齿。

默认值为 0。

blockx blocky

分别设置梳齿帧检测所用窗口的 x 轴和 y 轴大小。这与判定一帧为梳齿所需、在该窗口区域内检测到 combpel 个像素的大小有关。更多信息请参见 combpel 参数说明。可取的值为从 4 开始、直到 512 的任意 2 的幂。

默认值是 16。

combpel

判定一帧为梳齿所需的、在任意一个 blocky × blockx 大小的块内出现的梳齿像素数量。cthresh 控制梳齿必须多“明显”，而此设置控制在帧上任意局部区域（由 blockx 和 blocky 设置定义的窗口）内梳齿必须“有多少”。最小值是 0，最大值是 blocky x blockx（此时永远不会有帧被判定为梳齿）。此设置在 TFM/VFM 术语中称为 MI。

默认值是 80。

11.93.1 p/c/n/u/b 含义

11.93.1.1 p/c/n

假设有如下经过电视电影转换的流：

Top fields:     1 2 2 3 4
Bottom fields:  1 2 3 4 4

这些数字对应各场所关联的逐行帧。这里，前两帧是逐行的，第 3、第 4 帧存在梳齿，以此类推。

当 fieldmatch 配置为从底场进行匹配（field=bottom）时，该输入流会按如下方式转换：

Input stream:
                T     1 2 2 3 4
                B     1 2 3 4 4   <-- matching reference

Matches:              c c n n c

Output stream:
                T     1 2 3 4 4
                B     1 2 3 4 4

从场匹配的结果可以看出，有些帧被重复了。要完成完整的逆电视电影转换，需要在此操作之后使用抽取滤镜。例如可参见 decimate 滤镜。

现在对同一操作改为从顶场进行匹配（field=top），效果如下：

Input stream:
                T     1 2 2 3 4   <-- matching reference
                B     1 2 3 4 4

Matches:              c c p p c

Output stream:
                T     1 2 2 3 4
                B     1 2 2 3 4

从这些示例可以看出 p、c、n 分别是什么含义；简单来说，它们指向场奇偶性相反的帧和场：

p 匹配前一帧中场奇偶性相反的场
c 匹配当前帧中场奇偶性相反的场
n 匹配后一帧中场奇偶性相反的场

11.93.1.2 u/b

u 和 b 匹配有些特殊，它们是根据相反的奇偶性标志进行匹配的。在下面的示例中，假设当前正在匹配第 2 帧（Top:2，bottom:2）。根据匹配结果，会在每个匹配到的场的上下各放置一个 ’x’。

底场匹配（field=bottom）时：

Match:           c         p           n          b          u

                 x       x               x        x          x
  Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
  Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
                 x         x           x        x              x

Output frames:
                 2          1          2          2          2
                 2          2          2          1          3

顶场匹配（field=top）时：

Match:           c         p           n          b          u

                 x         x           x        x              x
  Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
  Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
                 x       x               x        x          x

Output frames:
                 2          2          2          1          2
                 2          1          3          2          2

11.93.2 示例

顶场优先且经过电视电影转换的流的简单 IVTC：

fieldmatch=order=tff:combmatch=none, decimate

高级 IVTC，对仍然存在梳齿的帧回退使用 yadif：

fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate

11.94 fieldorder

变换输入视频的场序。

它接受以下参数：

order

输出的场序。有效值为表示顶场优先的 tff，或表示底场优先的 bff。

默认值是 ‘tff’。

该变换通过将画面内容整体上移或下移一行、并用合适的画面内容填充剩余的一行来完成。这种方法与大多数广播级场序转换器一致。

如果输入视频没有被标记为隔行，或者已经被标记为所需的输出场序，则此滤镜不会更改输入视频。

在与底场优先的 PAL DV 素材相互转换时非常有用。

例如：

ffmpeg -i in.vob -vf "fieldorder=bff" out.dv

11.95 fillborders

在不改变视频流尺寸的前提下填充输入视频的边框。有时视频四周边缘会有一些无用数据，而你可能不想为了让尺寸是某个数的倍数而裁剪输入视频。

此滤镜接受以下选项：

left

从左边框填充的像素数。

right

从右边框填充的像素数。

top

从上边框填充的像素数。

bottom

从下边框填充的像素数。

mode

设置填充模式。

可接受的值有：

‘smear’

使用最外层像素填充

‘mirror’

使用镜像（半采样对称）填充像素

‘fixed’

使用固定值填充像素

‘reflect’

使用反射（全采样对称）填充像素

‘wrap’

使用环绕方式填充像素

‘fade’

将像素渐变为固定值

‘margins’

使用边框附近像素的加权平均值填充上下边框的像素

默认值是 smear。

color

设置 fixed 或 fade 模式下像素的颜色。默认值是 black。

11.95.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.96 find_rect

在输入视频中查找矩形对象。

要查找的对象必须通过 object 选项指定为一张 gray8 图像。

对每个可能的匹配都会计算一个分数。如果分数达到指定的阈值，就认为已找到该对象。

如果输入视频中包含该对象的多个实例，此滤镜只会找到其中一个。

找到对象后，会在匹配的帧上设置以下元数据条目：

lavfi.rect.w

对象的宽度

lavfi.rect.h

对象的高度

lavfi.rect.x

对象的 x 坐标

lavfi.rect.y

对象的 y 坐标

lavfi.rect.score

找到的对象的匹配分数

它接受以下选项：

object

对象图像的文件路径，需要是 gray8 格式。

threshold

检测阈值，用 0 到 1 之间的小数表示。

阈值为 0.01 意味着只有完全匹配才算，阈值为 0.99 则意味着几乎所有内容都会匹配。

默认值是 0.5。

mipmaps

mipmap 的数量，默认值是 3。

xmin, ymin, xmax, ymax

指定要搜索的矩形范围。

discard

丢弃未检测到对象的帧。默认是禁用。

11.96.1 示例

使用 ffmpeg，用指定的图像覆盖某个视频中的矩形对象：

ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv

使用 ffprobe 查找每一帧中对象的位置，并将其写入日志文件：

ffprobe -f lavfi movie=test.mp4,find_rect=object=object.pgm:threshold=0.3 \
  -show_entries frame=pkt_pts_time:frame_tags=lavfi.rect.x,lavfi.rect.y \
  -of csv -o find_rect.csv

11.97 floodfill

将像素分量值相同的区域泛洪填充为其他值。

它接受以下选项：

设置像素的 x 坐标。

设置像素的 y 坐标。

设置源 #0 分量的值。

设置源 #1 分量的值。

设置源 #2 分量的值。

设置源 #3 分量的值。

设置目标 #0 分量的值。

设置目标 #1 分量的值。

设置目标 #2 分量的值。

设置目标 #3 分量的值。

11.98 format

将输入视频转换为指定的某一种 pixel format。Libavfilter 会尝试挑选一个适合作为下一个滤镜输入的格式。

它接受以下参数：

pix_fmts

以 ’|’ 分隔的 pixel format 名称列表，例如 "pix_fmts=yuv420p|monow|rgb24"。

color_spaces

以 ’|’ 分隔的色彩空间名称列表，例如 "color_spaces=bt709|bt470bg|bt2020nc"。

color_ranges

以 ’|’ 分隔的色彩范围名称列表，例如 "color_ranges=tv|pc"。

alpha_modes

以 ’|’ 分隔的色彩范围名称列表，例如 "alpha_modes=straight|premultiplied"。

11.98.1 示例

将输入视频转换为 yuv420p 格式
```
format=pix_fmts=yuv420p
```

将输入视频转换为列表中的任意一种格式

    format=pix_fmts=yuv420p|yuv444p|yuv410p

11.99 fps

通过在必要时复制或丢弃帧，将视频转换为指定的固定帧率。

它接受以下参数：

fps

期望的输出帧率。接受包含以下常量的表达式：

‘source_fps’

输入的帧率

‘ntsc’

NTSC 帧率为 30000/1001

‘pal’

PAL 帧率为 25.0

‘film’

电影帧率为 24.0

‘ntsc_film’

NTSC 电影帧率为 24000/1001

默认值是 25。

start_time

假定第一个 PTS 应为给定值（以秒为单位）。这样可以在流的开头进行填充或截取。默认情况下，不对第一帧的预期 PTS 做任何假设，因此不会进行填充或截取。例如，如果视频流是在音频流之后才开始的，可以将此值设为 0，用第一帧的重复副本填充开头；也可以用它截取掉 PTS 为负值的帧。

round

时间戳（PTS）舍入方法。

可接受的值有：

zero

向 0 舍入

inf

向远离 0 的方向舍入

down

向负无穷舍入

向正无穷舍入

near

舍入到最接近的值

默认值是 near。

eof_action

读取最后一帧时执行的动作。

可接受的值有：

round

使用与其他帧相同的时间戳舍入方法。

pass

如果尚未到达输入的时长，则原样传递最后一帧。

默认值是 round。

也可以将这些选项指定为一个扁平字符串：fps[:start_time[:round]]。

另请参见 setpts 滤镜。

11.99.1 示例

将 fps 设置为 25 的典型用法：
```
fps=fps=25
```
使用缩写并将舍入方法设为“舍入到最接近的值”，将 fps 设为 24：
```
fps=fps=film:round=near
```

11.100 framepack

将两个不同的视频流打包为一个立体视频（stereoscopic video），并在受支持的 codec 上设置相应的元数据。两个视图应具有相同的尺寸和帧率，处理会在较短的视频结束时停止。请注意，可以方便地使用 scale 和 fps 滤镜调整视图的属性。

它接受以下参数：

format

期望的打包格式。支持的值有：

sbs

两个视图并排放置（默认）。

tab

两个视图上下叠放。

lines

两个视图按行打包。

columns

两个视图按列打包。

frameseq

两个视图在时间上交织排列。

一些示例：

# 将左右视图转换为帧序列视频
ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT

# 将视图转换为与输入相同输出分辨率的并排（side-by-side）视频
ffmpeg -i LEFT -i RIGHT -filter_complex [0:v]scale=w=iw/2[left],[1:v]scale=w=iw/2[right],[left][right]framepack=sbs OUTPUT

11.101 framerate

通过从源帧插值生成新的视频输出帧来改变帧率。

此滤镜并非设计用于正确处理隔行素材。如果想更改隔行素材的帧率，则必须在此滤镜之前先去隔行，并在此滤镜之后重新隔行。

接受的选项说明如下。

fps

指定输出的每秒帧数。此选项也可以只指定一个值。默认值是 50。

interp_start

指定一个范围的起点，在此范围内输出帧将作为两帧的线性插值生成。范围是 [0-255]，默认值是 15。

interp_end

指定一个范围的终点，在此范围内输出帧将作为两帧的线性插值生成。范围是 [0-255]，默认值是 240。

scene

以 0 到 100 之间的值指定判定场景切换的级别；较低的值表示当前帧引入新场景的可能性较低，较高的值则表示当前帧更可能是新场景。默认值是 8.2。

flags

指定影响滤镜处理过程的标志。

flags 可用的值是：

scene_change_detect, scd

使用 scene 选项的值启用场景切换检测。此标志默认启用。

11.102 frc_amf

使用 AMD Advanced Media Framework 库提供的帧率转换器（Frame Rate Converter，FRC）进行硬件加速，将帧率提高一倍。

该滤镜接受以下选项：

engine_type

指定用于运行着色器（shader）的引擎。

‘dx11’

DirectX 11。

‘dx12’

DirectX 12（默认值）。

enable

布尔值：启用/禁用 FRC。这是一个动态值，可以在运行时更改而无需重新初始化滤镜。（默认值：启用）。

fallback_mode

插值置信度较低时的回退行为。

‘duplicate’

复制帧。

‘blend’

将两帧混合在一起（默认值）。

indicator

布尔值：在视频左上角显示 FRC 指示方块（默认值：禁用）。

profile

分层运动搜索的级别。

‘low’

分层运动搜索的级别较少。仅推荐用于极低的分辨率。

‘high’

推荐用于最高到 1440p 的任意分辨率。（默认值）

‘super’

分层运动搜索的级别较多。推荐用于 1440p 及以上的分辨率。

mv_search_mode

运动搜索的性能模式。

‘native’

在源图像的完整分辨率上进行运动搜索。

‘performance’

在缩小后的源图像上进行运动搜索。推荐在 APU 或低端 GPU 上使用以获得更好的性能。

use_future_frame

布尔值：启用对未来帧的依赖，以延迟为代价提升质量（默认值：启用）。

11.103 framestep

每 N 帧选择一帧。

此滤镜接受以下选项：

step

每隔 step 帧选择一帧。允许的值为大于 0 的正整数。默认值是 1。

11.104 freezedetect

检测静止的视频。

当检测到输入视频在指定时长内内容没有明显变化时，此滤镜会记录一条消息并设置帧元数据。视频静止检测会计算视频帧所有分量的平均绝对差值，并将其与噪声下限进行比较。

打印出的时间和时长均以秒为单位表示。lavfi.freezedetect.freeze_start 元数据键会设置在时间戳等于或超过检测时长的第一帧上，其值为静止开始的第一帧的时间戳。lavfi.freezedetect.freeze_duration 和 lavfi.freezedetect.freeze_end 元数据键会设置在静止结束后的第一帧上。

该滤镜接受以下选项：

noise, n

设置噪声容差。可以用 dB 为单位指定（在指定值后附加 "dB"），也可以指定为 0 到 1 之间的差值比率。默认值是 -60dB，即 0.001。

duration, d

设置触发通知前的静止时长（默认值是 2 秒）。

11.105 freezeframes

冻结视频帧。

此滤镜使用第 2 个输入的帧来冻结视频帧。

该滤镜接受以下选项：

first

设置开始冻结的起始帧编号。

last

设置结束冻结的末尾帧编号。

replace

设置用来替换被替换帧的、第 2 个输入中的帧编号。

11.106 frei0r

对输入视频应用一个 frei0r 特效。

要启用此滤镜的编译，需要安装 frei0r 头文件，并使用 --enable-frei0r 来配置 FFmpeg。

它接受以下参数：

filter_name

要加载的 frei0r 特效的名称。如果定义了环境变量 FREI0R_PATH，就会在 FREI0R_PATH 中以冒号分隔列出的各个目录中搜索该 frei0r 特效。否则会按以下顺序搜索标准的 frei0r 路径：HOME/.frei0r-1/lib/、/usr/local/lib/frei0r-1/、/usr/lib/frei0r-1/。

filter_params

以 ’|’ 分隔的、传给 frei0r 特效的参数列表。

frei0r 特效的参数可以是布尔值（其值为 "y" 或 "n"）、double 值、颜色（以 R/G/B 形式指定，其中 R、G、B 是 0.0 到 1.0 之间（含）的浮点数），或按照 ffmpeg-utils 手册中「Color」一节所规定的颜色描述、位置（以 X/Y 形式指定，其中 X 和 Y 为浮点数），和/或一个字符串。

参数的数量和类型取决于所加载的特效。如果没有指定某个特效参数，就会使用默认值。

11.106.1 示例

应用 distort0r 特效，设置前两个 double 参数：
```
frei0r=filter_name=distort0r:filter_params=0.5|0.01
```

应用 colordistance 特效，将颜色作为第一个参数：

frei0r=colordistance:0.2/0.3/0.4
frei0r=colordistance:violet
frei0r=colordistance:0x112233

应用 perspective 特效，指定图像左上角和右上角的位置：
```
frei0r=perspective:0.2/0.2|0.8/0.2
```

更多信息请参见 http://frei0r.dyne.org

11.106.2 命令

此滤镜支持将 filter_params 选项用作命令。

11.107 fspp

应用快速简易的后处理。它是 spp 的更快版本。

它将 (I)DCT 拆分为水平/垂直两个处理阶段。与简易后处理滤镜不同，其中一个阶段是按块而不是按像素执行一次，这样可以大幅提高速度。

该滤镜接受以下选项：

quality

设置质量。此选项定义用于平均化的级别数。接受 4 到 5 范围内的整数。默认值是 4。

强制使用固定的量化参数。接受 0 到 63 范围内的整数。如果未设置，此滤镜会使用视频流中的 QP（如果可用）。

strength

设置滤镜强度。接受 -15 到 32 范围内的整数。值越低细节越多，但伪影也越多；值越高图像越平滑，但也越模糊。默认值是 0 − PSNR 最优。

use_bframe_qp

设为 1 时启用使用 B 帧的 QP。使用此选项可能导致闪烁，因为 B 帧的 QP 通常更大。默认值是 0（未启用）。

11.108 fsync

根据来自文件的外部映射同步视频帧。

对于映射文件中给出的每个输入 PTS，会按需丢弃或创建帧，以重现映射文件中给出的输出帧序列。

此滤镜适用于重现由 fps 滤镜进行帧率转换后的输出帧（该输出帧序列已通过 ffmpeg 的 -stats_mux_pre 选项记录到映射文件中），并对相应的帧做进一步处理，例如质量比较。

映射文件的每一行必须包含每个输入帧对应的三项内容：输入 PTS（十进制）、输出 PTS（十进制）和输出 TIMEBASE（十进制/十进制），以空格分隔。此文件格式对应于 -stats_mux_pre_fmt="{ptsi} {pts} {tb}" 的输出。

此滤镜假定映射文件已按输入 PTS 升序排序。

该滤镜接受以下选项：

file, f

要使用的映射文件的文件名。

示例：

# 将视频转换为 25 fps，并以此滤镜的默认格式记录一个 MAP_FILE 文件
ffmpeg -i INPUT -vf fps=fps=25 -stats_mux_pre MAP_FILE -stats_mux_pre_fmt "{ptsi} {pts} {tb}" OUTPUT

# 按输入 PTS 升序对 MAP_FILE 排序
sort -n MAP_FILE

# 使用上面的 INPUT、OUTPUT 和 MAP_FILE，通过 SSIM 比较 INPUT 和 OUTPUT 中对应的帧
ffmpeg -i INPUT -i OUTPUT -filter_complex '[0:v]fsync=file=MAP_FILE[ref];[1:v][ref]ssim' -f null -

11.109 gblur

应用高斯模糊滤镜。

该滤镜接受以下选项：

sigma

设置水平方向的 sigma，即高斯模糊的标准差。默认值是 0.5。

steps

设置高斯近似的步数。默认值是 1。

planes

设置要过滤的平面。默认情况下会过滤所有平面。

sigmaV

设置垂直方向的 sigma，如果为负值，则与 sigma 相同。默认值是 -1。

11.109.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.110 geq

对每个像素应用通用方程。

该滤镜接受以下选项：

lum_expr, lum

设置亮度（luma）表达式。

cb_expr, cb

设置蓝色色度（chrominance blue）表达式。

cr_expr, cr

设置红色色度（chrominance red）表达式。

alpha_expr, a

设置 alpha 表达式。

red_expr, r

设置红色表达式。

green_expr, g

设置绿色表达式。

blue_expr, b

设置蓝色表达式。

色彩空间会根据所指定的选项来选择。如果指定了 lum_expr、cb_expr 或 cr_expr 中的任意一个选项，此滤镜会自动选择 YCbCr 色彩空间。如果指定了 red_expr、green_expr 或 blue_expr 中的任意一个选项，则会选择 RGB 色彩空间。

如果色度表达式中的一个未定义，就会回退使用另一个。如果没有指定 alpha 表达式，则会计算为不透明值。如果两个色度表达式都未指定，则会计算为亮度表达式的值。

这些表达式可以使用以下变量和函数：

已处理帧的序号，从 0 开始。

X Y

当前采样点的坐标。

W H

图像的宽度和高度。

SW SH

取决于当前处理的平面的宽度和高度缩放比例。它是对应亮度平面的像素数与当前平面像素数之比。例如对于 YUV4:2:0，亮度平面的值为 1,1，色度平面的值为 0.5,0.5。

当前帧的时间，以秒为单位表示。

p(x, y)

返回当前平面上位置 (x,y) 处像素的值。

lum(x, y)

返回亮度平面上位置 (x,y) 处像素的值。

cb(x, y)

返回蓝色差色度平面上位置 (x,y) 处像素的值。如果不存在该平面，则返回 0。

cr(x, y)

返回红色差色度平面上位置 (x,y) 处像素的值。如果不存在该平面，则返回 0。

r(x, y) g(x, y) b(x, y)

返回红/绿/蓝分量上位置 (x,y) 处像素的值。如果不存在该分量，则返回 0。

alpha(x, y)

返回 alpha 平面上位置 (x,y) 处像素的值。如果不存在该平面，则返回 0。

psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)

(0,0) 到 (x,y) 矩形范围内采样值的总和，通过它可以获得矩形范围内采样值的总和。请参见不带 sum 后缀的函数。

interpolation

设置以下插值方法之一：

nearest, n bilinear, b

默认值是 bilinear。

对于这些函数，如果 x 和 y 超出区域范围，值会自动裁剪到最接近的边缘。

请注意，此滤镜可以使用多线程，在这种情况下每个条带都会有自己的表达式状态。如果你的表达式依赖于之前的状态，只想使用单一的表达式状态，则应将滤镜线程数限制为 1。

11.110.1 示例

水平翻转图像：
```
geq=p(W-X\,Y)
```

生成一个二维正弦波，角度为 PI/3，波长为 100 像素：

geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128

生成一种奇特神秘的移动光效：

nullsrc=s=256x256,geq=random(1)/hypot(X-cos(N*0.07)*W/2-W/2\,Y-sin(N*0.09)*H/2-H/2)^2*1000000*sin(N*0.02):128:128

生成快速浮雕效果：

format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'

根据像素位置修改 RGB 分量：

geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'

创建一个与输入相同大小的径向渐变（另请参阅 vignette 滤镜）：
```
geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
```

11.111 gradfun

修复因截断为 8 位色深而在近乎平坦的区域中偶尔产生的条带伪影。对条带所在处应有的梯度进行插值，并施加抖动。

该滤镜仅设计用于播放阶段。请勿在有损压缩之前使用它，因为压缩往往会丢失抖动效果并使条带重新出现。

它接受以下参数：

strength

该滤镜对单个像素所做改动的最大幅度，同时也是检测近乎平坦区域的阈值。可接受的取值范围为 .51 到 64，默认值为 1.2。超出范围的值会被裁剪到有效范围内。

radius

用于拟合梯度的邻域范围。radius 越大，梯度越平滑，但也会使滤镜难以修改细节区域附近的像素。可接受的取值范围为 8-32，默认值为 16。超出范围的值会被裁剪到有效范围内。

此外，也可以将选项指定为扁平字符串：strength[:radius]

11.111.1 示例

应用该滤镜，strength 为 3.5，radius 为 8：
```
gradfun=3.5:8
```
指定 radius，省略 strength（将回退到默认值）：
```
gradfun=radius=8
```

11.112 graphmonitor

显示各种 filtergraph 统计信息。

使用该滤镜可以调试整个 filtergraph，尤其适合排查链路中排队帧堆积的问题。

该滤镜接受以下选项：

size, s

设置视频输出尺寸。默认值为 hd720。

opacity, o

设置视频不透明度。默认值为 0.9，允许的范围是 0 到 1。

mode, m

设置输出模式标志。

可用的标志值如下：

‘full’

不进行任何过滤。默认值。

‘compact’

仅显示存在排队帧的滤镜。

‘nozero’

仅显示统计值非零的滤镜。

‘noeof’

仅显示未处于 EOF 状态的滤镜。

‘nodisabled’

仅显示在时间线上已启用的滤镜。

flags, f

设置用于控制视频中显示哪些统计信息的标志。

可用的标志值如下：

‘none’

关闭所有标志。

‘all’

开启所有标志。

‘queue’

显示每条链路中排队帧的数量。

‘frame_count_in’

显示从滤镜取出的帧数。

‘frame_count_out’

显示由滤镜输出的帧数。

‘frame_count_delta’

显示以上两个值之间帧数的差值。

‘pts’

显示当前滤镜处理帧的 pts。

‘pts_delta’

显示当前帧与前一帧之间 pts 的差值。

‘time’

显示当前滤镜处理帧的时间。

‘time_delta’

显示当前帧与前一帧之间的时间差值。

‘timebase’

显示滤镜链路的时间基。

‘format’

显示滤镜链路所使用的格式。

‘size’

显示滤镜链路所用的视频尺寸；若为音频链路，则显示声道数。

‘rate’

显示滤镜链路所用的视频帧率；若为音频链路，则显示采样率。

‘eof’

显示链路的输出状态。

‘sample_count_in’

显示从滤镜取出的采样数。

‘sample_count_out’

显示由滤镜输出的采样数。

‘sample_count_delta’

显示以上两个值之间采样数的差值。

‘disabled’

显示时间线滤镜的状态。

rate, r

设置输出流视频速率的上限，默认值为 25。这可保证输出视频的帧率不会超过该值。

11.113 grayworld

一个基于灰度世界假设进行颜色校正的色彩恒常性滤镜。

参见：https://www.researchgate.net/publication/275213614_A_New_Color_Correction_Method_for_Underwater_Imaging

该算法使用线性光，因此输入数据应事先进行线性化处理（并且可能还需要正确地标注）。

ffmpeg -i INPUT -vf zscale=transfer=linear,grayworld,zscale=transfer=bt709,format=yuv420p OUTPUT

11.114 greyedge

一种色彩恒常性变体滤镜，通过灰边算法估计场景光照，并据此校正场景颜色。

参见：https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf

该滤镜接受以下选项：

difford

对场景应用的微分阶数。必须在 [0,2] 范围内选取，默认值为 1。

minknorm

用于计算闵可夫斯基距离的闵可夫斯基参数。必须在 [0,20] 范围内选取，默认值为 1。设为 0 时将获取最大值，而不是计算闵可夫斯基距离。

sigma

对场景应用的高斯模糊的标准差。必须在 [0,1024.0] 范围内选取，默认值 = 1。若 difford 大于 0，则 floor( sigma * break_off_sigma(3) ) 不能等于 0。

11.114.1 示例

灰边（Grey Edge）：
```
greyedge=difford=1:minknorm=5:sigma=2
```
最大边缘（Max Edge）：
```
greyedge=difford=1:minknorm=0:sigma=2
```

11.115 guided

应用引导滤波（guided filter），实现保边平滑、去雾等效果。

该滤镜接受以下选项：

radius

以像素为单位设置方框半径。允许的范围是 1 到 20，默认值为 3。

eps

设置正则化参数（取平方）。允许的范围是 0 到 1，默认值为 0.01。

mode

设置滤镜模式，可以是 basic 或 fast。默认值为 basic。

sub

设置 fast 模式下的二次采样比例。范围是 2 到 64，默认值为 4。basic 模式下不进行二次采样。

guidance

设置引导模式，可以是 off 或 on。默认值为 off。若为 off，则只需要一个输入；若为 on，则需要两个分辨率和 pixel format 相同的输入，第二个输入用作引导图。

planes

设置要过滤的平面。默认仅第一个。

11.115.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.115.2 示例

使用引导滤波进行保边平滑：
```
ffmpeg -i in.png -vf guided out.png
```
使用引导滤波实现去雾、结构转移滤波和细节增强。关于引导图像的生成方法，请参阅论文 "Guided Image Filtering"。参见：http://kaiminghe.com/publications/pami12guidedfilter.pdf。
```
ffmpeg -i in.png -i guidance.png -filter_complex guided=guidance=on out.png
```

11.116 haldclut

对视频流应用 Hald CLUT。

第一个输入是待处理的视频流，第二个输入是 Hald CLUT。Hald CLUT 输入既可以是一张简单的图片，也可以是完整的视频流。

该滤镜接受以下选项：

clut

设置从第二个输入流中处理哪些 CLUT 视频帧，可以是 first 或 all。默认值为 all。

shortest

当最短的输入结束时强制终止。默认值为 0。

repeatlast

在流结束后继续应用最后一个 CLUT。值为 0 时，在到达 CLUT 的最后一帧后禁用该滤镜。默认值为 1。

haldclut 还具有与 lut3d 相同的插值选项（两个滤镜共享相同的内部实现）。

该滤镜还支持 framesync 选项。

关于 Hald CLUT 的更多信息，请参见 Eskil Steenberg（Hald CLUT 的作者）的网站 http://www.quelsolaar.com/technology/clut.html。

11.116.1 命令

该滤镜支持将 interp 选项作为命令使用。

11.116.2 工作流程示例

11.116.2.1 Hald CLUT 视频流

生成一个恒等（identity）Hald CLUT 流，并用各种效果对其进行改变：

ffmpeg -f lavfi -i haldclutsrc=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut

注意：请务必使用无损 codec。

然后使用 haldclut 将其应用到某个随机流上：

ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv

该 Hald CLUT 会应用于最初的 10 秒（即 clut.nut 的时长），此后该 CLUT 流的最后一张图像会应用于 mandelbrot 流的其余帧。

11.116.2.2 带预览的 Hald CLUT

Hald CLUT 应当是一张 Level*Level*Level × Level*Level*Level 像素的正方形图像。对于给定的 Hald CLUT，FFmpeg 会从图像左上角开始选取尽可能大的正方形区域，剩余的填充像素（底部或右侧）将被忽略。这部分区域可用于添加 Hald CLUT 的预览。

通常，按以下方式生成的 Hald CLUT 可被 haldclut 滤镜所支持：

ffmpeg -f lavfi -i haldclutsrc=8 -vf "
   pad=iw+320 [padded_clut];
   smptebars=s=320x256, split [a][b];
   [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
   [main][b] overlay=W-320" -frames:v 1 clut.png

其中包含原始图像以及 CLUT 效果的预览：右上方显示 SMPTE 彩条，其下方显示经过颜色变化处理后的同一彩条。

随后，可以通过以下方式查看该 Hald CLUT 的效果：

ffplay input.mkv -vf "movie=clut.png, [in] haldclut"

11.117 hflip

水平翻转输入视频。

例如，使用 ffmpeg 水平翻转输入视频：

ffmpeg -i in.avi -vf "hflip" out.avi

11.118 histeq

该滤镜以逐帧为单位应用全局颜色直方图均衡化。

可用于校正像素强度范围被压缩的视频。该滤镜会重新分配像素强度，使其在整个强度范围内均匀分布，可将其视为一种“自动调节对比度的滤镜”。该滤镜仅在校正劣化或拍摄质量不佳的源视频时才有意义。

该滤镜接受以下选项：

strength

决定要应用的均衡化程度。strength 越小，像素强度的分布就越接近输入帧本身的分布。该值必须是 [0,1] 范围内的浮点数，默认值为 0.200。

intensity

设置可以生成的最大强度，并据此对输出值进行相应缩放。应先按需设置 strength，再视需要限制 intensity 以避免画面过曝。该值必须是 [0,1] 范围内的浮点数，默认值为 0.210。

antibanding

设置抗条带级别。启用后，滤镜会以微小幅度随机改变输出像素的亮度，以避免直方图出现条带。可选值为 none、weak 或 strong，默认值为 none。

11.119 histogram

为输入视频计算并绘制颜色分布直方图。

计算得到的直方图表示的是图像中颜色分量的分布情况。

标准直方图显示图像中各颜色分量的分布，为每个颜色分量绘制颜色图。根据输入格式的不同，显示当前帧中 Y、U、V、A 或 R、G、B 分量的分布。每个图下方都会显示一个颜色分量刻度表。

该滤镜接受以下选项：

level_height

设置电平高度。默认值为 200，允许的范围是 [50, 2048]。

scale_height

设置颜色刻度的高度。默认值为 12，允许的范围是 [0, 40]。

display_mode

设置显示模式。接受以下值：

‘stack’

各颜色分量的图彼此上下排列。

‘parade’

各颜色分量的图并排排列。

‘overlay’

所显示的信息与 parade 相同，区别在于表示各颜色分量的图会直接相互叠加。

默认值为 stack。

levels_mode

设置模式，可以是 linear 或 logarithmic。默认值为 linear。

components

设置要显示哪些颜色分量。默认值为 7。

fgopacity

设置前景不透明度。默认值为 0.7。

bgopacity

设置背景不透明度。默认值为 0.5。

colors_mode

设置颜色模式，接受以下值：

‘whiteonblack’ ‘blackonwhite’ ‘whiteongray’ ‘blackongray’ ‘coloronblack’ ‘coloronwhite’ ‘colorongray’ ‘blackoncolor’ ‘whiteoncolor’ ‘grayoncolor’

默认值为 whiteonblack。

11.119.1 示例

计算并绘制直方图：
```
ffplay -i input -vf histogram
```

11.120 hqdn3d

这是一个高精度/高质量的三维降噪滤镜，旨在减少图像噪声，生成平滑的图像，让静止画面真正静止下来，并应能提升可压缩性。

该滤镜接受以下可选参数：

luma_spatial

一个非负浮点数，指定空间维度上的亮度强度，默认值为 4.0。

chroma_spatial

一个非负浮点数，指定空间维度上的色度强度，默认值为 3.0*luma_spatial/4.0。

luma_tmp

一个浮点数，指定时间维度上的亮度强度，默认值为 6.0*luma_spatial/4.0。

chroma_tmp

一个浮点数，指定时间维度上的色度强度，默认值为 luma_tmp*chroma_spatial/luma_spatial。

11.120.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.121 hwdownload

将硬件帧下载到系统内存。

输入必须是硬件帧，输出则是非硬件格式。并非所有格式都能作为输出被支持——可能需要在图中紧随其后插入一个额外的 format 滤镜，才能获得受支持的输出格式。

11.122 hwmap

将硬件帧映射到系统内存或另一个设备。

该滤镜有多种不同的工作模式，具体使用哪一种取决于输入和输出格式：

硬件帧输入，普通帧输出

将输入帧映射到系统内存并传递给输出。如果之后需要用到原始硬件帧（例如在其部分区域上叠加了其他内容之后），可以再次以下一种模式使用 hwmap 滤镜来取回它。

普通帧输入，硬件帧输出

如果输入实际上是一个已软件映射的硬件帧，则将其取消映射——也就是返回原始的硬件帧。

否则，必须提供一个设备：在该设备上为输出创建新的硬件表面，再将其映射回输入端的软件格式，并把这些帧交给前面的滤镜。这样其行为就类似于 hwupload 滤镜，但在输入已经是兼容格式时，可以避免一次额外的复制。

硬件帧输入和输出

必须为输出提供一个设备，可以直接指定，也可以通过 derive_device 选项指定。输入和输出设备的类型必须不同且相互兼容——这具体意味着什么取决于系统，但通常是指两者必须指向同一个底层硬件上下文（例如指向同一块显卡）。

如果输入帧最初就是在输出设备上创建的，则取消映射即可取回原始帧。

否则，将这些帧映射到输出设备——在输出端为输入端的帧创建对应的新硬件帧。

还接受以下附加参数：

mode

设置帧映射模式，可以是以下项的某种组合：

read

映射得到的帧应当可读。

write

映射得到的帧应当可写。

overwrite

该映射总是会覆盖整个帧。

在某些情况下这可以提升性能，因为无需加载帧的原始内容。

direct

该映射不得涉及任何复制。

在直接映射不可行、或直接映射会产生意外特性的某些情况下，会创建指向帧副本的间接映射。设置该标志可确保映射是直接的，若无法做到则会失败。

若未指定，默认值为 read+write。

derive_device type

不使用初始化时提供的设备，而是从输入帧所在的设备派生出一个 type 类型的新设备。

reverse

在硬件到硬件的映射中反向映射——在汇（sink）端创建帧，再将其映射回源（source）端。当只需要单向映射，而所用设备却只支持相反方向时，这一做法可能是必要的。

该选项是危险的——如果前一个滤镜的输出存在其他约束，它可能以未定义的方式破坏该滤镜。在未完全理解其使用后果之前，请勿使用该选项。

11.123 hwupload

将系统内存中的帧上传到硬件表面。

必须在滤镜初始化时提供要上传到的设备。若使用 ffmpeg，可通过 -filter_hw_device 选项或 derive_device 选项选择合适的设备。输入和输出设备的类型必须不同且相互兼容——这具体意味着什么取决于系统，但通常是指两者必须指向同一个底层硬件上下文（例如指向同一块显卡）。

还接受以下附加参数：

derive_device type

不使用初始化时提供的设备，而是从输入帧所在的设备派生出一个 type 类型的新设备。

11.124 hwupload_cuda

将系统内存中的帧上传到 CUDA 设备。

该滤镜接受以下可选参数：

device

要使用的 CUDA 设备编号

11.125 hqx

应用一种专为像素艺术设计的高质量放大滤镜。该滤镜最初由 Maxim Stepin 创建。

它接受以下选项：

设置缩放倍数：hq2x 为 2，hq3x 为 3，hq4x 为 4。默认值为 3。

11.126 hstack

将输入视频水平堆叠。

所有流必须具有相同的 pixel format 和相同的高度。

注意，该滤镜比使用 overlay 和 pad 滤镜来生成相同输出的方式更快。

该滤镜接受以下选项：

inputs

设置输入流的数量。默认值为 2。

shortest

若设为 1，则在最短的输入结束时强制终止输出。默认值为 0。

11.127 hsvhold

将特定的 HSV 范围转换为灰色值。

该滤镜测量选项中设置的 HSV 颜色与视频流中实际测得颜色之间的色差。根据选项设置，输出颜色可以被改为灰色，也可以不变。

该滤镜接受以下选项：

hue

设置用于计算色差的色相（hue）值。允许的范围是 -360 到 360，默认值为 0。

sat

设置用于计算色差的饱和度（saturation）值。允许的范围是 -1 到 1，默认值为 0。

val

设置用于计算色差的明度（value）值。允许的范围是 -1 到 1，默认值为 0。

similarity

设置与关键色的相似度百分比。允许的范围是 0 到 1，默认值为 0.01。

0.00001 仅匹配与关键色完全相同的颜色，而 1.0 则匹配所有颜色。

blend

混合百分比。允许的范围是 0 到 1，默认值为 0。

0.0 会使像素要么完全变灰，要么完全不变灰。

值越大，变灰的像素越多；像素颜色与关键色越相似，其灰度就越高。

11.128 hsvkey

将特定的 HSV 范围转换为透明。

该滤镜测量选项中设置的 HSV 颜色与视频流中实际测得颜色之间的色差。根据选项设置，可以通过添加 alpha 通道将输出颜色改为透明。

该滤镜接受以下选项：

hue

设置用于计算色差的色相（hue）值。允许的范围是 -360 到 360，默认值为 0。

sat

设置用于计算色差的饱和度（saturation）值。允许的范围是 -1 到 1，默认值为 0。

val

设置用于计算色差的明度（value）值。允许的范围是 -1 到 1，默认值为 0。

similarity

设置与关键色的相似度百分比。允许的范围是 0 到 1，默认值为 0.01。

0.00001 仅匹配与关键色完全相同的颜色，而 1.0 则匹配所有颜色。

blend

混合百分比。允许的范围是 0 到 1，默认值为 0。

0.0 会使像素要么完全透明，要么完全不透明。

数值越大，像素越呈现半透明；像素颜色与键控颜色越相似，透明度就越高。

11.129 hue

修改输入的色相和/或饱和度。

它接受以下参数：

指定色相角度，以度数表示。可接受一个表达式，默认值为 "0"。

在 [-10,10] 范围内指定饱和度。可接受一个表达式，默认值为 "1"。

指定色相角度，以弧度表示。可接受一个表达式，默认值为 "0"。

在 [-10,10] 范围内指定亮度。可接受一个表达式，默认值为 "0"。

h 和 H 互斥，不能同时指定。

b、h、H、s 选项的值是包含以下常量的表达式：

输入帧的帧计数，从 0 开始

pts

以时间基单位表示的输入帧 presentation timestamp

输入视频的帧率，如果输入帧率未知则为 NAN

以秒为单位表示的时间戳；如果输入时间戳未知则为 NAN

输入视频的时间基

11.129.1 示例

将色相设为 90 度，饱和度设为 1.0：
```
hue=h=90:s=1
```
相同的命令，但以弧度表示色相：
```
hue=H=PI/2:s=1
```
旋转色相，并使饱和度在 1 秒周期内于 0 到 2 之间摆动：
```
hue="H=2*PI*t: s=sin(2*PI*t)+1"
```
从 0 秒开始应用一个持续 3 秒的饱和度淡入效果：
```
hue="s=min(t/3\,1)"
```

淡入的通用表达式可以写成：

    hue="s=min(0\, max((t-START)/DURATION\, 1))"

从第 5 秒开始应用一个持续 3 秒的饱和度淡出效果：
```
hue="s=max(0\, min(1\, (8-t)/3))"
```

淡出的通用表达式可以写成：

    hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"

11.129.2 命令

该滤镜支持以下命令：

b s h H

修改输入视频的色相和/或饱和度和/或亮度。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.130 huesaturation

对输入视频流应用色相-饱和度-强度调整。

该滤镜在 RGB 色彩空间中运行。

此滤镜接受以下选项：

hue

以度数设置要应用的色相偏移量。默认值为 0，允许的范围是 -180 到 180。

saturation

设置饱和度偏移量。默认值为 0，允许的范围是 -1 到 1。

intensity

设置强度偏移量。默认值为 0，允许的范围是 -1 到 1。

colors

设置要调整哪些原色和互补色。该选项通过提供一个或多个值来设置，可以一次选择多种颜色。默认情况下选择所有颜色。

‘r’

调整红色。

‘y’

调整黄色。

‘g’

调整绿色。

‘c’

调整青色。

‘b’

调整蓝色。

‘m’

调整品红色。

‘a’

调整所有颜色。

strength

设置滤波强度。允许的范围是 0 到 100，默认值为 1。

rw, gw, bw

设置每个 RGB 分量的权重。允许的范围是 0 到 1，默认设置为 0.333、0.334、0.333。这些选项用于饱和度和明度处理。

lightness

设置是否保持明度，默认禁用。调整色相可能会改变原始 RGB 三元组的明度，启用该选项后，明度会保持不变。

11.131 hysteresis

通过连接分量，将第一路流扩展到第二路流中。这样可以构建更稳健的边缘掩模。

此滤镜接受以下选项：

planes

设置将作为位图处理的平面，未处理的平面将从第一路流中复制。默认值为 0xf，即处理所有平面。

threshold

设置滤波所使用的阈值。若像素分量值高于该阈值，则会启动用于连接分量的滤波算法。默认值为 0。

hysteresis 滤镜还支持 framesync 选项。

11.132 iccdetect

从嵌入的 ICC 配置文件（如果存在）中检测色彩空间，并据此更新帧的标签。

此滤镜接受以下选项：

force

若为 true，帧现有的色彩空间标签将始终被从 ICC 配置文件中检测到的值覆盖。否则，只有当标签的值为 unknown 时才会被赋值。默认启用。

11.133 iccgen

生成 ICC 配置文件并将其附加到帧上。

此滤镜接受以下选项：

color_primaries color_trc

配置要为其生成 ICC 配置文件的色彩空间。默认值 auto 会根据输入帧的元数据推断该值，并在适当情况下默认使用 BT.709/sRGB。

可能取值的列表请参见 setparams 滤镜，但请注意 unknown 不是该滤镜的有效值。

force

若为 true，即使会覆盖已存在的 ICC 配置文件，也会生成新的 ICC 配置文件。默认禁用。

11.134 identity

求两个输入视频之间的同一性分数（identity score）。

此滤镜接受两个输入视频。

要使该滤镜正常工作，两个输入视频必须具有相同的分辨率和 pixel format。此外，该滤镜假定两个输入具有相同的帧数，并逐帧比较。

得到的按分量、平均值、最小值和最大值统计的同一性分数会通过日志系统输出。

该滤镜会将计算得到的各帧同一性分数存储在帧元数据中。

该滤镜还支持 framesync 选项。

在下面的示例中，正在处理的输入文件 main.mpg 会与参考文件 ref.mpg 比较。

ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null -

11.135 idet

检测视频的隔行方式。

该滤镜尝试检测输入帧是隔行、逐行、顶场优先还是底场优先。它还会尝试检测相邻帧之间重复出现的场（这是电视电影转换的迹象）。

单帧检测在对每一帧分类时只考虑紧邻的相邻帧。多帧检测则会纳入之前帧的分类历史。

该滤镜会记录以下元数据值：

single.current_frame

使用单帧检测得到的当前帧类型。取值为以下之一：“tff”（顶场优先）、“bff”（底场优先）、“progressive”或“undetermined”

single.tff

使用单帧检测被判定为顶场优先的帧的累积数。

multiple.tff

使用多帧检测被判定为顶场优先的帧的累积数。

single.bff

使用单帧检测被判定为底场优先的帧的累积数。

multiple.current_frame

使用多帧检测得到的当前帧类型。取值为以下之一：“tff”（顶场优先）、“bff”（底场优先）、“progressive”或“undetermined”

multiple.bff

使用多帧检测被判定为底场优先的帧的累积数。

single.progressive

使用单帧检测被判定为逐行的帧的累积数。

multiple.progressive

使用多帧检测被判定为逐行的帧的累积数。

single.undetermined

使用单帧检测无法分类的帧的累积数。

multiple.undetermined

使用多帧检测无法分类的帧的累积数。

repeated.current_frame

当前帧中哪个场是从上一帧重复而来。取值为“neither”、“top”或“bottom”之一。

repeated.neither

没有重复场的帧的累积数。

repeated.top

顶场从上一帧的顶场重复而来的帧的累积数。

repeated.bottom

底场从上一帧的底场重复而来的帧的累积数。

该滤镜接受以下选项：

intl_thres

设置隔行检测的阈值。

prog_thres

设置逐行检测的阈值。

rep_thres

重复场检测的阈值。

half_life

经过多少帧后，某一帧对统计量的贡献减半（即其对分类的贡献仅为 0.5）。默认值 0 表示所有已见过的帧都永远被赋予 1.0 的满权重。

analyze_interlaced_flag

当此值不为 0 时，idet 将使用指定数量的帧来判断隔行标志是否准确，且不会计入未确定的帧。如果判定该标志准确，则会直接采用该标志而不再进行任何后续计算；如果判定该标志不准确，则会直接清除该标志而不再进行任何后续计算。这样便可以将 idet 滤镜作为一种低计算量的方法插入，用来清理隔行标志

11.135.1 示例

详细检查视频前 360 帧的场顺序：

ffmpeg -i INPUT -filter:v idet,metadata=mode=print -frames:v 360 -an -f null -

idet 滤镜会为每一帧添加分析元数据，随后该元数据会被丢弃。最后，该滤镜还会打印一份包含统计信息的最终报告。

11.136 il

对场进行解交织或交织。

该滤镜允许在不对隔行图像去隔行的情况下处理其场。解交织会将输入帧拆分为 2 个场（即所谓的半图）。奇数行被移到输出图像的上半部分，偶数行被移到下半部分。你可以分别对它们进行处理（滤波），然后再重新将它们交织起来。

该滤镜接受以下选项：

luma_mode, l chroma_mode, c alpha_mode, a

luma_mode、chroma_mode 和 alpha_mode 的可用值为：

‘none’

不做任何处理。

‘deinterleave, d’

对场进行解交织，将其中一个放置在另一个之上。

‘interleave, i’

对场进行交织。此操作会撤销解交织的效果。

默认值为 none。

luma_swap, ls chroma_swap, cs alpha_swap, as

交换 luma/chroma/alpha 的场。交换偶数行和奇数行。默认值为 0。

11.136.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.137 inflate

对视频应用 inflate（膨胀）效果。

该滤镜会用局部（3x3）平均值替换像素，该平均值只考虑高于该像素的值。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量，默认值为 65535。若为 0，则该平面将保持不变。

11.137.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.138 interlace, interlace_vulkan

一个将逐行内容转换为隔行的简单滤镜。它会将奇数帧的上半（或下半）行与偶数帧的下半（或上半）行交织在一起，从而使帧率减半，同时保持图像高度不变。

   Original        Original             New Frame
   Frame 'j'      Frame 'j+1'             (tff)
  ==========      ===========       ==================
    Line 0  -------------------->    Frame 'j' Line 0
    Line 1          Line 1  ---->   Frame 'j+1' Line 1
    Line 2 --------------------->    Frame 'j' Line 2
    Line 3          Line 3  ---->   Frame 'j+1' Line 3
     ...             ...                   ...
New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on

该滤镜接受以下可选参数：

scan

这决定了隔行帧是从逐行帧的偶数行（tff，默认）还是奇数行（bff）中提取的。

lowpass

用于避免行间闪烁并减少摩尔纹的垂直低通滤波器。

‘0, off’

禁用垂直低通滤波器

‘1, linear’

启用线性滤波器（默认）

‘2, complex’

启用复杂滤波器。这种方式对行间闪烁和摩尔纹的削减程度略低，但能更好地保留细节，主观锐度观感也更好。

11.139 kerndeint

通过应用 Donald Graft 的自适应内核去隔行算法对输入视频进行去隔行处理。对视频中的隔行部分进行处理，以生成逐行帧。

以下是所接受参数的说明。

thresh

设置阈值，它会影响该滤镜在判断某条像素行是否需要处理时的容差。该值必须是 [0,255] 范围内的整数，默认值为 10。值为 0 时会对每个像素都应用该处理。

map

设置为 1 时，会将超过阈值的像素涂成白色。默认值为 0。

order

设置场顺序。设为 1 时交换场，设为 0 时保持场不变。默认值为 0。

sharp

设为 1 时启用额外的锐化。默认值为 0。

twoway

设为 1 时启用双向锐化。默认值为 0。

11.139.1 示例

应用默认值：

kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0

启用额外的锐化：
```
kerndeint=sharp=1
```
将处理后的像素涂成白色：
```
kerndeint=map=1
```

11.140 kirsch

对输入视频流应用 kirsch 算子。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

scale

设置与滤波结果相乘的值。

delta

设置与滤波结果相加的值。

11.140.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.141 lagfun

缓慢更新较暗的像素。

该滤镜可以让短暂的闪光看起来持续更久。该滤镜接受以下选项：

decay

设置衰减系数。默认值为 .95。允许的范围是 0 到 1。

planes

设置要滤波的平面。默认为 all。允许的范围是 0 到 15。

11.141.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.142 lenscorrection

校正径向镜头畸变

该滤镜可用于校正因使用广角镜头而产生的径向畸变，从而重新校正图像。要找到合适的参数，可以使用诸如 opencv 中提供的工具，或者简单地反复试验。要使用 opencv，可使用 opencv 源码中的校准示例（位于 samples/cpp 下），并从得到的矩阵中提取 k1 和 k2 系数。

请注意，KDE 项目的开源工具 Krita 和 Digikam 中实际上也提供了同样的滤镜。

与同样可用于补偿镜头误差的 vignette 滤镜不同，该滤镜校正的是图像的畸变，而 vignette 滤镜校正的是亮度分布，因此在某些情况下你可能想同时使用这两个滤镜，不过需要注意应用顺序，即 vignette 处理应在镜头校正之前还是之后进行。

11.142.1 选项

该滤镜接受以下选项：

图像焦点（也即畸变中心）的相对 x 坐标。该值的取值范围为 [0,1]，以图像宽度的分数表示。默认值为 0.5。

图像焦点（也即畸变中心）的相对 y 坐标。该值的取值范围为 [0,1]，以图像高度的分数表示。默认值为 0.5。

二次校正项的系数。该值的取值范围为 [-1,1]。0 表示不进行校正。默认值为 0。

双二次校正项的系数。该值的取值范围为 [-1,1]。0 表示不进行校正。默认值为 0。

设置插值类型。可以是 nearest 或 bilinear。默认值为 nearest。

指定未映射像素的颜色。关于此选项的语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。默认颜色为 black@0。

生成该校正的公式为：

r_src = r_tgt * (1 + k1 * (r_tgt / r_0)^2 + k2 * (r_tgt / r_0)^4)

其中 r_0 是图像对角线长度的一半，r_src 和 r_tgt 分别是源图像和目标图像中到焦点的距离。

11.142.2 命令

该滤镜支持将以上所有选项作为命令使用。

11.143 lensfun

通过 lensfun 库应用镜头校正（http://lensfun.sourceforge.net/）。

lensfun 滤镜需要相机厂商、相机型号和镜头型号才能应用镜头校正。该滤镜会加载 lensfun 数据库，并在其中查询对应的相机和镜头条目。只要能根据给定的选项找到这些条目，该滤镜就可以对帧执行校正。请注意，字符串不完整会导致该滤镜根据给定的选项选择最匹配的条目，并输出所选定的相机和镜头型号（以 "info" 级别记录日志）。你必须提供厂商、相机型号和镜头型号，因为它们都是必需的。

要获取可用厂商和型号的列表，请省略 make 和 model 选项中的一个或两个。该滤镜会以 INFO 级别将完整列表发送到日志。第一列是厂商，第二列是型号。要获取可用镜头的列表，请为 make 和 model 设置任意值并省略 lens_model 选项。该滤镜会以 INFO 级别将完整的镜头列表发送到日志。列表打印完毕后，ffmpeg 工具会退出。

该滤镜接受以下选项：

make

相机厂商（例如 "Canon"）。此选项为必需项。

model

相机型号（例如 "Canon EOS 100D"）。此选项为必需项。

lens_model

镜头型号（例如 "Canon EF-S 18-55mm f/3.5-5.6 IS STM"）。此选项为必需项。

db_path

镜头数据库文件夹的完整路径。若未设置，该滤镜会尝试从库编译时的安装路径加载数据库。默认未设置。

mode

要应用的校正类型。以下是有效的选项值：

‘vignetting’

启用镜头暗角的修正。

‘geometry’

启用镜头几何形变的修正。此为默认值。

‘subpixel’

启用色差的修正。

‘vig_geo’

启用镜头暗角和几何形变的修正。

‘vig_subpixel’

启用镜头暗角和色差的修正。

‘distortion’

同时启用镜头几何形变和色差的修正。

‘all’

启用所有可能的校正。

focal_length

图像/视频的焦距（变焦；对于视频，预期为恒定值）。例如，18–55mm 镜头的焦距范围为 [18–55]，因此使用该镜头时应选择该范围内的值。默认值为 18。

aperture

图像/视频的光圈（对于视频，预期为恒定值）。请注意，光圈仅用于暗角校正。默认值为 3.5。

focus_distance

图像/视频的对焦距离（对于视频，预期为恒定值）。请注意，对焦距离仅用于暗角处理，且只会轻微影响暗角校正过程。若未知，请保留默认值（即 1000）。

scale

变换之后应用的缩放系数。校正之后，视频不一定还是矩形的。该参数控制结果图像中有多少内容可见。值为 0 表示会自动选择一个值，使输出图像中几乎没有未映射的区域。1.0 表示不进行额外的缩放。较低的值可能会使校正后图像中更多内容可见，而较高的值则可能避免输出中出现未映射区域。

target_geometry

输出图像/视频的目标几何形状。以下是有效的选项值：

‘rectilinear (default)’ ‘fisheye’ ‘panoramic’ ‘equirectangular’ ‘fisheye_orthographic’ ‘fisheye_stereographic’ ‘fisheye_equisolid’ ‘fisheye_thoby’ reverse

应用图像校正的反向操作（不进行畸变校正，而是施加畸变）。

interpolation

校正畸变时使用的插值类型。以下是有效的选项值：

‘nearest’ ‘linear (default)’ ‘lanczos’

11.143.1 示例

使用厂商 "Canon"、相机型号 "Canon EOS 100D"、镜头型号 "Canon EF-S 18-55mm f/3.5-5.6 IS STM"，并将焦距设为 "18"、光圈设为 "8.0" 来应用镜头校正。
```
ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov
```

应用与之前相同的操作，但仅对视频的前 5 秒生效。

ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov

11.144 lcevc

基于 liblcevc_dec 的低复杂度增强视频 codec（Low Complexity Enhancement Video Codec）滤镜（https://github.com/v-novaltd/LCEVCdec）。

11.145 libplacebo

基于 libplacebo 的灵活 GPU 加速处理滤镜（https://code.videolan.org/videolan/libplacebo）。

11.145.1 选项

该滤镜的选项分为以下几个部分：

11.145.1.1 输出模式

这些选项控制整体的输出模式。默认情况下，libplacebo 会尽量保留源的色彩特性和尺寸，但会应用源帧中存在的任何嵌入胶片颗粒、杜比视界元数据或变形宽银幕 SAR。

inputs

设置输入的数量。它可以与 idx 变量搭配使用，以便在输出帧内放置/混合多路输入。这实际上启用了类似 hstack、overlay 等的功能。

w h

设置输出视频尺寸的表达式。默认值分别为 iw 和 ih。

允许使用与 scale 滤镜相同的表达式。

crop_x crop_y

设置输入裁剪 x/y 的表达式，默认值分别为 (iw-cw)/2 和 (ih-ch)/2。

crop_w crop_h

设置输入裁剪宽度/高度的表达式，默认值分别为 iw 和 ih。

pos_x pos_y

设置输出放置位置 x/y 的表达式，默认值分别为 (ow-pw)/2 和 (oh-ph)/2。

pos_w pos_h

设置输出放置宽度/高度的表达式，默认值分别为 ow 和 oh。

rotate

将输入帧按指定角度顺时针旋转。

‘0, 360’ ‘90’ ‘180’ ‘270’ fps

设置输出帧率。它可以是有理数，例如 60000/1001。若设为特殊字符串 none（默认值），则输入时间戳会原样直接传递到输出。否则，输入视频帧会按需进行插值，以便按 frame_mixer 选项决定的方式将视频重新缩放到指定的目标帧率。

format

设置输出格式的覆盖值。若未设置（默认），帧将以与各自输入帧相同的格式输出。否则，将执行格式转换。

force_original_aspect_ratio force_divisible_by

与 scale 滤镜中同名选项的作用相同。请注意 force_divisible_by 在 fit_sense=constraint 时也同样有效。

reset_sar

若启用，输出帧的像素宽高比将始终为 1:1。若禁用（默认），任何宽高比不匹配的情况（包括例如变形宽银幕视频源产生的情况）都会被传递到输出的像素宽高比。

normalize_sar

与 reset_sar 类似，但不是拉伸视频内容以填充新的输出宽高比，而是按需对内容进行填充或裁剪。与 fit_mode 互斥。默认禁用。

pad_crop_ratio

当输入宽高比与输出宽高比不一致且 normalize_sar 生效时，指定填充与裁剪之间的比例（介于 0.0 和 1.0 之间）。默认值 0.0 总是用黑边填充内容，而值为 1.0 时总是裁掉部分内容。也可以取中间值，从而混合这两种方式。

fit_mode

根据一组预定义模式指定内容适配策略。决定输入图像应如何放置在目标裁剪矩形内（由 pos_x/y 和 pos_w/h 定义）。这些名称及其实现取自 CSS 的 ’object-fit’ 属性。请注意，此选项与 normalize_sar 互斥。默认值为 fill。有效值为：

‘fill’

将输入拉伸至输出矩形，忽略宽高比不匹配的情况。请注意，除非同时启用 reset_sar，否则输出仍会被标记为正确的像素宽高比。

‘contain’

缩放输入以适配输出内部，通过填充来保持宽高比。等效于将 normalize_sar 与 pad_crop_ratio 设为 0.0。

‘cover’

缩放输入以填满输出，通过裁剪来保持宽高比。等效于将 normalize_sar 与 pad_crop_ratio 设为 1.0。

‘none, place’

不缩放输入。输入将以其原始尺寸放置在输出矩形内，这可能会导致额外的填充或裁剪。

‘scale_down’

按需将输入缩小以适配输出内部。根据输入是否大于输出，等效于 contain 或 none。

fit_sense

当使用 fit_mode 时，此选项控制适配策略如何针对指定的输出分辨率应用。与 force_original_aspect_ratio 互斥。有效值为：

‘target’

计算得到的输出分辨率将被视为输出帧的确切尺寸。这是默认行为。

‘constraint’

计算得到的输出分辨率将作为一个尺寸参照，适配模式会针对该参照进行应用，并按需放大或缩小真实帧尺寸以适配内容。

fillcolor

设置用于填充输出图像未覆盖到的输出区域的颜色，例如由 normalize_sar 产生的情况。关于此选项的通用语法，请查看 ffmpeg-utils 手册中的 “Color” 一节。默认值为 black@0。

corner_rounding

以圆角渲染帧。该值为一个浮点数，范围从 0.0 到 1.0，表示圆角的相对程度，从完全方正到完全圆形。换句话说，它给出的是半径除以较短边长度的一半所得的值。默认值为 0.0。

lut

指定要在颜色转换过程中应用于颜色的自定义 LUT（Adobe .cube 格式）。具体的解读方式取决于 lut_type 的值。

lut_type

控制传入和传出由 lut 指定的 LUT 的颜色值的解读方式。有效值为：

‘auto’

根据标记的元数据自动选择 LUT 的解读方式，否则回退到 ‘native’。（默认）

‘native’

在转换到输出色彩空间之前，应用于处于其原生 RGB 色彩空间（非线性光）中的原始图像内容。

‘normalized’

在转换到输出色彩空间之前，应用于线性光下经过归一化的 RGB 图像内容。

‘conversion’

完全替代从图像色彩空间到输出色彩空间的转换。若存在这样的 LUT，它具有最高优先级，会覆盖任何 ICC 配置文件，以及与色调映射和输出色彩特性相关的选项（color_primaries、color_trc）。

extra_opts

传递额外的 libplacebo 内部配置选项。可以将其指定为以 ’:’ 分隔的 key=value 对列表。以下示例展示了如何配置自定义滤波内核（"EWA LanczosSharp"）并用它将输入图像分辨率提升为原来的两倍：

-vf "libplacebo=w=iw*2:h=ih*2:extra_opts='upscaler=custom\:upscaler_preset=ewa_lanczos\:upscaler_blur=0.9812505644269356'"

shader_cache

libplacebo 用于存储和加载已缓存着色器对象的缓存目录的文件路径。该缓存不会自动清理。若路径不以目录分隔符结尾，则生成的文件名实际上会以路径的最后一部分作为前缀。所有目录都必须已经存在。

-vf "libplacebo=shader_cache=/tmp/pl-shader-"

colorspace color_primaries color_trc range chroma_location

配置输出帧将以何种色彩空间交付。默认值 auto 会以与输入帧相同的格式输出帧，即不做任何改变。对于任何其他值，都会执行转换。

可能取值的列表请参见 setparams 滤镜。

alpha_mode

当输出格式带有 alpha 通道时，选择所需的输出 alpha 模式。可能取值的列表请参见 setparams 滤镜。

apply_filmgrain

若源帧中存在胶片颗粒（例如来自 AV1 或 H.274 的），则应用该胶片颗粒，并将其从输出中剥离。默认启用。

apply_dolbyvision

若源帧中存在杜比视界（Dolby Vision）RPU 元数据，则应用该元数据，并将其从输出中剥离。默认启用。请注意，杜比视界始终会输出 BT.2020+PQ，覆盖通常的输入帧元数据。这些值也会被选作各个帧输出选项中 auto 对应的值。

除了 scale 滤镜文档中记录的表达式常量之外，crop_w、crop_h、crop_x、crop_y、pos_w、pos_h、pos_x 和 pos_y 选项还可以包含以下常量：

in_idx, idx

当前激活输入流的（从 0 开始的）数字索引。

crop_w, cw crop_h, ch

crop_w 和 crop_h 计算得到的值。

pos_w, pw pos_h, ph

pos_w 和 pos_h 计算得到的值。

in_t, t

输入帧的时间戳，以秒为单位。若输入时间戳未知，则为 NAN。

out_t, ot

输入帧的时间戳，以秒为单位。若输入时间戳未知，则为 NAN。

输入帧编号，从 0 开始。

11.145.1.2 缩放

本节中的选项控制 libplacebo 如何执行放大以及（在必要时）缩小。请注意，libplacebo 内部始终以 4:4:4 内容进行处理，因此像 yuv420p 这样经过色度二次采样的格式，在渲染过程中必然会被上采样和下采样。这意味着即使源分辨率与目标分辨率相同，缩放也可能仍会生效。

upscaler downscaler

配置用于放大和缩小的滤波内核。二者的默认值分别为 spline36 和 mitchell。要获取完整的可能取值列表，请为这些选项传入 help。最重要的取值有：

‘none’

强制使用内置的 GPU 纹理采样（通常为双线性）。速度极快，但质量较差，尤其是在缩小时。

‘bilinear’

双线性插值。通常在 GPU 上可以免费完成，除非这样做会导致混叠。速度快但质量低。

‘nearest’

最近邻插值。清晰但混叠严重。

‘oversample’

一种视觉效果类似最近邻插值，但会尝试保留像素宽高比的算法。适合像素艺术，因为它对艺术外观造成的畸变极小。

‘lanczos’

标准的 sinc-sinc 插值内核。

‘spline36’

lanczos 的三次样条近似。性能上没有差异，但振铃略少一些。

‘ewa_lanczos’

lanczos 的椭圆加权平均版本，基于 jinc-jinc 内核。这种方法也常被俗称为 "Jinc scaling"（Jinc 缩放）。速度慢，但质量非常高。

‘gaussian’

高斯内核。具有一定的理想数学性质，但主观观感非常模糊。

‘mitchell’

采用 Mitchell 和 Netravali 推荐参数的三次 BC 样条。振铃极少。

frame_mixer

控制用于在时间上混合帧的内核。默认值为 none，表示禁用帧混合。要获取完整的可能取值列表，请为该选项传入 help。最重要的取值有：

‘none’

禁用帧混合，得到等效于 "nearest neighbour"（最近邻）语义的结果。

‘oversample’

对输入视频进行过采样，以产生类似 "Smooth Motion"（平滑运动）的效果：若某个输出帧恰好落在两个视频帧的过渡处，则会按相对重叠程度进行混合。只要希望保留原始的主观观感，就推荐使用此选项。

‘mitchell_clamp’

一种更大的滤波内核，它以尽量消除振铃和其他伪影的方式平滑地在多个帧之间进行插值。只要希望获得最大程度的视觉平滑感，就推荐使用此选项。

‘linear’

在帧之间进行线性混合/淡化。对于构建例如幻灯片放映之类的效果尤其有用。

antiringing

启用抗振铃（适用于非 EWA 滤波器）。该值（介于 0.0 和 1.0 之间）配置抗振铃算法的强度。若设置过高，可能会增加混叠。默认禁用。

sigmoid

在放大过程中启用 S 型（sigmoid）压缩。可稍微减少振铃。默认启用。

11.145.1.3 去隔行

当帧被标记为隔行时，去隔行会自动获得支持；但除非选择了去隔行算法，否则帧不会被去隔行处理。

deinterlace

要使用的去隔行算法。

‘weave’

不进行去隔行，只是将两场交织合并成一帧。这是默认值。

‘bob’

简单的 bob 去隔行，只是将每一场的行简单重复两次。

‘yadif’

Yet another deinterlacing filter（意为“又一个去隔行滤镜”）。详情参见 yadif 滤镜。

‘bwdif’

Bob weaver 去隔行滤镜。详情参见 bwdif 滤镜。

skip_spatial_check

在使用 yadif 去隔行时跳过空间去隔行检查。

send_fields

为每一场（而非每一帧）输出一帧。注意，即使输入不包含任何隔行帧，这也会始终使标记的输出帧率翻倍。默认禁用。

11.145.1.4 去带化

libplacebo 内置了一个去带化滤镜，擅长消除许多常见的色带和块效应来源。若追求画质，强烈建议启用此选项。

deband

启用（快速）去带化算法。默认禁用。

deband_iterations

去带化算法的迭代次数。每次迭代都会逐步增大半径（并减小阈值）。推荐值为 1 到 4。默认值为 1。

deband_threshold

去带化滤镜强度。数值越大，去带化效果越激进。默认值为 4.0。

deband_radius

去带化滤镜半径。半径越大越适合平缓的渐变，半径越小越适合陡峭的渐变。默认值为 16.0。

deband_grain

要额外添加的输出颗粒量。有助于掩盖瑕疵。默认值为 6.0。

11.145.1.5 色彩调整

一组主观色彩控制项。这些控制并不十分严谨，因此确切效果会因输入的原色和色彩空间而有所不同。

brightness

亮度提升，取值范围 -1.0 到 1.0。默认值为 0.0。

contrast

对比度增益，取值范围 0.0 到 16.0。默认值为 1.0。

saturation

饱和度增益，取值范围 0.0 到 16.0。默认值为 1.0。

hue

色相偏移，以弧度为单位，取值范围 -3.14 到 3.14。默认值为 0.0。此选项会旋转 UV 子向量，对 RGB 输入默认使用 BT.709 系数。

gamma

伽马调整，取值范围 0.0 到 16.0。默认值为 1.0。

temperature

色温调整。值越低，输出越偏暖色/偏红，下限为 1667；值越高，输出越偏冷色/偏蓝，上限为 25000。默认值为 6500（中性白）。

cones

用于色盲模拟的锥体模型。可接受 l、m、s 的任意组合。以下是一些示例：

‘m’

第二色弱/第二色盲（影响 3%-4% 的人口）

‘l’

第一色弱/第一色盲（影响 1%-2% 的人口）

‘l+m’

单色觉（极为罕见）

‘l+m+s’

全色盲（完全丧失日间视觉，极其罕见）

cone-strength

cones 指定的锥体的增益系数，取值范围 0.0 到 10.0。值为 1.0 时对色觉没有影响。值为 0.0（默认值）会模拟这些锥体的完全丧失。高于 1.0 的值会夸大锥体之间的差异，有助于补偿减弱的色觉。

11.145.1.6 峰值检测

为了处理只有静态 HDR10 元数据（或完全没有标记）的来源，libplacebo 会使用自身内部的帧分析计算着色器来分析源帧，并实时调整色调映射函数。如果这一过程太慢，或者需要逐帧精确可复现的结果，建议关闭此功能。

peak_detect

启用 HDR 峰值检测。忽略静态的 MaxCLL/MaxFALL 值，优先采用从输入中动态检测得到的值。注意，检测到的值不会写回输出帧，仅用于指导内部的色调映射过程。默认启用。

smoothing_period

峰值检测平滑周期，取值范围 0.0 到 1000.0。值越大，峰值检测对输入变化的响应就越迟钝。默认值为 20.0。

scene_threshold_low scene_threshold_high

场景切换检测的下限与上限阈值。以 0.0 到 100.0 之间的对数刻度表示。默认值分别为 1.0 和 3.0。将任一项设为负值都会禁用此功能。

percentile

指定使用帧亮度直方图中的哪个百分位数作为色调映射的源峰值。默认值为 99.995，是一个相当保守的值。将其设置为 100.0 会禁用帧直方图测量，转而使用真实峰值亮度进行色调映射。

11.145.1.7 色调映射

本节的选项控制 libplacebo 在处理广色域或 HDR 内容不匹配的情况时如何执行色调映射与色域映射。总体而言，libplacebo 依赖准确的源标记和母版显示器色域信息以获得最佳效果。

gamut_mode

设置如何处理测色色域映射所产生的越界色彩。

‘clip’

不做任何处理，直接将越界色彩裁剪到 RGB 体积内。质量低但速度极快。

‘perceptual’

将色彩以感知方式软裁剪到色域体积内。这是默认值。

‘relative’

相对测色硬裁剪。与 perceptual 类似，但没有软拐点。

‘saturation’

饱和度映射，将原色直接映射到 RGB 空间中的原色。除非需要明亮、饱和度高的显示效果（例如人工计算机图形），否则不建议使用。

‘absolute’

绝对测色硬裁剪。不对白点做任何调整。

‘desaturate’

在保持亮度的同时，将越界色彩硬性去饱和至白色。往往会使明亮物体的视觉外观产生失真。

‘darken’

线性降低内容亮度以保留饱和细节，随后再裁剪剩余的越界色彩。

‘warn’

（通过反转/标记）高亮显示越界像素。

‘linear’

线性降低整幅图像的色度，使其适应目标色彩体积。在没有适当母版元数据的 BT.2020 源上使用此选项时要小心，因为这样做会导致过度去饱和。

tonemapping

要使用的色调映射算法。可用值如下：

‘auto’

基于内部启发式算法的自动选择。这是默认值。

‘clip’

不执行色调映射，只是裁剪越界色彩。对范围内的色彩保持完美的色彩精度，但会完全丢失范围外的信息。不进行任何黑点适配。不可配置。

‘st2094-40’

来自 SMPTE ST 2094-40 附录 B 的 EETF，应用基于 HDR10+ 动态元数据的贝塞尔曲线来进行色调映射。所使用的 OOTF 会根据目标显示峰值亮度与实际显示峰值亮度之比进行调整。

‘st2094-10’

来自 SMPTE ST 2094-10 附录 B.2 的 EETF，除最大/最小值外还会考虑输入信号的平均亮度。可配置的 contrast 参数会影响线性输出区段的斜率，默认值为 1.0，表示不增减对比度。注意，此选项目前尚不包含附录 B.3 中定义的主观增益/偏移/伽马控制。

‘bt.2390’

来自 ITU-R Report BT.2390 的 EETF，是带线性区段的 Hermite 样条滚降曲线。拐点偏移可配置。注意，此参数默认值为 1.0，而非 ITU-R 规范中的 0.5。

‘bt.2446a’

来自 ITU-R Report BT.2446 方法 A 的 EETF。专为经过良好母版制作的 HDR 源设计。可用于正向和逆向色调映射。不可配置。

‘spline’

由两条多项式曲线通过单个枢轴点连接而成的简单样条曲线。参数给出（PQ 空间中的）枢轴点，默认值为 0.30。可用于正向和逆向色调映射。

‘reinhard’

简单的非线性全局色调映射算法。参数指定显示峰值处的局部对比度系数。本质上，参数为 0.5 意味着参考白将约为裁剪时亮度的一半。默认值为 0.5，对应该函数最简单的公式形式。

‘mobius’

对 reinhard 色调映射算法的一种推广，在黑色附近增加了额外的线性斜率。色调映射参数表示线性区段与非线性区段之间的权衡。本质上，对于给定的参数 x，低于 x 的所有色彩值都会被线性映射，而更高的值则会被非线性地色调映射。接近 1.0 的值会使该曲线表现得像 clip，接近 0.0 的值则会使其表现得像 reinhard。默认值为 0.3，在色彩精度和越界细节保留之间取得了良好的平衡。

‘hable’

由 John Hable 为《神秘海域 2》开发的分段式电影感色调映射算法，其灵感来自柯达（Kodak）使用的类似色调映射算法。因在采用 HDR 渲染的电子游戏中使用而广为流传。能非常好地保留暗部与亮部细节，但缺点是会相当明显地改变平均亮度。这在一定程度上类似于参数为 0.24 的 reinhard。

‘gamma’

拟合一个伽马（幂）函数，在源色彩空间与目标色彩空间之间进行转换，实质上产生一个连接两段近似线性区间的感知硬拐点。这能相当准确地保留各个尺度的细节，但可能导致图像呈现出色彩浑浊、暗淡的观感。该参数用作截止点，默认值为 0.5。

‘linear’

在 PQ 空间中，将输入范围线性拉伸到输出范围。能准确保留所有细节，但会导致平均亮度出现明显变化。除常规色调映射外，还可用于逆向色调映射。该参数可用作附加的线性增益系数（默认值为 1.0）。

tonemapping_param

对于可调的色调映射函数，可使用此参数微调曲线行为。请参阅 tonemapping 的文档。默认值 0.0 会被替换为该曲线自身首选的默认设置。

inverse_tonemapping

启用后，此滤镜还会尝试拉伸 SDR 信号以填满 HDR 输出的色彩体积。默认禁用。

tonemapping_lut_size

色调映射 LUT 的大小，取值范围 2 到 1024。默认值为 256。注意，与 peak_detect 组合使用时，此数值会被平方。

contrast_recovery

对比度恢复强度。若设置为大于 0.0 的值，源图像将被分为高频分量和低频分量，高频图像的一部分会被加回到色调映射后的输出中。对某些 HDR 源可能会导致过度的振铃伪影，但可以改善色调映射后图像中残留的主观锐度和细节。默认值为 0.30。

contrast_smoothness

对比度恢复低通内核大小。默认值为 3.5。增大或减小此值会显著影响视觉效果。当 contrast_recovery 被禁用时不起作用。

11.145.1.8 抖动

默认情况下，libplacebo 会在必要时始终进行抖动处理，这包括渲染到任何低于 16 位精度的整数格式。建议始终保持此选项开启，因为不这样做可能会导致输出中出现明显的色带，即使启用了 debanding 滤镜也是如此。若需要最大性能，可使用 ordered_fixed 来代替禁用抖动。

dithering

要使用的抖动方式。可接受以下值：

‘none’

完全禁用抖动。可能会产生明显的色带。

‘blue’

使用伪蓝噪声进行抖动。这是默认值。

‘ordered’

可调节的有序抖动图案。

‘ordered_fixed’

固定大小为 6 的更快有序抖动，不含纹理。

‘white’

使用白噪声进行抖动。不含纹理。

dither_lut_size

抖动 LUT 大小，以 2 为底的对数表示，取值范围 1 到 8。默认值为 6，对应 LUT 大小 64x64。

dither_temporal

启用时间维度的抖动。默认禁用。

11.145.1.9 自定义着色器

libplacebo 支持多种基于 mpv .hook GLSL 语法的自定义着色器。可以在此处找到此类着色器集合：https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders

mpv 着色器格式的完整说明超出了本节范围，但可以在此处找到概要：https://mpv.io/manual/master/#options-glsl-shader

custom_shader_path

指定运行时要加载的自定义着色器文件的路径。

custom_shader_bin

以原始字符串形式指定完整的自定义着色器。

11.145.1.10 调试/性能

本节中的所有选项默认关闭。在试图以牺牲质量为代价压榨出最大性能时，它们可能会有所帮助。

skip_aa

在缩小画面时禁用抗混叠。

disable_linear

禁用线性光缩放。

disable_builtin

禁用内置的 GPU 采样（强制使用 LUT）。

disable_fbos

强制禁用 FBO，几乎会失去所有功能，但可获得可能的最高速度。

11.145.2 命令

该滤镜支持将上述几乎所有选项作为命令使用。

11.145.3 示例

将输入色调映射为标准色域的 BT.709 输出：

libplacebo=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv

使用高质量缩放，将输入重新缩放以适配标准 1080p：

libplacebo=w=1920:h=1080:force_original_aspect_ratio=decrease:normalize_sar=true:upscaler=ewa_lanczos:downscaler=ewa_lanczos

对低 FPS / VFR 的输入进行插值，得到平滑的恒定 60 fps 输出：
```
libplacebo=fps=60:frame_mixer=mitchell_clamp
```

将输入转换为标准 sRGB JPEG：

libplacebo=format=yuv420p:colorspace=bt470bg:color_primaries=bt709:color_trc=iec61966-2-1:range=pc

使用更高质量的去带化设置：

libplacebo=deband=true:deband_iterations=3:deband_radius=8:deband_threshold=6

在安装了 Mesa 的系统上，在 CPU 上运行此滤镜（同时禁用了开销最大的选项）：

ffmpeg ... -init_hw_device vulkan:llvmpipe ... -vf libplacebo=upscaler=none:downscaler=none:peak_detect=false

抑制 decoder 中基于 CPU 的 AV1/H.274 胶片颗粒应用，改为使用此滤镜进行处理。注意，只有当帧已经位于 GPU 上，或者你出于其他目的使用 libplacebo 时，这样做才有优势，否则 VRAM 往返的开销会抵消预期的加速效果。
```
ffmpeg -export_side_data +film_grain ... -vf libplacebo=apply_filmgrain=true
```

与 VAAPI 硬件解码互操作，避免往返 RAM：

ffmpeg -init_hw_device vulkan -hwaccel vaapi -hwaccel_output_format vaapi ... -vf libplacebo

11.146 libvmaf

为一对参考/失真输入视频计算 VMAF（Video Multi-Method Assessment Fusion）分数。

第一路输入为失真视频，第二路输入为参考视频。

得到的 VMAF 分数会通过日志系统输出。

需要以 Netflix 的 vmaf 库（libvmaf）作为前提条件。安装该库后，可使用 ./configure --enable-libvmaf 启用它。

该滤镜具有以下选项：

model

以 | 分隔的 vmaf 模型列表。每个模型都可以通过若干参数进行配置。默认值："version=vmaf_v0.6.1"

feature

以 | 分隔的 feature 列表。每个 feature 都可以通过若干参数进行配置。

log_path

设置用于存储日志文件的文件路径。

log_fmt

设置日志文件的格式（xml、json、csv 或 sub）。

pool

设置计算 vmaf 时使用的池化方法。可选值为 min、harmonic_mean 或 mean（默认值）。

n_threads

设置初始化 libvmaf 时使用的线程数。默认值：0，即不使用线程。

n_subsample

设置要使用的帧二次采样间隔。

该滤镜还支持 framesync 选项。

11.146.1 示例

在以下示例中，将失真视频 distorted.mpg 与参考文件 reference.mpg 进行比较。

基本用法：

ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf=log_path=output.xml -f null -

使用多个模型的示例：

ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='model=version=vmaf_v0.6.1\\:name=vmaf|version=vmaf_v0.6.1neg\\:name=vmaf_neg' -f null -

使用多个附加 feature 的示例：

ffmpeg -i distorted.mpg -i reference.mpg -lavfi libvmaf='feature=name=psnr|name=ciede' -f null -

带选项及不同容器的示例：

ffmpeg -i distorted.mpg -i reference.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=log_fmt=json:log_path=output.json" -f null -

11.147 libvmaf_cuda

这是 libvmaf 滤镜的 CUDA 版本。它只接受 CUDA 帧。

需要以 Netflix 的 vmaf 库（libvmaf）作为前提条件。安装该库后，可使用 ./configure --enable-nonfree --enable-ffnvcodec --enable-libvmaf 启用它。

11.147.1 示例

展示 CUVID 硬件解码与 scale_cuda 进行 CUDA 缩放的基本用法示例：

ffmpeg \
    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i dis.obu \
    -hwaccel cuda -hwaccel_output_format cuda -codec:v av1_cuvid -i ref.obu \
    -filter_complex "
        [0:v]scale_cuda=format=yuv420p[dis]; \
        [1:v]scale_cuda=format=yuv420p[ref]; \
        [dis][ref]libvmaf_cuda=log_fmt=json:log_path=output.json
    " \
    -f null -

11.148 limitdiff

使用第二个以及（可选的）第三个视频流应用限定差异滤镜。

该滤镜接受以下选项：

threshold

设置在判断视频流之间可容许差异时使用的阈值。绝对差异值低于或等于此阈值的部分，将采用第一个视频流的像素分量。

elasticity

设置处理视频流时软阈值处理的弹性。此值与第一个阈值相乘得到第二个阈值。绝对差异值大于或等于第二个阈值的部分，将采用第二个视频流的像素分量。介于两个阈值之间的值，将在第一个和第二个视频流之间使用线性插值。

reference

启用参考（第三个）视频流的处理。默认禁用。若设置此项，该视频流将用于计算与第一个视频流的绝对差异。

planes

指定要处理的平面。默认为所有可用平面。

11.148.1 命令

该滤镜支持将以上除 ‘reference’ 选项外的所有选项作为命令使用。

11.149 limiter

将像素分量的值限制在指定范围 [min, max] 内。

该滤镜接受以下选项：

min

下限。默认值为输入所允许的最低值。

max

上限。默认值为输入所允许的最高值。

planes

指定要处理的平面。默认为所有可用平面。

11.149.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.150 loop

循环播放视频帧。

该滤镜接受以下选项：

loop

设置循环次数。将此值设为 -1 会导致无限循环。默认值为 0。

size

以帧数设置最大大小。默认值为 0。

start

设置循环的起始帧。默认值为 0。

time

以秒为单位设置循环起始时间。仅当名为 start 的选项设为 -1 时才会使用。

11.150.1 示例

无限循环第一帧：
```
loop=loop=-1:size=1:start=0
```
将第一帧循环 10 次：
```
loop=loop=10:size=1:start=0
```
将前 10 帧循环 5 次：
```
loop=loop=5:size=10:start=0
```

11.151 lut1d

对输入视频应用一维 LUT。

该滤镜接受以下选项：

file

设置一维 LUT 文件名。

目前支持的格式：

‘cube’

Iridas

‘csp’

cineSpace

interp

选择插值模式。

可用值如下：

‘nearest’

使用最近的已定义点的值。

‘linear’

使用线性插值来插值数值。

‘cosine’

使用余弦插值来插值数值。

‘cubic’

使用三次插值来插值数值。

‘spline’

使用样条插值来插值数值。

11.151.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.152 lut3d

对输入视频应用三维 LUT。

该滤镜接受以下选项：

file

设置三维 LUT 文件名。

目前支持的格式：

‘3dl’

AfterEffects

‘cube’

Iridas

‘dat’

DaVinci

‘m3d’

Pandora

‘csp’

cineSpace

interp

选择插值模式。

可用值如下：

‘nearest’

使用最近的已定义点的值。

‘trilinear’

使用定义立方体的 8 个点进行插值。

‘tetrahedral’

使用四面体进行插值。

‘pyramid’

使用四棱锥进行插值。

‘prism’

使用三棱柱进行插值。

11.152.1 命令

该滤镜支持将 interp 选项作为命令使用。

11.153 lumakey

将特定的 luma 值转换为透明。

该滤镜接受以下选项：

threshold

设置作为透明基准的 luma 值。默认值为 0。

tolerance

设置要被抠除的 luma 值范围。默认值为 0.01。

softness

设置柔化范围。默认值为 0。用于控制从完全不透明到完全透明的渐变过渡。

11.153.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.154 lut、lutrgb、lutyuv

为将每个像素分量的输入值映射到输出值计算一个查找表，并将其应用于输入视频。

lutyuv 将查找表应用于 YUV 输入视频，lutrgb 应用于 RGB 输入视频。

这些滤镜接受以下参数：

设置第一个像素分量表达式

设置第二个像素分量表达式

设置第三个像素分量表达式

设置第四个像素分量表达式，对应 alpha 分量

设置红色分量表达式

设置绿色分量表达式

设置蓝色分量表达式

alpha 分量表达式

设置 Y/luma 分量表达式

设置 U/Cb 分量表达式

设置 V/Cr 分量表达式

以上每一项都指定用于计算对应像素分量值查找表的表达式。

每个 c* 选项所对应的具体分量取决于输入的格式。

lut 滤镜要求输入为 YUV 或 RGB pixel format，lutrgb 要求输入为 RGB pixel format，lutyuv 要求输入为 YUV。

表达式可以包含以下常量和函数：

w h

输入的宽度和高度。

val

像素分量的输入值。

clipval

裁剪到 minval-maxval 范围内的输入值。

maxval

像素分量的最大值。

minval

像素分量的最小值。

negval

像素分量值取反后再裁剪到 minval-maxval 范围内的值；对应表达式 "maxval-clipval+minval"。

clip(val)

val 中计算得到的值，裁剪到 minval-maxval 范围内。

gammaval(gamma)

像素分量值的伽马校正计算值，裁剪到 minval-maxval 范围内。对应表达式 "pow((clipval-minval)/(maxval-minval)\,gamma)*(maxval-minval)+minval"

所有表达式默认值为 "clipval"。

11.154.1 命令

此滤镜支持与选项相同的命令。

11.154.2 示例

反转输入视频：

lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"

上述效果等同于：

    lutrgb="r=negval:g=negval:b=negval"
    lutyuv="y=negval:u=negval:v=negval"

反转亮度：
```
lutyuv=y=negval
```
移除色度分量，将视频转换为灰阶图像：
```
lutyuv="u=128:v=128"
```
应用亮度加深效果：
```
lutyuv="y=2*val"
```
移除绿色和蓝色分量：
```
lutrgb="g=0:b=0"
```
为输入设置恒定的 alpha 通道值：
```
format=rgba,lutrgb=a="maxval-minval/2"
```
将亮度伽马校正为 0.5 倍：
```
lutyuv=y=gammaval(0.5)
```
丢弃亮度的最低有效位：
```
lutyuv=y='bitand(val, 128+64+32)'
```

类似 Technicolor 的效果：

lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'

11.155 lut2, tlut2

lut2 滤镜接受两个输入流，并输出一个流。

tlut2（time lut2）滤镜从单个流中获取两个连续帧。

此滤镜接受以下参数：

设置第一个像素分量的表达式

设置第二个像素分量的表达式

设置第三个像素分量的表达式

设置第四个像素分量的表达式，对应 alpha 分量

设置输出位深度，仅 lut2 滤镜可用。默认值为 0，表示会根据第一个输入的格式自动选取位深度。

lut2 滤镜还支持 framesync 选项。

每个选项都用于指定计算相应像素分量值查找表所使用的表达式。

c* 各选项对应的具体分量取决于输入的格式。

表达式可以包含以下常量：

w h

输入的宽度和高度。

像素分量的第一个输入值。

像素分量的第二个输入值。

bdx

第一个输入视频的位深度。

bdy

第二个输入视频的位深度。

所有表达式的默认值都是 "x"。

11.155.1 命令

此滤镜支持除 d 之外的以上所有选项作为命令。

11.155.2 示例

高亮两个 RGB 视频流之间的差异：

lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)'

高亮两个 YUV 视频流之间的差异：

lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)'

显示两个视频流之间的最大差异：

lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))'

11.156 maskedclamp

使用第二个和第三个输入流钳制第一个输入流。

将第一个流的值限制在第二个输入流 - undershoot 到第三个输入流 + overshoot 之间并返回。

此滤镜接受以下选项：

undershoot

默认值为 0。

overshoot

默认值为 0。

planes

设置将作为位图处理的平面，未处理的平面将从第一个流中复制。默认值为 0xf，即处理所有平面。

11.156.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.157 maskedmax

使用第二个输入流与第一个输入流之间的绝对差，以及第三个输入流与第一个输入流之间的绝对差，将第二个和第三个输入流合并到输出流中。若第二个绝对差大于第一个，则采用第二个输入流的值，否则采用第三个输入流的值。

此滤镜接受以下选项：

planes

设置将作为位图处理的平面，未处理的平面将从第一个流中复制。默认值为 0xf，即处理所有平面。

11.157.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.158 maskedmerge

使用第三个输入流中逐像素的权重，将第一个输入流与第二个输入流合并。

第三个流像素分量的值为 0 时，表示原样返回第一个流的像素分量；为最大值时（例如 8 位视频为 255），表示原样返回第二个流的像素分量。中间值则决定两个输入流像素分量的合并程度。

此滤镜接受以下选项：

planes

设置将作为位图处理的平面，未处理的平面将从第一个流中复制。默认值为 0xf，即处理所有平面。

11.158.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.159 maskedmin

使用第二个输入流与第一个输入流之间的绝对差，以及第三个输入流与第一个输入流之间的绝对差，将第二个和第三个输入流合并到输出流中。若第二个绝对差小于第一个，则采用第二个输入流的值，否则采用第三个输入流的值。

此滤镜接受以下选项：

planes

设置将作为位图处理的平面，未处理的平面将从第一个流中复制。默认值为 0xf，即处理所有平面。

11.159.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.160 maskedthreshold

通过将两个视频流的绝对差与固定阈值比较来挑选像素。

若第一个和第二个视频流像素分量的绝对差等于或低于用户提供的阈值，则采用第一个视频流的像素分量，否则采用第二个视频流的像素分量。

此滤镜接受以下选项：

threshold

设置根据两个输入视频流的绝对差挑选像素时所使用的阈值。

planes

设置将作为位图处理的平面，未处理的平面将从第二路流中复制。默认值为 0xf，即处理所有平面。

mode

设置滤镜的操作模式，可以是 abs 或 diff。默认值为 abs。

11.160.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.161 maskfun

从输入视频创建蒙版。

例如，可用于在 tblend 滤镜之后创建运动蒙版。

此滤镜接受以下选项：

low

设置低阈值。任何低于或等于该值的像素分量都会被设为 0。

high

设置高阈值。任何高于该值的像素分量都会被设为当前 pixel format 所允许的最大值。

planes

设置要滤波的平面，默认对所有可用平面进行滤波。

fill

用该值填充帧中所有像素。

sum

设置帧的最大平均像素值。若所有像素分量之和高于该平均值，输出帧将完全用 fill 选项设置的值填充。与 tblend 滤镜配合使用时，通常有助于处理场景切换。

11.161.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.162 mcdeint

应用运动补偿去隔行。

它需要每帧一个场作为输入，因此必须与 yadif=1/3 或等效滤镜配合使用。

此滤镜接受以下选项：

mode

设置去隔行模式。

它接受以下值之一：

‘fast’ ‘medium’ ‘slow’

使用迭代运动估计

‘extra_slow’

与 ‘slow’ 类似，但使用多个参考帧。

默认值是 ‘fast’。

parity

设置输入视频所假定的画面场奇偶性，必须是以下值之一：

‘0, tff’

假定顶场在前

‘1, bff’

假定底场在前

默认值是 ‘bff’。

设置内部 encoder 所使用的逐块量化参数（QP）。

值越大，运动矢量场越平滑，但单个矢量的最优性越差。默认值为 1。

11.163 median

从由半径定义的矩形区域中挑选中值像素。

此滤镜接受以下选项：

radius

设置水平半径大小。默认值为 1，允许的范围是 1 到 127 之间的整数。

planes

设置要处理的平面。默认值为 15，即所有可用平面。

radiusV

设置垂直半径大小。默认值为 0，允许的范围是 0 到 127 之间的整数。若为 0，则使用水平方向 radius 选项的值。

percentile

设置中值百分位。默认值为 0.5：默认值 0.5 始终挑选中值，0 挑选最小值，1 挑选最大值。

11.163.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.164 mergeplanes

合并多个视频流的颜色通道分量。

此滤镜最多接受 4 个输入流，并将选定的输入平面合并到输出视频中。

此滤镜接受以下选项：

mapping

设置从输入到输出的平面映射。默认值为 0。

该映射以位图形式指定，应写成 0xAa[Bb[Cc[Dd]]] 形式的十六进制数。’Aa’ 描述输出流第一个平面的映射：’A’ 设置要使用的输入流编号（0 到 3），’a’ 设置对应输入中要使用的平面编号（0 到 3）。其余映射依此类推：’Bb’ 描述输出流第二个平面的映射，’Cc’ 描述输出流第三个平面的映射，’Dd’ 描述输出流第四个平面的映射。

format

设置输出 pixel format。默认值为 yuva444p。

map0s map1s map2s map3s

设置输出第 N 个平面对应的从输入到输出的流映射。默认值为 0。

map0p map1p map2p map3p

设置输出第 N 个平面对应的从输入到输出的平面映射。默认值为 0。

11.164.1 示例

将三个宽高相同的灰度视频流合并为一个视频流：
```
[a0][a1][a2]mergeplanes=0x001020:yuv444p
```
将第 1 个 yuv444p 流和第 2 个灰度视频流合并为 yuva444p 视频流：
```
[a0][a1]mergeplanes=0x00010210:yuva444p
```

交换 yuva444p 流中的 Y 平面和 A 平面：

format=yuva444p,mergeplanes=0x03010200:yuva444p

交换 yuv420p 流中的 U 平面和 V 平面：
```
format=yuv420p,mergeplanes=0x000201:yuv420p
```

将 rgb24 片段转换为 yuv444p：

format=rgb24,mergeplanes=0x000102:yuv444p

11.165 mestimate

使用块匹配算法估计并导出运动矢量。运动矢量存储在帧的侧数据中，供其他滤镜使用。

此滤镜接受以下选项：

method

指定运动估计方法，接受以下值之一：

‘esa’

穷举搜索算法。

‘tss’

三步搜索算法。

‘tdls’

二维对数搜索算法。

‘ntss’

新三步搜索算法。

‘fss’

四步搜索算法。

‘ds’

菱形搜索算法。

‘hexbs’

基于六边形的搜索算法。

‘epzs’

增强预测区域搜索算法。

‘umh’

非均匀多六边形搜索算法。

默认值是 ‘esa’。

mb_size

宏块大小。默认值为 16。

search_param

搜索参数。默认值为 7。

11.166 mestimate_d3d12

使用 D3D12 硬件加速运动估计来估计并导出运动矢量。此滤镜使用 DirectX 12 Video API 提供的 GPU 硬件运动估计能力，相比基于软件的 mestimate 滤镜实现了显著的性能提升。

运动矢量存储在帧的侧数据中，供其他滤镜使用。

此滤镜要求输入为 d3d12 硬件 pixel format。该滤镜以四分之一像素精度进行运动矢量估计。

此滤镜接受以下选项：

mb_size

宏块大小，仅支持 8 和 16。默认值为 16。

11.166.1 示例

使用 D3D12 硬件加速以 16x16 的块估计运动矢量，并将其可视化：

ffmpeg -hwaccel d3d12va -hwaccel_output_format d3d12 -i input.mp4 \
        -vf mestimate_d3d12=mb_size=16,hwdownload,format=nv12,codecview=mv=pf \
        -c:v libx264 -preset fast -b:v 5M output.mp4

11.167 midequalizer

使用两个视频流应用 Midway Image Equalization（中途图像均衡）效果。

Midway Image Equalization 会调整一对图像使其具有相同的直方图，同时尽可能保留各自的动态范围。例如可用于匹配一对立体相机的曝光。

此滤镜有两个输入和一个输出，二者必须使用相同的 pixel format，但尺寸可以不同。该滤镜的输出是用两个输入的中间直方图调整后的第一个输入。

此滤镜接受以下选项：

planes

设置要处理的平面。默认值为 15，即所有可用平面。

11.168 minterpolate

使用运动插值将视频转换为指定的帧率。

此滤镜接受以下选项：

fps

指定输出帧率，可以是有理数，例如 60000/1001。若 fps 低于源视频的 fps，则会丢弃部分帧。默认值为 60。

mi_mode

运动插值模式，接受以下值：

‘dup’

复制前一帧或后一帧以插值生成新帧。

‘blend’

混合源帧。插值帧是前一帧和后一帧的均值。

‘mci’

运动补偿插值。选择此模式时，以下选项生效：

‘mc_mode’

运动补偿模式，接受以下值：

‘obmc’

重叠块运动补偿。

‘aobmc’

自适应重叠块运动补偿。根据相邻运动矢量的可靠性自适应地控制窗口加权系数，以减少过度平滑。

默认模式是 ‘obmc’。

‘me_mode’

运动估计模式，接受以下值：

‘bidir’

双向运动估计。为每个源帧分别在前向和后向估计运动矢量。

‘bilat’

双边运动估计。直接为插值帧估计运动矢量。

默认模式是 ‘bilat’。

‘me’

用于运动估计的算法，接受以下值：

‘esa’

穷举搜索算法。

‘tss’

三步搜索算法。

‘tdls’

二维对数搜索算法。

‘ntss’

新三步搜索算法。

‘fss’

四步搜索算法。

‘ds’

菱形搜索算法。

‘hexbs’

基于六边形的搜索算法。

‘epzs’

增强预测区域搜索算法。

‘umh’

非均匀多六边形搜索算法。

默认算法是 ‘epzs’。

‘mb_size’

宏块大小。默认值为 16。

‘search_param’

运动估计的搜索参数。默认值为 32。

‘vsbmc’

启用可变块大小运动补偿。在物体边界处使用更小的块进行运动估计，以减少边界模糊。默认值为 0（禁用）。

scd

场景切换检测方式。场景切换会使运动矢量指向随机方向。场景切换检测会用复制帧替换插值帧。其他模式可能不需要此选项。接受以下值：

‘none’

禁用场景切换检测。

‘fdiff’

帧差分。比较对应的像素值，若满足 scd_threshold 则判定为发生场景切换。

默认方式是 ‘fdiff’。

scd_threshold

场景切换检测阈值。默认值为 10.。

11.169 mix

将多个视频输入流混合为一个视频流。

接受的选项说明如下。

inputs

输入的数量。若未指定，默认值为 2。

weights

以序列形式指定每个输入视频流的权重，各权重之间用空格分隔。若权重数量少于帧数，则最后指定的权重将用于所有剩余未设置的权重。

scale

指定 scale；若设置了该值，会与各权重乘以像素值之和相乘，得到最终的目标像素值。默认情况下 scale 会自动缩放为权重之和。

planes

设置要滤波的平面。默认为 all。允许的范围是 0 到 15。

duration

指定如何判定流的结束。

‘longest’

最长输入的时长。（默认）

‘shortest’

最短输入的时长。

‘first’

第一个输入的时长。

11.169.1 命令

该滤镜支持以下命令：

weights scale planes

语法与同名选项相同。

11.170 monochrome

使用自定义颜色滤镜将视频转换为灰度。

接受的选项说明如下。

设置蓝色色度点。允许的范围是 -1 到 1。默认值为 0。

设置红色色度点。允许的范围是 -1 到 1。默认值为 0。

size

设置颜色滤镜的大小。允许的范围是 .1 到 10。默认值为 1。

high

设置高光强度。允许的范围是 0 到 1。默认值为 0。

11.170.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.171 morpho

此滤镜允许应用主要的灰度形态学变换 erode（腐蚀）和 dilate（膨胀），可使用第二个输入流中设置的任意结构元素。

与朴素实现相比，erosion 和 dilation 滤镜的性能要慢得多；在速度至关重要时，应改用 morpho 滤镜。

接受的选项说明如下，

mode

设置要应用的形态学变换，可以是：

‘erode’ ‘dilate’ ‘open’ ‘close’ ‘gradient’ ‘tophat’ ‘blackhat’

默认值为 erode。

planes

设置要滤波的平面，默认对除 alpha 之外的所有平面进行滤波。

structure

设置处理第二个输入流中的哪些结构视频帧，可以是 first 或 all。默认值为 all。

morpho 滤镜还支持 framesync 选项。

11.171.1 命令

此滤镜支持与选项相同的命令。

11.172 mpdecimate

丢弃与前一帧差异不大的帧，以降低帧率。

此滤镜主要用于极低比特率的编码（例如通过拨号调制解调器进行流式传输），但理论上也可用于修复被错误地做了逆 telecine（inverse-telecine）处理的影片。

接受的选项说明如下。

max

设置可连续丢弃的帧数上限（若为正值），或丢弃帧之间的最小间隔（若为负值）。若该值为 0，则无论此前已连续丢弃多少帧，都会丢弃当前帧。

默认值为 0。

keep

设置在开始丢弃相似帧之前，可忽略的连续相似帧数上限。若该值为 0，则无论此前已连续出现多少相似帧，都会丢弃当前帧。

默认值为 0。

hi lo frac

设置丢帧的阈值。

hi 和 lo 的值针对 8x8 像素块，表示实际的像素值差异；因此阈值 64 相当于每个像素 1 个单位的差异，或该差异以其他方式分布在整个块中。

若没有任何 8x8 块的差异超过 hi 阈值，且差异超过 lo 阈值的块不超过 frac（1 表示整幅图像），则该帧可作为丢弃候选。

hi 的默认值为 6412，lo 的默认值为 645，frac 的默认值为 0.33。

11.173 msad

求取两个输入视频之间的 MSAD（绝对差总和的平均值）。

此滤镜接受两个输入视频。

要使该滤镜正常工作，两个输入视频必须具有相同的分辨率和 pixel format。此外，该滤镜假定两个输入具有相同的帧数，并逐帧比较。

所求得的按分量、平均、最小和最大 MSAD 会通过日志系统输出。

此滤镜会将每帧计算得到的 MSAD 存储在帧元数据中。

该滤镜还支持 framesync 选项。

在下面的示例中，正在处理的输入文件 main.mpg 会与参考文件 ref.mpg 比较。

ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null -

11.174 multiply

将第一个视频流的像素值与第二个视频流的像素值相乘。

该滤镜接受以下选项：

scale

设置应用于第二个视频流的缩放系数。默认值为 1，允许的范围是 0 到 9。

offset

设置应用于第二个视频流的偏移量。默认值为 0.5，允许的范围是 -1 到 1。

planes

指定输入视频流中要处理的平面。默认处理所有平面。

11.174.1 命令

此滤镜支持与选项相同的命令。

11.175 negate

对输入视频取反（反色）。

它接受以下选项：

components

设置要取反的分量。

components 可用的取值如下：

‘y’ ‘u’ ‘v’ ‘a’ ‘r’ ‘g’ ‘b’ negate_alpha

设为 1 时，如果存在 alpha 分量，则将其取反。默认值为 0。

11.175.1 命令

此滤镜支持与选项相同的命令。

11.176 nlmeans

使用非局部均值（Non-Local Means）算法对帧降噪。

每个像素通过寻找具有相似上下文的其他像素来调整。该上下文相似度通过比较其周围 pxp 大小的图像块来定义。图像块在该像素周围 rxr 大小的区域内搜索。

请注意，搜索区域定义的是图像块的中心，这意味着部分图像块会由该搜索区域之外的像素组成。

该滤镜接受以下选项。

设置降噪强度。默认值为 1.0，取值必须在 [1.0, 30.0] 范围内。

设置图像块大小。默认值为 7，必须是 [0, 99] 范围内的奇数。

与 p 相同，但用于色度平面。

默认值为 0，表示自动。

设置搜索范围大小。默认值为 15，必须是 [0, 99] 范围内的奇数。

与 r 相同，但用于色度平面。

默认值为 0，表示自动。

11.177 nnedi

使用神经网络边缘导向插值对视频去隔行。

此滤镜接受以下选项：

weights

必需选项，没有该二进制文件滤镜将无法工作。目前该文件可在此处找到：https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin

deint

设置要去隔行的帧，默认为 all。可以是 all 或 interlaced。

field

设置操作模式。

可以是以下之一：

‘af’

使用帧标志，处理两个场。

‘a’

使用帧标志，仅处理单个场。

‘t’

仅使用顶场。

‘b’

仅使用底场。

‘tf’

使用两个场，顶场优先。

‘bf’

使用两个场，底场优先。

planes

设置要处理的平面，默认情况下滤镜会处理所有帧。

nsize

设置预测神经网络所使用的、围绕每个像素的局部邻域大小。

可以是以下之一：

‘s8x6’ ‘s16x6’ ‘s32x6’ ‘s48x6’ ‘s8x4’ ‘s16x4’ ‘s32x4’ nns

设置预测神经网络中的神经元数量。可以是以下值之一：

‘n16’ ‘n32’ ‘n64’ ‘n128’ ‘n256’ qual

控制混合在一起以计算最终输出值的不同神经网络预测的数量。可以是 fast（默认）或 slow。

etype

设置预测器中使用的权重集。可以是以下值之一：

‘a, abs’

为最小化绝对误差而训练的权重

‘s, mse’

为最小化平方误差而训练的权重

pscrn

控制是否使用预筛选神经网络来判断哪些像素应由预测神经网络处理，哪些像素可以用简单的三次插值处理。预筛选器经过训练，能够判断某个像素使用三次插值是否已经足够，还是应该交由预测神经网络预测。预筛选神经网络的计算复杂度远低于预测神经网络。由于大多数像素都可以用三次插值处理，使用预筛选器通常能显著加快处理速度。预筛选器相当准确，因此使用与不使用它之间的差异几乎总是难以察觉的。

可以是以下之一：

‘none’ ‘original’ ‘new’ ‘new2’ ‘new3’

默认值为 new。

11.177.1 命令

此滤镜支持与选项相同的命令，但不包括 weights 选项。

11.178 noformat

强制 libavfilter 在向下一个滤镜提供输入时，不使用任何指定的 pixel format。

它接受以下参数：

pix_fmts

以 ’|’ 分隔的 pixel format 名称列表，例如 pix_fmts=yuv420p|monow|rgb24"。

11.178.1 示例

强制 libavfilter 为 vflip 滤镜的输入使用与 yuv420p 不同的格式：
```
noformat=pix_fmts=yuv420p,vflip
```
将输入视频转换为列表中未包含的任意格式：
```
noformat=yuv420p|yuv444p|yuv410p
```

11.179 noise

对输入视频帧添加噪声。

该滤镜接受以下选项：

all_seed c0_seed c1_seed c2_seed c3_seed

为特定像素分量设置噪声种子，若为 all_seed 则应用于所有像素分量。默认值为 123457。

all_strength, alls c0_strength, c0s c1_strength, c1s c2_strength, c2s c3_strength, c3s

为特定像素分量设置噪声强度，若为 all_strength 则应用于所有像素分量。默认值为 0，允许的范围是 [0, 100]。

all_flags, allf c0_flags, c0f c1_flags, c1f c2_flags, c2f c3_flags, c3f

设置像素分量的标志，若为 all_flags 则为所有分量设置标志。分量标志可用的值如下：

‘a’

时间方向平均噪声（更平滑）

‘p’

将随机噪声与（半）规则图案混合

‘t’

时间方向噪声（噪声图案在帧间变化）

‘u’

均匀噪声（否则为高斯噪声）

11.179.1 示例

为输入视频添加时间方向噪声和均匀噪声：

noise=alls=20:allf=t+u

11.180 normalize

对 RGB 视频进行归一化（又称直方图拉伸、对比度拉伸）。参见：https://en.wikipedia.org/wiki/Normalization_(image_processing)

对每一帧的每个通道，此滤镜都会计算输入范围，并将其线性映射到用户指定的输出范围。输出范围默认是从纯黑到纯白的完整动态范围。

可以对输入范围使用时间方向平滑，以减少因较小的暗部或亮部物体进入或离开画面而产生的闪烁（亮度的急剧变化）。这与摄像机的自动曝光（自动增益控制）类似，并且与摄像机一样，可能会导致视频出现一段过曝或欠曝的时间。

R、G、B 通道可以独立归一化，这可能会导致一定的偏色，也可以作为单一通道联动归一化，从而避免偏色。联动归一化会保留色相，独立归一化则不会，因此可以用来去除某些偏色。独立归一化和联动归一化可以按任意比例组合。

normalize 滤镜接受以下选项：

blackpt whitept

定义输出范围的颜色。最小输入值会映射到 blackpt，最大输入值会映射到 whitept。默认值分别为黑色和白色。将 blackpt 指定为白色、whitept 指定为黑色，会得到颜色反转的归一化视频。使用灰色调可以缩小动态范围（对比度）。在此指定饱和色可以创造一些有趣的效果。

smoothing

用于时间方向平滑的先前帧数。每个通道的输入范围会使用当前帧和之前 smoothing 帧的滚动平均值进行平滑。默认值为 0（不进行时间方向平滑）。

independence

控制独立（会偏色）通道归一化与联动（保色）归一化之间的比例。0.0 表示完全联动，1.0 表示完全独立。默认值为 1.0（完全独立）。

strength

滤镜的整体强度。1.0 为完全强度，0.0 相当于一个开销较大的空操作（no-op）。默认值为 1.0（完全强度）。

11.180.1 命令

此滤镜支持与选项相同的命令，但不包括 smoothing 选项。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.180.2 示例

在没有时间方向平滑的情况下，将视频对比度拉伸到完整动态范围；根据源内容不同，画面可能会闪烁：

normalize=blackpt=black:whitept=white:smoothing=0

同上，但使用 50 帧的时间方向平滑；根据源内容不同，闪烁应会有所减少：

normalize=blackpt=black:whitept=white:smoothing=50

同上，但使用保留色相的联动通道归一化：

normalize=blackpt=black:whitept=white:smoothing=50:independence=0

同上，但强度减半：

normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5

将最暗的输入颜色映射为红色，最亮的输入颜色映射为青色：

normalize=blackpt=red:whitept=cyan

11.181 null

将视频源不加改变地传递到输出。

11.182 ocio

OpenColorIO 库滤镜

此滤镜允许你使用 OpenColorIO 库来管理色彩。更多详情请参见 https://opencolorio.org/。要启用此滤镜的编译，需要在 configure FFmpeg 时加上 --enable-libopencolorio。

它接受以下选项：

config

默认情况下，滤镜会使用由 OCIO 环境变量定义的 OCIO 配置，但此参数允许你显式指定其位置。如果你刚开始使用，可以使用 config=ocio://studio-config-v1.0.0_aces-v1.3_ocio-v2.1，它指定了一个内置的默认配置。

input

设置输入色彩空间。

output

设置输出色彩空间。

display

设置显示色彩空间，与 view 配合使用。

view

设置视图色彩空间，与 display 配合使用。

inverse

与 display 和 view 组合使用时，此选项会反转变换，即从 display/view 转换到 "input colorspace"。

filetransform

允许你指定一个外部的文件变换（file-transform），以代替 OCIO 配置文件使用。这在只需应用单个变换、而不需要完整 OCIO 配置文件的场景中很有用。

format

允许你指定 OCIO 滤镜的输出 pix_fmt。它必须是 RGB 色彩空间，因此实际上只能限于 rgb24, rgba, rgb48, rgba48, gbrp10, gbrp12, gbrpf32le, gbrapf32le，对大多数编码场景我们推荐使用 rgb48

context_params

允许你为 OCIO 滤镜指定额外的上下文参数。这是一个以冒号分隔的 key=value 键值对列表。

11.182.1 示例

从 ACEScg 映射到 ACEScct，此示例假定 OCIO 文件已通过 OCIO 环境变量定义。

input=ACEScg:output=ACEScct:format=rgb48

使用 "ACES 1.0 - SDR Video" 视图变换，从 ACEScg 映射到 sRGB 显示，此示例假定 OCIO 文件已通过 OCIO 环境变量定义。请注意，为确保空格被正确解释，你需要用引号将参数括起来。

input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48

同上，但使用 OCIO 文件 studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio，而不是 OCIO 环境变量。

config=studio-config-v1.0.0_aces-v1.3_ocio-v2.1_ns.ocio:input=ACEScg:display=sRGB - Display:view=ACES 1.0 - SDR Video:format=rgb48

如果要转换为 YCrCb，你仍然需要为该转换设置色彩矩阵。下面是一个很好的示例，展示了如何将两者结合使用。

ffmpeg -y -i SOURCEFRAMES.%05d.exr -c:v libx265 -vf "ocio=input=ACEScg:output=ACEScct:format=rgb48,scale=in_color_matrix=bt709:out_color_matrix=bt709,format=yuv444p10"  OUTPUTFILE.mov

11.183 ocr

光学字符识别（OCR）

此滤镜使用 Tesseract 进行光学字符识别。要启用此滤镜的编译，需要在 configure FFmpeg 时加上 --enable-libtesseract。

它接受以下选项：

datapath

设置 tesseract 数据的 datapath。默认使用安装时设置的值。

language

设置语言，默认为 "eng"。

whitelist

设置字符白名单。

blacklist

设置字符黑名单。

此滤镜会将识别出的文本导出为帧元数据 lavfi.ocr.text，并将识别出的单词的置信度导出为帧元数据 lavfi.ocr.confidence。

11.184 ocv

使用 libopencv 应用视频变换。

要启用此滤镜，需要安装 libopencv 库及其头文件，并在 configure FFmpeg 时加上 --enable-libopencv。

它接受以下参数：

filter_name

要应用的 libopencv 滤镜的名称。

filter_params

传递给 libopencv 滤镜的参数。如果未指定，则假定使用默认值。

更精确的信息请参见 libopencv 官方文档：http://docs.opencv.org/master/modules/imgproc/doc/filtering.html

支持多个 libopencv 滤镜；请参见以下各小节。

11.184.1 dilate

使用特定的结构元素膨胀图像。对应于 libopencv 函数 cvDilate。

接受参数：struct_el|nb_iterations。

struct_el 表示一个结构元素，其语法为：colsxrows+anchor_xxanchor_y/shape

cols 和 rows 表示结构元素的列数和行数，anchor_x 和 anchor_y 表示锚点，shape 表示结构元素的形状。shape 必须是 "rect"、"cross"、"ellipse" 或 "custom" 之一。

如果 shape 的值为 "custom"，其后必须跟一个形如 "=filename" 的字符串。名为 filename 的文件被假定表示一幅二值图像，每个可打印字符对应一个亮像素。使用自定义形状时，cols 和 rows 会被忽略，转而使用所读取文件的列数和行数。

struct_el 的默认值为 "3x3+0x0/rect"。

nb_iterations 指定该变换应用于图像的次数，默认值为 1。

一些示例：

# 使用默认值
ocv=dilate

# 使用 5x5 十字形结构元素，迭代两次进行膨胀
ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2

# 从文件 diamond.shape 读取形状，迭代两次。
# 文件 diamond.shape 中可以包含如下字符图案
#   *
#  ***
# *****
#  ***
#   *
# 指定的列数和行数会被忽略，
# 但锚点坐标不会
ocv=dilate:0x0+2x2/custom=diamond.shape|2

11.184.2 erode

使用特定的结构元素腐蚀图像。对应于 libopencv 函数 cvErode。

接受参数：struct_el:nb_iterations，其语法和语义与 dilate 滤镜相同。

11.184.3 smooth

平滑输入视频。

此滤镜接受以下参数：type|param1|param2|param3|param4。

type 是要应用的平滑滤镜类型，必须是以下值之一："blur"、"blur_no_scale"、"median"、"gaussian" 或 "bilateral"。默认值为 "gaussian"。

param1、param2、param3 和 param4 的含义取决于 smooth 的 type。param1 和 param2 接受正整数或 0，param3 和 param4 接受浮点数值。

param1 的默认值为 3，其他参数的默认值为 0。

这些参数对应于赋给 libopencv 函数 cvSmooth 的参数。

11.185 oscilloscope

2D 视频示波器。

可用于测量空间脉冲响应、阶跃响应、色度延迟等。

它接受以下参数：

设置示波器中心的 x 位置。

设置示波器中心的 y 位置。

设置示波器大小，相对于帧对角线的比例。

设置示波器的倾斜/旋转角度。

设置轨迹的不透明度。

设置轨迹中心的 x 位置。

设置轨迹中心的 y 位置。

设置轨迹宽度，相对于帧宽度的比例。

设置轨迹高度，相对于帧高度的比例。

设置要追踪的分量。默认追踪前三个分量。

绘制轨迹网格。默认启用。

绘制一些统计信息。默认启用。

绘制示波器。默认启用。

11.185.1 命令

该滤镜支持与选项相同的命令。命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.185.2 示例

检查视频帧的完整第一行。
```
oscilloscope=x=0.5:y=0:s=1
```
检查视频帧的完整最后一行。
```
oscilloscope=x=0.5:y=1:s=1
```
检查高度为 1080 的视频帧的完整第 5 行。
```
oscilloscope=x=0.5:y=5/1080:s=1
```
检查视频帧的完整最后一列。
```
oscilloscope=x=1:y=0.5:s=1:t=1
```

11.186 overlay

将一个视频叠加在另一个视频之上。

它接受两个输入并产生一个输出。第一个输入是 "main"（主）视频，第二个输入叠加在其上。

它接受以下参数：

接受的选项说明如下。

x y

设置被叠加视频在主视频上的 x、y 坐标表达式。两个表达式的默认值均为 "0"。如果表达式无效，则设为一个极大的值（即叠加内容不会显示在输出的可见区域内）。

eof_action

参见 framesync。

eval

设置 x、y 表达式的求值时机。

可接受的值有：

‘init’

仅在滤镜初始化期间或处理命令时对表达式求值一次。

‘frame’

对每个输入帧都求值表达式

默认值为 ‘frame’。

shortest

参见 framesync。

format

设置输出视频的格式。

可接受的值有：

‘yuv420’

强制 YUV 4:2:0 8-bit 平面输出

‘yuv420p10’

强制 YUV 4:2:0 10-bit 平面输出

‘yuv422’

强制 YUV 4:2:2 8-bit 平面输出

‘yuv422p10’

强制 YUV 4:2:2 10-bit 平面输出

‘yuv444’

强制 YUV 4:4:4 8-bit 平面输出

‘yuv444p10’

强制 YUV 4:4:4 10-bit 平面输出

‘rgb’

强制 RGB 8-bit 紧缩（packed）输出

‘gbrp’

强制 RGB 8-bit 平面输出

‘auto’

自动选择格式

默认值为 ‘yuv420’。

repeatlast

参见 framesync。

alpha

设置被叠加视频的 alpha 格式，可以是 straight 或 premultiplied，也可以是 auto 以自动选择 alpha 模式。默认值为 auto。

x、y 表达式可以包含以下参数。

main_w, W main_h, H

主输入的宽度和高度。

overlay_w, w overlay_h, h

叠加输入的宽度和高度。

x y

x 和 y 的计算值。它们在每个新帧都会被求值。

hsub vsub

输出格式的水平和垂直色度二次采样值。例如 pixel format "yuv422p" 的 hsub 为 2，vsub 为 1。

输入帧的编号，从 0 开始

pos

输入帧在文件中的位置，未知时为 NAN；已弃用，请勿使用

以秒为单位表示的时间戳。如果输入时间戳未知，则为 NAN。

该滤镜还支持 framesync 选项。

请注意，n、t 变量仅在按每帧求值时可用，当 eval 设为 ‘init’ 时会求值为 NAN。

请注意，帧是按时间戳顺序从每个输入视频中取出的，因此如果它们的初始时间戳不同，最好将两个输入都通过 setpts=PTS-STARTPTS 滤镜处理，使它们从相同的零时间戳开始，正如 movie 滤镜的示例所做的那样。

你可以将多个 overlay 串联在一起，但应测试这种方式的效率。

11.186.1 命令

该滤镜支持以下命令：

x y

修改叠加输入的 x 和 y。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.186.2 示例

在距主视频右下角 10 像素处绘制叠加内容：
```
overlay=main_w-overlay_w-10:main_h-overlay_h-10
```

使用具名选项，上面的示例可写成：

    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10

使用 ffmpeg 工具及 -filter_complex 选项，在输入左下角插入一张透明 PNG 徽标：
```
ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
```

使用 ffmpeg 工具插入两张不同的透明 PNG 徽标（第二张位于右下角）：

ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output

在主视频上方添加一个透明色层；WxH 必须指定 overlay 滤镜的主输入尺寸：
```
color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
```
使用 ffplay 工具并排播放原始视频和经过滤镜处理的版本（此处使用 deshake 滤镜）：
```
ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
```

上面的命令等价于：

    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'

制作一个从时刻 2 开始、由左向右滑动出现在屏幕右上部分的叠加效果：
```
overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
```

将两个输入视频并排放置以合成输出：

ffmpeg -i left.avi -i right.avi -filter_complex "
nullsrc=size=200x100 [background];
[0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
[1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
[background][left]       overlay=shortest=1       [background+left];
[background+left][right] overlay=shortest=1:x=100 [left+right]
"

通过对某个片段应用 delogo 滤镜，遮蔽视频 10-20 秒的区间

ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
-vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
masked.avi

将多个叠加操作串联成级联结构：

nullsrc=s=200x200 [bg];
testsrc=s=100x100, split=4 [in0][in1][in2][in3];
[in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
[in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
[in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
[in3] null,       [mid2] overlay=100:100 [out0]

11.187 owdenoise

应用过完备小波（Overcomplete Wavelet）降噪器。

该滤镜接受以下选项：

depth

设置深度。

depth 值越大，对低频分量的降噪效果越强，但滤镜处理速度也会随之变慢。

必须是 8-16 范围内的整数，默认值为 8。

luma_strength, ls

设置亮度强度。

必须是 0-1000 范围内的双精度浮点值，默认值为 1.0。

chroma_strength, cs

设置色度强度。

必须是 0-1000 范围内的双精度浮点值，默认值为 1.0。

11.188 pad

在输入图像上添加填充，并将原始输入放置在指定的 x, y 坐标处。

它接受以下参数：

width, w height, h

指定添加填充后输出图像尺寸的表达式。如果 width 或 height 的值为 0，则输出使用对应的输入尺寸。

width 表达式可以引用 height 表达式设置的值，反之亦然。

width 和 height 的默认值为 0。

x y

指定将输入图像放置在填充区域内的偏移量，相对于输出图像的左上边界。

x 表达式可以引用 y 表达式设置的值，反之亦然。

x 和 y 的默认值为 0。

如果 x 或 y 求值为负数，会自动调整为使输入图像居中于填充区域。

color

指定填充区域的颜色。此选项的语法请参阅 ffmpeg-utils 手册中的 “Color” 一节。

color 的默认值为 "black"。

eval

指定何时对 width、height、x 和 y 表达式求值。

可接受的值有：

‘init’

仅在滤镜初始化时或处理命令时对表达式求值一次。

‘frame’

对每个输入帧都求值表达式。

默认值为 ‘init’。

aspect

按宽高比而非分辨率进行填充。

width、height、x 和 y 选项的值是包含以下常量的表达式：

in_w in_h

输入视频的宽度和高度。

iw ih

与 in_w 和 in_h 相同。

out_w out_h

由 width 和 height 表达式指定的输出宽度和高度（即填充区域的尺寸）。

ow oh

与 out_w 和 out_h 相同。

x y

由 x 和 y 表达式指定的 x、y 偏移量，若尚未指定则为 NAN。

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，与 (iw / ih) * sar 相同

hsub vsub

水平和垂直的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

11.188.1 示例

为输入视频添加颜色为 "violet" 的填充。输出视频尺寸为 640x480，输入视频的左上角放置在第 0 列、第 40 行
```
pad=640:480:0:40:violet
```

上面的示例等价于以下命令：

    pad=width=640:height=480:x=0:y=40:color=violet

对输入进行填充，得到尺寸放大为 3/2 倍的输出，并将输入视频放在填充区域的中央：
```
pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
```
对输入进行填充，得到边长等于输入宽度和高度中较大值的正方形输出，并将输入视频放在填充区域的中央：
```
pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
```
对输入进行填充，使最终的 w/h 比为 16:9：
```
pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
```
对于变形（anamorphic）视频，为了正确设置输出的显示宽高比，需要按照以下关系在表达式中使用 sar：
```
(ih * X / ih) * sar = output_dar
X = output_dar / sar
```

因此前面的示例需要修改为：

    pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"

将输出尺寸加倍，并将输入视频放在输出填充区域的右下角：
```
pad="2*iw:2*ih:ow-iw:oh-ih"
```

11.189 palettegen

为整个视频流生成一个调色板。

它接受以下选项：

max_colors

设置调色板中量化的最大颜色数。注意：调色板仍将包含 256 种颜色；未使用的调色板项将为黑色。

reserve_transparent

创建最多 255 种颜色的调色板，并保留最后一个颜色用于透明。保留透明色有助于 GIF 优化。如果未设置，调色板中的最大颜色数将为 256。对于单独的图像，你可能希望禁用此选项。默认已设置。

transparency_color

设置用作透明背景的颜色。

stats_mode

设置统计模式。

可接受的值有：

‘full’

计算完整帧的直方图。

‘diff’

只对与前一帧不同的部分计算直方图。如果背景是静态的，这有助于让输入中移动的部分获得更高的权重。

‘single’

为每一帧都计算新的直方图。

默认值为 full。

该滤镜还会导出帧元数据 lavfi.color_quant_ratio（nb_color_in / nb_color_out），可用于评估调色板的颜色量化程度。该信息在 info 日志级别下也可见。

11.189.1 示例

使用 ffmpeg 为给定视频生成具有代表性的调色板：
```
ffmpeg -i input.mkv -vf palettegen palette.png
```

11.190 paletteuse

使用调色板对输入视频流进行降采样。

该滤镜接受两个输入：一个视频流和一个调色板。调色板必须是一张 256 像素的图像。

它接受以下选项：

dither

选择抖动模式。可用的算法有：

‘bayer’

有序 8x8 bayer 抖动（确定性）

‘heckbert’

由 Paul Heckbert 于 1982 年定义的抖动算法（简单误差扩散）。注意：这种抖动有时被认为是“错误的”，此处仅作为参考收录。

‘floyd_steinberg’

Floyd 和 Steinberg 抖动（误差扩散）

‘sierra2’

Frankie Sierra 抖动 v2（误差扩散）

‘sierra2_4a’

由 Frankie Sierra 提出的抖动 v2 "Lite" 版（误差扩散）

‘sierra3’

Frankie Sierra 抖动 v3（误差扩散）

‘burkes’

Burkes 抖动（误差扩散）

‘atkinson’

由 Apple Computer 的 Bill Atkinson 提出的 Atkinson 抖动（误差扩散）

‘none’

禁用抖动。

默认值为 sierra2_4a。

bayer_scale

选择 bayer 抖动时，此选项定义图案的比例（即交叉阴影图案的可见程度）。较低的值意味着图案更明显但色带更少，较高的值意味着图案更不明显但代价是色带增多。

该选项必须是 [0,5] 范围内的整数值。默认值为 2。

diff_mode

如果设置，则定义要处理的区域

‘rectangle’

只有发生变化的矩形区域会被重新处理。这类似于 GIF 的裁剪/偏移压缩机制。如果图像中只有一部分发生变化，此选项有助于提升速度，其应用场景包括将误差扩散抖动的范围限制在包含运动场景的矩形内（如果场景变化不大，这会使输出更具确定性，从而减少运动噪声并提升 GIF 压缩效果）。

默认值为 none。

new

每个输出帧都使用新的调色板。

alpha_threshold

设置用于透明的 alpha 阈值。高于此阈值的 alpha 值将被视为完全不透明，低于此阈值的值将被视为完全透明。

该选项必须是 [0,255] 范围内的整数值。默认值为 128。

11.190.1 示例

使用调色板（例如由 palettegen 生成）配合 ffmpeg 编码 GIF：
```
ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
```

11.191 perspective

校正未垂直于屏幕拍摄的视频的透视。

下面是所接受参数的说明。

x0 y0 x1 y1 x2 y2 x3 y3

设置左上、右上、左下和右下角的坐标表达式。默认值为 0:0:W:0:0:H:W:H，此时透视保持不变。如果 sense 选项设置为 source，则指定的点将被发送到目标的各角。如果 sense 选项设置为 destination，则源的各角将被发送到指定的坐标。

表达式可以使用以下变量：

W H

视频帧的宽度和高度。

输入帧计数。

输出帧计数。

interpolation

设置透视校正使用的插值方式。

可接受的值有：

‘linear’ ‘cubic’

默认值为 ‘linear’。

sense

设置坐标选项的解释方式。

可接受的值有：

‘0, source’

将源中由给定坐标指定的点发送到目标的各角。

‘1, destination’

将源的各角发送到目标中由给定坐标指定的点。

默认值为 ‘source’。

eval

设置坐标 x0,y0,...x3,y3 的表达式何时求值。

可接受的值有：

‘init’

仅在滤镜初始化期间或处理命令时对表达式求值一次。

‘frame’

对每个输入帧都求值表达式

默认值为 ‘init’。

11.192 phase

将隔行视频延迟一个场时间，从而改变场顺序。

其目的用途是修复采集时场顺序与胶转磁（film-to-video）顺序相反的 PAL 影片。

下面是所接受参数的说明。

mode

设置 phase 模式。

可接受的值有：

‘t’

采集场顺序为顶场优先，转换为底场优先。滤镜将延迟底场。

‘b’

采集场顺序为底场优先，转换为顶场优先。滤镜将延迟顶场。

‘p’

采集和转换使用相同的场顺序。此模式仅用于文档中供其他选项参照，如果实际选择它，滤镜将什么都不做。

‘a’

采集场顺序由场标志自动确定，转换为相反顺序。滤镜会根据场标志逐帧在 ‘t’ 和 ‘b’ 模式之间选择。如果没有可用的场信息，则效果等同于 ‘u’。

‘u’

采集顺序未知或不定，转换为相反顺序。滤镜会通过分析图像逐帧在 ‘t’ 和 ‘b’ 之间选择能使场之间匹配度最佳的一项。

‘T’

采集为顶场优先，转换顺序未知或不定。滤镜通过图像分析在 ‘t’ 和 ‘p’ 之间选择。

‘B’

采集为底场优先，转换顺序未知或不定。滤镜通过图像分析在 ‘b’ 和 ‘p’ 之间选择。

‘A’

采集顺序由场标志确定，转换顺序未知或不定。滤镜通过场标志和图像分析在 ‘t’、‘b’ 和 ‘p’ 之间选择。如果没有可用的场信息，则效果等同于 ‘U’。这是默认模式。

‘U’

采集和转换均未知或不定。滤镜仅通过图像分析在 ‘t’、‘b’ 和 ‘p’ 之间选择。

11.192.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.193 photosensitivity

减少视频中的各种闪烁，以帮助患有癫痫的用户。

它接受以下选项：

frames, f

设置滤波时使用的帧数。默认值为 30。

threshold, t

设置检测阈值系数。默认值为 1。值越低越严格。

skip

设置采样帧时跳过的像素数。默认值为 1。允许的范围是 1 到 1024。

bypass

保持帧不变。默认禁用。

11.194 pixdesctest

pixel format 描述符测试滤镜，主要用于内部测试。输出视频应与输入视频相同。

例如：

format=monow, pixdesctest

可用于测试 monowhite pixel format 描述符定义。

11.195 pixelize

对视频流应用像素化。

该滤镜接受以下选项：

width, w height, h

设置用于像素化的块尺寸。默认值为 16。

mode, m

设置所使用的像素化模式。

可接受的值有：

‘avg’ ‘min’ ‘max’

默认值为 avg。

planes, p

设置要滤波的平面。默认对所有平面进行滤波。

11.195.1 命令

该滤镜支持将所有选项用作命令。

11.196 pixscope

显示颜色通道的样本值。主要用于检查颜色和电平。支持的最小分辨率为 640x480。

这些滤镜接受以下选项：

设置示波区域的 X 位置，即 X 轴上的相对偏移。

设置示波区域的 Y 位置，即 Y 轴上的相对偏移。

设置示波区域的宽度。

设置示波区域的高度。

设置窗口不透明度。该窗口还保存像素区域的统计信息。

设置窗口的 X 位置，即 X 轴上的相对偏移。

设置窗口的 Y 位置，即 Y 轴上的相对偏移。

11.196.1 命令

此滤镜支持与选项相同的命令。

11.197 pp7

应用后处理滤镜 7（Postprocessing filter 7）。它是 spp 滤镜的变体，类似于 spp = 6 并采用 7 点 DCT，在 IDCT 之后只使用中心样本。

该滤镜接受以下选项：

强制使用恒定的量化参数。它接受 0 到 63 范围内的整数。如果未设置，滤镜将使用视频流中的 QP（如果可用）。

mode

设置阈值处理模式。可用的模式有：

‘hard’

设置硬阈值处理。

‘soft’

设置软阈值处理（去振铃效果更好，但可能更模糊）。

‘medium’

设置中等阈值处理（效果良好，为默认值）。

11.198 premultiply

使用第二个流的第一个平面作为 alpha，对输入视频流应用 alpha 预乘效果。

两个流必须具有相同的尺寸和相同的 pixel format。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

inplace

处理时不需要第二个输入，而是使用输入流自身的 alpha 平面。

11.199 premultiply_dynamic

根据下游滤镜图的需求，按需对输入视频流动态进行预乘或取消预乘。这大致等价于 premultiply:inplace=yes 或 unpremultiply:inplace=yes，否则就是空操作（noop）。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

11.200 prewitt

对输入视频流应用 prewitt 算子。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

scale

设置与滤波结果相乘的值。

delta

设置与滤波结果相加的值。

11.200.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.201 pseudocolor

使用伪彩色改变视频中的帧颜色。

此滤镜接受以下选项：

设置像素第一分量的表达式

设置像素第二分量的表达式

设置像素第三分量的表达式

设置像素第四分量的表达式，对应 alpha 分量

index, i

设置用作改变颜色基准的分量

preset, p

选择一个内置 LUT。默认设置为 none。

可用的 LUT 有：

‘magma’ ‘inferno’ ‘plasma’ ‘viridis’ ‘turbo’ ‘cividis’ ‘range1’ ‘range2’ ‘shadows’ ‘highlights’ ‘solar’ ‘nominal’ ‘preferred’ ‘total’ ‘spectral’ ‘cool’ ‘heat’ ‘fiery’ ‘blues’ ‘green’ ‘helix’ opacity

设置输出颜色的不透明度。允许的范围是 0 到 1。默认值设置为 1。

每个表达式选项都指定用于计算相应像素分量值查找表的表达式。

表达式可以包含以下常量和函数：

w h

输入的宽度和高度。

val

像素分量的输入值。

ymin, umin, vmin, amin

分量允许的最小值。

ymax, umax, vmax, amax

分量允许的最大值。

所有表达式默认取 "val"。

11.201.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.201.2 示例

将过高的亮度值转换为渐变：

pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"

11.202 psnr

获取两个输入视频之间的平均、最大和最小 PSNR（峰值信噪比）。

该滤镜接受两个输入视频，第一个输入被视为“主”源，并原样传递到输出。第二个输入用作计算 PSNR 的“参考”视频。

要使该滤镜正常工作，两个视频输入必须具有相同的分辨率和 pixel format。此外还假定两个输入具有相同的帧数，逐帧进行比较。

得到的平均 PSNR 会通过日志系统输出。

该滤镜会存储每一帧累积的 MSE（均方误差），处理结束时对所有帧进行等权平均，并应用以下公式得到 PSNR：

PSNR = 10*log10(MAX^2/MSE)

其中 MAX 是图像各分量最大值的平均值。

以下是所接受参数的说明。

stats_file, f

如果指定，该滤镜会将每一帧的 PSNR 保存到指定文件。当文件名等于 "-" 时，数据会被发送到标准输出。

stats_version

指定要使用的统计文件格式版本。每种格式的细节见下文。默认值为 1。

output_max

决定是否将最大值输出到统计日志。默认值为 0。需要 stats_version >= 2。如果设置了此项而 stats_version < 2，滤镜将返回错误。

该滤镜还支持 framesync 选项。

如果选择了 stats_file，输出的文件针对每一对比较的帧包含一系列 key:value 形式的键值对。

如果指定的 stats_version 大于 1，逐帧对统计信息列表前会有一行头部，其键值对遵循帧格式，包含以下参数：

psnr_log_version

日志文件格式的版本。与 stats_version 一致。

fields

日志中包含的逐帧对参数的逗号分隔列表。

以下是所显示的每个逐帧对参数的说明：

输入帧的序号，从 1 开始

mse_avg

被比较帧逐像素差异的均方误差，在图像所有分量上取平均。

mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a

被比较帧中由后缀指定分量的逐像素差异均方误差。

psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a

被比较帧中由后缀指定分量的峰值信噪比。

max_avg, max_y, max_u, max_v

各通道允许的最大值，以及所有通道的平均值。

11.202.1 示例

例如：

movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
[main][ref] psnr="stats_file=stats.log" [out]

在此示例中，正在处理的输入文件会与参考文件 ref_movie.mpg 进行比较。每一帧的 PSNR 都存储在 stats.log 中。

另一个使用不同容器的示例：

ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -

11.203 pullup

反下拉（逆胶转磁，inverse telecine）滤镜，能够处理混合硬性胶转磁、24000/1001 fps 逐行以及 30000/1001 fps 逐行内容。

pullup 滤镜的设计利用了未来上下文来做出判断。该滤镜在不锁定某种模式来跟随这一意义上是无状态的，而是向前查看后续的场，以识别匹配并重建逐行帧。

为生成帧率均匀的内容，请在 pullup 之后插入 fps 滤镜；如果输入帧率为 29.97fps，使用 fps=24000/1001；对于 30fps 以及（罕见的）经过胶转磁处理的 25fps 输入，使用 fps=24。

该滤镜接受以下选项：

jl jr jt jb

这些选项分别设置图像左、右、上、下要忽略的“垃圾”量。左右以 8 像素为单位，上下以 2 行为单位。默认每边为 8 像素。

设置严格断点（strict breaks）。将此选项设为 1 会降低滤镜偶尔生成不匹配帧的概率，但也可能导致在高运动场景中丢弃过多的帧。相反，将其设为 -1 会让滤镜更容易匹配场。这有助于处理场之间存在轻微模糊的视频，但也可能导致输出中出现隔行帧。默认值为 0。

设置要使用的度量平面。它接受以下值：

‘l’

使用亮度平面。

‘u’

使用蓝色度平面。

‘v’

使用红色度平面。

可以设置此选项，使滤镜的计算使用色度平面而不是默认的亮度平面。这在源素材非常干净时可能会提高精度，但更多情况下会降低精度，尤其是在存在色度噪声（彩虹效应）或任何灰度视频时。将 mp 设为色度平面的主要目的是降低 CPU 负载，使 pullup 能在较慢的机器上实时使用。

为获得最佳效果（输出文件中不出现重复帧），需要更改输出帧率。例如，对 NTSC 输入进行反胶转磁：

ffmpeg -i input -vf pullup -r 24000/1001 ...

11.204 qp

更改视频的量化参数（QP）。

该滤镜接受以下选项：

设置量化参数的表达式。

该表达式通过 eval API 求值，其中可以包含以下常量（等等）：

known

如果 index 不为 129 则为 1，否则为 0。

从 -129 到 128 的连续索引。

11.204.1 示例

例如下面这样的表达式：
```
qp=2+2*sin(PI*qp)
```

11.205 qrencode

使用 libqrencode 库（参见 https://fukuchi.org/works/qrencode/）生成二维码，并将其叠加到当前帧之上。

要启用此滤镜的编译，需要在 configure FFmpeg 时指定 --enable-libqrencode。

二维码根据提供的文本或文本模式生成，并按照指定的选项缩放后叠加到视频输出中。

如果未指定文本，则不会叠加二维码。

此滤镜接受以下选项：

qrcode_width, q padded_qrcode_width, Q

分别为渲染后二维码有填充和无填充时的宽度指定表达式。qrcode_width 表达式可以引用 padded_qrcode_width 表达式设置的值，反之亦然。默认情况下 padded_qrcode_width 被设置为 qrcode_width，即没有填充。

这些表达式在每个新帧都会求值。

详情请参阅 qrencode 表达式一节。

x y

为带填充的二维码左上角的定位指定表达式。x 表达式可以引用 y 表达式设置的值，反之亦然。

默认情况下 x 和 y 都设置为 0，即二维码放置在输入的左上角。

这些表达式在每个新帧都会求值。

详情请参阅 qrencode 表达式一节。

case_sensitive, cs

指示 libqrencode 使用区分大小写的编码。默认启用此选项，可以禁用以减小二维码的编码尺寸。

level, l

指定二维码编码的纠错级别。纠错级别越高，编码尺寸越大，但二维码对损坏的容错能力也越强。最低级别是 L。

可接受的值有：

‘L’ ‘M’ ‘Q’ ‘H’ expansion

选择输入文本的展开方式，可以是 none，也可以是 normal（默认）。详情请参阅下方的 qrencode 文本展开一节。

text textfile

定义要渲染的文本。如果两者都未指定，则不编码二维码（仅输出一个纯色空帧）。

如果启用了展开功能，文本将使用 qrencode 的展开机制作为文本模板处理。详情请参阅下方的 qrencode 文本展开一节。

background_color, bc foreground_color, fc

设置二维码颜色和背景颜色。foreground_color 的默认值为 "black"，background_color 的默认值为 "white"。

关于颜色选项的语法，请参阅 (ffmpeg-utils)ffmpeg-utils 手册中的 "Color" 一节。

11.205.1 qrencode 表达式

由选项设置的表达式可以包含以下常量和函数。

dar

输入的显示宽高比，与 (w / h) * sar 相同

duration

当前帧的持续时间（秒）

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

main_h, H

输入的高度

main_w, W

输入的宽度

输入帧的编号，从 0 开始

pict_type

表示图像类型的数值

qr_w, w

编码后二维码的宽度

rendered_qr_w, q rendered_padded_qr_w, Q

渲染后二维码的宽度（无填充和有填充两种情况）。

这些参数使得 q 和 Q 表达式可以相互引用，因此可以指定例如 q=3/4*Q。

rand(min, max)

返回一个介于 min 和 max 之间的随机数

sar

输入的采样宽高比

以秒为单位表示的时间戳；如果输入时间戳未知则为 NAN

x y

绘制文本的 x、y 偏移坐标。

这些参数使得 x 和 y 表达式可以相互引用，因此可以指定例如 y=x/dar。

11.205.2 qrencode 文本展开

如果 expansion 设置为 none，文本将按原样输出。

如果 expansion 设置为 normal（默认值），则使用下述展开机制。

反斜杠字符 ‘\’ 后跟任意字符，总是展开为第二个字符。

形如 %{...} 的序列会被展开。花括号之间的文本是函数名，其后可能跟随以 ’:’ 分隔的参数。如果参数中包含特殊字符或分隔符（’:’ 或 ’}’），则必须转义。

请注意，它们可能还必须作为滤镜参数字符串中 text 选项的值再次转义，并作为 filtergraph 描述中的滤镜参数再次转义，也可能还需要为 shell 转义，最多可达四层转义；使用 textfile 选项指定文本文件可以避免这些问题。

可用的函数如下：

n, frame_num

返回帧编号

pts

返回当前帧的 presentation timestamp。

最多可以接受两个参数。

第一个参数是时间戳的格式；默认为 flt，即以微秒精度的十进制数表示的秒数；hms 表示以毫秒精度格式化的 [-]HH:MM:SS.mmm 时间戳；gmtime 表示以 UTC 时间格式化的帧时间戳；localtime 表示以本地时区时间格式化的帧时间戳。如果格式设置为 hms24hh，则时间以 24 小时制（00-23）格式化。

第二个参数是加到时间戳上的偏移量。

如果格式设置为 localtime 或 gmtime，则可以提供第三个参数：一个 strftime C 函数格式字符串。默认情况下使用 YYYY-MM-DD HH:MM:SS 格式。

expr, e

求出表达式的值并以 double 类型输出。

必须接受一个参数，用于指定要求值的表达式，可以使用 qrencode_expressions 中定义的常量和函数。

expr_formatted, ef

求出表达式的值并以格式化字符串输出。

第一个参数是要求值的表达式，与 expr 函数相同。第二个参数指定输出格式，可接受的值为 ‘x’、‘X’、‘d’ 和 ‘u’，其处理方式与 printf 函数完全相同。第三个参数是可选的，用于设置输出所占的位数，可用来在左侧填充零。

gmtime

滤镜运行时刻，以 UTC 表示。可以接受一个参数：一个 strftime C 函数格式字符串。该格式字符串经过扩展，支持变量 %[1-6]N，用于以可选指定的位数输出秒的小数部分。

localtime

滤镜运行时刻，以本地时区表示。可以接受一个参数：一个 strftime C 函数格式字符串。该格式字符串经过扩展，支持变量 %[1-6]N，用于以可选指定的位数输出秒的小数部分。

metadata

帧元数据。接受一个或两个参数。

第一个参数是必需的，用于指定元数据键。

第二个参数是可选的，用于指定默认值，在找不到元数据键或其值为空时使用。

可用的元数据可以通过检查运行 ffprobe -show_frames 时每个帧小节中打印的以 TAG 开头的条目来确定。

在 qrencode 滤镜之前的滤镜中生成的字符串元数据同样可用。

rand(min, max)

返回一个介于 min 和 max 之间的随机数

11.205.3 示例

以默认尺寸生成编码指定文本的二维码，并叠加到输入视频的左上角：
```
qrencode=text=www.ffmpeg.org
```

与上面相同，但改用粉底蓝色：

qrencode=text=www.ffmpeg.org:bc=pink@0.5:fc=blue

将二维码放置在输入视频的右下角：
```
qrencode=text=www.ffmpeg.org:x=W-Q:y=H-Q
```
生成宽度为 200 像素且带填充的二维码，使填充后的宽度为二维码宽度的 4/3：
```
qrencode=text=www.ffmpeg.org:q=200:Q=4/3*q
```
生成填充后宽度为 200 像素且带填充的二维码，使二维码宽度为填充后宽度的 3/4：
```
qrencode=text=www.ffmpeg.org:Q=200:q=3/4*Q
```
使二维码的宽度为输入视频宽度的一个比例：
```
qrencode=text=www.ffmpeg.org:q=W/5
```
生成编码帧编号的二维码：
```
qrencode=text=%{n}
```
生成编码 GMT 时间戳的二维码：
```
qrencode=text=%{gmtime}
```
生成编码以浮点数表示的时间戳的二维码：
```
qrencode=text=%{pts}
```

11.206 quirc

使用 libquirc 库（参见 https://github.com/dlbeer/quirc/）识别并解码二维码，并将识别到的二维码位置和有效载荷作为元数据输出。

要启用此滤镜的编译，需要在 configure FFmpeg 时指定 --enable-libquirc。

对于在输入视频中找到的每个二维码，会添加一些以 lavfi.quirc.N 为前缀的元数据条目，其中 N 是与该二维码关联的索引，从 0 开始。

各元数据值的说明如下：

lavfi.quirc.count

找到的二维码数量；如果一个也没找到，则不设置该值

lavfi.quirc.N.corner.M.x lavfi.quirc.N.coreer.M.y

包含该二维码的正方形四个角的 x/y 位置，其中 M 是角的索引，从 0 开始

lavfi.quirc.N.payload

该二维码的有效载荷

11.207 random

将内部帧缓存中的视频帧以随机顺序刷新输出。不会丢弃任何帧。灵感来自 frei0r 的 nervous 滤镜。

frames

设置内部缓存的大小（以帧数计），范围为 2 到 512。默认值为 30。

seed

设置随机数生成器的种子，必须是介于 0 和 UINT32_MAX 之间的整数。如果未指定，或显式设置为小于 0 的值，滤镜会尽力选用一个良好的随机种子。

11.208 readeia608

从视频帧顶部的若干行中读取隐藏式字幕（EIA-608）信息。

此滤镜会添加 lavfi.readeia608.X.cc 和 lavfi.readeia608.X.line 帧元数据，其中 X 是识别到 EIA-608 数据的行号（从 0 开始）。各元数据值的说明如下：

lavfi.readeia608.X.cc

作为 EIA-608 数据存储的两个字节（以十六进制打印）。

lavfi.readeia608.X.line

识别并读取到 EIA-608 数据的行号。

此滤镜接受以下选项：

scan_min

设置开始扫描 EIA-608 数据的行。默认值为 0。

scan_max

设置结束扫描 EIA-608 数据的行。默认值为 29。

spw

设置为同步码检测保留的宽度比例。默认值为 0.27。允许的范围是 [0.1 - 0.7]。

chp

启用奇偶校验位检查。发生奇偶校验错误时，滤镜会为该字符输出 0x00。默认值为 false。

在进一步处理前对行做低通滤波。默认启用。

11.208.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.208.2 示例

输出一个包含 presentation time 以及识别到的前两行 EIA-608 字幕数据的 csv。

ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv

11.209 readvitc

从视频帧顶部的若干行中读取垂直间隔时间码（VITC）信息。

如果检测到有效的时间码，此滤镜会添加带有该时间码值的帧元数据键 lavfi.readvitc.tc_str。此外，元数据键 lavfi.readvitc.found 会根据是否找到时间码数据被设置为 0/1。

此滤镜接受以下选项：

scan_max

设置扫描 VITC 数据的最大行数。如果值设置为 -1，则扫描整个视频帧。默认值为 45。

thr_b

设置黑色的亮度阈值。可接受范围 [0.0,1.0] 内的浮点数，默认值为 0.2。该值必须小于或等于 thr_w。

thr_w

设置白色的亮度阈值。可接受范围 [0.0,1.0] 内的浮点数，默认值为 0.6。该值必须大于或等于 thr_b。

11.209.1 示例

检测 VITC 数据并将其绘制到视频帧上；如果未检测到有效的 VITC，则绘制 --:--:--:-- 作为占位符：

ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--}:x=(w-tw)/2:y=400-ascent'

11.210 remap

使用第 2 个输入视频流 Xmap 和第 3 个输入视频流 Ymap 重新映射像素。

位置 (X, Y) 处的目标像素将从源的 (x, y) 位置取出，其中 x = Xmap(X, Y)，y = Ymap(X, Y)。如果映射值超出范围，目标像素将使用零值。

Xmap 和 Ymap 输入视频流必须具有相同的尺寸。输出视频流的尺寸将与 Xmap/Ymap 视频流相同。Xmap 和 Ymap 输入视频流为 16 位深度、单通道。

format

指定此滤镜输出的 pixel format，可以是 color 或 gray。默认值为 color。

fill

指定未被映射的像素的颜色。关于此选项的语法，请参阅 (ffmpeg-utils)ffmpeg-utils 手册中的 "Color" 一节。默认颜色为 black。

11.211 removegrain

removegrain 滤镜是一个用于逐行视频的空间降噪滤镜。

设置第一个平面的模式。

设置第二个平面的模式。

设置第三个平面的模式。

设置第四个平面的模式。

模式的取值范围是 0 到 24。各模式的说明如下：

保持输入平面不变。默认值。

用 8 个相邻像素的最小值和最大值裁剪该像素。

用 8 个相邻像素中第二小和第二大的值裁剪该像素。

用 8 个相邻像素中第三小和第三大的值裁剪该像素。

用 8 个相邻像素中第四小和第四大的值裁剪该像素，等效于中值滤波。

行敏感裁剪，产生最小的变化。

行敏感裁剪，居中方案。

沿相邻像素最接近的直线做行敏感裁剪。

用最接近的相邻像素替换目标像素。

[1 2 1] 水平和垂直核模糊。

与模式 11 相同。

Bob 模式，从相邻像素最接近的直线插值得到顶场。

Bob 模式，从相邻像素最接近的直线插值得到底场。

Bob 模式，插值得到顶场。与模式 13 相同，但使用更复杂的插值公式。

Bob 模式，插值得到底场。与模式 14 相同，但使用更复杂的插值公式。

分别取每对相对相邻像素中的最大值和最小值，再用这些值的最小值和最大值裁剪该像素。

使用与当前像素的最大距离最小的一对相对相邻像素做行敏感裁剪。

用 8 个相邻像素的平均值替换该像素。

对 9 个像素取平均（[1 1 1] 水平和垂直模糊）。

使用相对相邻像素的平均值裁剪像素。

与模式 21 相同，但更简单、更快。

去除细小的边缘和光晕，但据称并无实际效果。

与模式 23 类似。

11.212 removelogo

使用一个图像文件来判定哪些像素构成台标，从而消除电视台的台标。其原理是用相邻像素填充构成台标的像素。

该滤镜接受以下选项：

filename, f

设置滤镜使用的位图文件，可以是 libavformat 支持的任意图像格式。该图像文件的宽度和高度必须与被处理的视频流一致。

在所提供的位图图像中，值为零的像素不视为台标的一部分，非零像素则视为台标的一部分。如果台标使用白色（255），其余部分使用黑色（0），就不会有问题。制作滤镜位图时，建议先截取一帧包含可见台标的黑场画面，然后使用 threshold 滤镜，再用 erode 滤镜处理一到两次。

如有需要，可以手动修正小的斑点。请记住，如果台标像素未被完全覆盖，滤镜效果会大打折扣。将过多的像素标记为台标的一部分危害较小，但会增加为覆盖图像所需的模糊量，从而破坏比必要更多的信息；对于较大的台标，多余的像素还会拖慢处理速度。

11.213 repeatfields

此滤镜使用视频 ES 头中的 repeat_field 标志，并根据其值硬性重复场。

11.214 reverse

反转视频片段。

警告：此滤镜需要占用内存缓冲整个片段，因此建议先截取所需片段。

11.214.1 示例

截取片段的前 5 秒并将其反转。
```
trim=end=5,reverse
```

11.215 rgbashift

将 R/G/B/A 像素在水平和/或垂直方向上偏移。

该滤镜接受以下选项：

设置红色分量水平偏移的量。

设置红色分量垂直偏移的量。

设置绿色分量水平偏移的量。

设置绿色分量垂直偏移的量。

设置蓝色分量水平偏移的量。

设置蓝色分量垂直偏移的量。

设置 alpha 分量水平偏移的量。

设置 alpha 分量垂直偏移的量。

edge

设置边缘模式，可以是 smear、default 或 warp。

11.215.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.216 roberts

对输入视频流应用 Roberts 交叉算子。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

scale

设置与滤波结果相乘的值。

delta

设置与滤波结果相加的值。

11.216.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.217 rotate

将视频旋转任意角度（以弧度表示）。

该滤镜接受以下选项：

各可选参数的说明如下。

angle, a

设置输入视频顺时针旋转角度的表达式，以弧度数表示。负值会导致逆时针旋转。默认设置为 "0"。

该表达式在每一帧都会求值。

out_w, ow

设置输出宽度的表达式，默认值为 "iw"。该表达式仅在配置期间求值一次。

out_h, oh

设置输出高度的表达式，默认值为 "ih"。该表达式仅在配置期间求值一次。

bilinear

设置为 1 时启用双线性插值，设置为 0 时禁用。默认值为 1。

fillcolor, c

设置用于填充旋转后图像未覆盖的输出区域的颜色。关于此选项的通用语法，请参阅 (ffmpeg-utils)ffmpeg-utils 手册中的 "Color" 一节。如果选择特殊值 "none"，则不绘制背景（例如背景永远不会显示时可以这样用）。

默认值为 "black"。

角度和输出尺寸的表达式可以包含以下常量和函数：

输入帧的连续编号，从 0 开始。在第一帧被滤镜处理之前始终为 NAN。

以秒表示的输入帧时间，滤镜配置时会被设置为 0。在第一帧被滤镜处理之前始终为 NAN。

hsub vsub

水平和垂直方向的色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

in_w, iw in_h, ih

输入视频的宽度和高度

out_w, ow out_h, oh

输出的宽度和高度，即由 width 和 height 表达式指定的填充区域大小

rotw(a) roth(a)

完全容纳旋转 a 弧度后的输入视频所需的最小宽度/高度。

这些仅在计算 out_w 和 out_h 表达式时可用。

11.217.1 示例

将输入顺时针旋转 PI/6 弧度：
```
rotate=PI/6
```
将输入逆时针旋转 PI/6 弧度：
```
rotate=-PI/6
```
将输入顺时针旋转 45 度：
```
rotate=45*PI/180
```
应用周期为 T 的恒定旋转，从角度 PI/3 开始：
```
rotate=PI/3+2*PI*t/T
```
使输入视频的旋转以周期 T 秒、振幅 A 弧度振荡：
```
rotate=A*sin(2*PI/T*t)
```
旋转视频，并选择输出尺寸，使旋转中的输入视频始终完全包含在输出中：
```
rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
```
旋转视频，并缩小输出尺寸，使背景永远不会显示：
```
rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
```

11.217.2 命令

此滤镜支持以下命令：

a, angle

设置角度表达式。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.218 sab

应用形状自适应模糊（Shape Adaptive Blur）。

该滤镜接受以下选项：

luma_radius, lr

设置亮度模糊滤镜的强度，必须是 0.1-4.0 范围内的值，默认值为 1.0。值越大，图像越模糊，处理速度也越慢。

luma_pre_filter_radius, lpfr

设置亮度预滤波半径，必须是 0.1-2.0 范围内的值，默认值为 1.0。

luma_strength, ls

设置像素间仍被视为相关的最大亮度差，必须是 0.1-100.0 范围内的值，默认值为 1.0。

chroma_radius, cr

设置色度模糊滤镜的强度，必须是 -0.9-4.0 范围内的值。值越大，图像越模糊，处理速度也越慢。

chroma_pre_filter_radius, cpfr

设置色度预滤波半径，必须是 -0.9-2.0 范围内的值。

chroma_strength, cs

设置像素间仍被视为相关的最大色度差，必须是 -0.9-100.0 范围内的值。

每个色度选项的值，如果未显式指定，则设置为对应的亮度选项值。

11.219 scale

使用 libswscale 库缩放（调整尺寸）输入视频。

scale 滤镜通过更改输出的采样宽高比，强制使输出的显示宽高比与输入相同。

如果输入图像格式与下一个滤镜所要求的格式不同，scale 滤镜会将输入转换为所要求的格式。

11.219.1 选项

此滤镜接受以下选项、libswscale 缩放器支持的任意选项，以及任意 framesync 选项。

缩放器选项的完整列表请参阅 (ffmpeg-scaler)ffmpeg-scaler 手册。

width, w height, h

设置输出视频尺寸表达式。默认值为输入尺寸。

如果 width 或 w 的值为 0，输出将使用输入的宽度。如果 height 或 h 的值为 0，输出将使用输入的高度。

如果两个值中只有一个为 -n（n >= 1），scale 滤镜会根据另一个指定的尺寸计算出一个能保持输入图像宽高比的值。之后，它会确保计算出的尺寸能被 n 整除，必要时会调整该值。

如果两个值都是 -n（n >= 1），其行为将与前面所述的两个值都设置为 0 时相同。

可在尺寸表达式中使用的常量列表见下文。

eval

指定何时对 width 和 height 表达式求值。可接受以下值：

‘init’

仅在滤镜初始化期间或处理命令时对表达式求值一次。

‘frame’

对每个输入帧都求值表达式。

默认值为 ‘init’。

interl

设置隔行扫描模式。可接受以下值：

‘1’

强制使用感知隔行的缩放。

‘0’

不应用隔行感知缩放。

‘-1’

根据源帧是否被标记为隔行来选择是否使用隔行感知缩放。

默认值为 ‘0’。

flags

设置 libswscale 的缩放标志。完整的取值列表请参阅 (ffmpeg-scaler)ffmpeg-scaler 手册。如果未显式指定，滤镜将应用默认标志。

param0, param1

为需要参数的缩放算法设置 libswscale 输入参数。完整文档请参阅 (ffmpeg-scaler)ffmpeg-scaler 手册。如果未显式指定，滤镜将应用空参数。

intent

设置在不同色彩空间之间转换时使用的 ICC 渲染意图。可接受以下值：

‘perceptual’

使用感知引导的色调与色域映射曲线。所使用映射的具体细节可能随时变化，不应视为稳定不变。此意图推荐用于在典型观看环境下最终观看图像/视频内容。

‘relative_colorimetric’

使用测色裁剪曲线静态裁剪色域外的颜色，该曲线尝试找到测色上差异最小的色域内颜色。此意图会执行白点适配和黑点适配。这是默认值。在忠实的色彩还原至关重要的场合，即使需要以裁剪为代价，也推荐使用此意图。

‘absolute_colorimetric’

硬性裁剪色域外的颜色，不尝试还原白点或黑点。假设输出显示器已正确校准，此意图会将色域内的颜色按参考显示器上的效果 1:1 还原到输出显示器上。

‘saturation’

执行饱和度映射，即以非线性方式将输入色彩体积直接拉伸到输出色彩体积上，尽可能保留原始信号的观感。此意图不会导致任何裁剪，因此推荐用于信号内容评估。它大致相当于不做任何色彩映射，不过仍会考虑母版显示器的原色以及编码 TRC 的任何差异。

size, s

设置视频尺寸。关于此选项的语法，请参阅 (ffmpeg-utils)ffmpeg-utils 手册中的 "Video size" 一节。

in_color_matrix out_color_matrix

设置输入/输出的 YCbCr 色彩空间类型。

这既允许覆盖自动检测到的值，也允许强制为输出和 encoder 指定特定的值。

如果未指定，色彩空间类型将取决于 pixel format。

可选值：

‘auto’

自动选择。

‘bt709’

符合国际电信联盟（ITU）建议 BT.709 的格式。

‘fcc’

设置符合美国联邦通信委员会（FCC）联邦法规（CFR）第 47 篇（2003 年）73.682(a) 条的色彩空间。

‘bt601’ ‘bt470’ ‘smpte170m’

设置符合以下标准的色彩空间：

ITU 无线电通信部门（ITU-R）建议 BT.601
ITU-R Rec. BT.470-6（1998 年）B、B1 和 G 制式
电影电视工程师协会（SMPTE）ST 170:2004

‘smpte240m’

设置符合 SMPTE ST 240:1999 的色彩空间。

‘bt2020’

设置符合 ITU-R BT.2020 非恒定亮度系统的色彩空间。

in_range out_range

设置输入/输出的 YCbCr 采样范围。

这既允许覆盖自动检测到的值，也允许强制为输出和 encoder 指定特定的值。如果未指定，范围将取决于 pixel format。可能的值：

‘auto/unknown’

自动选择。

‘jpeg/full/pc’

设置为全范围（8 位亮度时为 0-255）。

‘mpeg/limited/tv’

设置为 "MPEG" 范围（8 位亮度时为 16-235）。

in_chroma_loc out_chroma_loc

设置输入/输出的色度采样位置。如果未指定，默认使用居中的色度位置。可能的值：

‘auto, unknown’ ‘left’ ‘center’ ‘topleft’ ‘top’ ‘bottomleft’ ‘bottom’ in_primaries out_primaries

设置输入/输出的 RGB 原色。

这既允许覆盖自动检测到的值，也允许强制为输出和 encoder 指定特定的值。可能的值：

‘auto’

自动选择。这是默认值。

‘bt709’ ‘bt470m’ ‘bt470bg’ ‘smpte170m’ ‘smpte240m’ ‘film’ ‘bt2020’ ‘smpte428’ ‘smpte431’ ‘smpte432’ ‘jedec-p22’ ‘ebu3213’ in_transfer out_transfer

设置输入/输出的传递响应曲线（TRC）。

这既允许覆盖自动检测到的值，也允许强制为输出和 encoder 指定特定的值。可能的值：

‘auto’

自动选择。这是默认值。

‘bt709’ ‘bt470m’ ‘gamma22’ ‘bt470bg’ ‘gamma28’ ‘smpte170m’ ‘smpte240m’ ‘linear’ ‘iec61966-2-1’ ‘srgb’ ‘iec61966-2-4’ ‘xvycc’ ‘bt1361e’ ‘bt2020-10’ ‘bt2020-12’ ‘smpte2084’ ‘smpte428’ ‘arib-std-b67’ force_original_aspect_ratio

如有必要，允许减小或增大输出视频的宽度或高度，以保持原始宽高比。可选值：

‘disable’

按指定方式缩放视频，并禁用此功能。

‘decrease’

如有需要，会自动减小输出视频的尺寸。

‘increase’

如有需要，会自动增大输出视频的尺寸。

此选项的一个实用场景是：当你知道某个设备允许的最大分辨率时，可以用它把输出视频限制在该范围内，同时保持宽高比。例如，设备 A 支持 1280x720 播放，而你的视频是 1920x800。使用此选项（设置为 decrease）并在命令行中指定 1280x720，输出将变为 1280x533。

请注意，这与为 w 或 h 指定 -1 是不同的，要让此选项生效，仍需要指定输出分辨率。

force_divisible_by

与 force_original_aspect_ratio 一起使用时，确保输出的宽度和高度都能被指定的整数整除。其效果与在 w 和 h 选项中使用 -n 类似。

此选项会遵循 force_original_aspect_ratio 设置的值，并据此增大或减小分辨率。视频的宽高比可能会因此略有变化。

如果你需要通过 force_original_aspect_ratio 让视频适配或超出某个指定分辨率，同时又要满足 encoder 对宽度或高度整除性的限制，此选项会很有用。

reset_sar

启用此选项会将输出 SAR 重置为 1。此外，如果用户通过 width 或 height 表达式（例如 w=-4:h=360 或 w=iw/2:h=-1）或启用 force_original_aspect_ratio 来请求按比例缩放，则会考虑输入的 DAR，并对输出进行缩放以生成正方形像素。默认值为 false。

w 和 h 选项的值是包含以下常量的表达式：

in_w in_h

输入的宽度和高度

iw ih

与 in_w 和 in_h 相同。

out_w out_h

输出（缩放后）的宽度和高度

ow oh

与 out_w 和 out_h 相同

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，由 (iw / ih) * sar 计算得出。

hsub vsub

输入色度的水平和垂直二次采样值。例如，对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

ohsub ovsub

输出色度的水平和垂直二次采样值。例如，对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

输入帧的（顺序）编号，从 0 开始。仅在 eval=frame 时可用。

输入帧的 presentation timestamp，以秒数表示。仅在 eval=frame 时可用。

pos

该帧在输入流中的位置（字节偏移量），如果此信息不可用和/或没有意义（例如合成视频的情况），则为 NaN。仅在 eval=frame 时可用。已弃用，请勿使用。

ref_w, rw ref_h, rh ref_a ref_dar, rdar ref_n ref_t ref_pos

与上述相同，但用于第二个参照输入。如果存在任何这些变量，此滤镜将接受两个输入。

11.219.2 示例

将输入视频缩放为 200x100 大小
```
scale=w=200:h=100
```

这等同于：

    scale=200:100

或：

    scale=200x100

为输出尺寸指定一个尺寸缩写：
```
scale=qcif
```

也可以写成：

    scale=size=qcif

将输入放大 2 倍：
```
scale=w=2*iw:h=2*ih
```
上面的写法等同于：
```
scale=2*in_w:2*in_h
```
将输入放大 2 倍，并强制使用隔行扫描缩放：
```
scale=2*iw:2*ih:interl=1
```
将输入缩小为一半尺寸：
```
scale=w=iw/2:h=ih/2
```
增大宽度，并将高度设置为相同的尺寸：
```
scale=3/2*iw:ow
```
追求希腊式的和谐比例：
```
scale=iw:1/PHI*iw
scale=ih*PHI:ih
```
增大高度，并将宽度设置为高度的 3/2：
```
scale=w=3/2*oh:h=3/5*ih
```
增大尺寸，使尺寸成为色度二次采样值的倍数：
```
scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
```
将宽度增大到最多 500 像素，并保持与输入相同的宽高比：
```
scale=w='min(500\, iw*3/2):h=-1'
```
结合 scale 和 setsar 使像素变为正方形：
```
scale='trunc(ih*dar):ih',setsar=1/1
```
使用 reset_sar 使像素变为正方形，并确保得到的分辨率为偶数（某些 codec 要求如此）：
```
scale='-2:ih-mod(ih,2):reset_sar=1'
```
精确缩放到目标尺寸，但将 SAR 重置为 1：
```
scale='400:300:reset_sar=1'
```
缩放到能容纳于 400x300 内的偶数尺寸，同时保留输入的 SAR：
```
scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2'
```

缩放以生成正方形像素，并使尺寸为能容纳于 400x300 内的偶数：

scale='400:300:force_original_aspect_ratio=decrease:force_divisible_by=2:reset_sar=1'

在叠加之前，将字幕流（sub）缩放到与主视频（main）相同的尺寸。（"scale2ref"）
```
'[main]split[a][b]; [ref][a]scale=rw:rh[c]; [b][c]overlay'
```
将徽标缩放为视频高度的 1/10，同时保留其显示宽高比。
```
[logo-in][video-in]scale=w=oh*dar:h=rh/10[logo-out]
```

11.219.3 命令

该滤镜支持以下命令：

width, w height, h

设置输出视频尺寸的表达式。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

11.220 scharr

对输入视频流应用 scharr 算子。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

scale

设置与滤波结果相乘的值。

delta

设置与滤波结果相加的值。

11.220.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.221 scroll

以恒定速度水平和/或垂直滚动输入视频。

该滤镜接受以下选项：

horizontal, h

设置水平滚动速度。默认值为 0。允许范围为 -1 到 1。负值会改变滚动方向。

vertical, v

设置垂直滚动速度。默认值为 0。允许范围为 -1 到 1。负值会改变滚动方向。

hpos

设置初始水平滚动位置。默认值为 0。允许范围为 0 到 1。

vpos

设置初始垂直滚动位置。默认值为 0。允许范围为 0 到 1。

11.221.1 命令

该滤镜支持以下命令：

horizontal, h

设置水平滚动速度。

vertical, v

设置垂直滚动速度。

11.222 scdet

检测视频场景切换。

此滤镜会在帧的元数据中设置帧间 mafd 和场景分数，并将该帧转发给下一个滤镜，以便后续处理可以利用这些元数据检测场景切换等信息。

此外，当此滤镜通过阈值检测到场景切换时，会记录一条消息并设置帧元数据。

每一帧都会设置 lavfi.scd.mafd 元数据键，其值为 mafd。

为了检测场景切换，每一帧都会设置 lavfi.scd.score 元数据键，其值为场景切换分数。

lavfi.scd.time 元数据键会设置为通过阈值检测到场景切换时，当前已过滤帧的时间。

该滤镜接受以下选项：

threshold, t

以最大变化量的百分比形式设置场景切换检测的阈值。较合适的值在 [8.0, 14.0] 范围内。threshold 的取值范围为 [0., 100.]。

默认值为 10.。

sc_pass, s

设置是否将场景切换帧传递给下一个滤镜的标志。默认值为 0。如果只想获取场景切换帧的快照，可以启用此选项。

11.223 selectivecolor

针对特定颜色范围（例如 "reds"、"yellows"、"greens"、"cyans" 等）调整青色、洋红、黄色和黑色（CMYK）。调整范围由该颜色的“纯度”（即已经有多饱和）来定义。

此滤镜类似于 Adobe Photoshop 的选择性颜色工具。

该滤镜接受以下选项：

correction_method

选择色彩校正方式。

可用值如下：

‘absolute’

指定的调整值将“原样”应用（对原始像素分量值进行加减）。

‘relative’

指定的调整值是相对于原始分量值的相对值。

默认值为 absolute。

reds

针对红色像素（红色分量为最大值的像素）的调整

yellows

针对黄色像素（蓝色分量为最小值的像素）的调整

greens

针对绿色像素（绿色分量为最大值的像素）的调整

cyans

针对青色像素（红色分量为最小值的像素）的调整

blues

针对蓝色像素（蓝色分量为最大值的像素）的调整

magentas

针对洋红色像素（绿色分量为最小值的像素）的调整

whites

针对白色像素（所有分量都大于 128 的像素）的调整

neutrals

针对除纯黑和纯白之外所有像素的调整

blacks

针对黑色像素（所有分量都小于 128 的像素）的调整

psfile

指定要从中导入设置的 Photoshop 选择性颜色文件（.asv）。

所有调整设置（reds、yellows 等）最多接受 4 个以空格分隔、范围在 [-1,1] 内的浮点调整值，分别用于调整该颜色范围内像素的青色、洋红、黄色和黑色的量。

11.223.1 示例

在所有绿色区域中将青色增加 50%、黄色减少 33%，并在蓝色区域中将洋红色增加 27%：
```
selectivecolor=greens=.5 0 -.33 0:blues=0 .27
```

使用 Photoshop 的选择性颜色预设：

selectivecolor=psfile=MySelectiveColorPresets/Misty.asv

11.224 separatefields

separatefields 接收基于帧的视频输入，并将每一帧拆分为其组成场，生成一个高度减半、帧率翻倍、帧数也翻倍的新片段。

此滤镜使用帧中的场优先（field-dominance）信息，来决定每对场中哪一个应放在输出的前面。如果判断有误，请在 separatefields 滤镜之前使用 setfield 滤镜。

11.225 setdar, setsar

setdar 滤镜用于设置滤镜输出视频的显示宽高比（Display Aspect Ratio）。

这是通过按照以下公式更改指定的样本（也称像素）宽高比来实现的：

DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR

请注意，setdar 滤镜不会修改视频帧的像素尺寸。另外，此滤镜设置的显示宽高比可能会被滤镜链（filterchain）中后续的滤镜更改，例如发生缩放，或应用了另一个 "setdar" 或 "setsar" 滤镜时。

setsar 滤镜用于设置滤镜输出视频的样本（也称像素）宽高比。

请注意，应用此滤镜后，输出的显示宽高比会按照上述公式发生变化。

请注意，setsar 滤镜设置的样本宽高比可能会被滤镜链中后续的滤镜更改，例如应用了另一个 "setsar" 或 "setdar" 滤镜时。

它接受以下参数：

r, ratio, dar (setdar only), sar (setsar only)

设置此滤镜使用的宽高比。

该参数可以是浮点数字符串，也可以是表达式。如果未指定该参数，则假定其值为 "0"，即表示使用与输入相同的值。

max

设置将表达式表示的宽高比约分为有理数时，用于表示分子和分母的最大整数值。默认值为 100。

参数 sar 是一个包含以下常量的表达式：

w, h

输入的宽度和高度。

与 w / h 相同。

sar

输入的样本宽高比。

dar

输入的显示宽高比，与 (w / h) * sar 相同。

hsub, vsub

色度的水平和垂直二次采样值。例如，对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

11.225.1 示例

要将显示宽高比更改为 16:9，可指定以下任意一种：
```
setdar=dar=1.77777
setdar=dar=16/9
```
要将样本宽高比更改为 10:11，请指定：
```
setsar=sar=10/11
```
要将显示宽高比设置为 16:9，并在宽高比约分时指定最大整数值为 1000，请使用以下命令：
```
setdar=ratio=16/9:max=1000
```

11.226 setfield

强制设置输出视频帧的场。

setfield 滤镜会为输出帧标记隔行扫描的场类型。它不会更改输入帧本身，只是设置相应的属性，这会影响后续滤镜（例如 fieldorder 或 yadif）处理该帧的方式。

该滤镜接受以下选项：

mode

可用值如下：

‘auto’

保持相同的场属性。

‘bff’

将该帧标记为底场优先（bottom-field-first）。

‘tff’

将该帧标记为顶场优先（top-field-first）。

‘prog’

将该帧标记为逐行扫描（progressive）。

11.227 setparams

强制设置输出视频帧的参数。

setparams 滤镜会为输出帧标记隔行扫描方式和色彩范围。它不会更改输入帧本身，只是设置相应的属性，这会影响滤镜/encoder 处理该帧的方式。

field_mode

可用值如下：

‘auto’

保持相同的场属性（默认值）。

‘bff’

将该帧标记为底场优先（bottom-field-first）。

‘tff’

将该帧标记为顶场优先（top-field-first）。

‘prog’

将该帧标记为逐行扫描（progressive）。

range

可用值如下：

‘auto’

保持相同的色彩范围属性（默认值）。

‘unspecified, unknown’

将该帧标记为未指定色彩范围。

‘limited, tv, mpeg’

将该帧标记为受限范围（limited range）。

‘full, pc, jpeg’

将该帧标记为全范围（full range）。

color_primaries

设置色彩原色（color primaries）。可用值有：

‘auto’

保持相同的色彩原色属性（默认值）。

‘bt709’ ‘unknown’ ‘bt470m’ ‘bt470bg’ ‘smpte170m’ ‘smpte240m’ ‘film’ ‘bt2020’ ‘smpte428’ ‘smpte431’ ‘smpte432’ ‘jedec-p22’ color_trc

设置色彩传递特性（color transfer）。可用值有：

‘auto’

保持相同的 color trc 属性（默认值）。

‘bt709’ ‘unknown’ ‘bt470m’ ‘bt470bg’ ‘smpte170m’ ‘smpte240m’ ‘linear’ ‘log100’ ‘log316’ ‘iec61966-2-4’ ‘bt1361e’ ‘iec61966-2-1’ ‘bt2020-10’ ‘bt2020-12’ ‘smpte2084’ ‘smpte428’ ‘arib-std-b67’ colorspace

设置色彩空间（colorspace）。可用值有：

‘auto’

保持相同的色彩空间属性（默认值）。

‘gbr’ ‘bt709’ ‘unknown’ ‘fcc’ ‘bt470bg’ ‘smpte170m’ ‘smpte240m’ ‘ycgco’ ‘bt2020nc’ ‘bt2020c’ ‘smpte2085’ ‘chroma-derived-nc’ ‘chroma-derived-c’ ‘ictcp’ chroma_location

设置色度采样位置（chroma sample location）。可用值有：

‘auto’

保持相同的色度采样位置（默认值）。

‘unspecified, unknown’ ‘left’ ‘center’ ‘topleft’ ‘top’ ‘bottomleft’ ‘bottom’ alpha_mode

设置 alpha 模式。可用值有：

‘auto’

保持相同的 alpha 模式（默认值）。

‘unspecified, unknown’ ‘premultiplied’ ‘straight’

11.228 shear

对输入视频应用剪切（shear）变换。

此滤镜支持以下选项：

shx

X 方向的剪切系数。默认值为 0。允许范围为 -2 到 2。

shy

Y 方向的剪切系数。默认值为 0。允许范围为 -2 到 2。

fillcolor, c

设置用于填充变换后视频未覆盖的输出区域的颜色。有关此选项的通用语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的"Color"一节。如果选择特殊值 "none"，则不会绘制背景（例如在背景永远不会显示的情况下很有用）。

默认值为 "black"。

interp

设置插值类型。可以是 bilinear 或 nearest。默认值为 bilinear。

11.228.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.229 showinfo

为每个输入视频帧显示一行包含各种信息的内容。输入视频不会被修改。

此滤镜支持以下选项：

checksum

计算每个平面的校验和。默认启用。

udu_sei_as_ascii

尽可能将用户数据无注册 SEI（user data unregistered SEI）打印为 ASCII 字符，否则以十六进制格式打印。

显示的这一行由一系列 key:value 形式的键/值对组成。

输出中会显示以下值：

输入帧的（顺序）编号，从 0 开始。

pts

输入帧的 Presentation TimeStamp，以时间基（time base）单位的数值表示。时间基单位取决于滤镜的输入 pad。

pts_time

输入帧的 Presentation TimeStamp，以秒数表示。

fmt

pixel format 的名称。

sar

输入帧的样本宽高比，以 num/den 的形式表示。

输入帧的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的"Video size"一节。

隔行扫描模式的类型（"P" 表示 "progressive"（逐行），"T" 表示顶场优先，"B" 表示底场优先）。

iskey

如果该帧是 keyframe（key frame），则为 1，否则为 0。

type

输入帧的图像类型（"I" 表示 I 帧，"P" 表示 P 帧，"B" 表示 B 帧，"?" 表示未知类型）。另请参阅 libavutil/avutil.h 中定义的 AVPictureType 枚举和 av_get_picture_type_char 函数的文档。

checksum

输入帧所有平面的 Adler-32 校验和（以十六进制打印）。

plane_checksum

输入帧每个平面的 Adler-32 校验和（以十六进制打印），以 "[c0 c1 c2 c3]" 的形式表示。

mean

输入帧每个平面中像素的平均值，以 "[mean0 mean1 mean2 mean3]" 的形式表示。

stdev

输入帧每个平面中像素值的标准差，以 "[stdev0 stdev1 stdev2 stdev3]" 的形式表示。

11.230 showpalette

显示每一帧的 256 色调色板。此滤镜仅适用于 pal8 pixel format 的帧。

它接受以下选项：

设置用于表示一个调色板颜色条目的方框大小。默认值为 30（即 30x30 像素的方框）。

11.231 shuffleframes

对视频帧进行重新排序和/或复制和/或丢弃。

它接受以下参数：

mapping

设置输入帧的目标索引。这是一个以空格或 ’|’ 分隔的索引列表，用于将输入帧映射到输出帧。索引的个数也决定了每个索引可以取的最大值。’-1’ 索引具有特殊含义，表示丢弃该帧。

第一帧的索引为 0。默认情况下会保持输入不变。

11.231.1 示例

将输入中每三帧里的第二帧和第三帧互换：
```
ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
```

将输入中每十帧里的第 10 帧和第 1 帧互换：

ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT

11.232 shufflepixels

对视频帧中的像素进行重新排序。

此滤镜接受以下选项：

direction, d

设置洗牌（shuffle）方向。可以是正向（forward）或反向（inverse）。默认方向为正向。

mode, m

设置洗牌模式。可以是水平（horizontal）、垂直（vertical）或分块（block）模式。

width, w height, h

设置洗牌的 block_size。在水平洗牌模式下，只使用尺寸中的 width 部分；在垂直洗牌模式下，只使用尺寸中的 height 部分。

seed, s

设置用于像素洗牌的随机数种子。主要用于让滤镜处理过程可逆，以便恢复原始输入。例如，要还原正向洗牌，需要使用相同的参数和完全相同的种子，并将 direction 设置为 inverse。

11.233 shuffleplanes

重新排列和/或复制视频平面。

它接受以下参数：

map0

用作第一个输出平面的输入平面索引。

map1

用作第二个输出平面的输入平面索引。

map2

用作第三个输出平面的输入平面索引。

map3

用作第四个输出平面的输入平面索引。

第一个平面的索引为 0。默认保持输入不变。

11.233.1 示例

交换输入的第二个和第三个平面：

ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT

11.234 signalstats

评估各种视觉指标，以帮助判断与模拟视频媒体数字化相关的问题。

默认情况下，该滤镜会记录以下元数据值：

YMIN

显示输入帧中包含的最小 Y 值。范围为 [0-255]。

YLOW

显示输入帧中处于 10% 百分位的 Y 值。范围为 [0-255]。

YAVG

显示输入帧中 Y 值的平均值。范围为 [0-255]。

YHIGH

显示输入帧中处于 90% 百分位的 Y 值。范围为 [0-255]。

YMAX

显示输入帧中包含的最大 Y 值。范围为 [0-255]。

UMIN

显示输入帧中包含的最小 U 值。范围为 [0-255]。

ULOW

显示输入帧中处于 10% 百分位的 U 值。范围为 [0-255]。

UAVG

显示输入帧中 U 值的平均值。范围为 [0-255]。

UHIGH

显示输入帧中处于 90% 百分位的 U 值。范围为 [0-255]。

UMAX

显示输入帧中包含的最大 U 值。范围为 [0-255]。

VMIN

显示输入帧中包含的最小 V 值。范围为 [0-255]。

VLOW

显示输入帧中处于 10% 百分位的 V 值。范围为 [0-255]。

VAVG

显示输入帧中 V 值的平均值。范围为 [0-255]。

VHIGH

显示输入帧中处于 90% 百分位的 V 值。范围为 [0-255]。

VMAX

显示输入帧中包含的最大 V 值。范围为 [0-255]。

SATMIN

显示输入帧中包含的最小饱和度值。范围为 [0-~181.02]。

SATLOW

显示输入帧中处于 10% 百分位的饱和度值。范围为 [0-~181.02]。

SATAVG

显示输入帧中饱和度的平均值。范围为 [0-~181.02]。

SATHIGH

显示输入帧中处于 90% 百分位的饱和度值。范围为 [0-~181.02]。

SATMAX

显示输入帧中包含的最大饱和度值。范围为 [0-~181.02]。

HUEMED

显示输入帧中色相的中值。范围为 [0-360]。

HUEAVG

显示输入帧中色相的平均值。范围为 [0-360]。

YDIF

显示当前帧 Y 平面所有值与前一个输入帧对应值之间样本值差异的平均值。范围为 [0-255]。

UDIF

显示当前帧 U 平面所有值与前一个输入帧对应值之间样本值差异的平均值。范围为 [0-255]。

VDIF

显示当前帧 V 平面所有值与前一个输入帧对应值之间样本值差异的平均值。范围为 [0-255]。

YBITDEPTH

显示当前帧 Y 平面的位深度。范围为 [0-16]。

UBITDEPTH

显示当前帧 U 平面的位深度。范围为 [0-16]。

VBITDEPTH

显示当前帧 V 平面的位深度。范围为 [0-16]。

该滤镜接受以下选项：

stat out

stat 用于指定附加的图像分析方式，out 用于输出高亮显示指定类型像素的视频。

这两个选项都接受以下值：

‘tout’

识别时间性异常值像素。时间性异常值是指与同一场（field）内相邻像素不同的像素。时间性异常值的例子包括视频信号丢失、磁头堵塞或磁带循迹问题所导致的结果。

‘vrep’

识别垂直线重复。垂直线重复是指帧内出现相似的像素行。在原生数字视频中，垂直线重复很常见，但在由模拟信号源数字化而来的视频中这种模式并不常见。当它出现在由模拟信号源数字化而成的视频中时，可能表明存在信号丢失补偿器（dropout compensator）造成的掩盖。

‘brng’

识别落在合法广播范围之外的像素。

color, c

设置 out 选项的高亮颜色。默认颜色为黄色。

11.234.1 示例

输出各种视频指标的数据：

ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames

输出每帧 Y 平面最小值和最大值的具体数据：

ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN

播放视频，同时将超出广播范围的像素用红色高亮显示。
```
ffplay example.mov -vf signalstats="out=brng:color=red"
```

播放视频，并在帧上绘制 signalstats 元数据。

ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt

命令中使用的 signalstat_drawtext.txt 的内容如下：

    time %{pts:hms}
    Y (%{metadata:lavfi.signalstats.YMIN}-%{metadata:lavfi.signalstats.YMAX})
    U (%{metadata:lavfi.signalstats.UMIN}-%{metadata:lavfi.signalstats.UMAX})
    V (%{metadata:lavfi.signalstats.VMIN}-%{metadata:lavfi.signalstats.VMAX})
    saturation maximum: %{metadata:lavfi.signalstats.SATMAX}

11.235 signature

计算 MPEG-7 视频签名（Video Signature）。该滤镜可以处理多个输入，此时可以额外计算各输入之间的匹配情况。该滤镜始终会原样传递第一个输入。每个流的签名都可以写入文件。

它接受以下选项：

detectmode

启用或禁用匹配处理。

可用值如下：

‘off’

禁用匹配计算（默认）。

‘full’

计算整个视频的匹配情况，并输出是整个视频匹配还是仅部分匹配。

‘fast’

只计算到找到匹配或视频结束为止。某些情况下速度会更快。

nb_inputs

设置输入的数量。选项值必须是非负整数。默认值为 1。

filename

设置输出写入的路径。如果有多个输入，路径必须是一个原型，即必须包含 %d 或 %0nd（n 为正整数），它会被替换为输入编号。如果未指定 filename，则不会写入任何输出，这是默认行为。

format

选择输出格式。

可用值如下：

‘binary’

使用指定的二进制表示形式（默认）。

‘xml’

使用指定的 xml 表示形式。

th_d

设置将单个词判定为相似的阈值。选项值必须是大于零的整数。默认值为 9000。

th_dc

设置将所有词判定为相似的阈值。选项值必须是大于零的整数。默认值为 60000。

th_xh

设置将帧判定为相似的阈值。选项值必须是大于零的整数。默认值为 116。

th_di

设置将一个序列识别为匹配序列所需的最小长度（以帧数计）。选项值必须是非负整数值。默认值为 0。

th_it

设置匹配帧相对于全部帧必须具有的最小比例。选项值必须是介于 0 到 1 之间的 double 值。默认值为 0.5。

11.235.1 示例

计算输入视频的签名并将其存储到 signature.bin：

ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -

检测两个视频是否匹配，并将签名以 XML 格式存储到 signature0.xml 和 signature1.xml：

ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null -

11.236 siti

计算视频的空间信息（Spatial Information, SI）和时间信息（Temporal Information, TI）得分，定义见 ITU-T Rec. P.910 (11/21): Subjective video quality assessment methods for multimedia applications。PDF 可从 https://www.itu.int/rec/T-REC-P.910-202111-S/en 获取。请注意，这是对应于已被取代的建议书的旧版实现。最新版本请参阅 ITU-T Rec. P.910 (07/22)：https://www.itu.int/rec/T-REC-P.910-202207-I/en

它接受以下选项：

print_summary

如果设置为 1，摘要统计信息将打印到控制台。默认值为 0。

11.236.1 示例

计算 SI/TI 指标并打印摘要：

ffmpeg -i input.mp4 -vf siti=print_summary=1 -f null -

11.237 smartblur

在不影响轮廓的情况下模糊输入视频。

它接受以下选项：

luma_radius, lr

设置亮度半径。选项值必须是 [0.1,5.0] 范围内的浮点数，指定用于模糊图像的高斯滤波器的方差（值越大速度越慢）。默认值为 1.0。

luma_strength, ls

设置亮度强度。选项值必须是 [-1.0,1.0] 范围内的浮点数，用于配置模糊程度。[0.0,1.0] 范围内的值会模糊图像，而 [-1.0,0.0] 范围内的值会锐化图像。默认值为 1.0。

luma_threshold, lt

设置用作系数的亮度阈值，用于判断像素是否应被模糊。选项值必须是 [-30,30] 范围内的整数。值为 0 时会处理整幅图像，[0,30] 范围内的值会处理平坦区域，[-30,0] 范围内的值会处理边缘。默认值为 0。

chroma_radius, cr

设置色度半径。选项值必须是 [0.1,5.0] 范围内的浮点数，指定用于模糊图像的高斯滤波器的方差（值越大速度越慢）。默认值为 luma_radius。

chroma_strength, cs

设置色度强度。选项值必须是 [-1.0,1.0] 范围内的浮点数，用于配置模糊程度。[0.0,1.0] 范围内的值会模糊图像，而 [-1.0,0.0] 范围内的值会锐化图像。默认值为 luma_strength。

chroma_threshold, ct

设置用作系数的色度阈值，用于判断像素是否应被模糊。选项值必须是 [-30,30] 范围内的整数。值为 0 时会处理整幅图像，[0,30] 范围内的值会处理平坦区域，[-30,0] 范围内的值会处理边缘。默认值为 luma_threshold。

alpha_radius, ar

设置 alpha 半径。选项值必须是 [0.1,5.0] 范围内的浮点数，指定用于模糊图像的高斯滤波器的方差（值越大速度越慢）。默认值为 luma_radius。

alpha_strength, as

设置 alpha 强度。选项值必须是 [-1.0,1.0] 范围内的浮点数，用于配置模糊程度。[0.0,1.0] 范围内的值会模糊图像，而 [-1.0,0.0] 范围内的值会锐化图像。默认值为 luma_strength。

alpha_threshold, at

设置用作系数的 alpha 阈值，用于判断像素是否应被模糊。选项值必须是 [-30,30] 范围内的整数。值为 0 时会处理整幅图像，[0,30] 范围内的值会处理平坦区域，[-30,0] 范围内的值会处理边缘。默认值为 luma_threshold。

如果未显式设置色度或 alpha 选项，则会使用对应的亮度值。

11.238 sobel

对输入视频流应用 sobel 算子。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

scale

设置与滤波结果相乘的值。

delta

设置与滤波结果相加的值。

11.238.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.239 spp

应用一个简单的后处理滤镜：在多个偏移量（当质量等级为 6 时为全部偏移量）下压缩并解压缩图像，然后对结果取平均。

该滤镜接受以下选项：

quality

设置质量。该选项定义用于平均化的级别数量。接受 0-6 范围内的整数。设置为 0 时该滤镜不起作用。值为 6 表示更高的质量。该值每增加 1，速度大约下降为原来的一半。默认值为 3。

强制使用恒定的量化参数。如果未设置，该滤镜将使用视频流中的 QP（如果可用）。

mode

设置阈值处理模式。可用的模式如下：

‘hard’

设置硬阈值处理（默认）。

‘soft’

设置软阈值处理（去振铃效果更好，但可能更模糊）。

use_bframe_qp

设置为 1 时启用使用 B 帧的 QP。由于 B 帧的 QP 通常较大，使用该选项可能会导致闪烁。默认值为 0（不启用）。

11.239.1 命令

该滤镜支持以下命令：

quality, level

设置质量级别。可以使用值 max 来设置最大级别，目前为 6。

11.240 sr

通过应用基于卷积神经网络的超分辨率方法之一来缩放输入。支持的模型如下：

Super-Resolution Convolutional Neural Network 模型（SRCNN）。参见 https://arxiv.org/abs/1501.00092。
Efficient Sub-Pixel Convolutional Neural Network 模型（ESPCN）。参见 https://arxiv.org/abs/1609.05158。

训练脚本以及用于保存模型文件（.pb）的脚本可以在 https://github.com/XueweiMeng/sr/tree/sr_dnn_native 找到。原始仓库位于 https://github.com/HighVoltageRocknRoll/sr.git。

该滤镜接受以下选项：

dnn_backend

指定用于模型加载和执行的 DNN 后端。该选项接受以下值：

‘tensorflow’

TensorFlow 后端。要启用该后端，需要安装 TensorFlow for C 库（参见 https://www.tensorflow.org/install/lang_c），并使用 --enable-libtensorflow 配置 FFmpeg

model

设置指定网络架构及其参数的模型文件路径。请注意，不同的后端使用不同的文件格式。TensorFlow、OpenVINO 后端只能加载各自格式的文件。

scale_factor

设置 SRCNN 模型的缩放系数。允许的值为 2、3 和 4。默认值为 2。SRCNN 模型需要指定缩放系数，因为它接受的输入是先以相应缩放系数经双三次插值放大后的结果。

要获得完整功能（例如异步执行），请使用 dnn_processing 滤镜。

11.241 sr_amf

借助 AMD Advanced Media Framework 库对输入视频做硬件加速放大（增大尺寸），使用高级算法以获得更高质量的输出。输出宽度和高度的设置方式与 scale 滤镜相同。

该滤镜接受以下选项：

w h

设置输出视频尺寸表达式。默认值为输入尺寸。

允许使用与 scale 滤镜相同的表达式。

algorithm

设置用于缩放的算法：

bilinear

双线性

bicubic

双三次

sr1-0

Video SR1.0，这是默认值

point

邻近点

sr1-1

Video SR1.1

sharpness

控制 hq 缩放器的锐化程度。该值是 [0.0, 2.0] 范围内的浮点数

format

控制输出 pixel format。默认情况下，或未指定时，使用输入的 pixel format。

keep-ratio

当输出尺寸的宽高比与输入不同时，强制缩放器保持输入图像的宽高比。默认值为 false。

fill

指定当感兴趣区域未填满整个输出画面时，输出图像中该区域之外的部分是否应使用纯色填充。

11.241.1 示例

将输入缩放为 720p，保持宽高比并确保输出为 yuv420p。
```
sr_amf=-2:720:format=yuv420p
```
使用算法 video SR1.1 放大到 4K。
```
sr_amf=4096:2160:algorithm=sr1-1
```

11.242 ssim

求两个输入视频之间的 SSIM（Structural SImilarity Metric，结构相似性指标）。

该滤镜接受两个输入视频，第一个输入被视为“主”源，并原样传递到输出。第二个输入用作计算 SSIM 的“参考”视频。

要使该滤镜正常工作，两个视频输入必须具有相同的分辨率和 pixel format。此外，它假定两个输入的帧数相同，并会逐帧比较。

该滤镜会存储每一帧计算得到的 SSIM。

以下是所接受参数的说明。

stats_file, f

如果指定该选项，滤镜会将各帧的 SSIM 保存到指定名称的文件中。当文件名等于 "-" 时，数据会被发送到标准输出。

如果选择了 stats_file，输出的文件会为每一对比较的帧包含一系列 key:value 形式的键/值对。

各个显示参数的说明如下：

输入帧的序号，从 1 开始

Y, U, V, R, G, B

由后缀指定的分量在所比较帧之间的 SSIM。

All

整个帧在所比较帧之间的 SSIM。

与上面相同，但以 dB 形式表示。

该滤镜还支持 framesync 选项。

11.242.1 示例

例如：

movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
[main][ref] ssim="stats_file=stats.log" [out]

在这个例子中，正在处理的输入文件会与参考文件 ref_movie.mpg 比较。每一帧的 SSIM 会存储到 stats.log 中。

同时使用 psnr 和 ssim 的另一个例子：

ffmpeg -i main.mpg -i ref.mpg -lavfi  "ssim;[0:v][1:v]psnr" -f null -

使用不同容器的另一个例子：

ffmpeg -i main.mpg -i ref.mkv -lavfi  "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -

11.243 stereo3d

在不同的立体图像格式之间转换。

这些滤镜接受以下选项：

设置输入的立体图像格式。

输入图像格式可用的值如下：

‘sbsl’

并排平行（左眼在左，右眼在右）

‘sbsr’

并排交叉（右眼在左，左眼在右）

‘sbs2l’

并排平行，宽度减半分辨率（左眼在左，右眼在右）

‘sbs2r’

并排交叉，宽度减半分辨率（右眼在左，左眼在右）

‘abl’ ‘tbl’

上下（左眼在上，右眼在下）

‘abr’ ‘tbr’

上下（右眼在上，左眼在下）

‘ab2l’ ‘tb2l’

上下，高度减半分辨率（左眼在上，右眼在下）

‘ab2r’ ‘tb2r’

上下，高度减半分辨率（右眼在上，左眼在下）

‘al’

交替帧（左眼在先，右眼在后）

‘ar’

交替帧（右眼在先，左眼在后）

‘irl’

行交织（左眼位于首行，右眼从下一行开始）

‘irr’

行交织（右眼位于首行，左眼从下一行开始）

‘icl’

列交织，左眼在先

‘icr’

列交织，右眼在先

默认值为 ‘sbsl’。

out

设置输出的立体图像格式。

‘sbsl’

并排平行（左眼在左，右眼在右）

‘sbsr’

并排交叉（右眼在左，左眼在右）

‘sbs2l’

并排平行，宽度减半分辨率（左眼在左，右眼在右）

‘sbs2r’

并排交叉，宽度减半分辨率（右眼在左，左眼在右）

‘abl’ ‘tbl’

上下（左眼在上，右眼在下）

‘abr’ ‘tbr’

上下（右眼在上，左眼在下）

‘ab2l’ ‘tb2l’

上下，高度减半分辨率（左眼在上，右眼在下）

‘ab2r’ ‘tb2r’

上下，高度减半分辨率（右眼在上，左眼在下）

‘al’

交替帧（左眼在先，右眼在后）

‘ar’

交替帧（右眼在先，左眼在后）

‘irl’

行交织（左眼位于首行，右眼从下一行开始）

‘irr’

行交织（右眼位于首行，左眼从下一行开始）

‘arbg’

补色立体图（anaglyph）：红/蓝，灰阶（左眼使用红色滤光片，右眼使用蓝色滤光片）

‘argg’

补色立体图：红/绿，灰阶（左眼使用红色滤光片，右眼使用绿色滤光片）

‘arcg’

补色立体图：红/青，灰阶（左眼使用红色滤光片，右眼使用青色滤光片）

‘arch’

补色立体图：红/青，半彩色（左眼使用红色滤光片，右眼使用青色滤光片）

‘arcc’

补色立体图：红/青，彩色（左眼使用红色滤光片，右眼使用青色滤光片）

‘arcd’

补色立体图：红/青，使用 Dubois 最小二乘投影优化的彩色（左眼使用红色滤光片，右眼使用青色滤光片）

‘agmg’

补色立体图：绿/品红，灰阶（左眼使用绿色滤光片，右眼使用品红色滤光片）

‘agmh’

补色立体图：绿/品红，半彩色（左眼使用绿色滤光片，右眼使用品红色滤光片）

‘agmc’

补色立体图：绿/品红，彩色（左眼使用绿色滤光片，右眼使用品红色滤光片）

‘agmd’

补色立体图：绿/品红，使用 Dubois 最小二乘投影优化的彩色（左眼使用绿色滤光片，右眼使用品红色滤光片）

‘aybg’

补色立体图：黄/蓝，灰阶（左眼使用黄色滤光片，右眼使用蓝色滤光片）

‘aybh’

补色立体图：黄/蓝，半彩色（左眼使用黄色滤光片，右眼使用蓝色滤光片）

‘aybc’

补色立体图：黄/蓝，彩色（左眼使用黄色滤光片，右眼使用蓝色滤光片）

‘aybd’

补色立体图：黄/蓝，使用 Dubois 最小二乘投影优化的彩色（左眼使用黄色滤光片，右眼使用蓝色滤光片）

‘ml’

单目输出（仅左眼）

‘mr’

单目输出（仅右眼）

‘chl’

棋盘格，左眼在先

‘chr’

棋盘格，右眼在先

‘icl’

列交织，左眼在先

‘icr’

列交织，右眼在先

‘hdmi’

HDMI 帧打包

默认值为 ‘arcd’。

11.243.1 示例

将输入视频从并排（parallel）格式转换为黄/蓝色差 Dubois 效果：

    stereo3d=sbsl:aybd

将输入视频从上下格式（左眼在上，右眼在下）转换为并排交叉眼（crosseye）格式。

    stereo3d=abl:sbsr

11.244 streamselect, astreamselect

选择视频或音频流。

该滤镜接受以下选项：

inputs

设置输入数量。默认值为 2。

map

设置要重新映射到输出的输入索引。

11.244.1 命令

streamselect 和 astreamselect 滤镜支持以下命令：

map

设置要重新映射到输出的输入索引。

11.244.2 示例

前 5 秒选择第 1 个流，其余时间选择第 2 个流：

    sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0

与上面相同，但用于音频：

    asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0

11.245 subtitles

使用 libass 库在输入视频上绘制字幕。

要启用该滤镜的编译，需要使用 --enable-libass 配置 FFmpeg。此外，该滤镜还需要包含 libavcodec 和 libavformat 的构建，以便将传入的字幕文件转换为 ASS（Advanced Substation Alpha）字幕格式。

该滤镜接受以下选项：

filename, f

设置要读取的字幕文件的文件名。必须指定。

original_size

指定原始视频的尺寸，即制作该 ASS 文件所依据的视频尺寸。有关该选项的语法，请查看 ffmpeg-utils 手册中的“(ffmpeg-utils)Video size”一节。由于 ASS 宽高比运算存在设计缺陷，若宽高比发生了变化，需要此设置才能正确缩放字体。

fontsdir

设置一个包含滤镜可使用字体的目录路径。这些字体会在字体提供程序所用字体的基础上追加使用。

alpha

处理 alpha 通道，默认情况下 alpha 通道不受影响。

charenc

设置字幕输入的字符编码。仅适用于 subtitles 滤镜。仅当字符编码不是 UTF-8 时才有用。

stream_index, si

设置字幕流的索引。仅适用于 subtitles 滤镜。

force_style

覆盖字幕的默认样式或脚本信息参数。接受一个字符串，其中包含以 "," 分隔的 ASS 样式格式 KEY=VALUE 组合。

wrap_unicode

按照 Unicode 换行算法进行折行。要使用此功能，至少需要 libass 0.17.0 版本（或 LIBASS_VERSION 0x01600010），并且 libass 必须使用 libunibreak 构建。

除原生 ASS 外，该选项默认启用。

shaping

设置整形（shaping）引擎。

可用值如下：

‘auto’

默认的 libass 整形引擎，是现有可用选项中最好的一个。

‘simple’

快速且不依赖字体的整形器，只能执行替换。

‘complex’

使用 OpenType 进行替换和定位的较慢整形器。渲染阿拉伯语、希伯来语、天城文、泰语等复杂文字体系时需要用到。要求 libass 使用 HarfBuzz 构建。

默认值为 auto。

如果未指定第一个键，则假定第一个值指定的是文件名。

例如，要在输入视频上渲染文件 sub.srt，可使用以下命令：

subtitles=sub.srt

这等价于：

subtitles=filename=sub.srt

要渲染文件 video.mkv 中的默认字幕流，使用：

subtitles=video.mkv

要渲染该文件中的第二条字幕流，使用：

subtitles=video.mkv:si=1

要让来自 sub.srt 的字幕流以 80% 透明的蓝色 DejaVu Serif 字体显示，使用：

subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'

11.246 super2xsai

使用 Super2xSaI（Scale and Interpolate）像素画缩放算法，将输入放大 2 倍并进行平滑处理。

适用于在不降低锐度的情况下放大像素画图像。

11.247 swaprect

交换视频中的两个矩形区域。

此滤镜接受以下选项：

设置对象宽度。

设置对象高度。

设置第 1 个矩形的 x 坐标。

设置第 1 个矩形的 y 坐标。

设置第 2 个矩形的 x 坐标。

设置第 2 个矩形的 y 坐标。

所有表达式都在每一帧计算一次。

所有选项均为包含以下常量的表达式：

w h

输入的宽度和高度。

与 w / h 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，与 (w / h) * sar 相同

输入帧的编号，从 0 开始。

以秒表示的时间戳。如果输入时间戳未知，则为 NAN。

pos

输入帧在文件中的位置，未知时为 NAN；已弃用，请勿使用

11.247.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.248 swapuv

交换 U 和 V 平面。

11.249 tblend

混合连续的视频帧。

参见 blend

11.250 telecine

对视频应用电视电影（telecine）处理。

此滤镜接受以下选项：

first_field

‘top, t’

顶场在前

‘bottom, b’

底场在前。默认值为 top。

pattern

表示所需应用的下拉（pulldown）模式的数字字符串。默认值为 23。

Some typical patterns:

NTSC output (30i):
27.5p: 32222
24p: 23 (classic)
24p: 2332 (preferred)
20p: 33
18p: 334
16p: 3444

PAL output (25i):
27.5p: 12222
24p: 222222222223 ("Euro pulldown")
16.67p: 33
16p: 33333334

11.251 thistogram

计算并绘制输入视频随时间变化的颜色分布直方图。

与仅显示某一时刻单帧直方图的 histogram 视频滤镜不同，该滤镜还会显示由 width 选项定义的若干帧的历史直方图。

所计算的直方图表示图像中各颜色分量的分布。

该滤镜接受以下选项：

width, w

设置单个颜色分量输出的宽度。默认值为 0。值为 0 表示宽度将从输入视频中选取。这同时也设置了要保留的历史直方图数量。允许的范围是 [0, 8192]。

display_mode, d

设置显示模式。接受以下值：

‘stack’

各颜色分量的图形依次上下排列。

‘parade’

各颜色分量的图形并排放置。

‘overlay’

所显示的信息与 parade 相同，区别在于表示各颜色分量的图会直接相互叠加。

默认值为 stack。

levels_mode, m

设置模式。可以是 linear 或 logarithmic。默认值为 linear。

components, c

设置要显示的颜色分量。默认值为 7。

bgopacity, b

设置背景不透明度。默认值为 0.9。

envelope, e

显示包络线。默认禁用。

ecolor, ec

设置包络线颜色。默认值为 gold。

slide

设置滑动模式。

slide 可用的值有：

‘frame’

到达右边界时绘制新帧。

‘replace’

用新列替换旧列。

‘scroll’

从右向左滚动。

‘rscroll’

从左向右滚动。

‘picture’

绘制单张图片。

默认值为 replace。

11.252 threshold

对视频流应用阈值（threshold）效果。

该滤镜需要 4 个视频流来执行阈值处理。第 1 个流是要进行滤镜处理的流；第 2 个流保存阈值；第 3 个流保存最小值；最后第 4 个流保存最大值。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

例如，如果第 1 个流的像素分量值小于第 2 个阈值流对应像素分量的阈值，则选取第 3 个流的值，否则选取第 4 个流的像素分量值。

借助 color 源滤镜可以执行各种类型的阈值处理：

11.252.1 命令

该滤镜支持将所有选项用作命令。

11.252.2 示例

使用灰色作为阈值的二值化阈值处理：

    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi

使用灰色作为阈值的反转二值化阈值处理：

    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi

使用灰色作为阈值的截断二值化阈值处理：

    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi

使用灰色作为阈值的归零阈值处理：

    ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi

使用灰色作为阈值的反转归零阈值处理：

    ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi

11.253 thumbnail

从给定的一系列连续帧中选出最具代表性的一帧。

该滤镜接受以下选项：

设置要分析的帧批次大小；在一组 n 帧中，滤镜会从中选出一帧，然后处理下一批 n 帧，直到结束。默认值为 100。

log

设置用于显示所选帧统计信息的日志级别。默认值为 info。

由于该滤镜会追踪整个帧序列，n 值越大内存占用也越高，因此不建议设置过大的值。

11.253.1 示例

每 50 帧提取一张图片：

    thumbnail=50

使用 ffmpeg 创建缩略图的完整示例：

    ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png

11.254 tile

将若干连续帧平铺在一起。

untile 滤镜可以执行相反的操作。

该滤镜接受以下选项：

layout

以 COLUMNSxROWS 的形式设置网格大小。范围最多为 UINT_MAX 个单元格。默认值为 6x5。

nb_frames

设置在给定区域内渲染的最大帧数。该值必须小于等于 wxh。默认值为 0，表示将使用整个区域。

margin

以像素为单位设置外边距。范围为 0 到 1024。默认值为 0。

padding

设置内边框的厚度（即帧与帧之间的像素数）。若需要更高级的填充选项（例如让各边使用不同的值），请参考 pad 视频滤镜。范围为 0 到 1024。默认值为 0。

color

指定未使用区域的颜色。有关该选项的语法，请查看 ffmpeg-utils 手册中的“(ffmpeg-utils)Color”一节。color 的默认值为 "black"。

overlap

设置将若干连续帧平铺在一起时重叠的帧数。该值必须介于 0 和 nb_frames - 1 之间。默认值为 0。

init_padding

设置在显示第一个输出帧之前初始为空的帧数。这可以控制得到第一个输出帧的快慢。该值必须介于 0 和 nb_frames - 1 之间。默认值为 0。

11.254.1 示例

为影片中的所有 keyframe（-skip_frame nokey）生成 8x8 的 PNG 平铺图：

    ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -fps_mode passthrough keyframes%03d.png

需要 -fps_mode passthrough 来防止 ffmpeg 为匹配原本检测到的帧率而复制每个输出帧。

在 3x2 帧的区域内显示 5 张图片，图片间距 7 像素，初始边距为 2 像素，混合使用扁平式和具名选项：

    tile=3x2:nb_frames=5:padding=7:margin=2

11.255 tiltandshift

应用移轴（tilt-and-shift）效果。

如果将时间和空间互换会发生什么？

通常，视频由若干帧组成，每帧代表不同的时间瞬间，展示了在该帧所捕捉的空间中不断演变的场景。该滤镜是这一概念的对立面，其灵感来自移轴摄影。

经过滤镜处理的一帧包含了构成整个序列的完整事件时间线，这是通过将每一帧中的一条像素条带放入同一帧中来实现的。然而，由于不存在无限宽度的帧，这一处理会以输入帧的宽度为限，并通过为每个后续帧移走一列来重新组成视频。为了将空间映射到时间，该滤镜还会对每个输入帧进行倾斜处理，以保留运动信息。这是通过从每个输入帧中逐步选取不同的列来实现的。

最终结果是一种反转的视差效果，使得远处的物体比前景中的物体移动得快得多。这种视频效果的理想条件是：要么运动极少且背景静止，要么运动很多且景深非常大（例如在火车上移动时拍摄的广阔全景）。

该滤镜接受以下参数：

tilt

在平移的同时对视频进行倾斜（默认）。取消设置后，视频将滑动一张由每帧的第一列组成的静止图像。

start

滤镜处理开始时执行的操作（见下文）。

end

滤镜处理结束时执行的操作（见下文）。

hold

在开始滤镜处理之前应通过多少列。

pad

在结束滤镜处理之前应插入多少列。

通常滤镜从第一帧开始就进行平移和倾斜，并在收到最后一帧时停止。不过，在滤镜处理开始之前，可以保留正常的视频，以便效果缓慢地移入其位置。同样，最后一帧视频也可以在结尾处被重新构建。此外，也可以简单地以黑屏作为开始和结束。

‘none’

滤镜处理立即开始，并在收到最后一帧时结束。

‘frame’

处理期间保持最初几帧或最后一帧原样不变。

‘black’

在滤镜处理的开始或结束处填充黑屏。

11.256 tinterlace

执行各种类型的时间方向场隔行处理。

帧从 1 开始计数，因此第一个输入帧被视为奇数帧。

该滤镜接受以下选项：

mode

指定隔行处理的模式。该选项也可以仅通过一个值来指定。该选项可用值的列表见下文。

可用值如下：

‘merge, 0’

将奇数帧移入上场，偶数帧移入下场，以一半的帧率生成高度加倍的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444

Output:
11111                           33333
22222                           44444
11111                           33333
22222                           44444
11111                           33333
22222                           44444
11111                           33333
22222                           44444

‘drop_even, 1’

仅输出奇数帧，偶数帧被丢弃，以一半的帧率生成高度不变的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444

Output:
11111                           33333
11111                           33333
11111                           33333
11111                           33333

‘drop_odd, 2’

仅输出偶数帧，奇数帧被丢弃，以一半的帧率生成高度不变的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444

Output:
                22222                           44444
                22222                           44444
                22222                           44444
                22222                           44444

‘pad, 3’

将每帧扩展至全高，但用黑色填充交替的行，以相同的输入帧率生成高度加倍的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444

Output:
11111           .....           33333           .....
.....           22222           .....           44444
11111           .....           33333           .....
.....           22222           .....           44444
11111           .....           33333           .....
.....           22222           .....           44444
11111           .....           33333           .....
.....           22222           .....           44444

‘interleave_top, 4’

将奇数帧的上场与偶数帧的下场交织在一起，以一半的帧率生成高度不变的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111<-         22222           33333<-         44444
11111           22222<-         33333           44444<-
11111<-         22222           33333<-         44444
11111           22222<-         33333           44444<-

Output:
11111                           33333
22222                           44444
11111                           33333
22222                           44444

‘interleave_bottom, 5’

将奇数帧的下场与偶数帧的上场交织在一起，以一半的帧率生成高度不变的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222<-         33333           44444<-
11111<-         22222           33333<-         44444
11111           22222<-         33333           44444<-
11111<-         22222           33333<-         44444

Output:
22222                           44444
11111                           33333
22222                           44444
11111                           33333

‘interlacex2, 6’

帧率加倍，高度不变。每个插入的帧都包含来自前一个输入帧的第二个时间场和来自下一个输入帧的第一个时间场。此模式依赖于 top_field_first 标志。适用于没有场同步的隔行视频显示设备。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
 11111           22222           33333           44444
11111           22222           33333           44444
 11111           22222           33333           44444

Output:
11111   22222   22222   33333   33333   44444   44444
 11111   11111   22222   22222   33333   33333   44444
11111   22222   22222   33333   33333   44444   44444
 11111   11111   22222   22222   33333   33333   44444

‘mergex2, 7’

将奇数帧移入上场，偶数帧移入下场，以相同的帧率生成高度加倍的帧。

 ------> time
Input:
Frame 1         Frame 2         Frame 3         Frame 4

11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444
11111           22222           33333           44444

Output:
11111           33333           33333           55555
22222           22222           44444           44444
11111           33333           33333           55555
22222           22222           44444           44444
11111           33333           33333           55555
22222           22222           44444           44444
11111           33333           33333           55555
22222           22222           44444           44444

数值形式已弃用，但出于向后兼容的原因仍被接受。

默认模式为 merge。

flags

指定影响滤镜处理过程的标志。

flags 可用的值有：

low_pass_filter, vlpf

在滤镜中启用线性垂直低通滤波。从包含高频垂直细节的逐行源生成隔行输出时，需要进行垂直低通滤波。滤波将减少“隔行闪烁”和摩尔纹。

complex_filter, cvlpf

启用复杂垂直低通滤波。这种方式对“隔行闪烁”和摩尔纹的削减程度略低，但能更好地保留细节，主观锐度观感也更好。

bypass_il

跳过已经是隔行的帧，仅调整帧率。

垂直低通滤波以及跳过已隔行帧的功能，仅在 mode 为 interleave_top 和 interleave_bottom 时才能启用。

11.257 tmedian

从若干连续输入视频帧中选取中值像素。

该滤镜接受以下选项：

radius

设置中值滤波的半径。默认值为 1。允许的范围是 1 到 127。

planes

设置要滤镜处理的平面。默认值为 15，表示处理所有平面。

percentile

设置中值百分位。默认值为 0.5：默认值 0.5 始终挑选中值，0 挑选最小值，1 挑选最大值。

11.257.1 命令

该滤镜支持将上述所有选项（radius 选项除外）用作命令。

11.258 tmidequalizer

应用时间方向中途视频均衡（Temporal Midway Video Equalization）效果。

中途视频均衡会调整一系列视频帧，使其具有相同的直方图，同时尽可能保持其动态范围。它适用于例如匹配一系列视频帧的曝光等场景。

此滤镜接受以下选项：

radius

设置滤波半径。默认值为 5。允许的范围是 1 到 127。

sigma

设置滤波 sigma。默认值为 0.5。这控制滤波的强度。将该选项设为 0 实际上不会产生任何效果。

planes

设置要处理的平面。默认值为 15，即所有可用平面。

11.259 tmix

混合连续的视频帧。

接受的选项说明如下。

frames

要混合的连续帧数。若未指定，默认值为 3。

weights

指定每个输入视频帧的权重。各权重之间以空格分隔。若权重数量少于帧数，最后指定的权重将用于所有剩余未设置的权重。

scale

指定缩放系数；若设置了该值，会将各权重与像素值相乘后的总和再乘以该系数，得到最终的目标像素值。默认情况下，缩放系数会自动设为权重之和。

planes

设置要滤波的平面。默认为 all。允许的范围是 0 到 15。

11.259.1 示例

平均 7 个连续帧：
```
tmix=frames=7:weights="1 1 1 1 1 1 1"
```
应用简单的时间卷积：
```
tmix=frames=3:weights="-1 3 -1"
```
与上面类似，但仅显示时间差异：
```
tmix=frames=3:weights="-1 2 -1":scale=1
```

11.259.2 命令

该滤镜支持以下命令：

weights scale planes

语法与同名选项相同。

11.260 tonemap

对来自不同动态范围的颜色进行色调映射。

该滤镜要求数据为单精度浮点格式，因为它需要处理（并可以输出）超出范围的值。需要使用另一个滤镜（例如 zscale）将得到的帧转换为可用的格式。

实现的色调映射算法仅适用于线性光（linear light），因此输入数据应事先线性化（并尽可能正确标记）。

ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT

11.260.1 选项

该滤镜接受以下选项。

tonemap

设置要使用的色调映射算法。

可接受的值有：

none

不应用任何色调映射，仅对过亮的像素降低饱和度。

clip

硬性裁剪所有超出范围的值。适用于要求范围内色彩绝对准确的场合，但会使超出范围的值失真。

linear

将整个参考色域线性拉伸为显示设备的倍数。

gamma

在色调曲线之间拟合一条对数传递函数。

reinhard

使用简单曲线保留图像整体亮度，采用非线性对比度，这会使细节变平并降低色彩准确度。

hable

比 reinhard 更好地保留暗部和亮部细节，代价是整体略微变暗。当细节保留比色彩和亮度准确度更重要时使用。

mobius

平滑地映射超出范围的值，同时尽可能保留范围内素材的对比度和色彩。当色彩准确度比细节保留更重要时使用。

默认值为 none。

param

调整色调映射算法。

这会影响以下算法：

none

忽略。

linear

指定拉伸时使用的缩放系数。默认为 1.0。

gamma

指定函数的指数。默认为 1.8。

clip

指定裁剪前与信号相乘的额外线性系数。默认为 1.0。

reinhard

指定显示峰值处的局部对比度系数。默认为 0.5，这意味着色域内的值亮度约为裁剪时的一半。

hable

忽略。

mobius

指定从线性变换过渡到 mobius 变换的转折点。低于该点的所有值都保证按 1:1 映射。值越大，结果越精确，但代价是丢失亮部细节。默认为 0.3，由于初始阶段坡度较陡，范围内的色彩仍能相当准确地保留。

desat

对超过该亮度级别的高光区域进行降饱和处理。参数越大，保留的色彩信息越多。此设置通过将超高光（平滑地）转为白色，来防止色彩出现不自然的过曝。这会让图像看起来更自然，但代价是减少了关于超出范围色彩的信息。

默认值 2.0 较为保守，通常只会作用于天空或阳光直射的表面。设为 0.0 可禁用此选项。

此选项仅在输入帧带有受支持的色彩标签时才有效。

peak

用此值覆盖信号/标称/参考峰值。当显示元数据中嵌入的峰值信息不可靠，或从较低范围向较高范围进行色调映射时很有用。

11.261 tpad

按时间方向填充视频帧。

该滤镜接受以下选项：

start

指定输入视频流之前的延迟帧数。默认为 0。

stop

指定输入视频流之后的填充帧数。设为 -1 可无限填充。默认为 0。

start_mode

设置添加到流开头的帧的种类。可以是 add 或 clone。使用 add 时添加纯色帧；使用 clone 时添加首帧的副本。默认为 add。

stop_mode

设置添加到流末尾的帧的种类。可以是 add 或 clone。使用 add 时添加纯色帧；使用 clone 时添加末帧的副本。默认为 add。

start_duration, stop_duration

指定开始/结束延迟的时长。可接受的语法见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Time duration 一节。这些选项会覆盖 start 和 stop。默认为 0。

color

指定填充区域的颜色。此选项的语法请参阅 ffmpeg-utils 手册中的 “Color” 一节。

color 的默认值为 "black"。

11.262 transpose

交换输入视频的行与列，并可选择将其翻转。

它接受以下参数：

dir

指定转置方向。

可取以下值：

‘0, 4, cclock_flip’

逆时针旋转 90 度并垂直翻转（默认），即：

L.R     L.l
. . ->  . .
l.r     R.r

‘1, 5, clock’

顺时针旋转 90 度，即：

L.R     l.L
. . ->  . .
l.r     r.R

‘2, 6, cclock’

逆时针旋转 90 度，即：

L.R     R.r
. . ->  . .
l.r     L.l

‘3, 7, clock_flip’

顺时针旋转 90 度并垂直翻转，即：

L.R     r.R
. . ->  . .
l.r     l.L

对于 4-7 之间的值，只有当输入视频的几何形状为纵向而非横向时才会执行转置。这些值已弃用，应改用 passthrough 选项。

数值已弃用，应改用符号常量。

passthrough

如果输入的几何形状与指定值所表示的形状相符，则不应用转置。可接受以下值：

‘none’

始终应用转置。

‘portrait’

保持纵向几何形状（当高度 >= 宽度时）。

‘landscape’

保持横向几何形状（当宽度 >= 高度时）。

默认值为 none。

例如，要顺时针旋转 90 度并保持纵向布局：

transpose=dir=1:passthrough=portrait

上面的命令也可以写成：

transpose=1:portrait

11.263 trim

截取输入，使输出只包含输入中连续的一部分。

它接受以下参数：

start

指定保留部分的起始时间，即时间戳为 start 的帧将成为输出中的第一帧。

end

指定第一个将被丢弃的帧的时间，即紧邻时间戳为 end 的帧之前的那一帧，将成为输出中的最后一帧。

start_pts

与 start 相同，只是此选项以时间基（timebase）单位而非秒来设置起始时间戳。

end_pts

与 end 相同，只是此选项以时间基（timebase）单位而非秒来设置结束时间戳。

duration

输出的最大时长，单位为秒。

start_frame

应传递给输出的第一帧的编号。

end_frame

应被丢弃的第一帧的编号。

start、end 和 duration 均以时间长度规格表示；可接受的语法见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的 Time duration 一节。

请注意，前两组 start/end 选项以及 duration 选项依据的是帧时间戳，而 _frame 变体只是单纯统计通过该滤镜的帧数。另请注意，此滤镜不会修改时间戳。如果希望输出的时间戳从零开始，请在 trim 滤镜之后插入一个 setpts 滤镜。

如果设置了多个 start 或 end 选项，此滤镜会尽量贪婪地保留所有至少满足其中一个指定约束的帧。若只想保留同时满足全部约束的部分，请串联多个 trim 滤镜。

各选项的默认值会保留全部输入。因此例如可以只设置 end 值，以保留指定时间之前的所有内容。

示例：

丢弃除输入的第二分钟之外的所有内容：
```
ffmpeg -i INPUT -vf trim=60:120
```
只保留第一秒：
```
ffmpeg -i INPUT -vf trim=duration=1
```

11.264 unpremultiply

以第二个流的第一个平面作为 alpha，对输入视频流施加 alpha 反预乘（unpremultiply）效果。

两个流必须具有相同的尺寸和相同的 pixel format。

该滤镜接受以下选项：

planes

设置要处理的平面，未处理的平面将被直接复制。默认值为 0xf，即处理所有平面。

如果该格式有 1 或 2 个分量，则亮度为第 0 位。如果该格式有 3 或 4 个分量：对于 RGB 格式，第 0 位是绿色，第 1 位是蓝色，第 2 位是红色；对于 YUV 格式，第 0 位是亮度，第 1 位是色度 U，第 2 位是色度 V。如果存在 alpha 通道，它始终是最后一位。

inplace

处理时不要求第二路输入，而是使用输入流自身的 alpha 平面。

11.265 unsharp

锐化或模糊输入视频。

它接受以下参数：

luma_msize_x, lx

设置亮度矩阵的水平尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

luma_msize_y, ly

设置亮度矩阵的垂直尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

luma_amount, la

设置亮度效果的强度。必须是浮点数，合理取值在 -1.5 到 1.5 之间。

负值会使输入视频模糊，正值会使其锐化，值为零则禁用该效果。

默认值为 1.0。

chroma_msize_x, cx

设置色度矩阵的水平尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

chroma_msize_y, cy

设置色度矩阵的垂直尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

chroma_amount, ca

设置色度效果的强度。必须是浮点数，合理取值在 -1.5 到 1.5 之间。

负值会使输入视频模糊，正值会使其锐化，值为零则禁用该效果。

默认值为 0.0。

alpha_msize_x, ax

设置 alpha 矩阵的水平尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

alpha_msize_y, ay

设置 alpha 矩阵的垂直尺寸。必须是 3 到 23 之间的奇数整数。默认值为 5。

alpha_amount, aa

设置 alpha 效果的强度。必须是浮点数，合理取值在 -1.5 到 1.5 之间。

负值会使输入视频模糊，正值会使其锐化，值为零则禁用该效果。

默认值为 0.0。

所有参数都是可选的，默认相当于字符串 ’5:5:1.0:5:5:0.0’。

11.265.1 示例

应用强烈的亮度锐化效果：

unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5

对亮度和色度参数同时应用强烈的模糊效果：
```
unsharp=7:7:-2:7:7:-2
```

11.266 untile

将由平铺图像组成的视频分解为各个独立的图像。

输出视频的帧率是输入视频的帧率乘以平铺图像的数量。

此滤镜执行与 tile 相反的操作。

该滤镜接受以下选项：

layout

设置网格大小（即行数和列数）。此选项的语法请参阅 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。

11.266.1 示例

从由 25 帧垂直堆叠组成的静态图像文件生成一段 1 秒的视频，如同一段模拟胶片：
```
ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
```

11.267 uspp

应用一个超慢速/简单的后处理滤镜，它会以多种（若质量等级为 8，则为全部）偏移方式对图像进行压缩和解压缩，并对结果取平均。

它与 spp 行为的不同之处在于，uspp 实际上会用 libavcodec 的 Snow 对每种情况进行编码和解码，而 spp 使用的是类似 MJPEG 的简化版仅帧内 8x8 DCT。

此滤镜在 5.0 到 6.0 之间的 ffmpeg 版本中不可用。

该滤镜接受以下选项：

quality

设置质量。此选项定义用于取平均的等级数。接受 0-8 范围内的整数。若设为 0，此滤镜将不起作用。值为 8 表示最高质量。该值每增加一级，速度大约下降一半。默认值为 3。

强制使用恒定的量化参数。如果未设置，此滤镜将使用视频流中的 QP（若可用）。

codec

使用指定的 codec，而不是 snow。

11.268 v360

在各种格式之间转换 360 度视频。

该滤镜接受以下选项：

input output

设置输入/输出视频的格式。

可用的格式：

‘e’ ‘equirect’

等距柱状投影。

‘c3x2’ ‘c6x1’ ‘c1x6’

3x2/6x1/1x6 布局的立方体贴图。

特定于该格式的选项：

in_pad out_pad

设置输入/输出立方体贴图的填充比例。以小数表示。

示例值：

‘0’

不使用填充。

‘0.01’

面的 1% 用作填充。例如，在 1920x1280 分辨率下，面的大小为 640x640，每一侧的填充为 3 像素。（640 * 0.01 = 6 像素）

默认值为 ‘ 0’。最大值为 ‘ 0.1’。

fin_pad fout_pad

设置输入/输出立方体贴图的固定填充。以像素表示。

默认值为 ‘ 0’。若大于零，则会覆盖其他填充选项。

in_forder out_forder

设置输入/输出立方体贴图各面的顺序。为每个位置选择一个方向。

各方向的标记：

‘r’

右

‘l’

左

‘u’

上

‘d’

下

‘f’

前

‘b’

后

默认值为 ‘ rludfb’。

in_frot out_frot

设置输入/输出立方体贴图各面的旋转角度。为每个位置选择一个角度。

各角度的标记：

‘0’

顺时针 0 度

‘1’

顺时针 90 度

‘2’

顺时针 180 度

‘3’

顺时针 270 度

默认值为 ‘ 000000’。

‘eac’

等角立方体贴图（Equi-Angular Cubemap）。

‘flat’ ‘gnomonic’ ‘rectilinear’

普通视频。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘dfisheye’

双鱼眼。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘barrel’ ‘fb’ ‘barrelsplit’

Facebook 的 360 度格式。

‘sg’

球极平面投影格式。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘mercator’

墨卡托投影格式。

‘ball’

球形格式，越靠近后方畸变越明显。

‘hammer’

汉默-艾托夫（Hammer-Aitoff）地图投影格式。

‘sinusoidal’

正弦曲线地图投影格式。

‘fisheye’

鱼眼投影。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘pannini’

帕尼尼（Pannini）投影。

特定于该格式的选项：

h_fov

设置输出的 pannini 参数。

ih_fov

设置输入的 pannini 参数。

‘cylindrical’

柱面投影。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘perspective’

透视投影。（仅限输出）

特定于该格式的选项：

v_fov

设置透视参数。

‘tetrahedron’

四面体投影。

‘tsp’

截头方锥投影。

‘he’ ‘hequirect’

半等距柱状投影。

‘equisolid’

等积（equisolid）格式。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘og’

正射投影格式。

特定于该格式的选项：

h_fov v_fov d_fov

设置输出的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

ih_fov iv_fov id_fov

设置输入的水平/垂直/对角视场角。以度为单位。

如果设置了对角视场角，它会覆盖水平和垂直视场角。

‘octahedron’

八面体投影。

‘cylindricalea’

柱面等积投影。

interp

设置插值方法。
注意：更复杂的插值方法运行时需要占用更多内存。

可用的方法：

‘near’ ‘nearest’

11.268.1 示例

使用双三次插值，将等距柱状投影视频转换为 3x2 布局、1% 填充的立方体贴图：
```
ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
```
提取等角立方体贴图（Equi-Angular Cubemap）的后视图：
```
ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
```
将转置且水平翻转的并排立体格式等角立方体贴图，转换为上下立体格式的等距柱状投影：
```
v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
```

11.268.2 命令

此滤镜支持上述部分选项作为命令。

11.269 vaguedenoiser

应用基于小波的降噪器。

它将视频输入的每一帧使用 Cohen-Daubechies-Feauveau 9/7 变换到小波域，然后对得到的系数进行一些滤波处理，之后再进行小波逆变换。由于小波的特性，这应能在不模糊图像细节的前提下，得到平滑良好、噪声减少的结果。

此滤镜接受以下选项：

threshold

滤波强度。值越高，视频被滤波的程度越强。在视频看起来被过度滤波之前，硬阈值处理可以使用比软阈值处理更高的阈值。默认值为 2。

method

滤镜使用的滤波方法。

可接受的值有：

‘hard’

低于阈值的所有值都将被置零。

‘soft’

低于阈值的所有值都将被置零，高于阈值的所有值都将按阈值减小。

‘garrote’

对系数进行缩放或置零——介于（更）软和（更弱）硬阈值处理之间。

默认值为 garrote。

nsteps

小波对图像进行分解的次数。图像不能被分解超过某个特定点（典型情况下，对于 640x480 的帧为 8 次，因为 2^9 = 512 > 480）。有效值为 1 到 32 之间的整数。默认值为 6。

percent

相对于完全降噪的部分程度（限制系数收缩），范围为 0 到 100。默认值为 85。

planes

要处理的平面列表。默认情况下处理所有平面。

type

滤镜使用的阈值类型。

可接受的值有：

‘universal’

所有分解使用相同的阈值。

‘bayes’

使用的阈值还取决于每次分解的系数。

默认值为 universal。

11.270 varblur

通过使用第 2 个视频流来设置模糊半径，从而应用可变模糊滤镜。第 2 个流必须具有相同的尺寸。

此滤镜接受以下选项：

min_r

设置允许的最小半径。允许范围为 0 到 254。默认值为 0。

max_r

设置允许的最大半径。允许范围为 1 到 255。默认值为 8。

planes

设置要处理的平面。默认情况下使用全部平面。

varblur 滤镜也支持 framesync 选项。

11.270.1 命令

此滤镜支持将上述所有选项作为命令。

11.271 vectorscope

在二维图（称为矢量示波器）上显示 2 个色彩分量的值。

此滤镜接受以下选项：

mode, m

设置矢量示波器模式。

可接受的值有：

‘gray’ ‘tint’

图上显示灰度值，亮度越高表示图上该位置具有相同分量色彩值的像素越多。这是默认模式。

‘color’

图上显示灰度值。视频帧中不存在的周围像素值，按选项 x 和 y 设置的 2 个色彩分量的渐变绘制。第 3 个色彩分量是固定的。

‘color2’

图上显示视频帧中实际存在的色彩分量值。

‘color3’

与 color2 类似，但图上相同 x 和 y 值出现的频率越高，另一个色彩分量（x 和 y 默认值下即亮度）的值就越高。

‘color4’

图上显示视频帧中实际存在的颜色。如果两种不同的颜色映射到图上同一位置，则选择图中未表示的分量值较高的颜色。

‘color5’

图上显示灰度值。与 color 类似，但第 3 个色彩分量取自径向渐变。

设置在 X 轴上表示的色彩分量。默认值为 1。

设置在 Y 轴上表示的色彩分量。默认值为 2。

intensity, i

设置强度，供 gray、color、color3 和 color5 模式使用，用于提高表示图上 (X, Y) 位置出现频率的色彩分量的亮度。

envelope, e

‘none’

无包络，这是默认值。

‘instant’

瞬时包络，即使最暗的单个像素也会被清晰地突出显示。

‘peak’

随时间保留图上出现的最大值和最小值。这样即使不持续盯着矢量示波器，也仍能发现超出范围的值。

‘peak+instant’

峰值包络与瞬时包络的组合。

graticule, g

设置绘制的刻度线类型。

‘none’ ‘green’ ‘color’ ‘invert’ opacity, o

设置刻度线的不透明度。

flags, f

设置刻度线标志。

‘white’

绘制白点的刻度线。

‘black’

绘制黑点的刻度线。

‘name’

绘制颜色点的简称。

bgopacity, b

设置背景不透明度。

lthreshold, l

设置未在 X 轴或 Y 轴上表示的色彩分量的低阈值。低于该值的值将被忽略。默认值为 0。请注意，此值会与该像素分量可能取得的实际最大值相乘。因此对于 8 位输入且低阈值为 0.1 时，实际阈值为 0.1 * 255 = 25。

hthreshold, h

设置未在 X 轴或 Y 轴上表示的色彩分量的高阈值。高于该值的值将被忽略。默认值为 1。请注意，此值会与该像素分量可能取得的实际最大值相乘。因此对于 8 位输入且高阈值为 0.9 时，实际阈值为 0.9 * 255 = 230。

colorspace, c

设置绘制刻度线时使用的色彩空间类型。

‘auto’ ‘601’ ‘709’

默认值为 auto。

tint0, t0 tint1, t1

设置 gray/tint 矢量示波器模式的色调。默认情况下两个选项均为零，表示无色调，输出将保持灰色。

11.272 vidstabdetect

分析视频稳像/去抖动。执行共两遍处理中的第 1 遍，第 2 遍请参见 vidstabtransform。

此滤镜生成一个文件，其中包含关于后续帧的相对平移和旋转变换信息，随后由 vidstabtransform 滤镜使用。

要启用此滤镜的编译，需要在配置 FFmpeg 时使用 --enable-libvidstab。

此滤镜接受以下选项：

result

设置用于写入变换信息的文件路径。默认值为 transforms.trf。

shakiness

设置视频的抖动程度以及摄像机移动的快慢。它接受 1-10 范围内的整数，值为 1 表示轻微抖动，值为 10 表示剧烈抖动。默认值为 5。

accuracy

设置检测过程的精度。必须是 1-15 范围内的值。值为 1 表示低精度，值为 15 表示高精度。默认值为 15。

stepsize

设置搜索过程的步长。以 1 像素的分辨率扫描最小值周围的区域。默认值为 6。

mincontrast

设置最小对比度。低于此值的局部测量区域将被丢弃。必须是 0-1 范围内的浮点值。默认值为 0.3。

tripod

设置三脚架模式的参考帧编号。

如果启用，帧的运动将与滤镜后的流中由指定编号标识的参考帧进行比较。其思路是补偿一个基本静止场景中的所有运动，使摄像机视角保持绝对静止。

如果设置为 0，则禁用此功能。帧从 1 开始计数。

show

在结果帧中显示测量区域和变换。它接受 0-2 范围内的整数。默认值为 0，即禁用任何可视化。

fileformat

要写入的变换数据文件的格式。可接受的值为

‘ascii’

人类可读的纯文本

‘binary’

二进制格式，比 ascii 大约小 40%。(default)

11.272.1 示例

使用默认值：
```
vidstabdetect
```
分析剧烈抖动的影片，并将结果放入文件 mytransforms.trf：
```
vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
```
在结果视频中可视化内部变换的结果：
```
vidstabdetect=show=1
```

使用 ffmpeg 分析抖动程度中等的视频：

ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi

11.273 vidstabtransform

视频稳像/去抖动：共两遍中的第 2 遍，第 1 遍请参见 vidstabdetect。

读取包含每帧变换信息的文件并对其进行应用/补偿。与 vidstabdetect 滤镜配合使用，可用于消除视频抖动。另请参见 http://public.hronopik.de/vid.stab。同时使用 unsharp 滤镜也很重要，见下文。

要启用此滤镜的编译，需要在配置 FFmpeg 时使用 --enable-libvidstab。

11.273.1 选项

input

设置用于读取变换的文件路径。默认值为 transforms.trf。

smoothing

设置用于对摄像机运动进行低通滤波的帧数（value*2 + 1）。默认值为 10。

例如数值为 10 意味着使用 21 帧（过去 10 帧和未来 10 帧）来平滑视频中的运动。较大的值会使视频更平滑，但会限制摄像机的加速度（摇摄/俯仰运动）。0 是模拟静止摄像机的特殊情况。

optalgo

设置摄像机路径优化算法。

接受的值为：

‘gauss’

对摄像机运动使用高斯核低通滤波（默认）

‘avg’

对变换进行平均

maxshift

设置平移帧的最大像素数。默认值为 -1，表示无限制。

maxangle

设置以弧度（degree*PI/180）表示的旋转帧最大角度。默认值为 -1，表示无限制。

crop

指定如何处理因运动补偿而可能显现的边框。

可用值如下：

‘keep’

保留前一帧的图像信息（默认）

‘black’

将边框填充为黑色

invert

设置为 1 时反转变换。默认值为 0。

relative

设置为 1 时将变换视为相对于前一帧，设置为 0 时视为绝对值。默认值为 0。

zoom

设置缩放百分比。正值会产生放大效果，负值会产生缩小效果。默认值为 0（不缩放）。

optzoom

设置用于避免出现边框的最优缩放。

接受的值为：

‘0’

禁用

‘1’

确定最优的静态缩放值（只有非常剧烈的运动才会导致出现可见边框）（默认）

‘2’

确定最优的自适应缩放值（不会出现可见边框），参见 zoomspeed

请注意，zoom 中给出的值会与此处计算出的值相加。

zoomspeed

设置每帧最大缩放的百分比（当 optzoom 设置为 2 时启用）。范围为 0 到 5，默认值为 0.25。

interpol

指定插值类型。

可用值如下：

‘no’

不插值

‘linear’

仅水平方向线性插值

‘bilinear’

双方向线性插值（默认）

‘bicubic’

双方向三次插值（较慢）

tripod

设置为 1 时启用虚拟三脚架模式，等价于 relative=0:smoothing=0。默认值为 0。

另请使用 vidstabdetect 的 tripod 选项。

debug

设置为 1 时提高日志详细程度，检测到的全局运动也会写入临时文件 global_motions.trf。默认值为 0。

11.273.2 示例

使用 ffmpeg 以默认值进行典型的稳像处理：

ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg

请注意此处使用了 unsharp 滤镜，始终建议这样做。

再放大一些，并从给定文件加载变换数据：
```
vidstabtransform=zoom=5:input="mytransforms.trf"
```
将视频进一步平滑：
```
vidstabtransform=smoothing=30
```

11.274 vflip

将输入视频垂直翻转。

例如，使用 ffmpeg 垂直翻转视频：

ffmpeg -i in.avi -vf "vflip" out.avi

11.275 vfrdet

检测可变帧率视频。

此滤镜尝试检测输入是可变帧率还是固定帧率。

结束时，它会输出检测到具有可变增量 pts 的帧数，以及具有恒定增量 pts 的帧数。如果存在增量可变的帧，还会显示遇到的增量的最小值、最大值和平均值。

11.276 vibrance

提升或改变饱和度。

该滤镜接受以下选项：

intensity

设置正值时提升的强度，或负值时改变的强度。默认值为 0。允许范围为 -2 到 2。

rbal

设置红色平衡。默认值为 1。允许范围为 -10 到 10。

gbal

设置绿色平衡。默认值为 1。允许范围为 -10 到 10。

bbal

设置蓝色平衡。默认值为 1。允许范围为 -10 到 10。

rlum

设置红色亮度系数。

glum

设置绿色亮度系数。

blum

设置蓝色亮度系数。

alternate

如果 intensity 为负值且此项设置为 1，颜色将发生变化；否则颜色饱和度会降低，趋向灰色。

11.276.1 命令

该滤镜支持将以上所有选项作为命令使用。

11.277 vif

求两个输入视频之间的平均 VIF（Visual Information Fidelity）。

此滤镜接受两个输入视频。

要使该滤镜正常工作，两个输入视频必须具有相同的分辨率和 pixel format。此外，该滤镜假定两个输入具有相同的帧数，并逐帧比较。

得到的平均 VIF 分数会通过日志系统打印出来。

此滤镜会存储每一帧计算得到的 VIF 分数。

该滤镜还支持 framesync 选项。

在下面的示例中，正在处理的输入文件 main.mpg 会与参考文件 ref.mpg 比较。

ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null -

11.278 vignette

制造或反转自然的暗角效果。

该滤镜接受以下选项：

angle, a

设置镜头角度表达式，以弧度数表示。

该值会被限制在 [0,PI/2] 范围内。

默认值: "PI/5"

x0 y0

设置中心坐标表达式。默认分别为 "w/2" 和 "h/2"。

mode

设置正向/反向模式。

可用的模式为：

‘forward’

距中心点的距离越大，图像越暗。

‘backward’

距中心点的距离越大，图像越亮。这可用于反转暗角效果，不过（目前）还没有自动检测来提取镜头角度和其他设置。它也可用于制造烧灼效果。

默认值为 ‘forward’。

eval

设置表达式（angle、x0、y0）的求值模式。

可接受的值有：

‘init’

仅在滤镜初始化时对表达式求值一次。

‘frame’

对每一个到来的帧求值表达式。由于需要重新计算所有缩放器，这比 ‘init’ 模式慢得多，但可以实现高级的动态表达式。

默认值为 ‘init’。

dither

设置抖动以减少环状色带效应。默认值为 1（启用）。

aspect

设置暗角的宽高比。此设置可用于调整暗角的形状。将该值设为输入的 SAR，即可得到跟随视频尺寸的矩形暗角。

默认值为 1/1。

11.278.1 表达式

alpha、x0 和 y0 表达式可以包含以下参数。

w h

输入的宽度和高度

输入帧的编号，从 0 开始

pts

滤镜后视频帧的 PTS（Presentation TimeStamp）时刻，以 TB 为单位表示，未定义时为 NAN

输入视频的帧率，如果输入帧率未知则为 NAN

滤镜后视频帧的 PTS（Presentation TimeStamp），以秒为单位表示，未定义时为 NAN

输入视频的时间基

11.278.2 示例

应用简单的强暗角效果：
```
vignette=PI/4
```

制造闪烁的暗角效果：

vignette='PI/4+random(1)*PI/50':eval=frame

11.279 vmafmotion

求视频的平均 VMAF 运动分数，这是 VMAF 的组成指标之一。

得到的平均运动分数会通过日志系统打印出来。

该滤镜接受以下选项：

stats_file

如果指定，滤镜将使用命名文件保存每帧相对于前一帧的运动分数。当文件名等于 "-" 时，数据会发送到标准输出。

示例：

ffmpeg -i ref.mpg -vf vmafmotion -f null -

11.280 vpp_amf

使用 AMD Advanced Media Framework 库进行硬件加速，对输入视频进行缩放（调整大小）并转换色彩空间、传输特性或色域。设置输出宽度和高度的方式与 scale 滤镜相同。

该滤镜接受以下选项：

w h

设置输出视频尺寸表达式。默认值为输入尺寸。

允许使用与 scale 滤镜相同的表达式。

scale_type

设置用于缩放的算法：

bilinear

双线性

这是默认值。

bicubic

双三次

format

控制输出 pixel format。默认情况下，或未指定时，使用输入的 pixel format。

force_original_aspect_ratio force_divisible_by

与同名的 scale 滤镜选项工作方式相同。

reset_sar

与同名的 scale 滤镜选项工作方式相同。

in_color_range

覆盖输入的色彩范围。

out_color_range

指定输出色彩范围。

in_trc 和 out_trc 接受的值为：

‘studio’

演播室（或受限、或 MPEG）色彩范围。

‘full’

全（或 JPEG）色彩范围。

color_profile

一次性指定所有色彩属性。

可接受的值如下：

‘bt601’

BT.601

‘bt709’

BT.709

‘bt2020’

BT.2020

in_trc

覆盖输入的传输特性。

out_trc

指定输出的传输特性。

in_trc 和 out_trc 接受的值为：

‘bt709’

BT.709

‘gamma22’

固定伽马值 2.2

‘gamma28’

固定伽马值 2.8

‘smpte170m’

SMPTE-170M

‘smpte240m’

SMPTE-240M

‘linear’

线性

‘log’

LOG

‘log-sqrt’

LOG_SQRT

‘iec61966-2-4’

iec61966-2-4

‘bt1361-ecg’

BT1361_ECG

‘iec61966-2-1’

iec61966-2-1

‘bt2020-10’

面向 10 位内容的 BT.2020

‘bt2020-12’

面向 12 位内容的 BT.2020

‘smpte2084’

SMPTE2084

‘smpte428’

SMPTE428

‘arib-std-b67’

ARIB_STD_B67

in_primaries

覆盖输入的色彩原色。

out_primaries

指定输出的色彩原色。

in_primaries 和 out_primaries 接受的值为：

‘bt709’

BT.709

‘bt470m’

BT.470M

‘bt470bg’

BT.470BG 或 BT.601-6 625

‘smpte170m’

SMPTE-170M 或 BT.601-6 525

‘smpte240m’

SMPTE-240M

‘film’

胶片

‘bt2020’

BT.2020

‘smpte428’

SMPTE-428

‘smpte431’

SMPTE-431

‘smpte432’

SMPTE-432

‘jedec-p22’

JEDEC P22 荧光粉

11.280.1 示例

将输入缩放为 720p，保持宽高比并确保输出为 yuv420p。
```
vpp_amf=-2:720:format=yuv420p
```
放大为 4K 并将色彩配置文件改为 bt2020。
```
vpp_amf=4096:2160:color_profile=bt2020
```

覆盖输入的原色和输入的传输特性，两者都改为 bt709。

vpp_amf=color_profile=bt2020:in_trc=smpte2084:in_primaries=bt2020:out_trc=bt709:out_primaries=bt709

11.281 vstack

将输入视频垂直堆叠。

所有输入流必须具有相同的 pixel format 且宽度相同。

请注意，此滤镜比使用 overlay 滤镜和 pad 滤镜生成同样的输出要快。

该滤镜接受以下选项：

inputs

设置输入流的数量。默认值为 2。

shortest

若设为 1，则在最短的输入结束时强制终止输出。默认值为 0。

11.282 w3fdif

对输入视频进行去隔行处理（“w3fdif” 是 “Weston 3 Field Deinterlacing Filter” 的缩写）。

该滤镜基于 BBC R&D 的 Martin Weston 所描述的处理流程，并基于 BBC R&D 的 Jim Easterbrook 编写的去隔行算法实现，使用了 BBC R&D 计算出的滤波器系数。

此滤镜利用帧内的场主导信息来决定每对场中哪一个应先放置在输出中。若判断有误，可在 w3fdif 滤镜之前使用 setfield 滤镜。

滤波器系数有两组，分别称为 “simple” 和 “complex”。可通过一个可选参数设置使用哪一组系数：

filter

设置去隔行滤波器系数。接受以下值之一：

‘simple’

简单滤波器系数组。

‘complex’

更复杂的滤波器系数组。

默认值为 ‘complex’。

mode

采用的去隔行模式。接受以下值之一：

frame

每个帧输出一帧。

field

每个场输出一帧。

默认值为 field。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

tff

假定顶场在前。

bff

假定底场在前。

auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

‘all’

对所有帧进行去隔行处理，

‘interlaced’

仅对标记为隔行的帧进行去隔行处理。

默认值为 ‘all’。

11.282.1 命令

此滤镜支持与选项相同的命令。

11.283 waveform

视频波形监视器。

波形监视器绘制色彩分量强度。默认仅显示亮度。波形的每一列对应源视频中的一列像素。

它接受以下选项：

mode, m

可为 row 或 column。默认值为 column。在 row 模式下，图形左侧代表色彩分量值 0，右侧代表值 255。在 column 模式下，上侧代表色彩分量值 0，下侧代表值 255。

intensity, i

设置强度。较小的值有助于查看相同亮度的值在输入的行/列中分布的数量。默认值为 0.04。允许范围为 [0, 1]。

mirror, r

设置镜像模式。0 表示不镜像，1 表示镜像。在镜像模式下，row 模式下较高的值会显示在左侧，column 模式下则显示在顶部。默认值为 1（镜像）。

display, d

设置显示模式。接受以下值：

‘overlay’

所显示的信息与 parade 相同，区别在于表示各颜色分量的图会直接相互叠加。

这种显示模式可以更容易地发现中性白、灰、黑等本应相同的色彩分量在重叠区域中的相对差异或相似之处。

‘stack’

在 row 模式下将各色彩分量的图形并排显示，在 column 模式下则上下排列显示。

‘parade’

在 column 模式下将各色彩分量的图形并排显示，在 row 模式下则上下排列显示。

使用这种显示模式，通过比较每个波形上下两条图形的轮廓，可以轻松发现图像高光和阴影中的偏色。由于白、灰、黑的红、绿、蓝分量精确相等，画面中的中性区域应显示出宽度/高度大致相等的三条波形。若并非如此，只需对这三条波形进行电平调整即可轻松校正。

默认值为 stack。

components, c

设置要显示的色彩分量。默认值为 1，表示仅显示亮度（若输入为 RGB 色彩空间，则为红色分量）。例如设为 7，则会显示全部 3 个（若可用）色彩分量。

envelope, e

‘none’

无包络，此为默认值。

‘instant’

瞬时包络。即使 step 值很小，图形中显示的最小值和最大值也能清晰可见。

‘peak’

在时间轴上保留图形中显示的最小值和最大值。这样即可在不持续盯着波形的情况下发现超出范围的值。

‘peak+instant’

peak 与 instant 包络的组合。

filter, f

‘lowpass’

无滤波，此为默认值。

‘flat’

亮度与色度组合在一起。

‘aflat’

与上相同，但显示蓝色度与红色度之间的差异。

‘xflat’

与上相同，但使用不同的颜色。

‘yflat’

与上相同，但再次使用不同的颜色。

‘chroma’

仅显示色度。

‘color’

在波形上显示实际颜色值。

‘acolor’

与上相同，但亮度显示的是色度值的频率。

graticule, g

设置要显示的标线。

‘none’

不显示标线。

‘green’

显示表示合法广播范围的绿色标线。

‘orange’

显示表示合法广播范围的橙色标线。

‘invert’

显示表示合法广播范围的反色标线。

opacity, o

设置标线不透明度。

flags, fl

设置标线标志。

‘numbers’

在线条上方绘制数字。默认启用。

‘dots’

用点代替线条绘制。

scale, s

设置显示标线所用的刻度。

‘digital’ ‘millivolts’ ‘ire’

默认值为 digital。

bgopacity, b

设置背景不透明度。

tint0, t0 tint1, t1

设置输出的色调。仅在使用 lowpass 滤波、display 不为 overlay 且输入 pixel format 不是 RGB 时使用。

fitmode, fm

设置视频输出帧的采样宽高比。可用于配置波形，使其不会在某个方向上过度拉伸。

‘none’

将采样宽高比设为 1/1。

‘size’

将采样宽高比设置为匹配视频的输入尺寸。

默认值为 ‘none’。

input

设置滤镜可选用的输入格式。可为 ‘all’（从所有可用格式中选择），或 ‘first’（选择第一个可用格式）。默认值为 ‘first’。

11.284 weave, doubleweave

weave 接受基于场的视频输入，将每两个连续的场合并为单帧，生成高度加倍、帧率和帧数减半的新片段。

doubleweave 的工作方式与 weave 相同，但不会将帧率和帧数减半。

它接受以下选项：

first_field

设置首场。可用值为：

‘top, t’

将该帧设为顶场优先。

‘bottom, b’

将该帧设为底场优先。

11.284.1 示例

使用 select 和 separatefields 滤镜对视频进行隔行处理：
```
separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
```

11.285 xbr

应用专为像素艺术设计的 xBR 高质量放大滤镜。它遵循一套边缘检测规则，参见 https://forums.libretro.com/t/xbr-algorithm-tutorial/123。

它接受以下选项：

设置缩放维度：2 表示 2xBR，3 表示 3xBR，4 表示 4xBR。默认值为 3。

11.286 xcorrelate

在第一个和第二个输入视频流之间应用归一化互相关。

第二个输入视频流的尺寸必须小于第一个输入视频流。

该滤镜接受以下选项：

planes

设置要处理的平面。

secondary

设置将处理第二个输入视频流的哪些次要视频帧，可为 first 或 all。默认值为 all。

xcorrelate 滤镜还支持 framesync 选项。

11.287 xfade

对一个输入视频流应用到另一个输入视频流的交叉淡化。交叉淡化会持续指定的时长。

两路输入必须是恒定帧率，且具有相同的分辨率、pixel format、帧率和时间基。

该滤镜接受以下选项：

transition

设置以下可用过渡效果之一：

‘custom’ ‘fade’ ‘wipeleft’ ‘wiperight’ ‘wipeup’ ‘wipedown’ ‘slideleft’ ‘slideright’ ‘slideup’ ‘slidedown’ ‘circlecrop’ ‘rectcrop’ ‘distance’ ‘fadeblack’ ‘fadewhite’ ‘radial’ ‘smoothleft’ ‘smoothright’ ‘smoothup’ ‘smoothdown’ ‘circleopen’ ‘circleclose’ ‘vertopen’ ‘vertclose’ ‘horzopen’ ‘horzclose’ ‘dissolve’ ‘pixelize’ ‘diagtl’ ‘diagtr’ ‘diagbl’ ‘diagbr’ ‘hlslice’ ‘hrslice’ ‘vuslice’ ‘vdslice’ ‘hblur’ ‘fadegrays’ ‘wipetl’ ‘wipetr’ ‘wipebl’ ‘wipebr’ ‘squeezeh’ ‘squeezev’ ‘zoomin’ ‘fadefast’ ‘fadeslow’ ‘hlwind’ ‘hrwind’ ‘vuwind’ ‘vdwind’ ‘coverleft’ ‘coverright’ ‘coverup’ ‘coverdown’ ‘revealleft’ ‘revealright’ ‘revealup’ ‘revealdown’

默认过渡效果为 fade。

duration

以秒为单位设置交叉淡化时长。范围为 0 到 60 秒。默认时长为 1 秒。

offset

以秒为单位设置交叉淡化相对于第一个输入流的起始位置。默认偏移量为 0。

expr

设置自定义过渡效果的表达式。

该表达式可以使用以下变量和函数：

X Y

当前采样点的坐标。

W H

图像的宽度和高度。

过渡效果的进度。

PLANE

当前正在处理的平面。

返回第一个输入在当前位置和平面的值。

返回第二个输入在当前位置和平面的值。

a0(x, y) a1(x, y) a2(x, y) a3(x, y)

返回第一个输入的第一/第二/第三/第四分量在位置 (x,y) 处的像素值。

b0(x, y) b1(x, y) b2(x, y) b3(x, y)

返回第二个输入的第一/第二/第三/第四分量在位置 (x,y) 处的像素值。

11.287.1 示例

从一个输入视频交叉淡化到另一个输入视频，使用 fade 过渡效果，过渡时长为 2 秒，从偏移 5 秒处开始：
```
ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
```

11.288 xmedian

从多个输入视频中选取中位数像素。

该滤镜接受以下选项：

inputs

设置输入数量。默认值为 3。允许范围为 3 到 255。若输入数量为偶数，则结果为两个中间值的平均值。

planes

设置要过滤的平面。默认值为 15，表示处理所有平面。

percentile

设置中值百分位。默认值为 0.5：默认值 0.5 始终挑选中值，0 挑选最小值，1 挑选最大值。

11.288.1 命令

此滤镜支持将以上所有选项作为命令，inputs 选项除外。

11.289 xpsnr

获取两个输入视频之间的平均值（跨所有输入帧）和最小值（跨所有色彩平面平均值）的扩展感知加权峰值信噪比（XPSNR）。

XPSNR 是一种低复杂度的、基于心理视觉感知的失真度量算法，用于评估两个视频流或图像之间的差异。这对于客观量化视频和图像 codec 造成的失真尤为有用，可作为正式主观测试的替代方案。对数化的 XPSNR 输出值与传统 psnr 评估的取值范围相近，但能更好地反映人类对视觉编码质量的感受。关于 XPSNR 度量（本质上是 PSNR 度量的分块加权变体）的更多细节，可参阅以下可免费获取的论文：

C. R. Helmrich, M. Siekmann, S. Becker, S. Bosse, D. Marpe, and T. Wiegand, "XPSNR: A Low-Complexity Extension of the Perceptually Weighted Peak Signal-to-Noise Ratio for High-Resolution Video Quality Assessment," in Proc. IEEE Int. Conf. Acoustics, Speech, Sig. Process. (ICASSP), virt./online, May 2020. www.ecodis.de/xpsnr.htm
C. R. Helmrich, S. Bosse, H. Schwarz, D. Marpe, and T. Wiegand, "A Study of the Extended Perceptually Weighted Peak Signal-to-Noise Ratio (XPSNR) for Video Compression with Different Resolutions and Bit Depths," ITU Journal: ICT Discoveries, vol. 3, no. 1, pp. 65 - 72, May 2020. http://handle.itu.int/11.1002/pub/8153d78b-en

在发表使用（例如）本 FFmpeg 滤镜获得的 XPSNR 评估结果时，强烈建议引用上述论文作为文档说明的方式。此滤镜需要两个输入视频。第一个输入被视为（通常未失真的）参考源，会原样传递到输出，而第二个输入是（经过失真处理的）测试信号。除位深度外，这两个视频输入必须具有相同的 pixel format。此外，为获得最佳性能，两个被比较的输入视频都应采用 YCbCr 色彩格式。

上述获得的整体 XPSNR 值会通过日志系统打印出来。对于具有多个色彩平面的输入，我们建议报告最小 XPSNR 平均值。

以下参数（其行为与 psnr 滤镜中的同名参数相同）会被接受：

stats_file, f

若指定，此滤镜会使用指定名称的文件保存每一帧及每个色彩平面的 XPSNR 值。当文件名等于 "-" 时，该数据会被发送到标准输出。

该滤镜还支持 framesync 选项。

11.289.1 示例

对两个 1080p 高清视频 ref_source.yuv 和 test_video.yuv 进行 XPSNR 分析，两者均为每秒 24 帧、色彩格式为 4:2:0、位深度为 8，并输出名为 "xpsnr.log" 的日志文件：
```
ffmpeg -s 1920x1080 -framerate 24 -pix_fmt yuv420p -i ref_source.yuv -s 1920x1080 -framerate
24 -pix_fmt yuv420p -i test_video.yuv -lavfi xpsnr="stats_file=xpsnr.log" -f null -
```
对两个 2160p 超高清视频进行 XPSNR 分析，其中 ref_source.yuv 位深度为 8，test_video.yuv 位深度为 10，两者均为每秒 60 帧、色彩格式为 4:2:0，不输出日志文件：
```
ffmpeg -s 3840x2160 -framerate 60 -pix_fmt yuv420p -i ref_source.yuv -s 3840x2160 -framerate
60 -pix_fmt yuv420p10le -i test_video.yuv -lavfi xpsnr="stats_file=-" -f null -
```

11.290 xstack

将视频输入堆叠为自定义布局。

所有输入流必须具有相同的 pixel format。

该滤镜接受以下选项：

inputs

设置输入流的数量。默认值为 2。

layout

指定输入的布局。此选项要求用户明确设置所需的布局配置。它设置每个视频输入在输出中的位置。每个输入之间用 ’|’ 分隔。第一个数字代表列，第二个数字代表行。数字从 0 开始，用 ’_’ 分隔。也可以选择使用 wX 和 hX，其中 X 是用来取宽度或高度的视频输入编号。用 ’+’ 分隔可使用多个值，此时这些值会被相加。

请注意，若各输入尺寸不同，可能会出现空隙，因为输出视频帧不会被完全填满。同样，若各输入的位置未能为相邻视频留出足够空间，视频之间也可能相互重叠。

对于 2 个输入，会设置默认布局 0_0|w0_0（等同于 grid=2x1）。在其他所有情况下，用户必须设置布局或网格。grid 和 layout 一次只能指定一个，若两者同时指定则会导致错误。

grid

指定固定尺寸的输入网格。此选项用于创建输入流的固定尺寸网格。以 COLUMNSxROWS 的形式设置网格尺寸。必须有 ROWS * COLUMNS 个输入流，它们将被排列为具有 ROWS 行和 COLUMNS 列的网格。使用此选项时，同一行内的每个输入流必须具有相同的高度，且所有行必须具有相同的宽度。

若设置了 grid，则 inputs 选项会被忽略，并被隐式设为 ROWS * COLUMNS。

对于 2 个输入，会设置默认网格 2x1（等同于 layout=0_0|w0_0）。在其他所有情况下，用户必须设置布局或网格。grid 和 layout 一次只能指定一个，若两者同时指定则会导致错误。

shortest

若设为 1，则在最短的输入结束时强制终止输出。默认值为 0。

fill

若设为合法颜色，所有未使用的像素都将被填充为该颜色。默认情况下 fill 设为 none，即禁用。

11.290.1 示例

将 4 个输入显示为 2x2 网格。

布局：

    input1(0, 0)  | input3(w0, 0)
    input2(0, h0) | input4(w0, h0)


    xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0

请注意，若各输入尺寸不同，可能出现空隙或重叠。

将 4 个输入显示为 1x4 网格。

布局：

    input1(0, 0)
    input2(0, h0)
    input3(0, h0+h1)
    input4(0, h0+h1+h2)


    xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2

请注意，若各输入宽度不同，将出现未使用的空间。

将 9 个输入显示为 3x3 网格。

布局：

    input1(0, 0)       | input4(w0, 0)      | input7(w0+w3, 0)
    input2(0, h0)      | input5(w0, h0)     | input8(w0+w3, h0)
    input3(0, h0+h1)   | input6(w0, h0+h1)  | input9(w0+w3, h0+h1)


    xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1

请注意，若各输入尺寸不同，可能出现空隙或重叠。

将 16 个输入显示为 4x4 网格。

布局：

    input1(0, 0)       | input5(w0, 0)       | input9 (w0+w4, 0)       | input13(w0+w4+w8, 0)
    input2(0, h0)      | input6(w0, h0)      | input10(w0+w4, h0)      | input14(w0+w4+w8, h0)
    input3(0, h0+h1)   | input7(w0, h0+h1)   | input11(w0+w4, h0+h1)   | input15(w0+w4+w8, h0+h1)
    input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)


    xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0|
    w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2

请注意，若各输入尺寸不同，可能出现空隙或重叠。

11.291 yadif

对输入视频进行去隔行处理（“yadif” 表示 “yet another deinterlacing filter”）。

它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

0, send_frame

每个帧输出一帧。

1, send_field

每个场输出一帧。

2, send_frame_nospatial

与 send_frame 相同，但跳过空间隔行检测。

3, send_field_nospatial

与 send_field 相同，但跳过空间隔行检测。

默认值为 send_frame。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

0, tff

假定顶场在前。

1, bff

假定底场在前。

-1, auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

0, all

对所有帧去隔行。

1, interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

11.292 yaepblur

应用在保留边缘的同时进行模糊的滤镜（“yaepblur” 表示 “yet another edge preserving blur filter”）。该算法记述于 “J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980.”。

它接受以下参数：

radius, r

设置窗口半径。默认值为 3。

planes, p

设置要过滤的平面。默认仅为第一个平面。

sigma, s

设置模糊强度。默认值为 128。

11.292.1 命令

此滤镜支持与选项相同的命令。

11.293 zoompan

应用缩放与平移（Zoom & Pan）效果。

此滤镜接受以下选项：

zoom, z

设置缩放表达式。范围为 1-10。默认值为 1。

x y

设置 x 和 y 表达式。默认值为 0。

以帧数设置时长表达式。它设置对单张输入图像该效果将持续多少帧。默认值为 90。

设置输出图像尺寸，默认值为 ’hd720’。

fps

设置输出帧率，默认值为 ’25’。

每个表达式可包含以下常量：

in_w, iw

输入宽度。

in_h, ih

输入高度。

out_w, ow

输出宽度。

out_h, oh

输出高度。

输入帧计数。

输出帧计数。

in_time, it

以秒表示的输入时间戳。若输入时间戳未知，则为 NAN。

out_time, time, ot

以秒表示的输出时间戳。

x y

根据当前输入帧的 ’x’ 和 ’y’ 表达式计算出的最后一次 ’x’ 和 ’y’ 位置。

px py

上一个输入帧最后一个输出帧的 ’x’ 和 ’y’，若尚无此类帧（第一个输入帧）则为 0。

zoom

根据当前输入帧的 ’z’ 表达式计算出的最后一次缩放值。

pzoom

上一个输入帧最后一个输出帧的最后一次计算缩放值。

duration

当前输入帧对应的输出帧数。根据每个输入帧的 ’d’ 表达式计算得出。

pduration

为上一个输入帧创建的输出帧数

有理数：输入宽度 / 输入高度

sar

采样宽高比

dar

显示宽高比

11.293.1 示例

放大到 1.5 倍并同时平移到图像中心附近的某个位置：

zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360

放大到 1.5 倍并始终围绕图像中心平移：

zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'

与上面相同，但不暂停：

zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'

仅在输入视频的第一秒内放大 2 倍到图像中心：

zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'

11.294 zscale

使用 z.lib 库缩放（调整大小）输入视频: https://github.com/sekrit-twc/zimg。要启用此滤镜的编译，需要在配置 FFmpeg 时加上 --enable-libzimg。

zscale 滤镜通过改变输出的采样宽高比，强制输出的显示宽高比与输入保持一致。

如果输入图像格式与下一个滤镜要求的格式不同，zscale 滤镜会将输入转换为所要求的格式。

11.294.1 选项

该滤镜接受以下选项。

width, w height, h

设置输出视频尺寸表达式。默认值为输入尺寸。

如果 width 或 w 的值为 0，输出将使用输入宽度。如果 height 或 h 的值为 0，输出将使用输入高度。

如果两个值中只有一个是 -n（n >= 1），zscale 滤镜会根据另一个指定的尺寸计算出一个能保持输入图像宽高比的值。之后它还会确保计算出的尺寸能被 n 整除，必要时会调整该值。

如果两个值都是 -n（n >= 1），其行为将与之前所述的两个值都设为 0 时相同。

尺寸表达式中可用常量的列表见下文。

size, s

设置视频大小。关于该选项的语法，请查阅 ffmpeg-utils 手册中的“Video size”一节。

dither, d

设置抖动类型。

可接受的值有：

none ordered random error_diffusion

默认值为 none。

filter, f

设置缩放滤镜的类型。

可接受的值有：

point bilinear bicubic spline16 spline36 spline64 lanczos

默认为 bilinear。

range, r

设置色彩范围。

可接受的值有：

input limited full

默认与输入相同。

primaries, p

设置色彩原色。

可接受的值有：

input 709 unspecified 170m 240m 2020

默认与输入相同。

transfer, t

设置传输特性。

可接受的值有：

input 709 unspecified 601 linear 2020_10 2020_12 smpte2084 iec61966-2-1 arib-std-b67

默认与输入相同。

matrix, m

设置色彩空间矩阵。

可接受的值有：

input 709 unspecified 470bg 170m 2020_ncl 2020_cl

默认与输入相同。

rangein, rin

设置输入色彩范围。

可接受的值有：

input limited full

默认与输入相同。

primariesin, pin

设置输入色彩原色。

可接受的值有：

input 709 unspecified 170m 240m 2020

默认与输入相同。

transferin, tin

设置输入传输特性。

可接受的值有：

input 709 unspecified 601 linear 2020_10 2020_12

默认与输入相同。

matrixin, min

设置输入色彩空间矩阵。

可接受的值有：

input 709 unspecified 470bg 170m 2020_ncl 2020_cl chromal, c

设置输出色度位置。

可接受的值有：

input left center topleft top bottomleft bottom chromalin, cin

设置输入色度位置。

可接受的值有：

input left center topleft top bottomleft bottom npl

设置标称峰值亮度。

param_a

缩放滤镜的参数 A。对 bicubic 而言是参数“b”，对 lanczos 而言是滤镜抽头数。

param_b

缩放滤镜的参数 B。对 bicubic 而言是参数“c”。

w 和 h 选项的值是包含以下常量的表达式：

in_w in_h

输入的宽度和高度

iw ih

与 in_w 和 in_h 相同。

out_w out_h

输出（缩放后）的宽度和高度

ow oh

与 out_w、out_h 相同

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入显示宽高比。由 (iw / ih) * sar 计算得出。

hsub vsub

输入的水平和垂直色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2、vsub 为 1。

ohsub ovsub

输出的水平和垂直色度二次采样值。例如对于 pixel format "yuv422p"，hsub 为 2、vsub 为 1。

11.294.2 命令

该滤镜支持以下命令：

width, w height, h

设置输出视频尺寸表达式。该命令接受与对应选项相同的语法。

如果指定的表达式无效，则保持当前值不变。

12 CUDA 视频滤镜

以下是目前可用的 Nvidia CUDA 视频滤镜说明。

前提条件：

安装 Nvidia CUDA Toolkit

注意: 如果 FFmpeg 在配置时检测到 Nvidia CUDA Toolkit，会自动启用 CUDA 滤镜，无需附加任何参数。如果想要显式启用它们，可使用以下选项：

配置 FFmpeg 时加上 --enable-cuda-nvcc --enable-nonfree。
配置 FFmpeg 时加上 --enable-cuda-llvm。附加要求: 必须安装 llvm 库。

运行 CUDA 滤镜要求你初始化一个硬件设备，并将该设备传递给滤镜图中的所有滤镜。

-init_hw_device cuda[=name][:device[,key=value...]]

初始化一个名为 name 的 cuda 类型新硬件设备，使用给定的设备参数。

-filter_hw_device name

将名为 name 的硬件设备传递给滤镜图中的所有滤镜。

更详细的信息见 https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options

初始化系统上的第二块 CUDA 设备，并运行 scale_cuda 与 bilateral_cuda 滤镜的示例。

./ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -init_hw_device cuda:1 -filter_complex \
"[0:v]scale_cuda=format=yuv444p[scaled_video];[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
-an -sn -c:v h264_nvenc -cq 20 out.mp4

由于 CUDA 滤镜只在 GPU 显存上操作，帧数据有时需要在处理前上传（hwupload）到相应 CUDA 设备关联的硬件表面上，处理完成后再下载（hwdownload）回普通内存（如有需要）。是否需要 hwupload 或 hwdownload 取决于具体的工作流程：

如果输入帧已经位于 GPU 显存中（例如使用 -hwaccel cuda 或 -hwaccel_output_format cuda 时），则不需要显式使用 hwupload，因为数据已经处于相应的内存空间中。
如果输入帧位于 CPU 内存中（例如软件解码的帧，或经过基于 CPU 的滤镜处理的帧），则需要使用 hwupload 将数据传输到 GPU 显存以供 CUDA 处理。
如果 CUDA 滤镜的输出还需要由基于软件的滤镜进一步处理，或需要保存为 GPU encoder 不支持的格式，则需要 hwdownload 将数据传回 CPU 内存。

请注意，hwupload 会将数据上传到与软件帧布局相同的表面，因此可能需要在 hwupload 之前紧接着添加一个 format 滤镜，以确保输入采用正确的格式。同样，hwdownload 可能不支持所有输出格式，因此可能需要在 hwdownload 之后紧接着插入一个附加的 format 滤镜，以确保滤镜图中的兼容性。

12.1 bilateral_cuda

CUDA 加速的双边滤镜，一种保边滤镜。得益于 GPU 加速的使用，该滤镜在数学上是精确的。为获得最佳输出质量，请使用一比一的色度二次采样，即 yuv444p 格式。

该滤镜接受以下选项：

sigmaS

设置用于计算空间权重的高斯函数的 sigma 值，也称为空间 sigma。允许的范围是 0.1 到 512。默认为 0.1。

sigmaR

设置用于计算颜色范围权重的高斯函数的 sigma 值，也称为颜色 sigma。允许的范围是 0.1 到 512。默认为 0.1。

window_size

设置双边函数的窗口大小，用于确定循环处理的邻居数量。如果输入的数值为偶数，会自动加一。允许的范围是 1 到 255。默认为 1。

12.1.1 示例

对视频应用双边滤镜。

./ffmpeg -v verbose \
-hwaccel cuda -hwaccel_output_format cuda -i input.mp4  \
-init_hw_device cuda \
-filter_complex \
" \
[0:v]scale_cuda=format=yuv444p[scaled_video];
[scaled_video]bilateral_cuda=window_size=9:sigmaS=3.0:sigmaR=50.0" \
-an -sn -c:v h264_nvenc -cq 20 out.mp4

12.2 bwdif_cuda

使用 bwdif 算法对输入视频去隔行，但以 CUDA 实现，因此可以作为 GPU 加速流水线的一部分与 nvdec 和/或 nvenc 协同工作。

它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

0, send_frame

每个帧输出一帧。

1, send_field

每个场输出一帧。

默认值为 send_field。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

0, tff

假定顶场在前。

1, bff

假定底场在前。

-1, auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

0, all

对所有帧去隔行。

1, interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

12.3 chromakey_cuda

CUDA 加速的 YUV 色彩空间色度键控。

此滤镜的工作方式与普通的 chromakey 滤镜相同，但操作对象为 CUDA 帧。更多细节和参数请参见 chromakey。

12.3.1 示例

将输入视频中所有绿色像素变为透明，并将其用作另一段视频的叠加层：

./ffmpeg \
    -hwaccel cuda -hwaccel_output_format cuda -i input_green.mp4  \
    -hwaccel cuda -hwaccel_output_format cuda -i base_video.mp4 \
    -init_hw_device cuda \
    -filter_complex \
    " \
        [0:v]chromakey_cuda=0x25302D:0.1:0.12:1[overlay_video]; \
        [1:v]scale_cuda=format=yuv420p[base]; \
        [base][overlay_video]overlay_cuda" \
    -an -sn -c:v h264_nvenc -cq 20 output.mp4

处理两个软件来源，显式上传帧：

./ffmpeg -init_hw_device cuda=cuda -filter_hw_device cuda \
    -f lavfi -i color=size=800x600:color=white,format=yuv420p \
    -f lavfi -i yuvtestsrc=size=200x200,format=yuv420p \
    -filter_complex \
    " \
        [0]hwupload[under]; \
        [1]hwupload,chromakey_cuda=green:0.1:0.12[over]; \
        [under][over]overlay_cuda" \
    -c:v hevc_nvenc -cq 18 -preset slow output.mp4

12.4 colorspace_cuda

CUDA 加速实现的 colorspace 滤镜。

它在功能上远不如软件版 colorspace 滤镜完备，目前仅支持 jpeg/full 与 mpeg/limited 范围之间的色彩范围转换。

该滤镜接受以下选项：

range

指定输出色彩范围。

可接受的值如下：

‘tv’

电视（受限）范围

‘mpeg’

MPEG（受限）范围

‘pc’

PC（全）范围

‘jpeg’

JPEG（全）范围

12.5 overlay_cuda

将一个视频叠加在另一个视频之上。

这是 overlay 滤镜的 CUDA 变体。它只接受 CUDA 帧。底层输入 pixel format 必须一致。

它接受两个输入并产生一个输出。第一个输入是 "main"（主）视频，第二个输入叠加在其上。

它接受以下参数：

x y

设置叠加视频在主视频上的 x、y 坐标表达式。

它们可以包含以下参数：

main_w, W main_h, H

主输入的宽度和高度。

overlay_w, w overlay_h, h

叠加输入的宽度和高度。

x y

x 和 y 的计算值。它们在每个新帧都会被求值。

主输入帧的序号，从 0 开始。

pos

主输入帧在文件中的字节偏移位置，如果未知则为 NAN。已弃用，请勿使用。

主输入帧的时间戳，以秒表示，如果未知则为 NAN。

两个表达式的默认值均为 "0"。

eval

设置何时对 x、y 表达式求值。

可接受的值有：

init

在滤镜初始化期间，或在处理某条命令时求值一次。

frame

对每个到来的帧求值

默认值为 frame。

eof_action

参见 framesync。

shortest

参见 framesync。

repeatlast

参见 framesync。

该滤镜还支持 framesync 选项。

12.6 pad_cuda

使用 CUDA 为输入视频流添加填充。

该滤镜是 pad 滤镜的 CUDA 加速版本。它接受相同的选项和表达式，并提供相同的核心功能。有关可用选项的详细说明，请参阅 pad 滤镜的文档。

12.6.1 示例

为视频帧的四边各添加 200 像素的黑边：

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=iw+400:h=ih+400:x=200:y=200" -c:v h264_nvenc out.mp4

将输入视频填充为 16:9 的宽高比，填充颜色为 "blue"：

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 -vf "pad_cuda=w=ih*16/9/sar:h=ih:x=(ow-iw)/2:y=(oh-ih)/2:color=blue" -c:v h264_nvenc out.mp4

12.7 scale_cuda

使用加速的 CUDA 内核对输入视频进行缩放（调整大小）和转换（pixel format）。设置输出宽度和高度的方式与 scale 滤镜相同。

该滤镜接受以下选项：

w h

设置输出视频尺寸表达式。默认值为输入尺寸。

允许使用与 scale 滤镜相同的表达式。

interp_algo

设置用于缩放的算法：

nearest

12.7.1 示例

将输入缩放为 720p，保持宽高比并确保输出为 yuv420p。
```
scale_cuda=-2:720:format=yuv420p
```

使用最近邻算法放大至 4K。

scale_cuda=4096:2160:interp_algo=nearest

不做任何转换或缩放，只是把所有输入帧复制到新分配的帧中。这在需要处理一个会耗尽 decoder 帧池的滤镜与编码链时很有用。
```
scale_cuda=passthrough=0
```

12.8 thumbnail_cuda

使用 CUDA 从一段连续帧序列中选出最具代表性的帧。

该滤镜接受以下选项：

设置要分析的帧批次大小；在一组 n 帧中，该滤镜会挑选其中一帧，然后处理下一批 n 帧，直到结束。默认为 100。

由于该滤镜会跟踪整个帧序列，n 值越大，内存占用越高，因此不建议使用过高的值。

12.8.1 示例

从每 n=150 帧的批次中提取缩略图，每批选出一帧。所选帧随后用 scale_cuda 缩放。

./ffmpeg  -hwaccel cuda -hwaccel_output_format cuda  -i ./input.mp4 -vf "thumbnail_cuda=150,scale_cuda=1920:1080,hwdownload,format=nv12" ./output/out%03d.png

12.9 transpose_cuda

在输入视频中转置行与列，并可选择性地翻转它。更深入的示例请参见 transpose 视频滤镜，它与本滤镜的选项大体相同。

它接受以下参数：

dir

指定转置方向。

可取以下值：

‘cclock_flip’

逆时针旋转 90 度并垂直翻转。（默认）

‘clock’

顺时针旋转 90 度。

‘cclock’

逆时针旋转 90 度。

‘clock_flip’

顺时针旋转 90 度并垂直翻转。

‘reversal’

旋转 180 度。

‘hflip’

水平翻转。

‘vflip’

垂直翻转。

passthrough

如果输入的几何形状与指定值所表示的形状相符，则不应用转置。可接受以下值：

‘none’

始终应用转置。（默认）

‘portrait’

保持纵向几何形状（当高度 >= 宽度时）。

‘landscape’

保持横向几何形状（当宽度 >= 高度时）。

12.10 yadif_cuda

使用 yadif 算法对输入视频去隔行，但以 CUDA 实现，因此可以作为 GPU 加速流水线的一部分与 nvdec 和/或 nvenc 协同工作。

它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

0, send_frame

每个帧输出一帧。

1, send_field

每个场输出一帧。

2, send_frame_nospatial

类似于 send_frame，但跳过空间隔行检查。

3, send_field_nospatial

类似于 send_field，但跳过空间隔行检查。

默认值为 send_frame。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

0, tff

假定顶场在前。

1, bff

假定底场在前。

-1, auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

0, all

对所有帧去隔行。

1, interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

13 OpenCL 视频滤镜

以下是当前可用的 OpenCL 视频滤镜说明。

要启用这些滤镜的编译，需要在配置 FFmpeg 时加上 --enable-opencl。

运行 OpenCL 滤镜需要先初始化一个硬件设备，并将该设备传递给滤镜图中的所有滤镜。

-init_hw_device opencl[=name][:device[,key=value...]]

使用给定的设备参数，初始化一个名为 name 的 opencl 类型新硬件设备。

-filter_hw_device name

将名为 name 的硬件设备传递给滤镜图中的所有滤镜。

更详细的信息见 https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options

选择第二个平台上的第一个设备，并在其上使用默认参数运行 avgblur_opencl 滤镜的示例。
```
-init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
```

由于 OpenCL 滤镜无法访问普通内存中的帧数据，因此所有帧数据在使用前都需要上传（hwupload）到与相应设备相连的硬件表面，处理后再下载（hwdownload）回普通内存。请注意，hwupload 会上传到与软件帧布局相同的表面，因此可能需要在其前面立即插入一个 format 滤镜以获得正确格式的输入；此外 hwdownload 在输出端并不支持所有格式，可能需要在滤镜图中紧随其后插入一个额外的 format 滤镜，使输出成为受支持的格式。

13.1 avgblur_opencl

应用平均模糊滤镜。

该滤镜接受以下选项：

sizeX

设置水平半径大小。范围是 [1, 1024]，默认值是 1。

planes

设置要过滤的平面。默认值是 0xf，即处理所有平面。

sizeY

设置垂直半径大小。范围是 [1, 1024]，默认值是 0。若为零，则使用 sizeX 的值。

13.1.1 示例

应用水平和垂直大小均为 3 的平均模糊滤镜，将输出的每个像素设置为输入中以该像素为中心的 7x7 区域的平均值。对于图像边缘的像素，该区域不会超出图像边界，因此计算中不会使用超出范围的坐标。
```
-i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
```

13.2 boxblur_opencl

对输入视频应用 boxblur 算法。

它接受以下参数：

luma_radius, lr luma_power, lp chroma_radius, cr chroma_power, cp alpha_radius, ar alpha_power, ap

接受的选项说明如下。

luma_radius, lr chroma_radius, cr alpha_radius, ar

设置用于模糊相应输入平面的框半径表达式（以像素为单位）。

半径值必须是非负数，并且不得大于亮度和 alpha 平面的表达式 min(w,h)/2 的值，以及色度平面的 min(cw,ch)/2 的值。

luma_radius 的默认值为 "2"。若未指定，chroma_radius 和 alpha_radius 默认使用为 luma_radius 设置的对应值。

表达式可以包含以下常量：

w h

以像素为单位的输入宽度和高度。

cw ch

以像素为单位的输入色度图像宽度和高度。

hsub vsub

水平和垂直色度二次采样值。例如，对于 pixel format "yuv422p"，hsub 为 2，vsub 为 1。

luma_power, lp chroma_power, cp alpha_power, ap

指定 boxblur 滤镜在相应平面上应用的次数。

luma_power 的默认值为 2。若未指定，chroma_power 和 alpha_power 默认使用为 luma_power 设置的对应值。

值为 0 将禁用该效果。

13.2.1 示例

应用 boxblur 滤镜，将输出的每个像素设置为各平面分别对应的 box 半径 luma_radius、chroma_radius、alpha_radius 的平均值。该滤镜会在相应平面上应用 luma_power、chroma_power、alpha_power 次。对于图像边缘的像素，半径不会超出图像边界，因此计算中不会使用超出范围的坐标。

应用 boxblur 滤镜，将亮度、色度和 alpha 半径设置为 2，亮度、色度和 alpha 的 power 设置为 3。该滤镜将对图像每个平面以半径 2 运行 3 次。
```
-i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
```
应用 boxblur 滤镜，将亮度半径设置为 2、luma_power 设置为 1、chroma_radius 设置为 4、chroma_power 设置为 5、alpha_radius 设置为 3、alpha_power 设置为 7。

对于亮度平面，将以 2x2 的 box 半径运行 1 次。

对于色度平面，将以 4x4 的 box 半径运行 5 次。

对于 alpha 平面，将以 3x3 的 box 半径运行 7 次。

    -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT

13.3 colorkey_opencl

RGB 色彩空间的颜色键控。

该滤镜接受以下选项：

color

将被替换为透明的颜色。

similarity

与键色的相似度百分比。

0.01 只匹配与键色完全一致的颜色，而 1.0 匹配所有颜色。

blend

混合百分比。

0.0 会使像素要么完全透明，要么完全不透明。

数值越大，像素越呈现半透明；像素颜色与键控颜色越相似，透明度就越高。

13.3.1 示例

将输入中每个偏绿的像素以轻微混合的方式变为透明：

-i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT

13.4 convolution_opencl

应用 3x3、5x5、7x7 矩阵的卷积。

该滤镜接受以下选项：

0m 1m 2m 3m

设置每个平面的矩阵。矩阵是由 9、25 或 49 个带符号数字组成的序列。每个平面的默认值为 0 0 0 0 1 0 0 0 0。

0rdiv 1rdiv 2rdiv 3rdiv

为每个平面设置计算值的乘数。若未设置或为 0，则取矩阵所有元素之和。该选项值必须是大于或等于 0.0 的浮点数。默认值为 1.0。

0bias 1bias 2bias 3bias

为每个平面设置偏置值。该值会加到乘法结果上。有助于使整体图像变亮或变暗。该选项值必须是大于或等于 0.0 的浮点数。默认值为 0.0。

13.4.1 示例

应用锐化：

-i INPUT -vf "hwupload, convolution_opencl=0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0, hwdownload" OUTPUT

应用模糊：

-i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9, hwdownload" OUTPUT

应用边缘增强：

-i INPUT -vf "hwupload, convolution_opencl=0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128, hwdownload" OUTPUT

应用边缘检测：

-i INPUT -vf "hwupload, convolution_opencl=0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128, hwdownload" OUTPUT

应用包含对角线方向的拉普拉斯边缘检测：

-i INPUT -vf "hwupload, convolution_opencl=1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0, hwdownload" OUTPUT

应用浮雕：

-i INPUT -vf "hwupload, convolution_opencl=-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2, hwdownload" OUTPUT

13.5 erosion_opencl

对视频应用腐蚀效果。

该滤镜用局部（3x3）最小值替换像素。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量。范围是 [0, 65535]，默认值是 65535。若为 0，平面将保持不变。

coordinates

指定要参照的像素的标志。范围是 [0, 255]，默认值是 255，即使用全部八个像素。

以 x 为中心的局部 3x3 坐标区域的标志：

1 2 3

4 x 5

6 7 8

13.5.1 示例

应用腐蚀滤镜，将 threshold0 设置为 30、threshold1 设置为 40、threshold2 设置为 50、coordinates 设置为 231，将输出的每个像素设置为输入中以该像素为中心的 3x3 区域内像素 1、2、3、6、7、8 之间的局部最小值。如果输入像素与局部最小值之间的差大于相应平面的阈值，输出像素将被设置为输入像素减去相应平面的阈值。
```
-i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
```

13.6 deshake_opencl

基于特征点的视频稳定滤镜。

该滤镜接受以下选项：

tripod

通过阻止原始帧发生任何相机移动来模拟三脚架。默认为 0。

debug

是否在处理后的输出以及控制台中显示额外的调试信息。

注意，要查看控制台调试输出，还需要向 ffmpeg 传递 -v verbose。

在输出视频中查看特征点匹配仅支持 RGB 输入。

默认为 0。

adaptive_crop

是否在边界处做少量裁剪，以减少镜像像素的数量。

默认为 1。

refine_features

是否在亚像素级别对特征点进行细化。

可以关闭此选项以略微提升性能，但会牺牲精度。

默认为 1。

smooth_strength

应用于相机路径的平滑强度，范围从 0.0 到 1.0。

1.0 是最大平滑强度，小于该值时平滑程度会相应降低。

0.0 会使滤镜以每帧为基础自适应地选择平滑强度。

默认为 0.0。

smooth_window_multiplier

控制平滑窗口的大小（即用于确定运动信息而缓冲的帧数）。

平滑窗口的大小由视频的帧率乘以该数值决定。

可接受的取值范围为 0.1 到 10.0。

较大的值会增加可用于确定如何平滑相机路径的运动数据量，可能会提高平滑度，但也会增加延迟和内存占用。

默认为 2.0。

13.6.1 示例

以固定的中等平滑强度稳定视频：

-i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT

在调试模式下稳定视频（同时在控制台和渲染视频中显示）：

-i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT

13.7 dilation_opencl

对视频应用膨胀效果。

该滤镜用局部（3x3）最大值替换像素。

它接受以下选项：

threshold0 threshold1 threshold2 threshold3

限制每个平面的最大变化量。范围是 [0, 65535]，默认值是 65535。若为 0，平面将保持不变。

coordinates

指定要参照的像素的标志。范围是 [0, 255]，默认值是 255，即使用全部八个像素。

以 x 为中心的局部 3x3 坐标区域的标志：

1 2 3

4 x 5

6 7 8

13.7.1 示例

应用膨胀滤镜，将 threshold0 设置为 30、threshold1 设置为 40、threshold2 设置为 50、coordinates 设置为 231，将输出的每个像素设置为输入中以该像素为中心的 3x3 区域内像素 1、2、3、6、7、8 之间的局部最大值。如果输入像素与局部最大值之间的差大于相应平面的阈值，输出像素将被设置为输入像素加上相应平面的阈值。
```
-i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
```

13.8 nlmeans_opencl

通过 OpenCL 实现的非局部均值降噪滤镜，该滤镜接受与 nlmeans 相同的选项。

13.9 overlay_opencl

将一个视频叠加在另一个视频之上。

它接受两个输入，产生一个输出。第一个输入是“主”视频，第二个输入被叠加在其上。该滤镜要求所有输入具有相同的内存布局，因此可能需要进行格式转换。

该滤镜接受以下选项：

设置叠加视频在主视频上的 x 坐标。默认值为 0。

设置叠加视频在主视频上的 y 坐标。默认值为 0。

13.9.1 示例

将图像 LOGO 叠加在 INPUT 视频的左上角。两个输入均为 yuv420p 格式。

-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT

两个输入的色彩通道具有相同的内存布局，叠加层还带有额外的 alpha 平面，例如 INPUT 是 yuv420p，而 LOGO 是 yuva420p。
```
-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
```

13.10 pad_opencl

在输入图像上添加填充，并将原始输入放置在指定的 x, y 坐标处。

它接受以下选项：

width, w height, h

指定添加填充后输出图像尺寸的表达式。如果 width 或 height 的值为 0，则输出使用对应的输入尺寸。

width 表达式可以引用 height 表达式设置的值，反之亦然。

width 和 height 的默认值为 0。

x y

指定将输入图像放置在填充区域内的偏移量，相对于输出图像的左上边界。

x 表达式可以引用 y 表达式设置的值，反之亦然。

x 和 y 的默认值为 0。

如果 x 或 y 求值为负数，会自动调整为使输入图像居中于填充区域。

color

指定填充区域的颜色。此选项的语法请参阅 ffmpeg-utils 手册中的 “Color” 一节。

aspect

按宽高比而非分辨率进行填充。

width、height、x 和 y 选项的值是包含以下常量的表达式：

in_w in_h

输入视频的宽度和高度。

iw ih

与 in_w 和 in_h 相同。

out_w out_h

由 width 和 height 表达式指定的输出宽度和高度（即填充区域的尺寸）。

ow oh

与 out_w 和 out_h 相同。

x y

由 x 和 y 表达式指定的 x、y 偏移量，若尚未指定则为 NAN。

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，与 (iw / ih) * sar 相同

13.11 prewitt_opencl

对输入视频流应用 Prewitt 算子（https://en.wikipedia.org/wiki/Prewitt_operator）。

该滤镜接受以下选项：

planes

设置要过滤的平面。默认值是 0xf，即处理所有平面。

scale

设置将与过滤结果相乘的值。范围是 [0.0, 65535]，默认值是 1.0。

delta

设置将加到过滤结果上的值。范围是 [-65535, 65535]，默认值是 0.0。

13.11.1 示例

应用 Prewitt 算子，将 scale 设置为 2、delta 设置为 10。

-i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT

13.12 program_opencl

使用 OpenCL 程序过滤视频。

source

OpenCL 程序源文件。

kernel

程序中的内核名称。

inputs

滤镜的输入数量。默认为 1。

size, s

输出帧的大小。默认与第一个输入相同。

program_opencl 滤镜还支持 framesync 选项。

程序源文件必须包含一个具有给定名称的内核函数，该函数会针对输出的每个平面运行一次。每个平面上的运行都会作为一个独立的二维全局 NDRange 进行排队，每个待生成的像素对应一个工作项。因此每个工作项的全局 ID 偏移量就是目标图像中某个像素的坐标。

内核函数需要接受以下参数：

目标图像，__write_only image2d_t。

该图像将成为输出；内核应写入其全部内容。

帧索引，unsigned int。

这是一个从零开始、每帧递增一的计数器。

源图像，__read_only image2d_t。

这些是每个输入上最新的图像。内核可以从中读取以生成输出，但不能写入它们。

示例程序：

将输入复制到输出（输出必须与输入大小相同）。

__kernel void copy(__write_only image2d_t destination,
                   unsigned int index,
                   __read_only  image2d_t source)
{
    const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;

    int2 location = (int2)(get_global_id(0), get_global_id(1));

    float4 value = read_imagef(source, sampler, location);

    write_imagef(destination, location, value);
}

应用一个简单的变换，以随索引计数器增大的角度旋转输入。像素值由采样器线性插值，输出的尺寸不必与输入相同。

__kernel void rotate_image(__write_only image2d_t dst,
                           unsigned int index,
                           __read_only  image2d_t src)
{
    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
                               CLK_FILTER_LINEAR);

    float angle = (float)index / 100.0f;

    float2 dst_dim = convert_float2(get_image_dim(dst));
    float2 src_dim = convert_float2(get_image_dim(src));

    float2 dst_cen = dst_dim / 2.0f;
    float2 src_cen = src_dim / 2.0f;

    int2   dst_loc = (int2)(get_global_id(0), get_global_id(1));

    float2 dst_pos = convert_float2(dst_loc) - dst_cen;
    float2 src_pos = {
        cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
        sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
    };
    src_pos = src_pos * src_dim / dst_dim;

    float2 src_loc = src_pos + src_cen;

    if (src_loc.x < 0.0f      || src_loc.y < 0.0f ||
        src_loc.x > src_dim.x || src_loc.y > src_dim.y)
        write_imagef(dst, dst_loc, 0.5f);
    else
        write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
}

将两个输入混合在一起，每个输入的使用比例随索引计数器变化。

__kernel void blend_images(__write_only image2d_t dst,
                           unsigned int index,
                           __read_only  image2d_t src1,
                           __read_only  image2d_t src2)
{
    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
                               CLK_FILTER_LINEAR);

    float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;

    int2  dst_loc = (int2)(get_global_id(0), get_global_id(1));
    int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
    int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);

    float4 val1 = read_imagef(src1, sampler, src1_loc);
    float4 val2 = read_imagef(src2, sampler, src2_loc);

    write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
}

13.13 remap_opencl

使用第二个输入 Xmap 和第三个输入 Ymap 视频流重映射像素。

位置 (X, Y) 处的目标像素将从源 (x, y) 位置取值，其中 x = Xmap(X, Y)，y = Ymap(X, Y)。若映射值超出范围，目标像素将使用零值。

Xmap 和 Ymap 输入视频流必须具有相同的尺寸。输出视频流的尺寸将与 Xmap/Ymap 视频流相同。Xmap 和 Ymap 输入视频流是 32 位浮点 pixel format，单通道。

interp

指定用于像素重映射的插值方式。允许的值为 near 和 linear。默认值为 linear。

fill

指定未映射像素的颜色。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的"Color"一节。默认颜色为 black。

13.14 roberts_opencl

对输入视频流应用 Roberts 交叉算子（https://en.wikipedia.org/wiki/Roberts_cross）。

该滤镜接受以下选项：

planes

设置要过滤的平面。默认值是 0xf，即处理所有平面。

scale

设置将与过滤结果相乘的值。范围是 [0.0, 65535]，默认值是 1.0。

delta

设置将加到过滤结果上的值。范围是 [-65535, 65535]，默认值是 0.0。

13.14.1 示例

应用 Roberts 交叉算子，将 scale 设置为 2、delta 设置为 10

-i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT

13.15 sobel_opencl

对输入视频流应用 Sobel 算子（https://en.wikipedia.org/wiki/Sobel_operator）。

该滤镜接受以下选项：

planes

设置要过滤的平面。默认值是 0xf，即处理所有平面。

scale

设置将与过滤结果相乘的值。范围是 [0.0, 65535]，默认值是 1.0。

delta

设置将加到过滤结果上的值。范围是 [-65535, 65535]，默认值是 0.0。

13.15.1 示例

应用 Sobel 算子，将 scale 设置为 2、delta 设置为 10

-i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT

13.16 tonemap_opencl

执行 HDR(PQ/HLG)到 SDR 的转换，并进行色调映射。

它接受以下参数：

tonemap

指定要使用的色调映射算子。与 tonemap 中的 tonemap 选项相同。

param

调节色调映射算法。与 tonemap 中的 param 选项相同。

desat

对超过此亮度水平的高光进行去饱和处理。参数越高，保留的色彩信息越多。此设置有助于防止超高光出现不自然的过曝色彩，方式是（平滑地）转为白色。这会让图像感觉更自然，但代价是丢失了一些超出范围的色彩信息。

默认值为 0.5，此处的算法与目前 CPU 版本的 tonemap 略有不同。设置为 0.0 会禁用此选项。

threshold

色调映射算法的参数会针对每个场景进行微调。阈值用于检测场景是否发生了变化。若当前帧平均亮度与当前运行平均值之间的差距超过阈值，就会重新计算场景平均亮度和峰值亮度。默认值为 0.2。

format

指定输出 pixel format。

目前支持的格式有：

p010 nv12 range, r

设置输出的色彩范围。

可接受的值有：

tv/mpeg pc/jpeg

默认与输入相同。

primaries, p

设置输出色彩原色。

可接受的值有：

bt709 bt2020

默认与输入相同。

transfer, t

设置输出传输特性。

可接受的值有：

bt709 bt2020

默认为 bt709。

matrix, m

设置输出色彩空间矩阵。

可接受的值有：

bt709 bt2020

默认与输入相同。

13.16.1 示例

使用线性算子将 HDR(PQ/HLG)视频转换为 bt2020 传输特性的 p010 格式。

-i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT

13.17 unsharp_opencl

锐化或模糊输入视频。

它接受以下参数：

luma_msize_x, lx

设置亮度矩阵的水平大小。范围是 [1, 23]，默认值是 5。

luma_msize_y, ly

设置亮度矩阵的垂直大小。范围是 [1, 23]，默认值是 5。

luma_amount, la

设置亮度效果强度。范围是 [-10, 10]，默认值是 1.0。

负值会使输入视频模糊，正值会使其锐化，值为零则禁用该效果。

chroma_msize_x, cx

设置色度矩阵的水平大小。范围是 [1, 23]，默认值是 5。

chroma_msize_y, cy

设置色度矩阵的垂直大小。范围是 [1, 23]，默认值是 5。

chroma_amount, ca

设置色度效果强度。范围是 [-10, 10]，默认值是 0.0。

负值会使输入视频模糊，正值会使其锐化，值为零则禁用该效果。

所有参数都是可选的，默认相当于字符串 ’5:5:1.0:5:5:0.0’。

13.17.1 示例

应用强烈的亮度锐化效果：

-i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT

对亮度和色度参数都应用强烈的模糊：

-i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT

13.18 xfade_opencl

使用 OpenCL 通过自定义转场效果交叉淡化两个视频。

它接受以下选项：

transition

设置可用的转场效果之一。

custom

选择自定义转场效果，实际的转场描述将从 source 和 kernel 选项中获取。

fade wipeleft wiperight wipeup wipedown slideleft slideright slideup slidedown

默认转场为 fade。

source

自定义转场所用的 OpenCL 程序源文件。

kernel

设置从程序源文件中用于自定义转场的内核名称。

duration

设置视频转场的时长。

offset

设置相对于第一个视频的转场开始时间。

程序源文件必须包含一个具有给定名称的内核函数，该函数会针对输出的每个平面运行一次。每个平面上的运行都会作为一个独立的二维全局 NDRange 入队，其中每个待生成的像素对应一个工作项。因此，每个工作项的全局 ID 偏移量即为目标图像中某像素的坐标。

内核函数需要接受以下参数：

目标图像，__write_only image2d_t。

该图像将成为输出；内核应写入其全部内容。

第一个源图像，__read_only image2d_t。第二个源图像，__read_only image2d_t。

这些是各输入上最新的图像。内核可以读取它们以生成输出，但不能写入它们。

转场进度，float。该值始终在 0 到 1（含）之间。

示例程序：

应用点状幕帘转场效果：

__kernel void blend_images(__write_only image2d_t dst,
                           __read_only  image2d_t src1,
                           __read_only  image2d_t src2,
                           float progress)
{
    const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
                               CLK_FILTER_LINEAR);
    int2  p = (int2)(get_global_id(0), get_global_id(1));
    float2 rp = (float2)(get_global_id(0), get_global_id(1));
    float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
    rp = rp / dim;

    float2 dots = (float2)(20.0, 20.0);
    float2 center = (float2)(0,0);
    float2 unused;

    float4 val1 = read_imagef(src1, sampler, p);
    float4 val2 = read_imagef(src2, sampler, p);
    bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));

    write_imagef(dst, p, next ? val1 : val2);
}

14 VAAPI 视频滤镜

VAAPI 视频滤镜通常与 VAAPI decoder 和 VAAPI encoder 配合使用。下面是对 VAAPI 视频滤镜的说明。

要启用这些滤镜的编译，需要在配置 FFmpeg 时加上 --enable-vaapi。

要使用 vaapi 滤镜，需要正确设置 vaapi 设备。更多信息请参阅 https://trac.ffmpeg.org/wiki/Hardware/VAAPI

14.1 overlay_vaapi

将一个视频叠加到另一个视频之上。

它接受两个输入并产生一个输出。第一个输入是 "main"（主）视频，第二个输入叠加在其上。

该滤镜接受以下选项：

x y

设置叠加视频在主视频上的 x 和 y 坐标表达式。

两个表达式的默认值均为 "0"。

w h

设置叠加视频在主视频上的宽度和高度表达式。

’w’ 的默认值为 ’overlay_iw’，’h’ 的默认值为 ’overlay_ih*w/overlay_iw’。

表达式可以包含以下参数：

main_w, W main_h, H

主输入的宽度和高度。

overlay_iw overlay_ih

叠加输入的宽度和高度。

overlay_w, w overlay_h, h

叠加输出的宽度和高度。

overlay_x, x overlay_y, y

叠加层在主视频内的位置

alpha

设置叠加视频的透明度。允许范围为 0.0 到 1.0。值越高表示透明度越低。默认值为 1.0。

eof_action

参见 framesync。

shortest

参见 framesync。

repeatlast

参见 framesync。

该滤镜还支持 framesync 选项。

14.1.1 示例

在 INPUT 视频的左上角叠加一张 LOGO 图像。该滤镜的两个输入均为 yuv420p 格式。

-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_vaapi" OUTPUT

在距 INPUT 视频左上角偏移 (200, 100) 处叠加一张 LOGO 图像。两个输入的颜色通道内存布局相同，叠加层带有额外的 alpha 平面，例如 INPUT 为 yuv420p，而 LOGO 为 yuva420p。
```
-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_vaapi=x=200:y=100:w=400:h=300:alpha=1.0, hwdownload, format=nv12" OUTPUT
```

14.2 tonemap_vaapi

执行 HDR 转 SDR 或 HDR 转 HDR 的色调映射。目前仅接受 HDR10 作为输入。

它接受以下参数：

format

指定输出 pixel format。

HDR 转 SDR 色调映射的默认值为 nv12，HDR 转 HDR 色调映射的默认值为 p010。

primaries, p

设置输出色彩原色。

HDR 转 SDR 色调映射的默认值为 bt709，HDR 转 HDR 色调映射的默认值与输入相同。

transfer, t

设置输出传输特性。

HDR 转 SDR 色调映射的默认值为 bt709，HDR 转 HDR 色调映射的默认值与输入相同。

matrix, m

设置输出色彩空间矩阵。

HDR 转 SDR 色调映射的默认值为 bt709，HDR 转 HDR 色调映射的默认值与输入相同。

display

设置输出的母带显示色彩容积。它由一个以 ’|’ 分隔的两个值组成的列表给出，两个值之间以空格分隔。它依次设置 G、B、R 顺序的显示原色 x 和 y，然后是白点 x 和 y，以及标称最小和最大显示亮度。

设置此选项时将执行 HDR 转 HDR 色调映射。

light

设置输出内容的光级信息。它接受 2 个以空格分隔的值，第一个是最大光级，第二个是最大平均光级。

对于 HDR 转 SDR 色调映射会忽略此选项，对于 HDR 转 HDR 色调映射则为可选。

14.2.1 示例

将 HDR(HDR10) 视频转换为 bt2020 传输特性的 p010 格式
```
tonemap_vaapi=format=p010:t=bt2020-10
```

将 HDR 视频转换为 HDR 视频

tonemap_vaapi=display=7500\ 3000|34000\ 16000|13250\ 34500|15635\ 16450|500\ 10000000

14.3 hstack_vaapi

将输入视频水平堆叠。

这是 hstack 滤镜的 VA-API 变体，各输入流的高度可以不同，该滤镜会在保持原始宽高比的同时放大/缩小各输入流。

它接受以下选项：

inputs

参见 hstack。

shortest

参见 hstack。

height

设置输出的高度。若设为 0，该滤镜会将输出高度设为第一个输入流的高度。默认值为 0。

14.4 vstack_vaapi

将输入视频垂直堆叠。

这是 vstack 滤镜的 VA-API 变体，各输入流的宽度可以不同，该滤镜会在保持原始宽高比的同时放大/缩小各输入流。

它接受以下选项：

inputs

参见 vstack。

shortest

参见 vstack。

width

设置输出的宽度。若设为 0，该滤镜会将输出宽度设为第一个输入流的宽度。默认值为 0。

14.5 xstack_vaapi

将视频输入堆叠为自定义布局。

这是 xstack 滤镜的 VA-API 变体，各输入流的大小可以不同，该滤镜会将各输入流放大/缩小到给定的输出大小，或第一个输入流的大小。

它接受以下选项：

inputs

参见 xstack。

shortest

参见 xstack。

layout

参见 xstack。此外，它还允许用户为每个输入流提供输出大小。

xstack_vaapi=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080

grid

参见 xstack。

grid_tile_size

设置在设置了 grid 时每个输入流的输出大小。若未设置此选项，该滤镜会默认将输出大小设为第一个输入流的大小。有关此选项的语法，请查阅 ffmpeg-utils 手册中的“Video size”一节 (ffmpeg-utils)。

fill

参见 xstack。

14.6 pad_vaapi

在输入图像上添加填充，并将原始输入放置在指定的 x, y 坐标处。

它接受以下选项：

width, w height, h

指定添加填充后输出图像尺寸的表达式。如果 width 或 height 的值为 0，则输出使用对应的输入尺寸。

width 表达式可以引用 height 表达式设置的值，反之亦然。

width 和 height 的默认值为 0。

x y

指定将输入图像放置在填充区域内的偏移量，相对于输出图像的左上边界。

x 表达式可以引用 y 表达式设置的值，反之亦然。

x 和 y 的默认值为 0。

如果 x 或 y 求值为负数，会自动调整为使输入图像居中于填充区域。

color

指定填充区域的颜色。此选项的语法请参阅 ffmpeg-utils 手册中的 “Color” 一节。

aspect

按宽高比而非分辨率进行填充。

width、height、x 和 y 选项的值是包含以下常量的表达式：

in_w in_h

输入视频的宽度和高度。

iw ih

与 in_w 和 in_h 相同。

out_w out_h

由 width 和 height 表达式指定的输出宽度和高度（即填充区域的尺寸）。

ow oh

与 out_w 和 out_h 相同。

x y

由 x 和 y 表达式指定的 x、y 偏移量，若尚未指定则为 NAN。

与 iw / ih 相同

sar

输入的样本宽高比

dar

输入的显示宽高比，与 (iw / ih) * sar 相同

14.7 drawbox_vaapi

在输入图像上绘制一个彩色方框。

它接受以下参数：

x y

指定方框左上角坐标的表达式。默认值为 0。

width, w height, h

指定方框宽度和高度的表达式；若为 0 则解释为输入的宽度和高度。默认值为 0。

color, c

指定要绘制方框的颜色。有关此选项的一般语法，请查阅 ffmpeg-utils 手册中的“Color”一节 (ffmpeg-utils)。

thickness, t

设置方框边缘粗细的表达式。值为 fill 时会创建一个填充方框。默认值为 3。

可接受的常量列表见下文。

replace

值为 1 时，绘制的方框像素会覆盖视频原有的颜色和 alpha 像素。默认值为 0，即将方框合成到输入视频上。

x、y、w、h、t 参数是包含以下常量的表达式：

in_h, ih in_w, iw

输入的宽度和高度。

x y

方框绘制处的 x、y 偏移坐标。

w h

所绘制方框的宽度和高度。

所绘制方框的粗细。

14.7.1 示例

沿输入图像的边缘绘制一个黑色方框：
```
drawbox
```
绘制一个红色、不透明度为 50% 的方框：
```
drawbox=10:20:200:60:red@0.5
```

前面的示例也可以写作：

    drawbox=x=10:y=20:w=200:h=60:color=red@0.5

用粉色填充方框：

drawbox=x=10:y=10:w=100:h=100:color=pink@0.5:t=fill

绘制一个 2 像素宽的红色 2.40:1 遮罩：

drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red

15 VideoToolbox 视频滤镜

下面是对当前可用的 VideoToolbox 视频滤镜的说明。

VideoToolbox 滤镜依赖于 VideoToolbox 框架，在为 macOS 等 Apple 平台构建 ffmpeg 时会自动检测。若自动检测被禁用，请在 configure 时加上 --enable-videotoolbox。

15.1 scale_vt

使用 VTPixelTransferSession 缩放并转换色彩参数。

该滤镜接受以下选项：

w h

设置输出视频尺寸表达式。默认值为输入尺寸。

color_matrix

设置输出色彩空间矩阵。

color_primaries

设置输出色彩原色。

color_transfer

设置输出传输特性。

15.1.1 示例

执行 HDR 转 SDR 转换，并缩放为输入大小的一半

ffmpeg -hwaccel videotoolbox \
        -hwaccel_output_format videotoolbox_vld \
        -i hdr.mov \
        -c:v hevc_videotoolbox \
        -profile:v main \
        -b:v 3M \
        -vf scale_vt=w=iw/2:h=ih/2:color_matrix=bt709:color_primaries=bt709:color_transfer=bt709 \
        -c:a copy \
        -tag:v hvc1 \
        sdr.mp4

15.2 transpose_vt

在输入视频中转置行与列，并可选择性地翻转它。更深入的示例请参见 transpose 视频滤镜，它与本滤镜的选项大体相同。

它接受以下参数：

dir

指定转置方向。

可取以下值：

‘cclock_flip’

逆时针旋转 90 度并垂直翻转。（默认）

‘clock’

顺时针旋转 90 度。

‘cclock’

逆时针旋转 90 度。

‘clock_flip’

顺时针旋转 90 度并垂直翻转。

‘hflip’

水平翻转输入视频。

‘vflip’

垂直翻转输入视频。

passthrough

如果输入的几何形状与指定值所表示的形状相符，则不应用转置。可接受以下值：

‘none’

始终应用转置。（默认）

‘portrait’

保持纵向几何形状（当高度 >= 宽度时）。

‘landscape’

保持横向几何形状（当宽度 >= 高度时）。

16 Vulkan 视频滤镜

下面是对当前可用的 Vulkan 视频滤镜的说明。

要启用这些滤镜的编译，需要在配置 FFmpeg 时加上 --enable-vulkan，以及 --enable-libglslang 或 --enable-libshaderc 之一。

运行 Vulkan 滤镜需要先初始化一个硬件设备，并将该设备传递给任意滤镜图中的所有滤镜。

-init_hw_device vulkan[=name][:device[,key=value...]]

初始化一个名为 name、类型为 vulkan 的新硬件设备，使用给定的 device 参数以及 key=value 形式的选项。支持以下选项：

debug

若设为 1，则开启校验层。

linear_images

分配线性图像。不适用于解码。

disable_multiplane

禁用多平面图像。不适用于解码。

avoid_host_import

避免使用动态主机内存导入，改为对预先映射的缓冲区执行常规 memcpy()。

-filter_hw_device name

将名为 name 的硬件设备传递给滤镜图中的所有滤镜。

更详细的信息见 https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options

选择第一个设备并在其上以默认参数运行 nlmeans_vulkan 滤镜的示例。

-init_hw_device vulkan=vk:0 -filter_hw_device vk -i INPUT -vf "hwupload,nlmeans_vulkan,hwdownload" OUTPUT

由于 Vulkan 滤镜无法访问普通内存中的帧数据，所有帧数据在使用前都需要上传 (hwupload) 到连接至相应设备的硬件表面，使用后再下载 (hwdownload) 回普通内存。请注意，hwupload 会将数据上传为与软件帧布局相同的帧，因此可能需要在其前面紧接添加一个 format 滤镜以使输入变为正确的格式；而 hwdownload 在输出端并不支持所有格式——通常需要在滤镜图中紧随其后插入一个额外的 format 滤镜，以使输出成为受支持的格式。

16.1 avgblur_vulkan

应用平均模糊滤镜，在 GPU 上使用 Vulkan 实现。

该滤镜接受以下选项：

sizeX

设置水平半径大小。范围为 [1, 32]，默认值为 3。

sizeY

设置垂直半径大小。范围为 [1, 32]，默认值为 3。

planes

设置要过滤的平面。默认值是 0xf，即处理所有平面。

16.2 blend_vulkan

将两个 Vulkan 帧相互混合。

blend 滤镜接受两个输入流并输出一个流，第一个输入是“顶”层，第二个输入是“底”层。默认情况下，输出会在最长的输入结束时终止。

接受的选项说明如下。

c0_mode c1_mode c2_mode c3_mode all_mode

设置特定像素分量的混合模式，若为 all_mode 则设置所有像素分量的混合模式。默认值为 normal。

分量模式的可用值有：

‘normal’ ‘multiply’

16.3 bwdif_vulkan

使用 bwdif（“Bob Weaver Deinterlacing Filter”算法）进行去隔行，在 GPU 上使用 Vulkan 实现。

它接受以下参数：

mode

采用的去隔行模式。接受以下值之一：

0, send_frame

每个帧输出一帧。

1, send_field

每个场输出一帧。

默认值为 send_field。

parity

假定输入隔行视频的场优先顺序（奇偶性）。接受以下值之一：

0, tff

假定顶场在前。

1, bff

假定底场在前。

-1, auto

启用场奇偶性的自动检测。

默认值为 auto。若隔行方式未知，或 decoder 未导出该信息，则假定为顶场优先。

deint

指定要去隔行的帧。接受以下值之一：

0, all

对所有帧去隔行。

1, interlaced

仅对标记为隔行的帧进行去隔行处理。

默认值为 all。

16.4 chromaber_vulkan

应用一种模拟色差的效果。搭配 RGB 输入效果最佳，但对 YCbCr 输入也能提供类似的效果。

dist_x

水平位移倍数。每个色度像素的位置都会以图像中心为起点，乘以该倍数。默认值为 0。

dist_y

同理，此项设置垂直位移倍数。默认值为 0。

16.5 color_vulkan

生成纯色 Vulkan 帧的视频源。可用于基准测试或叠加。

它接受以下参数：

color

要使用的颜色。可以是名称，也可以是十六进制值。默认值为 black。

size

输出帧的大小。默认值为 1920x1080。

rate

输出的帧率。默认值为每秒 60 帧。

duration

视频时长。默认值为 -0.000001。

sar

视频信号的宽高比。默认值为 1/1。

format

输出 Vulkan 帧的 pixel format。默认值为 yuv444p。

out_range

设置输出的 YCbCr 采样范围。

这允许覆盖自动检测到的值，也允许强制指定用于输出和 encoder 的具体值。若未指定，则范围取决于 pixel format。可能的值：

‘auto/unknown’

自动选择。

‘jpeg/full/pc’

设置完整范围（8 位亮度时为 0-255）。

‘mpeg/limited/tv’

设置“MPEG”范围（8 位亮度时为 16-235）。

16.6 vflip_vulkan

垂直翻转图像。

16.7 hflip_vulkan

水平翻转图像。

16.8 flip_vulkan

沿垂直和水平两个轴翻转图像。

16.9 gblur_vulkan

在 Vulkan 帧上应用高斯模糊滤镜。

该滤镜接受以下选项：

sigma

设置水平 sigma，即高斯模糊的标准差。默认值为 0.5。

sigmaV

设置垂直 sigma，若为负值则与 sigma 相同。默认值为 -1。

planes

设置要过滤的平面。默认情况下会过滤所有平面。

size

设置水平轴上的内核大小。默认值为 19。

sizeV

设置垂直轴上的内核大小。默认值为 0，表示使用与 size 相同的值。

16.10 nlmeans_vulkan

使用非局部均值（Non-Local Means）算法为帧降噪，基于 Vulkan 在 GPU 上实现。相比 nlmeans 或 nlmeans_opencl，支持更多 pixel format，包括对 alpha 通道的支持。

该滤镜接受以下选项。

设置所有分量的降噪强度。默认为 1.0。必须在 [0.0, 100.0] 范围内。

设置所有平面的图像块大小。默认为 7。必须是 [0, 99] 范围内的奇数。

设置搜索窗口大小。默认为 15。必须是 [0, 99] 范围内的奇数。

设置并行度。默认为 8。必须是 [1, 64] 范围内的数值。较大的值会使用更多显存（VRAM），但不一定能带来更快的速度。最佳值取决于硬件和输入。

s0 s1 s2 s3

设置特定分量的降噪强度。默认为 1.0，与 s 相同。必须在 [0.0, 100.0] 范围内。设为 0.0 会禁用该分量的降噪。

p0 p1 p2 p3

设置特定分量的图像块大小。默认为 7，与 p 相同。必须是 [0, 99] 范围内的奇数。

16.11 overlay_vulkan

将一个视频叠加在另一个视频之上。

该滤镜接受两个输入，并产生一个输出。第一个输入是“主”视频，第二个输入将叠加在其上。该滤镜要求所有输入使用相同的 pixel format，因此可能需要转换格式。

该滤镜接受以下选项：

设置叠加视频在主视频上的 x 坐标。默认值为 0。

设置叠加视频在主视频上的 y 坐标。默认值为 0。

16.12 transpose_vulkan

在输入视频中转置行与列，并可选择性地翻转它。更深入的示例请参见 transpose 视频滤镜，它与本滤镜的选项大体相同。

它接受以下参数：

dir

指定转置方向。

可取以下值：

‘cclock_flip’

逆时针旋转 90 度并垂直翻转。（默认）

‘clock’

顺时针旋转 90 度。

‘cclock’

逆时针旋转 90 度。

‘clock_flip’

顺时针旋转 90 度并垂直翻转。

passthrough

如果输入的几何形状与指定值所表示的形状相符，则不应用转置。可接受以下值：

‘none’

始终应用转置。（默认）

‘portrait’

保持纵向几何形状（当高度 >= 宽度时）。

‘landscape’

保持横向几何形状（当宽度 >= 高度时）。

17 QSV 视频滤镜

以下是当前可用的 QSV 视频滤镜说明。

要启用这些滤镜的编译，需要使用 --enable-libmfx 或 --enable-libvpl 配置 FFmpeg。

要使用 QSV 滤镜，需要正确设置 QSV 设备。有关更多信息，请参阅 https://trac.ffmpeg.org/wiki/Hardware/QuickSync

17.1 hstack_qsv

将输入视频水平堆叠。

这是 hstack 滤镜的 QSV 变体，各输入流的高度可以不同，该滤镜会在保持原始宽高比的同时缩放各输入流。

它接受以下选项：

inputs

参见 hstack。

shortest

参见 hstack。

height

设置输出的高度。若设为 0，该滤镜会将输出高度设为第一个输入流的高度。默认值为 0。

17.2 vstack_qsv

将输入视频垂直堆叠。

这是 vstack 滤镜的 QSV 变体，各输入流的宽度可以不同，该滤镜会在保持原始宽高比的同时缩放各输入流。

它接受以下选项：

inputs

参见 vstack。

shortest

参见 vstack。

width

设置输出的宽度。若设为 0，该滤镜会将输出宽度设为第一个输入流的宽度。默认值为 0。

17.3 xstack_qsv

将视频输入堆叠为自定义布局。

这是 xstack 滤镜的 QSV 变体。

它接受以下选项：

inputs

参见 xstack。

shortest

参见 xstack。

layout

参见 xstack。此外，该选项还允许用户为每个输入流指定输出大小。

xstack_qsv=inputs=4:layout=0_0_1920x1080|0_h0_1920x1080|w0_0_1920x1080|w0_h0_1920x1080

grid

参见 xstack。

grid_tile_size

设置 grid 已设置时各输入流的输出大小。若未设置该选项，该滤镜默认会将输出大小设为第一个输入流的大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。

fill

参见 xstack。

18 视频源

以下是当前可用视频源的说明。

18.1 buffer

缓冲视频帧，并使其可供滤镜链使用。

该源主要用于编程方式的使用，特别是通过 libavfilter/buffersrc.h 中定义的接口。

它接受以下参数：

video_size

指定缓冲视频帧的大小（宽度和高度）。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。

width

输入视频的宽度。

height

输入视频的高度。

pix_fmt

表示缓冲视频帧 pixel format 的字符串。可以是与 pixel format 对应的数字，也可以是 pixel format 名称。

time_base

指定缓冲帧的时间戳所采用的时间基。

frame_rate

指定视频流所期望的帧率。

colorspace

表示缓冲视频帧色彩空间的字符串。可以是与色彩空间对应的数字，也可以是色彩空间名称。

range

表示缓冲视频帧色彩范围的字符串。可以是与色彩范围对应的数字，也可以是色彩范围名称。

alpha_mode

表示缓冲视频帧 alpha 模式的字符串。可以是与 alpha 模式对应的数字，也可以是 alpha 模式名称。

pixel_aspect, sar

输入视频的样本（像素）宽高比。

hw_frames_ctx

当使用硬件 pixel format 时，这应该是对描述输入帧的 AVHWFramesContext 的引用。

例如：

buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1

这会指示该源接受尺寸为 320x240、格式为 "yuv410p" 的视频帧，并假定时间戳的时间基为 1/24，像素为正方形（1:1 的样本宽高比）。由于名为 "yuv410p" 的 pixel format 对应数字 6（请查看 libavutil/pixfmt.h 中 enum AVPixelFormat 的定义），该示例等价于：

buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1

或者，也可以将选项指定为一个扁平字符串，但这种语法已弃用：

width:height:pix_fmt:time_base.num:time_base.den:pixel_aspect.num:pixel_aspect.den

18.2 cellauto

创建由基本元胞自动机生成的图案。

元胞自动机的初始状态可以通过 filename 和 pattern 选项定义。如果未指定这些选项，则会随机生成初始状态。

每生成一个新帧，视频中的新一行就会用元胞自动机下一代的结果填充。整个帧填满后的行为由 scroll 选项定义。

该源接受以下选项：

filename, f

从指定文件中读取元胞自动机的初始状态，即起始行。在文件中，每个非空白字符都被视为一个存活的元胞，换行符会终止该行，文件中之后的字符将被忽略。

pattern, p

从指定字符串中读取元胞自动机的初始状态，即起始行。

字符串中每个非空白字符都被视为一个存活的元胞，换行符会终止该行，字符串中之后的字符将被忽略。

rate, r

设置视频速率，即每秒生成的帧数。默认为 25。

random_fill_ratio, ratio

设置元胞自动机初始行的随机填充率。它是一个介于 0 到 1 之间的浮点数值，默认为 1/PHI。

指定文件或图案时，该选项会被忽略。

random_seed, seed

设置用于随机填充初始行的种子，必须是介于 0 和 UINT32_MAX 之间的整数。如果未指定，或显式设为 -1，滤镜会尽力尝试使用一个良好的随机种子。

rule

设置元胞自动机规则，是一个介于 0 到 255 之间的数字。默认值为 110。

size, s

设置输出视频的大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。

如果指定了 filename 或 pattern，大小默认设为指定初始状态行的宽度，高度设为 width * PHI。

如果设置了 size，它必须包含指定 pattern 字符串的宽度，指定的图案将居中放置在更大的行中。

如果未指定 filename 或 pattern 字符串，size 的值默认为 "320x518"（用于随机生成的初始状态）。

scroll

如果设为 1，当输出中所有行都已填满时，输出会向上滚动。如果设为 0，最下面一行填满后，新生成的行会覆写在最上面一行。默认为 1。

start_full, full

如果设为 1，会在输出第一帧之前用生成的行完全填满输出。这是默认行为，要禁用请将值设为 0。

stitch

如果设为 1，会将行的左右边缘缝合在一起。这是默认行为，要禁用请将值设为 0。

18.2.1 示例

从 pattern 读取初始状态，并指定大小为 200x400 的输出。
```
cellauto=f=pattern:s=200x400
```
生成一个宽度为 200 个元胞的随机初始行，填充率为 2/3：
```
cellauto=ratio=2/3:s=200x200
```
创建一个由 rule 18 生成的图案，从宽度为 100 的初始行中央的单个存活元胞开始：
```
cellauto=p=@:s=100x400:full=0:rule=18
```

指定一个更复杂的初始图案：

cellauto=p='@@ @ @@':s=100x400:full=0:rule=18

18.3 coreimagesrc

使用 Apple 的 CoreImage API 在 OSX 上的 GPU 生成的视频源。

该视频源是 coreimage 视频滤镜的特殊版本。请在所应用滤镜链的开头使用一个 core image 生成器来生成内容。

coreimagesrc 视频源接受以下选项：

list_generators

列出所有可用的生成器及其各自的选项，以及可能的最小值、最大值和默认值。

list_generators=true

size, s

指定源视频的大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。默认值为 320x240。

rate, r

指定源视频的帧率，以每秒生成的帧数表示。必须是 frame_rate_num/frame_rate_den 格式的字符串、整数、浮点数，或有效的视频帧率缩写。默认值为 "25"。

sar

设置源视频的样本宽高比。

duration, d

设置源视频的时长。有关可接受的语法，请参阅 ffmpeg-utils(1) 手册中的 (ffmpeg-utils)Time duration 一节。

如果未指定，或表示的时长为负值，则视频将被视为无限生成。

此外，还接受 coreimage 视频滤镜的所有选项。可以使用完整的滤镜链进一步处理生成的输入，而无需 CPU-HOST 传输。详情请参阅 coreimage 的文档和示例。

18.3.1 示例

使用 CIQRCodeGenerator 为 FFmpeg 主页创建二维码，以下以 Apple 标准 bash shell 的完整转义命令行形式给出：

ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@inputMessage=https\\\\\://FFmpeg.org/@inputCorrectionLevel=H -frames:v 1 QRCode.png

该示例与 coreimage 的 QRCode 示例等价，但无需 nullsrc 视频源。

18.4 ddagrab

通过 Desktop Duplication API 捕获 Windows 桌面。

该滤镜只返回 D3D11 硬件帧，用于 GPU 上的编码或处理。因此，任何软件处理都需要显式使用 hwdownload。

它接受以下选项：

output_idx

要捕获的 DXGI 输出索引。

通常对应 Windows 为该屏幕分配的索引减一，因此从 0 开始。

默认捕获输出 0。

draw_mouse

是否绘制鼠标光标。

默认为 true。

仅影响硬件光标。如果游戏或应用程序绘制自己的光标，该光标总是会被捕获。

framerate

捕获桌面的最大帧率——连续帧之间的间隔不会小于帧率的倒数。当 dup_frames 为 true（默认值）且桌面更新不够频繁时，滤镜会复制前一帧。请注意，后台不会进行任何缓冲，因此当滤镜轮询不够频繁时，实际的帧间隔可能会显著变大。

默认为 30 FPS。

video_size

指定捕获视频的大小。

默认是屏幕的完整大小。

如果小于屏幕大小，会从底部/右侧裁剪。

offset_x

捕获视频的水平偏移量。

offset_y

捕获视频的垂直偏移量。

output_fmt

期望的滤镜输出格式。默认为 8 位 BGRA。

可接受的值有：

‘auto’

将所有支持的输出格式传递给 DDA，并返回 DDA 决定使用的格式。

‘8bit’ ‘bgra’

8 位格式总是可用，必要时 DDA 会转换为这些格式。

‘10bit’ ‘x2bgr10’

如果请求了 10 位格式但不可用，滤镜初始化将失败。

dup_frames

当该选项设为 true（默认值）时，桌面未更新时滤镜会复制帧，以维持大致恒定的目标帧率。当该选项设为 false 时，滤镜会等待桌面更新（此时帧间隔可能会有显著变化）。

18.4.1 示例

捕获主屏幕并使用 nvenc 编码：

ffmpeg -f lavfi -i ddagrab -c:v h264_nvenc -cq 18 output.mp4

也可以跳过 lavfi 设备直接使用该滤镜。以下示例还演示了下载帧并使用 libx264 编码。这种情况下需要显式指定输出格式：

ffmpeg -filter_complex ddagrab=output_idx=1:framerate=60,hwdownload,format=bgra -c:v libx264 -crf 18 output.mp4

如果只想捕获桌面的一部分，可以通过指定较小的大小及其在屏幕中的偏移量来实现：

ddagrab=video_size=800x600:offset_x=100:offset_y=100

18.5 gfxcapture

使用 Windows.Graphics.Capture API 捕获窗口或显示器。

该源以低开销捕获应用程序窗口或整个显示器。滤镜以 d3d11 格式输出硬件帧；如果需要系统内存帧，请使用 hwdownload,format=。

要捕获的窗口可以通过其标题、类名或所属可执行文件名的正则表达式来选择，也可以通过显式的原生句柄，或者通过显示器索引或显式的原生句柄来选择。窗口必须匹配所有提供的表达式才会被选中。系统会选取第一个匹配的窗口，其顺序取决于 Windows 返回窗口的顺序。

显式句柄（hwnd、hmonitor）会覆盖基于模式或索引的选择。如果既未提供句柄，也未提供显示器索引，则会捕获第一个匹配所提供正则表达式的窗口。

该源不会保持稳定的 FPS。它会按合成器（compositor）提供帧的速率返回帧，仅受 max_framerate 的上限约束。如果需要稳定的速率，需要添加 fps 滤镜按需丢弃/复制帧。

如果捕获源在捕获过程中消失（窗口关闭、显示器断开连接），滤镜会返回 EOF。

该源接受以下选项：

window_title

与窗口标题匹配的 ECMAScript 正则表达式。支持 PCRE 风格的 (?i) 前缀以实现不区分大小写的匹配。

window_class

与 window_title 类似，但匹配的是窗口的类名。

window_exe

与 window_title 类似，但匹配的是窗口所属进程的可执行文件名。

monitor_idx

要捕获的显示器的从 0 开始的索引。

也可以设为 window，以捕获滤镜初始化时所选窗口所在的显示器。

hwnd

显式的原生窗口句柄（HWND）。

hmonitor

显式的原生显示器句柄（HMONITOR）。

capture_cursor

捕获鼠标光标。默认启用。

capture_border

捕获窗口的整个区域，包括窗口装饰/边框。默认禁用。

display_border

在捕获的窗口周围绘制一个黄色高亮边框。默认禁用。

max_framerate

最大捕获帧率。接受一个视频速率（例如 30、60/1、24000/1001）。默认值为 60 FPS。实际速率是合成器渲染窗口/显示器的速率，由该选项设置上限。

width

强制指定输出画布的宽度。如果为零（默认），则使用最初捕获源的宽度。如果提供负数，宽度会向下舍入到该数字的下一个倍数。

参见 resize_mode。

height

强制指定输出画布的高度。如果为零（默认），则使用最初捕获源的高度。如果提供负数，高度会向下舍入到该数字的下一个倍数。

参见 resize_mode。

crop_left

从捕获帧的左侧裁剪这么多像素。

crop_top

从捕获帧的顶部裁剪这么多像素。（原文此行及 crop_right/crop_bottom 说明均误写为“左侧”，已按选项名订正——译者注）

crop_right

从捕获帧的右侧裁剪这么多像素。

crop_bottom

从捕获帧的底部裁剪这么多像素。

premultiplied

如果设为 1，返回带预乘 alpha 的帧。默认值为 0（非预乘 alpha）。

resize_mode

定义捕获内容如何适配到输出画布大小。可能的值：

‘crop’

裁剪（或用黑色填充）至画布大小。（默认）

‘scale’

缩放源以填满画布，可能会改变宽高比。

‘scale_aspect’

在保持宽高比的同时缩放源以适应画布内部。剩余区域用黑色填充。

scale_mode

需要调整大小时使用的缩放算法。

可选值：

‘point’

最近邻（像素化）缩放。

‘bilinear’

双线性滤波。（默认）

‘bicubic’

双三次滤波。可能更模糊，但根据内容不同，缩放伪影可能更少。

output_fmt

D3D11 硬件帧内所需的输出 pixel format。

可选值：

‘bgra’ ‘8bit’

8 位 BGRA 输出（默认）

‘x2bgr10’ ‘10bit’

10 位 BGR 输出

‘rgbaf16’ ‘16bit’

16 位浮点 RGBA 输出

18.5.1 示例

按标题（不区分大小写）捕获窗口，最大帧率为 60 fps：

ffmpeg -filter_complex gfxcapture=window_title='(?i)My Application':max_framerate=60,hwdownload,format=bgra,format=yuv420p -c:v libx264 -crf 15 capture.mp4

以原生刷新率捕获显示器 1，10 位色深，保持宽高比缩放至 1920x1080：

ffmpeg -filter_complex gfxcapture=monitor_idx=1:width=1920:height=1080:resize_mode=scale_aspect:output_fmt=10bit -c:v hevc_nvenc -cq 15 capture.mp4

按可执行文件名捕获窗口，绘制边框，强制点缩放，固定 60 fps：

ffmpeg -filter_complex gfxcapture=window_exe='^firefox.exe$':display_border=1:scale_mode=point,fps=60 -rc qvbr -qvbr_quality_level 15 -c:v h264_amf capture.mp4

18.6 gradients

生成若干渐变。

size, s

设置帧大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。默认值为 "640x480"。

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

c0, c1, c2, c3, c4, c5, c6, c7

设置 8 种颜色。颜色的默认值是随机选取一种。

x0, y0, y0, y1

设置渐变线的起点和终点。如果为负数或超出范围，会随机选取。

nb_colors, n

设置同时使用的颜色数量。允许的范围是 2 到 8。默认值为 2。

seed

设置选取渐变线点的种子。

duration, d

设置源视频的时长。有关可接受的语法，请参阅 ffmpeg-utils(1) 手册中的 (ffmpeg-utils)Time duration 一节。

如果未指定，或表示的时长为负值，则视频将被视为无限生成。

speed

设置渐变旋转的速度。

type, t

设置渐变的类型。可用的值有：

‘linear’ ‘radial’ ‘circular’ ‘spiral’ ‘square’

默认类型为 linear。

18.6.1 命令

该源将上述部分选项作为命令支持。

18.7 mandelbrot

生成 Mandelbrot 集合分形，并向 start_x 和 start_y 指定的点逐步缩放。

该源接受以下选项：

end_pts

设置终止 pts 值。默认值为 400。

end_scale

设置终止缩放值。必须是浮点数值。默认值为 0.3。

inner

设置内部着色模式，即用于绘制 Mandelbrot 分形内部区域的算法。

取以下值之一：

black

设置黑色模式。

convergence

显示至收敛为止的时间。

mincol

根据最接近迭代原点的点设置颜色。

period

设置周期模式。

默认值为 mincol。

bailout

设置 bailout 值。默认值为 10.0。

maxiter

设置渲染算法执行的最大迭代次数。默认值为 7189。

outer

设置外部着色模式。取以下值之一：

iteration_count

设置迭代次数模式。

normalized_iteration_count

设置归一化迭代次数模式。

默认值为 normalized_iteration_count。

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

size, s

设置帧大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。默认值为 "640x480"。

start_scale

设置初始缩放值。默认值为 3.0。

start_x

设置初始 x 位置。必须是介于 -100 和 100 之间的浮点数值。默认值为 -0.743643887037158704752191506114774。

start_y

设置初始 y 位置。必须是介于 -100 和 100 之间的浮点数值。默认值为 -0.131825904205311970493132056385139。

18.8 mptestsrc

生成 MPlayer 测试滤镜所生成的各种测试图案。

生成视频的大小是固定的，为 512x512。该源尤其适用于测试编码功能。

该源接受以下选项：

rate, r

指定源视频的帧率，以每秒生成的帧数表示。必须是 frame_rate_num/frame_rate_den 格式的字符串、整数、浮点数，或有效的视频帧率缩写。默认值为 "25"。

duration, d

设置源视频的时长。有关可接受的语法，请参阅 ffmpeg-utils(1) 手册中的 (ffmpeg-utils)Time duration 一节。

如果未指定，或表示的时长为负值，则视频将被视为无限生成。

test, t

设置要执行的测试的编号或名称。支持的测试有：

dc_luma dc_chroma freq_luma freq_chroma amp_luma amp_chroma cbp mv ring1 ring2 all max_frames, m

设置每个测试生成的最大帧数，默认值为 30。

默认值为 "all"，会循环遍历所有测试的列表。

一些示例：

mptestsrc=t=dc_luma

这会生成一个 "dc_luma" 测试图案。

18.9 frei0r_src

提供一个 frei0r 源。

要启用此滤镜的编译，需要安装 frei0r 头文件，并使用 --enable-frei0r 配置 FFmpeg。

此源接受以下参数：

size

要生成的视频的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。

framerate

生成的视频的帧率。可以是 num/den 形式的字符串，也可以是帧率缩写。

filter_name

要加载的 frei0r 源的名称。有关 frei0r 及其参数设置方法的更多信息，请参阅视频滤镜文档中的 frei0r 一节。

filter_params

传递给 frei0r 源的参数列表，以 ’|’ 分隔。

例如，要生成一个尺寸为 200x200、帧率为 10 的 frei0r partik0l 源，并将其叠加到 overlay 滤镜的主输入上：

frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay

18.10 life

生成一个生命游戏图案。

此源基于对 John Conway 的生命游戏的一种推广。

源输入表示一个生命网格，每个像素表示一个可能处于两种状态之一（存活或死亡）的细胞。每个细胞与其八个邻居相互作用，这些邻居是水平、垂直或对角相邻的细胞。

在每次交互中，网格都会根据所采用的规则演化，该规则指定使一个细胞保持存活或诞生所需的邻居存活细胞数。rule 选项允许指定要采用的规则。

该源接受以下选项：

filename, f

设置用于读取初始网格状态的文件。在该文件中，每个非空白字符都被视为一个存活细胞，换行符用于分隔每一行的末尾。

如果未指定此选项，则随机生成初始网格。

rate, r

设置视频帧率，即每秒生成的帧数。默认值为 25。

random_fill_ratio, ratio

设置初始随机网格的随机填充比例。这是一个介于 0 到 1 之间的浮点数值，默认值为 1/PHI。指定了文件时会忽略此选项。

random_seed, seed

设置填充初始随机网格所用的种子。必须是介于 0 到 UINT32_MAX 之间的整数。如果未指定，或显式设置为 -1，滤镜将尽力选取一个较好的随机种子。

rule

设置生命游戏的规则。

规则可以用 "SNS/BNB" 这样的代码指定，其中 NS 和 NB 是 0-8 范围内的数字序列，NS 指定使存活细胞保持存活的邻居存活细胞数，NB 指定使死亡细胞变为存活（即“诞生”）的邻居存活细胞数。可以用 "s" 和 "b" 分别代替 "S" 和 "B"。

也可以用一个 18 位整数指定规则。高 9 位用于编码在每种邻居存活细胞数下、细胞若存活时的下一状态，低位则指定“诞生”新细胞的规则。位序越高，编码对应的邻居细胞数越多。例如数字 6153 = (12<<9)+9 指定了保持存活规则 12 和诞生规则 9，对应于 "S23/B03"。

默认值为 "S23/B3"，这是原始的 Conway 生命游戏规则:若一个细胞周围有 2 个或 3 个存活的邻居细胞则保持存活，若一个死亡细胞周围有 3 个存活细胞则诞生新细胞。

size, s

设置输出视频的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。

如果指定了 filename，则尺寸默认与输入文件相同。如果设置了 size，它必须包含输入文件中指定的尺寸，该文件中定义的初始网格会居中放置在更大的结果区域中。

如果未指定 filename，则 size 的值默认为 "320x240"（用于随机生成的初始网格）。

stitch

如果设为 1，则将网格的左右边缘缝合在一起，上下边缘同样如此。默认值为 1。

mold

设置细胞的霉变速度。设置后，死亡细胞将以 mold 为步长从 death_color 变化到 mold_color。mold 的取值范围为 0 到 255。

life_color

设置存活（或新诞生）细胞的颜色。

death_color

设置死亡细胞的颜色。如果设置了 mold，这将是表示死亡细胞所用的第一种颜色。

mold_color

设置霉变颜色，用于彻底死亡且已发霉的细胞。

有关这 3 个颜色选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Color”一节。

18.10.1 示例

从 pattern 读取网格，并将其居中放置在一个尺寸为 300x300 像素的网格中：
```
life=f=pattern:s=300x300
```
生成一个尺寸为 200x200、填充比例为 2/3 的随机网格：
```
life=ratio=2/3:s=200x200
```
为随机生成的网格的演化指定自定义规则：
```
life=rule=S14/B34
```

使用 ffplay 演示带缓慢死亡效果（mold）的完整示例：

ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16

18.11 perlin

生成 Perlin 噪声。

Perlin 噪声是一种在空间上具有局部连续性的噪声。它可用于生成在空间和时间上具有连续性的图案，例如模拟烟雾、流体或地形。

如果通过 octaves 选项指定了多于一个的倍频程，Perlin 噪声将生成为多个分量之和，每个分量的频率依次加倍。此时 persistence 选项指定各分量振幅相对于前一分量的比例。更多的倍频程分量能够在生成的噪声中体现更多高频细节（例如生成地形时由巨石造成的小尺寸变化）。

18.11.1 选项

size, s

指定缓冲视频帧的尺寸（宽度和高度）。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 320x240。

rate, r

指定预期的视频流帧率，以每秒帧数表示。默认值为 25。

octaves

指定构成噪声的分量总数，每个分量的频率依次加倍。默认值为 1。

persistence

设置用于计算下一倍频程分量相对于前一分量振幅的比例。默认值为 1。

xscale yscale

定义用于缩放 x、y 坐标的比例因子。这对于定义沿 x 或 y 轴拉伸的图案效果很有用。默认值为 1。

tscale

定义用于放大时间坐标的比例因子。这对于改变时间变化速度很有用。默认值为 1。

random_mode

设置用于计算初始图案的随机模式。

支持以下取值：

random

计算并使用随机种子。

ken

使用 Ken Perlin 在原始文章中定义的预先定义的初始图案，可用于将输出与其他源进行比较。

seed

使用 random_seed 选项指定的值。

默认值为 random。

random_seed, seed

当 random_mode 设为 random_seed 时，使用此值计算初始图案。默认值为 0。

18.11.2 示例

生成单一分量：
```
perlin
```
使用 7 个分量的 Perlin 噪声，每个分量对总振幅的贡献减半：
```
perlin=octaves=7:persistence=0.5
```

将 Perlin 噪声与 lutyuv 串联，生成黑白效果：

perlin=octaves=3:tscale=0.3,lutyuv=y='if(lt(val\,128)\,255\,0)'

沿 y 轴拉伸噪声，并将灰度级转换为仅红色信号：
```
perlin=octaves=7:tscale=0.4:yscale=0.3,lutrgb=r=val:b=0:g=0
```

18.12 qrencodesrc

使用 libqrencode 库生成二维码(参见 https://fukuchi.org/works/qrencode/)。

要启用此源的编译，需要使用 --enable-libqrencode 配置 FFmpeg。

二维码根据提供的文本或文本模板生成。相应的二维码会按指定的输出尺寸选项进行缩放并放入视频输出中。

如果未指定文本，则不会生成二维码，而是返回一个空的纯色输出。

该源接受以下选项：

qrcode_width, q padded_qrcode_width, Q

指定渲染出的二维码有内边距和无内边距时的宽度表达式。qrcode_width 表达式可以引用 padded_qrcode_width 表达式设置的值，反之亦然。默认情况下 padded_qrcode_width 被设为 qrcode_width，即没有内边距。

这些表达式仅在初始化源时求值一次。详情请参阅 qrencode 表达式一节。

请注意，此源缺少部分常量（例如 x、t 或 n），因为它们只有在逐帧求值而非仅在初始化时求值的场合才有意义。

rate, r

指定源视频的帧率，以每秒生成的帧数表示。必须是 frame_rate_num/frame_rate_den 格式的字符串、整数、浮点数，或有效的视频帧率缩写。默认值为 "25"。

case_sensitive, cs

指示 libqrencode 使用区分大小写的编码。默认启用。可以禁用以减小二维码编码尺寸。

level, l

指定二维码编码的纠错级别。纠错级别越高，编码尺寸越大，但二维码对损坏的鲁棒性越强。较低的级别是 L。

可接受的值有：

‘L’ ‘M’ ‘Q’ ‘H’ expansion

选择输入文本的展开方式。可以是 none，或 normal（默认）。详情请参阅 qrencode 文本展开一节。

text textfile

定义要渲染的文本。如果两者都未指定，则不编码任何二维码（仅生成一个空的纯色帧）。

如果启用了 expansion，文本将被当作文本模板处理，使用 qrencode 的展开机制。详情请参阅 qrencode 文本展开一节。

background_color, bc foreground_color, fc

设置二维码及背景颜色。foreground_color 的默认值为 "black"，background_color 的默认值为 "white"。

有关颜色选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Color”一节。

18.12.1 示例

使用默认尺寸生成一个编码指定文本的二维码：
```
qrencodesrc=text=www.ffmpeg.org
```

与下例相同，但选择粉底蓝色：

qrencodesrc=text=www.ffmpeg.org:bc=pink:fc=blue

生成一个宽度为 200 像素并带内边距的二维码，使带内边距的宽度为二维码宽度的 4/3：
```
qrencodesrc=text=www.ffmpeg.org:q=200:Q=4/3*q
```
生成一个带内边距宽度为 200 像素的二维码，使二维码宽度为带内边距宽度的 3/4：
```
qrencodesrc=text=www.ffmpeg.org:Q=200:q=3/4*Q
```
生成一个编码帧号的二维码：
```
qrencodesrc=text=%{n}
```
生成一个编码 GMT 时间戳的二维码：
```
qrencodesrc=text=%{gmtime}
```
生成一个编码浮点数形式时间戳的二维码：
```
qrencodesrc=text=%{pts}
```

18.13 allrgb, allyuv, color, colorchart, colorspectrum, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc

allrgb 源返回尺寸为 4096x4096、包含所有 rgb 颜色的帧。

allyuv 源返回尺寸为 4096x4096、包含所有 yuv 颜色的帧。

color 源提供均匀着色的输入。

colorchart 源提供色彩检查卡输入。

colorspectrum 源提供色谱输入。

haldclutsrc 源提供一个恒等 Hald CLUT。另请参阅 haldclut 滤镜。

nullsrc 源返回未经处理的视频帧。它主要用于分析/调试工具，或作为忽略输入数据的滤镜的源。

pal75bars 源生成一个基于 EBU PAL 建议、颜色电平为 75% 的彩条图案。

pal100bars 源生成一个基于 EBU PAL 建议、颜色电平为 100% 的彩条图案。

rgbtestsrc 源生成一个用于检测 RGB 与 BGR 问题的 RGB 测试图案。你应能看到从上到下依次排列的红、绿、蓝三条色带。

smptebars 源生成一个基于 SMPTE Engineering Guideline EG 1-1990 的彩条图案。

smptehdbars 源生成一个基于 SMPTE RP 219-2002 的彩条图案。

testsrc 源生成一个测试视频图案，显示色彩图案、滚动渐变以及时间戳。这主要用于测试目的。

testsrc2 源与 testsrc 类似，但支持更多 pixel format 而不仅是 rgb24。这使它可以作为其他测试的输入，而无需进行格式转换。

yuvtestsrc 源生成一个 YUV 测试图案。你应能看到从上到下依次排列的 y、cb 和 cr 三条色带。

这些源接受以下参数：

level

指定 Hald CLUT 的级别，仅在 haldclutsrc 源中可用。级别 N 会生成一张 N*N*N 乘 N*N*N 像素的图片，用作 3D 查找表的恒等矩阵。每个分量以 1/(N*N) 的比例编码。

color, c

指定源的颜色，仅在 color 源中可用。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Color”一节。

size, s

指定源视频的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 320x240。

此选项不适用于 allrgb、allyuv 和 haldclutsrc 滤镜。

rate, r

指定源视频的帧率，以每秒生成的帧数表示。必须是 frame_rate_num/frame_rate_den 格式的字符串、整数、浮点数，或有效的视频帧率缩写。默认值为 "25"。

duration, d

设置源视频的时长。有关可接受的语法，请参阅 ffmpeg-utils(1) 手册中的 (ffmpeg-utils)Time duration 一节。

如果未指定，或表示的时长为负值，则视频将被视为无限生成。

由于帧率被用作时间基，包括最后一帧在内的所有帧都将拥有完整的时长。如果指定的时长不是帧时长的整数倍，则会向上取整。

sar

设置源视频的样本宽高比。

alpha

指定背景的 alpha（不透明度），仅在 testsrc2 源中可用。取值必须介于 0（完全透明）和 255（完全不透明，默认值）之间。

decimals, n

设置时间戳中显示的小数位数，仅在 testsrc 源中可用。

显示的时间戳值将对应原始时间戳值乘以指定值的 10 的幂。默认值为 0。

type

设置色谱的类型，仅在 colorspectrum 源中可用。可以是以下之一：

‘black’ ‘white’ ‘all’ patch_size

设置单个色块的尺寸，仅在 colorchart 源中可用。默认为 64x64。

preset

设置色彩检查卡颜色预设，仅在 colorchart 源中可用。

可用值如下：

‘reference’ ‘skintones’

默认值为 reference。

18.13.1 示例

生成一个时长为 5.3 秒、尺寸为 176x144、帧率为每秒 10 帧的视频：
```
testsrc=duration=5.3:size=qcif:rate=10
```
以下滤镜图描述将生成一个不透明度为 0.2 的红色源，尺寸为 "qcif"，帧率为每秒 10 帧：
```
color=c=red@0.2:s=qcif:r=10
```
如果要忽略输入内容，可以使用 nullsrc。以下命令通过使用 geq 滤镜在亮度平面中生成噪声：
```
nullsrc=s=256x256, geq=random(1)*255:128:128
```

18.13.2 命令

color 源支持以下命令：

c, color

设置所创建图像的颜色。接受与相应 color 选项相同的语法。

18.14 openclsrc

使用 OpenCL 程序生成视频。

source

OpenCL 程序源文件。

kernel

程序中的内核名称。

size, s

要生成的帧的尺寸。此项必须设置。

format

用于生成帧的 pixel format。此项必须设置。

rate, r

每秒生成的帧数。默认值为 ’25’。

有关程序加载方式的详情，请参阅 program_opencl 滤镜。

示例程序：

通过设置输出图像中像素位置的像素值来生成色彩渐变。（请注意，这适用于所有 pixel format，但生成的输出效果并不相同。）

__kernel void ramp(__write_only image2d_t dst,
                   unsigned int index)
{
    int2 loc = (int2)(get_global_id(0), get_global_id(1));

    float4 val;
    val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));

    write_imagef(dst, loc, val);
}

生成一个谢尔宾斯基地毯图案，每帧平移一个像素。

__kernel void sierpinski_carpet(__write_only image2d_t dst,
                                unsigned int index)
{
    int2 loc = (int2)(get_global_id(0), get_global_id(1));

    float4 value = 0.0f;
    int x = loc.x + index;
    int y = loc.y + index;
    while (x > 0 || y > 0) {
        if (x % 3 == 1 && y % 3 == 1) {
            value = 1.0f;
            break;
        }
        x /= 3;
        y /= 3;
    }

    write_imagef(dst, loc, value);
}

18.15 sierpinski

生成谢尔宾斯基地毯/三角形分形，并随机平移。

该源接受以下选项：

size, s

设置帧大小。有关该选项语法，请查看 ffmpeg-utils 手册中的 (ffmpeg-utils)“Video size”一节。默认值为 "640x480"。

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

seed

设置用于随机平移的种子。

jump

设置单次平移目标的最大跳跃距离。允许范围为 1 到 10000。

type

设置分形类型，可以是默认的 carpet 或 triangle。

18.16 zoneplate

生成一个 zoneplate 测试视频图案。

该源接受以下选项：

size, s

设置帧尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 "320x240"。

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

duration, d

设置源视频的时长。有关可接受的语法，请参阅 ffmpeg-utils(1) 手册中的 (ffmpeg-utils)Time duration 一节。

如果未指定，或表示的时长为负值，则视频将被视为无限生成。

sar

设置源视频的样本宽高比。

precision

设置正弦计算查找表的精度位数。默认值为 10。允许范围为 4 到 16。

设置输出信号的水平轴偏移量。默认值为 0。

设置输出信号的垂直轴偏移量。默认值为 0。

设置输出信号的时间轴偏移量。默认值为 0。

设置 0 阶常数，添加到信号相位中。默认值为 0。

设置 1 阶，水平轴的相位因子乘数。默认值为 0。

设置 1 阶，垂直轴的相位因子乘数。默认值为 0。

设置 1 阶，时间轴的相位因子乘数。默认值为 0。

kxt, kyt, kxy

设置空间轴与时间轴组合的相位因子乘数。默认值为 0。

kx2

设置 2 阶，水平轴的相位因子乘数。默认值为 0。

ky2

设置 2 阶，垂直轴的相位因子乘数。默认值为 0。

kt2

设置 2 阶，时间轴的相位因子乘数。默认值为 0。

设置添加到最终相位以生成信号色度蓝分量的常数。默认值为 0。

设置添加到最终相位以生成信号色度红分量的常数。默认值为 0。

18.16.1 命令

该源将上述部分选项作为命令支持。

18.16.2 示例

生成水平彩色正弦扫描：

zoneplate=ku=512:kv=0:kt2=0:kx2=256:s=wvga:xo=-426:kt=11

生成垂直彩色正弦扫描：

zoneplate=ku=512:kv=0:kt2=0:ky2=156:s=wvga:yo=-240:kt=11

生成圆形 zone-plate：

zoneplate=ku=512:kv=100:kt2=0:ky2=256:kx2=556:s=wvga:yo=0:kt=11

19 视频汇

以下是当前可用的视频汇的说明。

19.1 buffersink

缓冲视频帧，并使其在滤镜图末端可用。

此汇主要供程序化使用，尤其是通过 libavfilter/buffersink.h 中定义的接口或选项系统使用。

它接受一个指向 AVBufferSinkContext 结构体的指针，该结构体定义了传入缓冲区的格式，作为 opaque 参数传递给 avfilter_init_filter 用于初始化。

19.2 nullsink

空视频汇:对输入视频完全不做任何处理。它主要用作模板以及在分析/调试工具中使用。

20 多媒体滤镜

以下是当前可用的多媒体滤镜的说明。

20.1 a3dscope

将输入音频转换为 3D 示波器视频输出。

该滤镜接受以下选项：

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

size, s

指定输出的视频尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 hd720。

fov

设置摄像机视场角。默认为 90 度。允许范围为 40 到 150。

roll

设置摄像机横滚角。

pitch

设置摄像机俯仰角。

yaw

设置摄像机偏航角。

xzoom

设置摄像机在 X 轴上的缩放。

yzoom

设置摄像机在 Y 轴上的缩放。

zzoom

设置摄像机在 Z 轴上的缩放。

xpos

设置摄像机在 X 轴上的位置。

ypos

设置摄像机在 Y 轴上的位置。

zpos

设置摄像机在 Z 轴上的位置。

length

以帧数设置显示的音频波形长度。

20.1.1 命令

此滤镜支持上述部分选项作为命令。

20.2 abitscope

将输入音频转换为视频输出，显示音频比特示波图。

该滤镜接受以下选项：

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

size, s

指定输出的视频尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 1024x256。

colors

指定用于绘制各声道的颜色列表，以空格或 ’|’ 分隔。无法识别或缺失的颜色将被替换为白色。

mode, m

设置输出模式。可以是 bars 或 trace。默认值为 bars。

20.3 adrawgraph

使用输入音频元数据绘制图表。

参见 drawgraph

20.4 agraphmonitor

参见 graphmonitor。

20.5 ahistogram

将输入音频转换为视频输出，显示音量直方图。

该滤镜接受以下选项：

dmode

指定直方图的计算方式。

可接受的值有：

‘single’

对所有声道使用同一个直方图。

‘separate’

为每个声道使用单独的直方图。

默认值为 single。

rate, r

设置帧率，以每秒帧数表示。默认值为 "25"。

size, s

指定输出的视频尺寸。有关此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的“Video size”一节。默认值为 hd720。

scale

设置显示比例。

可接受的值有：

‘log’

对数

‘sqrt’

平方根

‘cbrt’

立方根

‘lin’

线性

‘rlog’

反向对数

默认值为 log。

ascale

设置振幅刻度。

可接受的值有：

‘log’

对数

‘lin’

线性

默认值为 log。

acount

设置直方图中累积的帧数。默认值为 1。设为 -1 则累积所有帧。

rheight

设置直方图占窗口高度的比例。

slide

设置声谱图的滑动方式。

可接受的值有：

‘replace’

用新行替换旧行。

‘scroll’

从上到下滚动。

默认值为 replace。

hmode

设置直方图模式。

可接受的值有：

‘abs’

使用样本的绝对值。

‘sign’

使用样本的原始值。

默认值为 abs。

20.6 aphasemeter

测量输入音频的相位，并作为元数据 lavfi.aphasemeter.phase 导出，表示当前音频帧的平均相位。也可以生成视频输出，且默认已启用。音频作为第一个输出直接通过。

如果音频的声道布局不同，会被重新混合为立体声。相位值范围为 [-1, 1]，其中 -1 表示左右声道完全反相，1 表示声道同相。

此滤镜接受以下选项，均与其视频输出相关：

rate, r

设置输出帧率。默认值为 25。

size, s

设置输出视频的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)"Video size" section in the ffmpeg-utils manual。默认值为 800x400。

rc gc bc

指定红、绿、蓝的对比度。默认值分别为 2、7 和 1。允许的范围为 [0, 255]。

mpc

设置用于绘制中值相位的颜色。若颜色为默认值 none，则不绘制中值相位值。

video

启用视频输出。默认已启用。

20.6.1 反相检测

此滤镜还会检测立体声流中的反相和单声道片段。当片段持续时间达到或超过设置的最小值时，会将其起始、结束和持续时间记录到日志。

此滤镜接受以下选项用于该检测：

phasing

启用单声道和反相检测。默认已禁用。

tolerance, t

以振幅比设置单声道检测的相位容差。默认值为 0。允许的范围为 [0, 1]。

angle, a

以度为单位设置反相检测的角度阈值。默认值为 170。允许的范围为 [90, 180]。

duration, d

以秒为单位设置发出通知前的单声道或反相持续时间。默认值为 2。

20.6.2 示例

使用 ffmpeg 检测容差为 0.001 的 1 秒单声道的完整示例：

ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -

20.7 avectorscope

将输入音频转换为视频输出，表示该音频的矢量示波图。

此滤镜用于测量立体声音频流各声道之间的差异。左右信号相同的单声道信号会形成一条竖直线。任何立体声分离都会显现为偏离该线的图形，构成一个李萨如图形。若出现的直线（或其偏离）呈水平状，则表示左右声道反相。

该滤镜接受以下选项：

mode, m

设置矢量示波图模式。

可用值如下：

‘lissajous’

旋转 45 度的李萨如图形。

‘lissajous_xy’

与上面相同，但不旋转。

‘polar’

形似半圆的形状。

默认值为 ‘lissajous’。

size, s

设置输出视频的尺寸。有关此选项的语法，请查看 (ffmpeg-utils)"Video size" section in the ffmpeg-utils manual。默认值为 400x400。

rate, r

设置输出帧率。默认值为 25。

rc gc bc ac

指定红、绿、蓝、alpha 的对比度。默认值分别为 40、160、80 和 255。允许的范围为 [0, 255]。

rf gf bf af

指定红、绿、蓝、alpha 的衰减。默认值分别为 15、10、5 和 5。允许的范围为 [0, 255]。

zoom

设置缩放系数。默认值为 1。允许的范围为 [0, 10]。低于 1 的值会自动将缩放系数调整到可能的最大值。

draw

设置矢量示波图的绘制模式。

可用值如下：

‘dot’

为每个采样点绘制一个点。

‘line’

在前一个采样点与当前采样点之间绘制一条线。

‘aaline’

在前一个采样点与当前采样点之间绘制一条抗锯齿线。

默认值为 ‘dot’。

scale

指定音频采样点的振幅刻度。

可用值如下：

‘lin’

线性。

‘sqrt’

平方根。

‘cbrt’

立方根。

‘log’

对数。

swap

交换左声道轴与右声道轴。

mirror

镜像坐标轴。

‘none’

不镜像。

‘x’

仅镜像 x 轴。

‘y’

仅镜像 y 轴。

‘xy’

镜像两个轴。

20.7.1 示例

使用 ffplay 的完整示例：

ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
             [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'

20.7.2 命令

除 size 和 rate 选项外，此滤镜支持以上所有选项作为命令。

20.8 bench, abench

对 filtergraph 中的某一部分进行基准测试。

该滤镜接受以下选项：

action

启动或停止计时器。

可用值如下：

‘start’

获取当前时间，将其设置为帧元数据（使用键 lavfi.bench.start_time），并将该帧转发给下一个滤镜。

‘stop’

获取当前时间，并从输入帧元数据中取出 lavfi.bench.start_time 元数据以求出时间差。随后输出时间差、平均、最大和最小时间（分别为 t、avg、max 和 min）。时间戳以秒表示。

20.8.1 示例

对 selectivecolor 滤镜进行基准测试：

bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop

20.9 concat

连接音频流和视频流，将它们依次拼接在一起。

此滤镜作用于同步的视频流和音频流片段。所有片段每种类型的流数量必须相同，这也将是输出的流数量。

该滤镜接受以下选项：

设置片段数量。默认值为 2。

设置输出视频流的数量，也就是每个片段中的视频流数量。默认值为 1。

设置输出音频流的数量，也就是每个片段中的音频流数量。默认值为 0。

unsafe

启用非安全模式：即使片段格式不同也不失败。

此滤镜有 v+a 个输出：先是 v 个视频输出，然后是 a 个音频输出。

共有 nx(v+a) 个输入：先是第一个片段的输入，顺序与输出相同，然后是第二个片段的输入，依此类推。

由于 codec 帧大小或制作不严谨等各种原因，相关联的流未必总是具有完全相同的时长。因此，相关联的同步流（例如一段视频及其音轨）应当一次性拼接。concat 滤镜会使用每个片段（最后一个片段除外）中最长流的时长，如有需要会用静音填充较短的音频流。

要让此滤镜正常工作，所有片段都必须从时间戳 0 开始。

所有对应的流在各个片段中必须具有相同的参数；滤镜系统会自动为视频流选择通用的 pixel format，为音频流选择通用的 sample format、采样率和声道布局，但分辨率等其他设置必须由用户显式转换。

不同的帧率是可以接受的，但会导致输出为可变帧率；请确保将输出文件配置为能够处理这种情况。

20.9.1 示例

连接片头、正片和片尾，均为双语版本（视频在流 0，音频在流 1 和 2）：

ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
  '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
   concat=n=3:v=1:a=2 [v] [a1] [a2]' \
  -map '[v]' -map '[a1]' -map '[a2]' output.mkv

使用 (a)movie 源分别处理音频和视频，并调整分辨率，连接两个片段：

movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]

注意，如果第一个文件中的音频流和视频流时长不完全一致，拼接处会出现失步。

20.9.2 命令

该滤镜支持以下命令：

关闭当前片段并前进到下一个片段

20.10 ebur128

EBU R128 扫描滤镜。此滤镜接收音频流并分析其响度水平。默认情况下，它以 10Hz 的频率记录一条消息，其中包含瞬时响度（用 M 标识）、短期响度（S）、综合响度（I）和响度范围（LRA）。

此滤镜只能分析 sample format 为双精度浮点的流。如有需要，输入流会被转换为该格式。用户可能需要在此滤镜之后插入 aformat 和/或 aresample 滤镜，以恢复原始参数。

此滤镜还具有一个视频输出（参见 video 选项），带有实时图表以观察响度变化。该图表包含上文所述的记录消息，因此设置该选项后将不再打印这些消息，除非设置了 verbose 日志级别。主图表区域显示短期响度（3 秒的分析），右侧仪表用于显示瞬时响度（400 毫秒），但也可以配置为改为显示短期响度（参见 gauge）。

绿色区域标出以目标响度（默认为 -23LUFS，除非通过 target 修改）为中心、上下 1LU 的目标范围。

关于 Loudness Recommendation EBU R128 的更多信息，请参阅 http://tech.ebu.ch/loudness。

该滤镜接受以下选项：

video

启用视频输出。无论是否设置此选项，音频流都会原样通过。启用后，视频流将成为第一个输出流。默认值为 0。

size

设置视频尺寸。此选项仅用于视频。有关此选项的语法，请查看 (ffmpeg-utils)"Video size" section in the ffmpeg-utils manual。默认及最小分辨率为 640x480。

meter

设置 EBU 刻度表。默认值为 9。常用值为 9 和 18，分别对应 EBU 刻度表 +9 和 EBU 刻度表 +18。此范围内的其他任意整数值也是允许的。

metadata

设置元数据注入。若设为 1，音频输入将被分割为 100ms 的输出帧，每帧的元数据中包含各种响度信息。所有元数据键均以 lavfi.r128. 为前缀。

默认值为 0。

framelog

强制设置帧日志记录级别。

可用值如下：

‘quiet’

禁用日志记录

‘info’

信息级别的日志记录

‘verbose’

详细级别的日志记录

默认情况下，日志记录级别设为 info。若设置了 video 或 metadata 选项，则会切换为 verbose。

peak

设置峰值模式。

可用模式可以累加（此选项为 flag 类型）。可选值如下：

‘none’

禁用任何峰值模式（默认）。

‘sample’

启用采样峰值模式。

一种查找最高采样值的简单峰值模式。它会为采样峰值记录一条消息（用 SPK 标识）。

‘true’

启用真峰值模式。

启用后，峰值查找将在输入流的过采样版本上进行，以获得更高的峰值精度。它会记录真峰值消息（用 TPK 标识）以及每帧的真峰值（用 FTPK 标识）。此模式需要包含 libswresample 的构建。

dualmono

将单声道输入文件当作“双单声道”处理。若单声道文件用于在立体声系统上播放，其 EBU R128 测量值在听感上会不正确。设为 true 时，此选项会对这一影响进行补偿。多声道输入文件不受此选项影响。

panlaw

设置用于测量双单声道文件的特定声像法则（pan law）。此参数为可选，默认值为 -3.01dB。

target

设置在可视化中用作相对零点的特定目标电平（单位为 LUFS）。此参数为可选，默认值为 EBU R128 所规定的 -23LUFS。不过，在线发布的素材可能更倾向于使用 -16LUFS 的电平（例如用于播客或视频平台）。

gauge

设置仪表显示的值。有效值为 momentary 和 shortterm。默认使用瞬时值，但在某些场景下（例如实时混音）观察短期值可能更有用。

scale

设置响度的显示刻度。有效参数为 absolute（单位为 LUFS）或相对于 target 的 relative（单位为 LU）。这仅影响视频输出，不影响摘要或连续日志输出。

integrated

测得的综合响度（单位为 LUFS）的只读导出值。

range

测得的响度范围（单位为 LU）的只读导出值。

lra_low

测得的 LRA 下限（单位为 LUFS）的只读导出值。

lra_high

测得的 LRA 上限（单位为 LUFS）的只读导出值。

sample_peak

测得的采样峰值（单位为 dBFS）的只读导出值。

true_peak

测得的真峰值（单位为 dBFS）的只读导出值。

20.10.1 示例

使用 ffplay 显示实时图表，EBU 刻度表为 +18：

ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"

使用 ffmpeg 运行分析：

ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -

20.11 interleave, ainterleave

将多个输入的帧按时间交织。

interleave 用于视频输入，ainterleave 用于音频。

这些滤镜从多个输入读取帧，并将排队中最早的帧发送到输出。

输入流必须具有定义明确、单调递增的帧时间戳值。

为了向输出提交一帧，这些滤镜需要为每个输入至少排队一帧，因此，如果某个输入尚未结束且不会再接收传入帧，它们就无法工作。

例如，考虑这样一种情况：某个输入是一个始终丢弃输入帧的 select 滤镜。interleave 滤镜会持续从该输入读取，但在该输入发出流结束（end-of-stream）信号之前，它永远无法向输出发送新帧。

另外，根据各输入的同步情况，如果某个输入接收到的帧比其他输入多，且队列已满，这些滤镜会丢弃帧。

这些滤镜接受以下选项：

nb_inputs, n

设置不同输入的数量，默认值为 2。

duration

如何判定流结束。

longest

最长输入的时长。（默认）

shortest

最短输入的时长。

first

第一个输入的时长。

20.11.1 示例

使用 ffmpeg 交织属于不同流的帧：

ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi

添加闪烁模糊效果：

select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave

20.12 latency, alatency

测量滤镜延迟。

报告上一个滤镜的过滤延迟：对音频滤镜以音频采样点数表示，对视频滤镜以视频帧数表示。

在输入流结束时，滤镜会报告 filtergraph 中上一个运行滤镜所测得的最小和最大延迟。

20.13 metadata, ametadata

操作帧元数据。

此滤镜接受以下选项：

mode

设置滤镜的操作模式。

可以是以下之一：

‘select’

若同时设置了 value 和 key，则选择具有此类元数据的帧。若仅设置了 key，则选择元数据中包含该键的所有帧。

‘add’

添加新的元数据 key 和 value。若键已存在，则不做任何操作。

‘modify’

修改已存在键的值。

‘delete’

若设置了 value，则只删除具有该值的键；否则删除该键。若未设置 key，则删除帧中的所有元数据值。

‘print’

若找到元数据，则打印键及其值。若未设置 key，则打印帧中所有可用的元数据值。

key

设置所有模式所使用的键。除 print 和 delete 外的所有模式都必须设置此项。

value

设置将要使用的元数据值。此选项对 modify 和 add 模式是必需的。

function

比较元数据值与 value 时使用的函数。

可以是以下之一：

‘same_str’

将值解释为字符串，若元数据值与 value 相同则返回 true。

‘starts_with’

将值解释为字符串，若元数据值以 value 选项的字符串开头则返回 true。

‘less’

将值解释为浮点数，若元数据值小于 value 则返回 true。

‘equal’

将值解释为浮点数，若 value 与元数据值相等则返回 true。

‘greater’

将值解释为浮点数，若元数据值大于 value 则返回 true。

‘expr’

将值解释为浮点数，若选项 expr 的表达式求值为 true 则返回 true。

‘ends_with’

将值解释为字符串，若元数据值以 value 选项的字符串结尾则返回 true。

expr

设置当 function 设为 expr 时所使用的表达式。该表达式通过 eval API 求值，可以包含以下常量：

VALUE1, FRAMEVAL

元数据键中 value 的浮点表示。

VALUE2, USERVAL

用户在 value 选项中指定的 value 的浮点表示。

file

若在 print 模式下指定，输出会写入指定的文件。可以指定任意可写的 URL 来代替普通文件名。文件名 “-” 是标准输出的简写。若未设置 file 选项，输出会以 AV_LOG_INFO 日志级别写入日志。

direct

在 print 模式下，当输出写入通过 file 设置的 URL 时，减少缓冲。

20.13.1 示例

打印键 lavfi.signalstats.YDIF 值介于 0 和 1 之间的帧的所有元数据值。

signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'

将 silencedetect 的输出打印到文件 metadata.txt。
```
silencedetect,ametadata=mode=print:file=metadata.txt
```
将所有元数据定向到文件描述符 4 的管道。
```
metadata=mode=print:file='pipe\:4'
```

20.14 perms, aperms

设置输出帧的读写权限。

这些滤镜主要面向开发者，用于测试 filtergraph 中后续滤镜的直接路径。

这些滤镜接受以下选项：

mode

选择权限模式。

可接受的值有：

‘none’

不做任何操作。这是默认值。

‘ro’

将所有输出帧设为只读。

‘rw’

将所有输出帧设为可直接写入。

‘toggle’

若帧可写，则将其设为只读；若为只读，则将其设为可写。

‘random’

随机将每个输出帧设为只读或可写。

seed

设置 random 模式的种子，必须是介于 0 和 UINT32_MAX 之间的整数。若未指定，或明确设为 -1，滤镜会尽力选用一个良好的随机种子。

注意：如果在权限滤镜和下一个滤镜之间自动插入了滤镜，权限可能不会按预期在该下一个滤镜中被接收。在 perms/aperms 滤镜之前插入 format 或 aformat 滤镜可以避免此问题。

20.15 realtime, arealtime

放慢滤镜处理速度，使其大致匹配实时。

这些滤镜会暂停滤镜处理一段可变的时间，以使输出速率与输入时间戳匹配。它们类似于 ffmpeg 的 re 选项。

它们接受以下选项：

limit

暂停的时间上限。任何超过此值的暂停都会被视为时间戳不连续，并重置计时器。默认值为 2 秒。

speed

处理速度系数。该值必须是大于零的浮点数。大于 1.0 的值会使处理速度快于实时，较小的值则会放慢处理速度。limit 会相应地自动调整。默认值为 1.0。

无法实现比不使用这些滤镜时更快的处理速度。

20.15.1 命令

这两个滤镜都支持将以上所有选项作为命令。

20.16 segment, asegment

将单个输入流拆分为多个流。

此滤镜的作用与 concat 滤镜相反。

segment 作用于视频帧，asegment 作用于音频采样点。

此滤镜接受以下选项：

timestamps

以 ’|’ 分隔的输出片段时间戳。第一个片段从输入流的开头开始运行，最后一个片段运行到输入流的末尾结束

frames, samples

用于拆分片段的准确帧数/采样点数。

在这两种情况下，给每个片段加上前缀 ’+’ 都会使其相对于前一个片段。

20.16.1 示例

将输入音频流拆分为三个输出音频流：从输入音频流开头开始，存入第 1 个输出音频流；接着从第 60 秒起，存入第 2 个输出音频流；最后从输入音频流第 150 秒之后，存入第 3 个输出音频流：
```
asegment=timestamps="60|150"
```

20.17 select, aselect

选择要传递到输出的帧。

此滤镜接受以下选项：

expr, e

设置对每个输入帧求值的表达式。

若表达式求值为零，该帧会被丢弃。

若求值结果为负数或 NaN，该帧会被发送到第一个输出；否则会被发送到索引为 ceil(val)-1 的输出（假设输入索引从 0 开始）。

例如，值 1.2 对应索引为 ceil(1.2)-1 = 2-1 = 1 的输出，即第二个输出。

outputs, n

设置输出数量。选中的帧发送到哪个输出，取决于求值结果。默认值为 1。

该表达式可以包含以下常量：

被过滤帧的（顺序）编号，从 0 开始。

selected_n

被选中帧的（顺序）编号，从 0 开始。

prev_selected_n

上一个被选中帧的顺序编号。若未定义，则为 NAN。

输入时间戳的时间基。

pts

被过滤帧的 PTS（Presentation TimeStamp），以 TB 为单位表示。若未定义，则为 NAN。

被过滤帧的 PTS，以秒为单位表示。若未定义，则为 NAN。

prev_pts

上一个被过滤帧的 PTS。若未定义，则为 NAN。

prev_selected_pts

上一个被选中帧的 PTS。若未定义，则为 NAN。

prev_selected_t

上一个被选中帧的 PTS，以秒为单位表示。若未定义，则为 NAN。

start_pts

流中第一个非 NAN 的 PTS。若未找到，则保持为 NAN。

start_t

流中第一个非 NAN 的 PTS，以秒为单位。若未找到，则保持为 NAN。

pict_type （仅视频）

被过滤帧的类型。可以取以下值之一：

I P B S SI SP BI interlace_type （仅视频）

帧的隔行类型。可以取以下值之一：

PROGRESSIVE

该帧是逐行的（非隔行）。

TOPFIRST

该帧是顶场优先的。

BOTTOMFIRST

该帧是底场优先的。

consumed_sample_n （仅音频）

当前帧之前已选中的采样点数

samples_n （仅音频）

当前帧中的采样点数

sample_rate （仅音频）

输入的采样率

key

若被过滤的帧是 keyframe，则该值为 1，否则为 0。

pos

被过滤帧在文件中的位置，若信息不可用（例如合成视频）则为 -1；已弃用，请勿使用

scene （仅视频）

介于 0 和 1 之间的值，用于指示新场景；较低的值反映当前帧引入新场景的可能性较低，而较高的值意味着当前帧更可能是新场景（参见下面的示例）

concatdec_select

concat demuxer 可以通过设置 inpoint 和 outpoint 来只选择 concat 输入文件的一部分，但输出的数据包未必完全包含在所选区间内。使用此变量，可以跳过 concat demuxer 生成的、未精确包含在所选区间内的帧。

其原理是将帧的 pts 与 lavf.concat.start_time 及 lavf.concat.duration 这两个数据包元数据值进行比较，这两个值同样存在于解码后的帧中。

若帧的 pts 不小于 start_time，且 duration 元数据缺失或帧的 pts 小于 start_time + duration，则 concatdec_select 变量为 -1；否则为 0；若 start_time 元数据缺失，则为 NaN。

这基本上意味着：只要输入帧的 pts 落在 concat demuxer 设置的区间内，该帧就会被选中。

iw （仅视频）

表示输入视频帧的宽度。

ih （仅视频）

表示输入视频帧的高度。

view （仅视频）

多视点视频的视图 ID。

select 表达式的默认值为 "1"。

20.17.1 示例

选择输入中的所有帧：
```
select
```

上面的示例等同于：

    select=1

跳过所有帧：
```
select=0
```
只选择 I 帧：
```
select='eq(pict_type\,I)'
```
每 100 帧选择一帧：
```
select='not(mod(n\,100))'
```
只选择包含在 10-20 时间区间内的帧：
```
select=between(t\,10\,20)
```
只选择包含在 10-20 时间区间内的 I 帧：
```
select=between(t\,10\,20)*eq(pict_type\,I)
```

选择最小间隔为 10 秒的帧：

select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'

使用 aselect 只选择采样数大于 100 的音频帧：
```
aselect='gt(samples_n\,100)'
```

创建最初几个场景的拼图：

ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png

将 scene 与 0.3 到 0.5 之间的值进行比较通常是合理的选择。

将偶数帧和奇数帧发送到不同的输出并将其合成：

select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h

从使用了 inpoint 和 outpoint、但源文件并非只有帧内帧的 ffconcat 文件中选择有用的帧。

ffmpeg -copyts -segment_time_metadata 1 -i input.ffconcat -fps_mode passthrough -vf select=concatdec_select -af aselect=concatdec_select output.avi

20.18 sendcmd, asendcmd

将命令发送给 filtergraph 中的滤镜。

这些滤镜读取要发送给 filtergraph 中其他滤镜的命令。

sendcmd 必须插入在两个视频滤镜之间，asendcmd 必须插入在两个音频滤镜之间，除此之外二者的行为相同。

命令的规格说明可以通过 commands 选项在滤镜参数中提供，也可以在 filename 选项指定的文件中提供。

这些滤镜接受以下选项：

commands, c

设置要读取并发送给其他滤镜的命令。

filename, f

设置要读取并发送给其他滤镜的命令所在文件的文件名。

20.18.1 命令语法

命令的描述由一系列区间规格组成，每个区间规格包含在与该区间相关的特定事件发生时要执行的命令列表。所发生的事件通常是当前帧时间进入或离开给定的时间区间。

区间按以下语法指定：

START[-END] COMMANDS;

时间区间由 START 和 END 时间指定。END 是可选的，默认值为最大时间。

如果当前帧时间包含在区间 [START, END) 内，即时间大于或等于 START 且小于 END，则认为其处于指定区间内。

COMMANDS 由一个或多个命令规格组成，各命令规格以 "," 分隔，均与该区间相关。命令规格的语法为：

[FLAGS] TARGET COMMAND ARG

FLAGS 是可选的，用于指定与该时间区间相关、可触发发送指定命令的事件类型，必须是由 "+" 或 "|" 分隔并以 "[" 和 "]" 括起的非空标识符标志序列。

可识别的标志如下：

enter

当当前帧时间戳进入指定区间时发送该命令。换言之，当前一帧的时间戳不在给定区间内，而当前帧在区间内时发送该命令。

leave

当当前帧时间戳离开指定区间时发送该命令。换言之，当前一帧的时间戳在给定区间内，而当前帧不在区间内时发送该命令。

expr

命令的 ARG 被解释为表达式，表达式的结果作为 ARG 传递。

该表达式通过 eval API 求值，可以包含以下常量：

POS

帧在文件中的原始位置，若当前帧未定义则为 undefined。已弃用，请勿使用。

PTS

输入中的 presentation timestamp。

视频或音频输入帧的计数，从 0 开始。

当前帧的时间（以秒为单位）。

当前命令区间的开始时间（以秒为单位）。

当前命令区间的结束时间（以秒为单位）。

当前命令区间的插值时间，TI = (T - TS) / (TE - TS)。

视频帧的宽度。

视频帧的高度。

如果未指定 FLAGS，则假定默认值为 [enter]。

TARGET 指定命令的目标，通常是滤镜类的名称或特定滤镜实例的名称。

COMMAND 指定目标滤镜的命令名称。

ARG 是可选的，用于指定给定 COMMAND 的可选参数列表。

在一个区间规格与另一个区间规格之间，空白字符，或以 # 开头直到行尾的字符序列会被忽略，可用于添加注释。

命令规格语法的简化 BNF 描述如下：

COMMAND_FLAG  ::= "enter" | "leave"
COMMAND_FLAGS ::= COMMAND_FLAG [(+|"|")COMMAND_FLAG]
COMMAND       ::= ["[" COMMAND_FLAGS "]"] TARGET COMMAND [ARG]
COMMANDS      ::= COMMAND [,COMMANDS]
INTERVAL      ::= START[-END] COMMANDS
INTERVALS     ::= INTERVAL[;INTERVALS]

20.18.2 示例

在第 4 秒指定音频节奏变化：

asendcmd=c='4.0 atempo tempo 1.5',atempo

指定特定的滤镜实例作为目标：

asendcmd=c='4.0 atempo@my tempo 1.5',atempo@my

在文件中指定 drawtext 和 hue 的命令列表。

# show text in the interval 5-10
5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
         [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';

# desaturate the image in the interval 15-20
15.0-20.0 [enter] hue s 0,
          [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
          [leave] hue s 1,
          [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';

# apply an exponential saturation fade-out effect, starting from time 25
25 [enter] hue s exp(25-t)

可以用以下方式指定 filtergraph，读取并处理存储在文件 test.cmd 中的上述命令列表：

    sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue

20.19 setpts, asetpts

更改输入帧的 PTS（presentation timestamp）。

setpts 作用于视频帧，asetpts 作用于音频帧。

此滤镜接受以下选项：

expr

针对每一帧求值以构造其时间戳的表达式。

strip_fps （仅视频）

布尔选项，用于确定是否取消设置原始帧率和帧时长元数据。如果设置为 true，请注意，如果输出被发送到恒定帧率的 muxer，则应显式指定一个合理的帧率。默认值为 false。

该表达式通过 eval API 求值，可以包含以下常量：

FRAME_RATE, FR

帧率，仅对恒定帧率的视频有定义

PTS

输入中的 presentation timestamp

视频输入帧的计数，或音频已消耗采样数（不包括当前帧），从 0 开始。

NB_CONSUMED_SAMPLES

已消耗的采样数，不包括当前帧（仅音频）

NB_SAMPLES, S

当前帧中的采样数（仅音频）

SAMPLE_RATE, SR

音频采样率。

STARTPTS

第一帧的 PTS。

STARTT

第一帧的时间（以秒为单位）

INTERLACED

说明当前帧是否为隔行。

当前帧的时间（以秒为单位）

POS

帧在文件中的原始位置，若当前帧未定义则为 undefined；已弃用，请勿使用

PREV_INPTS

前一个输入 PTS。

PREV_INT

前一个输入时间（以秒为单位）

PREV_OUTPTS

前一个输出 PTS。

PREV_OUTT

前一个输出时间（以秒为单位）

RTCTIME

以微秒为单位的挂钟（RTC）时间。已弃用，请改用 time(0)。

RTCSTART

以微秒为单位的、影片开始时的挂钟（RTC）时间。

输入时间戳的时间基。

T_CHANGE

应用命令后第一帧的时间，若无命令则为第一帧的时间。

20.19.1 示例

从零开始计数 PTS
```
setpts=PTS-STARTPTS
```
应用快动作效果：
```
setpts=0.5*PTS
```
应用慢动作效果：
```
setpts=2.0*PTS
```
设置固定帧率为每秒 25 帧：
```
setpts=N/(25*TB)
```
应用 +/-100 个 TB 单位的随机抖动效果：
```
setpts=PTS+randomi(0, -100\,100)
```

设置固定帧率 25 fps，并带一些抖动：

setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'

对输入 PTS 应用 10 秒的偏移量：
```
setpts=PTS+10/TB
```
从“实时源”生成时间戳，并将其重新映射到当前时间基：
```
setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
```
通过对采样计数来生成时间戳：
```
asetpts=N/SR/TB
```

20.19.2 命令

这两个滤镜都支持将以上所有选项作为命令。

20.20 setrange

强制设置输出视频帧的色彩范围。

setrange 滤镜为输出帧标记色彩范围属性。它不会更改输入帧，只是设置相应的属性，从而影响后续滤镜对该帧的处理方式。

该滤镜接受以下选项：

range

可用值如下：

‘auto’

保持相同的色彩范围属性。

‘unspecified, unknown’

将色彩范围设置为未指定。

‘limited, tv, mpeg’

将色彩范围设置为有限（limited）。

‘full, pc, jpeg’

将色彩范围设置为全范围（full）。

20.21 settb, asettb

设置用于输出帧时间戳的时间基。这主要用于测试时间基配置。

它接受以下参数：

expr, tb

求值为输出时间基的表达式。

tb 的值是表示一个有理数的算术表达式。该表达式可以包含常量 "AVTB"（默认时间基）、"intb"（输入时间基）和 "sr"（采样率，仅音频）。默认值为 "intb"。

20.21.1 示例

将时间基设置为 1/25：
```
settb=expr=1/25
```
将时间基设置为 1/10：
```
settb=expr=0.1
```
将时间基设置为 1001/1000：
```
settb=1+0.001
```
将时间基设置为 2*intb：
```
settb=2*intb
```
设置默认的时间基值：
```
settb=AVTB
```

20.22 showcqt

将输入音频转换为以对数方式表示频谱的视频输出，采用 Brown-Puckette 常数 Q 变换算法直接计算频域系数（但该变换本身并非真正的常数 Q，实际上 Q 因子是可变/被限幅的），使用从 E0 到 D#10 的音阶。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。它必须是偶数。有关此选项语法，请参见 ffmpeg-utils 手册中的“视频尺寸”一节。默认值为 1920x1080。

fps, rate, r

设置输出帧率。默认值为 25。

bar_h

设置柱状图（bargraph）高度。它必须是偶数。默认值为 -1，表示自动计算柱状图高度。

axis_h

设置坐标轴高度。它必须是偶数。默认值为 -1，表示自动计算坐标轴高度。

sono_h

设置声谱图（sonogram）高度。它必须是偶数。默认值为 -1，表示自动计算声谱图高度。

fullhd

设置全高清分辨率。此选项已弃用，请改用 size, s。默认值为 1。

sono_v, volume

指定声谱图音量表达式。它可以包含变量：

bar_v

bar_v 求值后的表达式

frequency, freq, f

求值所在的频率

timeclamp, tc

timeclamp 选项的值

以及函数：

a_weighting(f)

等响度的 A 计权

b_weighting(f)

等响度的 B 计权

c_weighting(f)

等响度的 C 计权。

默认值为 16。

bar_v, volume2

指定柱状图音量表达式。它可以包含变量：

sono_v

sono_v 求值后的表达式

frequency, freq, f

求值所在的频率

timeclamp, tc

timeclamp 选项的值

以及函数：

a_weighting(f)

等响度的 A 计权

b_weighting(f)

等响度的 B 计权

c_weighting(f)

等响度的 C 计权。

默认值为 sono_v。

sono_g, gamma

指定声谱图伽马值。伽马值越低，频谱对比度越高；伽马值越高，频谱表现的范围越大。默认值为 3。可接受的范围是 [1, 7]。

bar_g, gamma2

指定柱状图伽马值。默认值为 1。可接受的范围是 [1, 7]。

bar_t

指定柱状图的透明度级别。值越低，柱状图越清晰。默认值为 1。可接受的范围是 [0, 1]。

timeclamp, tc

指定变换的 timeclamp。在低频时，时域精度和频域精度之间存在权衡。如果 timeclamp 较低，时域中的事件（例如快速的低音鼓）会被更准确地表现；否则频域中的事件（例如低音吉他）会被更准确地表现。可接受的范围是 [0.002, 1]。默认值为 0.17。

attack

设置起音时间（以秒为单位）。默认值为 0（禁用）。否则，它会通过在时域中应用非对称加窗来限制未来的采样，这在需要低延迟时很有用。可接受的范围是 [0, 1]。

basefreq

指定变换的基频。默认值为 20.01523126408007475，即比 E0 低 50 音分的频率。可接受的范围是 [10, 100000]。

endfreq

指定变换的终止频率。默认值为 20495.59681441799654，即比 D#10 高 50 音分的频率。可接受的范围是 [10, 100000]。

coeffclamp

此选项已弃用并被忽略。

tlength

指定时域中的变换长度。使用此选项可以控制每个频率采样点在时域和频域之间的精度权衡。它可以包含变量：

frequency, freq, f

求值所在的频率

timeclamp, tc

timeclamp 选项的值。

默认值为 384*tc/(384+tc*f)。

count

指定每个视频帧的变换计数。默认值为 6。可接受的范围是 [1, 30]。

fcount

指定每个像素的变换计数。默认值为 0，表示自动计算。可接受的范围是 [0, 10]。

fontfile

指定用于 freetype 绘制坐标轴的字体文件。若未指定，则使用内嵌字体。请注意，使用字体文件或内嵌字体进行绘制时，尚未实现自定义的 basefreq 和 endfreq，请改用 axisfile 选项。

font

指定 fontconfig 模式串。此选项的优先级低于 fontfile。模式串中的 : 可以替换为 |，以避免不必要的转义。

fontcolor

指定字体颜色表达式。这是应返回整数值 0xRRGGBB 的算术表达式。它可以包含变量：

frequency, freq, f

求值所在的频率

timeclamp, tc

timeclamp 选项的值

以及函数：

midi(f)

频率 f 对应的 midi 编号，一些 midi 编号示例: E0(16)、C1(24)、C2(36)、A4(69)

r(x), g(x), b(x)

强度 x 对应的红、绿、蓝值。

默认值为 st(0, (midi(f)-59.5)/12); st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); r(1-ld(1)) + b(ld(1))。

axisfile

指定用于绘制坐标轴的图像文件。此选项会覆盖 fontfile 和 fontcolor 选项。

axis, text

启用/禁用在坐标轴上绘制文本。如果设置为 0，则禁用坐标轴绘制，忽略 fontfile 和 axisfile 选项。默认值为 1。

csp

设置色彩空间。可接受的取值为：

‘unspecified’

未指定（默认）

‘bt709’

BT.709

‘fcc’

FCC

‘bt470bg’

BT.470BG 或 BT.601-6 625

‘smpte170m’

SMPTE-170M 或 BT.601-6 525

‘smpte240m’

SMPTE-240M

‘bt2020ncl’

具有非恒定亮度的 BT.2020

cscheme

设置声谱图配色方案。这是一个格式为 left_r|left_g|left_b|right_r|right_g|right_b 的浮点值列表。默认值为 1|0.5|0|0|0.5|1。

20.22.1 示例

播放音频的同时显示频谱：

ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'

与上面相同，但帧率为 30 fps：

ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'

以 1280x720 播放：

ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'

禁用声谱图显示：
```
sono_h=0
```

A1 及其泛音: A1、A2、（接近）E3、A3：

ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
                 asplit[a][out1]; [a] showcqt [out0]'

与上面相同，但在频域中有更高的精度：

ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t),
                 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'

自定义音量：
```
bar_v=10:sono_v=bar_v*a_weighting(f)
```
自定义伽马值，此时频谱与振幅呈线性关系。
```
bar_g=2:sono_g=2
```

自定义 tlength 方程：

tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))'

自定义 fontcolor 和 fontfile，C 音符着色为绿色，其他音符着色为蓝色：
```
fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
```
使用 fontconfig 自定义字体：
```
font='Courier New,Monospace,mono|bold'
```
使用图像文件自定义频率范围和坐标轴：
```
axisfile=myaxis.png:basefreq=40:endfreq=10000
```

20.23 showcwt

将输入音频转换为使用连续小波变换（Continuous Wavelet Transform）和 Morlet 小波表示频谱的视频输出。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。有关此选项语法，请参见 ffmpeg-utils 手册中的“视频尺寸”一节。默认值为 640x512。

rate, r

设置输出帧率。默认值为 25。

scale

设置使用的频率刻度。可用的取值为：

linear log bark mel erbs sqrt cbrt qdrt fm

默认值为 linear。

iscale

设置使用的强度刻度。可用的取值为：

linear log sqrt cbrt qdrt

默认值为 log。

min

设置输出中使用的最小频率。默认值为 20 Hz。

max

设置输出中使用的最大频率。默认值为 20000 Hz。实际的频率上限取决于输入音频的采样率，当此值设置为大于奈奎斯特频率的值时，将强制使用该上限。

imin

设置输出中使用的最小强度。

imax

设置输出中使用的最大强度。

logb

设置将计算出的幅值映射到像素值时用于亮度强度的对数底数。可接受的范围为 0 到 1。默认值为 0.0001。

deviation

设置频率偏差。低于 1 的值更偏向频率，高于 1 的值更偏向时间。可接受的范围为 0 到 10。默认值为 1。

pps

设置每秒每行输出的像素数。可接受的范围为 1 到 1024。默认值为 64。

mode

设置输出的视觉模式。可用的取值为：

magnitude

显示幅值。

phase

仅显示相位。

magphase

显示幅值与相位的组合。幅值映射为亮度，相位映射为颜色。

channel

按各声道的幅值显示独特的颜色。

stereo

按立体声差异显示独特的颜色。

默认值为 magnitude。

slide

设置输出的滑动方式。可用的取值为：

replace scroll frame direction

设置输出滑动方式的方向。可用的取值为：

从左到右的方向。

从右到左的方向。

从上到下的方向。

从下到上的方向。

bar

设置柱状图显示与显示尺寸的比例。默认值为 0。

rotation

设置颜色旋转，必须在 [-1.0, 1.0] 范围内。默认值为 0。

20.24 showfreqs

将输入音频转换为表示音频功率谱的视频输出，Y 轴为音频振幅，X 轴为频率。

该滤镜接受以下选项：

size, s

指定视频的尺寸。关于此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的 "Video size" 一节。默认值为 1024x512。

rate, r

设置视频帧率。默认值为 25。

mode

设置显示模式，决定每个频段如何呈现。

可接受的值有：

‘line’ ‘bar’ ‘dot’

默认值为 bar。

ascale

设置振幅刻度。

可接受的值有：

‘lin’

线性刻度。

‘sqrt’

平方根刻度。

‘cbrt’

立方根刻度。

‘log’

对数刻度。

默认值为 log。

fscale

设置频率刻度。

可接受的值有：

‘lin’

线性刻度。

‘log’

对数刻度。

‘rlog’

反向对数刻度。

默认值为 lin。

win_size

设置窗口大小，允许范围为 16 到 65536。

默认值为 2048

win_func

设置窗口函数。

可接受的值有：

‘rect’ ‘bartlett’ ‘hanning’ ‘hamming’ ‘blackman’ ‘welch’ ‘flattop’ ‘bharris’ ‘bnuttall’ ‘bhann’ ‘sine’ ‘nuttall’ ‘lanczos’ ‘gauss’ ‘tukey’ ‘dolph’ ‘cauchy’ ‘parzen’ ‘poisson’ ‘bohman’ ‘kaiser’

默认值为 hanning。

overlap

设置窗口重叠。范围为 [0, 1]。默认值为 1，表示会为所选窗口函数选取最佳重叠值。

averaging

设置时间平均。将其设为 0 会显示当前的最大峰值。默认值为 1，表示禁用时间平均。

colors

指定用空格或 ’|’ 分隔的颜色列表，用于绘制各声道的频率。无法识别或缺失的颜色将替换为白色。

cmode

设置声道显示模式。

可接受的值有：

‘combined’ ‘separate’

默认值为 combined。

minamp

设置 log 振幅缩放器所使用的最小振幅。

data

设置数据显示模式。

可接受的值有：

‘magnitude’ ‘phase’ ‘delay’

默认值为 magnitude。

channels

设置处理音频时使用的声道。默认处理所有声道。

20.25 showspatial

将立体声输入音频转换为视频输出，表示两个声道之间的空间关系。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。关于此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的 "Video size" 一节。默认值为 512x512。

win_size

设置窗口大小，允许范围为 1024 到 65536。默认大小为 4096。

win_func

设置窗口函数。

可接受的值有：

‘rect’ ‘bartlett’ ‘hann’ ‘hanning’ ‘hamming’ ‘blackman’ ‘welch’ ‘flattop’ ‘bharris’ ‘bnuttall’ ‘bhann’ ‘sine’ ‘nuttall’ ‘lanczos’ ‘gauss’ ‘tukey’ ‘dolph’ ‘cauchy’ ‘parzen’ ‘poisson’ ‘bohman’ ‘kaiser’

默认值为 hann。

rate, r

设置输出帧率。

20.26 showspectrum

将输入音频转换为视频输出，表示音频的频谱。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。关于此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的 "Video size" 一节。默认值为 640x512。

slide

指定频谱应如何沿窗口滑动。

可接受的值有：

‘replace’

样本到达右侧后从左侧重新开始

‘scroll’

样本从右向左滚动

‘fullframe’

仅当样本到达右侧时才会生成帧

‘rscroll’

样本从左向右滚动

‘lreplace’

样本到达左侧后从右侧重新开始

默认值为 replace。

mode

指定显示模式。

可接受的值有：

‘combined’

所有声道显示在同一行

‘separate’

所有声道分别显示在不同行

默认值为 ‘combined’。

color

指定显示的颜色模式。

可接受的值有：

‘channel’

各声道以不同颜色显示

‘intensity’

各声道使用相同的配色方案显示

‘rainbow’

各声道使用 rainbow 配色方案显示

‘moreland’

各声道使用 moreland 配色方案显示

‘nebulae’

各声道使用 nebulae 配色方案显示

‘fire’

各声道使用 fire 配色方案显示

‘fiery’

各声道使用 fiery 配色方案显示

‘fruit’

各声道使用 fruit 配色方案显示

‘cool’

各声道使用 cool 配色方案显示

‘magma’

各声道使用 magma 配色方案显示

‘green’

各声道使用 green 配色方案显示

‘viridis’

各声道使用 viridis 配色方案显示

‘plasma’

各声道使用 plasma 配色方案显示

‘cividis’

各声道使用 cividis 配色方案显示

‘terrain’

各声道使用 terrain 配色方案显示

默认值为 ‘channel’。

scale

指定用于计算强度颜色值的缩放方式。

可接受的值有：

‘lin’

线性

‘sqrt’

平方根（默认）

‘cbrt’

立方根

‘log’

对数

‘4thrt’

4 次方根

‘5thrt’

5 次方根

默认值为 ‘sqrt’。

fscale

指定频率刻度。

可接受的值有：

‘lin’

线性

‘log’

对数

默认值为 ‘lin’。

saturation

设置显示颜色的饱和度调整值。负值提供另一种配色方案。0 表示完全不饱和。饱和度必须在 [-10.0, 10.0] 范围内。默认值为 1。

win_func

设置窗口函数。

可接受的值有：

默认值为 hann。

orientation

设置时间轴与频率轴的方向。可以是 vertical 或 horizontal。默认值为 vertical。

overlap

设置重叠窗口的比例。默认值为 0。值为 1 时，重叠将设为当前所用窗口函数的推荐大小。

gain

设置用于计算强度颜色值的缩放增益。默认值为 1。

data

设置要显示的数据。可以是 magnitude（默认）、phase，或展开后的相位 uphase。

rotation

设置颜色旋转，必须在 [-1.0, 1.0] 范围内。默认值为 0。

start

设置开始显示频谱图的起始频率。默认值为 0。

stop

设置结束显示频谱图的终止频率。默认值为 0。

fps

设置帧率上限。默认值为 auto（无限制）。

legend

绘制时间轴、频率轴及图例。默认禁用。

drange

设置用于计算强度颜色值的动态范围。默认值为 120 dBFS。允许范围为 10 到 200。

limit

设置输入音频采样音量的上限，单位为 dBFS。默认值为 0 dBFS。允许范围为 -100 到 100。

opacity

设置在使用带 alpha 分量的 pixel format 输出时的不透明度强度。

用法与 showwaves 滤镜非常相似，请参阅该节中的示例。

20.26.1 示例

使用对数颜色缩放的大窗口：
```
showspectrum=s=1280x480:scale=log
```

使用 ffplay 按声道进行彩色滑动频谱显示的完整示例：

ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
             [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'

20.27 showspectrumpic

将输入音频转换为单个视频帧，表示音频的频谱。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。关于此选项的语法，请查看 (ffmpeg-utils)ffmpeg-utils 手册中的 "Video size" 一节。默认值为 4096x2048。

mode

指定显示模式。

可接受的值有：

‘combined’

所有声道显示在同一行

‘separate’

所有声道分别显示在不同行

默认值为 ‘combined’。

color

指定显示的颜色模式。

可接受的值有：

‘channel’

各声道以不同颜色显示

‘intensity’

各声道使用相同的配色方案显示

‘rainbow’

各声道使用 rainbow 配色方案显示

‘moreland’

各声道使用 moreland 配色方案显示

‘nebulae’

各声道使用 nebulae 配色方案显示

‘fire’

各声道使用 fire 配色方案显示

‘fiery’

各声道使用 fiery 配色方案显示

‘fruit’

各声道使用 fruit 配色方案显示

‘cool’

各声道使用 cool 配色方案显示

‘magma’

各声道使用 magma 配色方案显示

‘green’

各声道使用 green 配色方案显示

‘viridis’

各声道使用 viridis 配色方案显示

‘plasma’

各声道使用 plasma 配色方案显示

‘cividis’

各声道使用 cividis 配色方案显示

‘terrain’

各声道使用 terrain 配色方案显示

默认值为 ‘intensity’。

scale

指定用于计算强度颜色值的缩放方式。

可接受的值有：

‘lin’

线性

‘sqrt’

平方根（默认）

‘cbrt’

立方根

‘log’

对数

‘4thrt’

4 次方根

‘5thrt’

5 次方根

默认值为 ‘log’。

fscale

指定频率刻度。

可接受的值有：

‘lin’

线性

‘log’

对数

默认值为 ‘lin’。

saturation

设置显示颜色的饱和度调整值。负值提供另一种配色方案。0 表示完全不饱和。饱和度必须在 [-10.0, 10.0] 范围内。默认值为 1。

win_func

设置窗口函数。

可接受的值有：

默认值为 hann。

orientation

设置时间轴与频率轴的方向。可以是 vertical 或 horizontal。默认值为 vertical。

gain

设置用于计算强度颜色值的缩放增益。默认值为 1。

legend

绘制时间轴、频率轴及图例。默认启用。

rotation

设置颜色旋转，必须在 [-1.0, 1.0] 范围内。默认值为 0。

start

设置开始显示频谱图的起始频率。默认值为 0。

stop

设置结束显示频谱图的终止频率。默认值为 0。

drange

设置用于计算强度颜色值的动态范围。默认值为 120 dBFS。允许范围为 10 到 200。

limit

设置输入音频采样音量的上限，单位为 dBFS。默认值为 0 dBFS。允许范围为 -100 到 100。

opacity

设置在使用带 alpha 分量的 pixel format 输出时的不透明度强度。

20.27.1 示例

使用 ffmpeg 将整段音频轨道提取为 1024x1024 图片形式的音频频谱图：
```
ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
```

20.28 showvolume

将输入音频的音量转换为视频输出。

该滤镜接受以下选项：

rate, r

设置视频帧率。

设置边框宽度，允许范围为 [0, 5]。默认值为 1。

设置声道宽度，允许范围为 [80, 8192]。默认值为 400。

设置声道高度，允许范围为 [1, 900]。默认值为 20。

设置淡入淡出，允许范围为 [0, 1]。默认值为 0.95。

设置音量颜色表达式。

该表达式可以使用以下变量：

VOLUME

声道当前的最大音量（dB）。

PEAK

当前峰值。

CHANNEL

当前声道编号，从 0 开始。

设置后将显示声道名称。默认启用。

设置后将显示音量值。默认启用。

设置方向，可以是水平 h 或垂直 v，默认值为 h。

设置步长，允许范围为 [0, 5]。默认值为 0，表示禁用步长。

设置背景不透明度，允许范围为 [0, 1]。默认值为 0。

设置测量模式，可以是峰值 p 或 rms r，默认值为 p。

设置显示刻度，可以是线性 lin 或对数 log，默认值为 lin。

以秒为单位。若设为大于 0，则显示前几秒内最大电平的线条。默认禁用: 0.

dmc

最大电平线条的颜色。当 dm 选项设为大于 0. 时使用此选项。默认值为: orange

20.29 showwaves

将输入音频转换为视频输出，表示采样波形。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。关于此选项的语法，请参阅 (ffmpeg-utils) ffmpeg-utils 手册中的「Video size」小节。默认值为 600x240。

mode

设置显示模式。

可用值如下：

‘point’

为每个采样点绘制一个点。

‘line’

为每个采样点绘制一条竖线。

‘p2p’

为每个采样点绘制一个点，并在点之间连线。

‘cline’

为每个采样点绘制一条居中的竖线。

默认值为 point。

设置同一列中打印的采样点数量。值越大，帧率越低。必须为正整数。仅当未显式指定 rate 的值时才能设置此选项。

rate, r

设置（近似的）输出帧率。这是通过设置选项 n 来实现的。默认值为 "25"。

split_channels

设置各声道是分开绘制还是重叠绘制。默认值为 0。

colors

设置用 ’|’ 分隔的颜色列表，用于绘制各个声道。

scale

设置振幅刻度。

可用值如下：

‘lin’

线性。

‘log’

对数。

‘sqrt’

平方根。

‘cbrt’

立方根。

默认值为线性。

draw

设置绘制模式。这在 n 较大时最为有用。

可用值如下：

‘scale’

对每个绘制的采样点缩放像素值。

‘full’

直接绘制每个采样点。

默认值为 scale。

20.29.1 示例

同时输出输入文件的音频及其对应的视频表现形式：
```
amovie=a.mp3,asplit[out0],showwaves[out1]
```
生成一个合成信号，并用 showwaves 显示，同时将帧率强制设为每秒 30 帧：
```
aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
```

20.30 showwavespic

将输入音频转换为单帧视频，表示采样波形。

该滤镜接受以下选项：

size, s

指定输出的视频尺寸。关于此选项的语法，请参阅 (ffmpeg-utils) ffmpeg-utils 手册中的「Video size」小节。默认值为 600x240。

split_channels

设置各声道是分开绘制还是重叠绘制。默认值为 0。

colors

设置用 ’|’ 分隔的颜色列表，用于绘制各个声道。

scale

设置振幅刻度。

可用值如下：

‘lin’

线性。

‘log’

对数。

‘sqrt’

平方根。

‘cbrt’

立方根。

默认值为线性。

draw

设置绘制模式。

可用值如下：

‘scale’

对每个绘制的采样点缩放像素值。

‘full’

直接绘制每个采样点。

默认值为 scale。

filter

设置滤镜模式。

可用值如下：

‘average’

对每个绘制的采样点使用采样值的平均值。

‘peak’

对每个绘制的采样点使用采样值的峰值。

默认值为 average。

20.30.1 示例

使用 ffmpeg 将整条音轨的波形按声道分离，提取为一张 1024x800 的图片：
```
ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
```

20.31 sidedata, asidedata

删除帧的附加数据，或根据附加数据选择帧。

此滤镜接受以下选项：

mode

设置该滤镜的运行模式。

可以是以下之一：

‘select’

选择所有带有 type 附加数据的帧。

‘delete’

删除 type 的附加数据。如果未设置 type，则删除帧中的所有附加数据。

type

设置所有模式下使用的附加数据类型。select 模式下必须设置此项。

可接受的值有：

‘PANSCAN’ ‘A53_CC’ ‘STEREO3D’ ‘MATRIXENCODING’ ‘DOWNMIX_INFO’ ‘REPLAYGAIN’ ‘DISPLAYMATRIX’ ‘AFD’ ‘MOTION_VECTORS’ ‘SKIP_SAMPLES’ ‘AUDIO_SERVICE_TYPE’ ‘MASTERING_DISPLAY_METADATA’ ‘GOP_TIMECODE’ ‘SPHERICAL’ ‘CONTENT_LIGHT_LEVEL’ ‘ICC_PROFILE’ ‘S12M_TIMECODE’ ‘DYNAMIC_HDR_PLUS’ ‘REGIONS_OF_INTEREST’ ‘VIDEO_ENC_PARAMS’ ‘SEI_UNREGISTERED’ ‘FILM_GRAIN_PARAMS’ ‘DETECTION_BOUNDING_BOXES’ ‘DETECTION_BBOXES’ ‘DOVI_RPU_BUFFER’ ‘DOVI_METADATA’ ‘DYNAMIC_HDR_VIVID’ ‘AMBIENT_VIEWING_ENVIRONMENT’ ‘VIDEO_HINT’

20.32 spectrumsynth

从 2 个输入视频频谱合成音频，第一个输入流表示随时间变化的幅度，第二个表示随时间变化的相位。该滤镜会将视频中显示的频域变换回音频输出所呈现的时域。

该滤镜主要用于将处理过的 showspectrum 滤镜输出还原为音频，但也可以从其他频谱图合成声音。不过在这种情况下，如果没有相位数据，效果会比较差，因为此时需要重新生成相位数据，通常只是用随机噪声重新生成的。为获得最佳效果，请使用纯灰度输出（showspectrum 滤镜中的 channel 颜色模式），幅度视频使用 log 刻度，相位视频使用 lin 刻度。要生成相位，请对第 2 个视频使用 data 选项。输入视频通常应使用 fullframe 滑动模式，因为这样可以节省解码视频所需的资源。

该滤镜接受以下选项：

sample_rate

指定输出音频的采样率，与生成频谱所用音频的采样率可以不同。

channels

设置输入视频频谱中表示的声道数。

scale

设置生成幅度输入频谱时所使用的刻度，可以是 lin 或 log。默认值为 log。

slide

设置生成输入频谱时所使用的滑动方式，可以是 replace、scroll、fullframe 或 rscroll。默认值为 fullframe。

win_func

设置用于重新合成的窗函数。

overlap

设置窗口重叠度，范围为 [0, 1]。默认值为 1，表示会为所选窗函数选取最佳重叠度。

orientation

设置输入视频的方向，可以是 vertical 或 horizontal。默认值为 vertical。

20.32.1 示例

先从音频生成幅度视频和相位视频（假设音频为采样率 44100 的立体声），再用 spectrumsynth 将视频重新合成为音频：

ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac

20.33 split, asplit

将输入拆分为多个相同的输出。

asplit 适用于音频输入，split 适用于视频。

该滤镜接受一个参数，用于指定输出的数量。如果未指定，默认为 2。

20.33.1 示例

从同一个输入创建两个独立的输出：
```
[in] split [out0][out1]
```
要创建 3 个或更多输出，需要像下面这样指定输出的数量：
```
[in] asplit=3 [out0][out1][out2]
```

从同一个输入创建两个独立的输出，一个裁剪，一个填充：

[in] split [splitout1][splitout2];
[splitout1] crop=100:100:0:0    [cropout];
[splitout2] pad=200:200:100:100 [padout];

使用 ffmpeg 创建输入音频的 5 份副本：

ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT

20.34 zmq, azmq

接收通过 libzmq 客户端发送的命令，并将其转发给 filtergraph 中的滤镜。

zmq 和 azmq 是直通型滤镜。zmq 必须插入两个视频滤镜之间，azmq 必须插入两个音频滤镜之间。两者都能够向任意类型的滤镜发送消息。

要启用这些滤镜，需要安装 libzmq 库及其头文件，并在配置 FFmpeg 时加上 --enable-libzmq。

关于 libzmq 的更多信息，请参阅：http://www.zeromq.org/

zmq 和 azmq 滤镜作为 libzmq 服务器工作，通过 bind_address 选项（缩写为 "b"）定义的网络接口接收发送来的消息。该选项的默认值为 tcp://localhost:5555。可以根据需要更改这个值，但不要忘记转义其中的 ’:’ 符号（参见 filtergraph 转义）。

收到的消息必须采用以下格式：

TARGET COMMAND [ARG]

TARGET 指定命令的目标，通常是滤镜类的名称或特定滤镜实例的名称。默认的滤镜实例名称使用 ‘Parsed__’ 这种模式，但可以通过 ‘filter_name@id’ 语法覆盖它（参见 Filtergraph syntax）。

COMMAND 指定目标滤镜的命令名称。

ARG 是可选的，用于指定给定 COMMAND 的可选参数列表。

收到消息后，会对其进行处理，并将相应的命令注入 filtergraph。根据处理结果，滤镜会以下列格式向客户端发送回复：

ERROR_CODE ERROR_REASON
MESSAGE

MESSAGE 是可选的。

20.34.1 示例

关于可用于向这些滤镜发送命令的 zmq 客户端示例，请参阅 tools/zmqsend。

考虑由 ffplay 生成的以下 filtergraph。在这个示例中，最后一个 overlay 滤镜带有实例名称，其他滤镜都使用默认的实例名称。

ffplay -dumpgraph 1 -f lavfi "
color=s=100x100:c=red  [l];
color=s=100x100:c=blue [r];
nullsrc=s=200x100, zmq [bg];
[bg][l]   overlay     [bg+l];
[bg+l][r] overlay@my=x=100 "

要更改视频左侧的颜色，可以使用以下命令：

echo Parsed_color_0 c yellow | tools/zmqsend

要更改右侧：

echo Parsed_color_1 c pink | tools/zmqsend

要更改右侧的位置：

echo overlay@my x 150 | tools/zmqsend

21 多媒体源

下面介绍当前可用的多媒体源。

21.1 amovie

与 movie 源相同，只是默认选择音频流。

21.2 avsynctest

生成一个音视频同步测试。

生成的流会定期显示闪烁的视频帧，并在音频中发出蜂鸣声，便于检查音画同步问题。

它接受以下选项：

size, s

设置输出视频尺寸。默认值为 hd720。

framerate, fr

设置输出视频帧率。默认值为 30。

samplerate, sr

设置输出音频采样率。默认值为 44100。

amplitude, a

设置输出音频蜂鸣声的振幅。默认值为 0.7。

period, p

以秒为单位设置输出音频蜂鸣声的周期。默认值为 3。

delay, dl

以帧数设置输出视频闪烁的延迟。默认值为 0。

cycle, c

启用视频延迟的循环，默认情况下禁用。

duration, d

设置流输出的时长。默认情况下时长不受限制。

fg, bg, ag

设置前景色/背景色/附加色。

21.2.1 命令

该源将上述部分选项作为命令支持。

21.3 movie

从 movie 容器中读取音频和/或视频流。

它接受以下参数：

filename

要读取的资源名称（不一定是文件，也可以是设备，或通过某种协议访问的流）。

format_name, f

指定读取 movie 时假定使用的格式，可以是 container 的名称或输入设备。如果未指定，格式会根据 movie_name 推测，或通过探测确定。

seek_point, sp

以秒为单位指定定位点。帧将从该定位点开始输出。该参数使用 av_strtod 求值，因此数值可以带有 IS 后缀。默认值为 "0"。

streams, s

指定要读取的流，可以用 "+" 分隔指定多个流。这样源就会按相同顺序产生相应数量的输出。其语法在 (ffmpeg) ffmpeg 手册中的「Stream specifiers」小节中说明。"dv" 和 "da" 这两个特殊名称分别指定默认的（最合适的）视频流和音频流。默认值为 "dv"；如果该滤镜以 "amovie" 的名义调用，则默认值为 "da"。

stream_index, si

指定要读取的视频流的索引。如果值为 -1，将自动选择最合适的视频流。默认值为 "-1"。已弃用。如果该滤镜以 "amovie" 的名义调用，则会选择音频而不是视频。

loop

指定连续读取该流的次数。如果值为 0，该流将无限循环。默认值为 "1"。

请注意，movie 循环播放时源时间戳不会改变，因此会产生非单调递增的时间戳。

discontinuity

指定帧间时间差的阈值，超过该阈值即视为时间戳不连续，随后会通过调整后续时间戳来消除该不连续点。

dec_threads

指定用于解码的线程数

format_opts

为打开的文件指定格式选项。格式选项可以指定为用 ’:’ 分隔的 key=value 对列表。以下示例展示了如何添加 protocol_whitelist 和 protocol_blacklist 选项：

ffplay -f lavfi
"movie=filename='1.sdp':format_opts='protocol_whitelist=file,rtp,udp\:protocol_blacklist=http'"

这样就可以像下图所示的那样，将第二个视频叠加在 filtergraph 主输入的上方：

input -----------> deltapts0 --> overlay --> output
                                    ^
                                    |
movie --> scale--> deltapts1 -------+

21.3.1 示例

从 AVI 文件 in.avi 的开头跳过 3.2 秒，并将其叠加在标记为 "in" 的输入之上：

movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
[in] setpts=PTS-STARTPTS [main];
[main][over] overlay=16:16 [out]

从 video4linux2 设备读取，并将其叠加在标记为 "in" 的输入之上：

movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
[in] setpts=PTS-STARTPTS [main];
[main][over] overlay=16:16 [out]

从 dvd.vob 读取第一个视频流以及 id 为 0x81 的音频流；视频连接到名为 "video" 的 pad，音频连接到名为 "audio" 的 pad：
```
movie=dvd.vob:s=v:0+#0x81 [video] [audio]
```

21.3.2 命令

movie 和 amovie 都支持以下命令：

seek

使用 "av_seek_frame" 执行定位。语法为：seek stream_index|timestamp|flags

stream_index：如果 stream_index 为 -1，将选择一个默认流，并且 timestamp 会自动从 AV_TIME_BASE 单位转换为该流特有的 time_base。
timestamp：以 AVStream.time_base 为单位的时间戳；如果未指定流，则以 AV_TIME_BASE 为单位。
flags：用于选择方向和定位模式的标志。

get_duration

以 AV_TIME_BASE 为单位获取 movie 的时长。

22 参见

ffmpeg, ffplay, ffprobe, libavfilter

23 作者

FFmpeg 的开发者们。

关于作者身份的详细信息，请参见项目的 Git 历史（https://git.ffmpeg.org/ffmpeg），例如在 FFmpeg 源代码目录中输入 git log 命令，或浏览在线仓库 https://git.ffmpeg.org/ffmpeg。

各组件的维护者列在源代码树中的 MAINTAINERS 文件里。

主机托管由 telepoint.bg 提供