doc: Use the succinct syntax for the channelmap example
[libav.git] / doc / filters.texi
CommitLineData
1ebe5c4c
SS
1@chapter Filtergraph description
2@c man begin FILTERGRAPH DESCRIPTION
3
4A filtergraph is a directed graph of connected filters. It can contain
5cycles, and there can be multiple links between a pair of
6filters. Each link has one input pad on one side connecting it to one
7filter from which it takes its input, and one output pad on the other
d4a8a86c 8side connecting it to one filter accepting its output.
1ebe5c4c
SS
9
10Each filter in a filtergraph is an instance of a filter class
11registered in the application, which defines the features and the
12number of input and output pads of the filter.
13
d4a8a86c 14A filter with no input pads is called a "source", and a filter with no
1ebe5c4c
SS
15output pads is called a "sink".
16
3b266da3 17@anchor{Filtergraph syntax}
1ebe5c4c
SS
18@section Filtergraph syntax
19
d4a8a86c 20A filtergraph has a textual representation, which is
7ce118ba
AK
21recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
22options in @command{avconv} and @option{-vf} in @command{avplay}, and by the
d4a8a86c 23@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} functions defined in
38f0c078 24@file{libavfilter/avfilter.h}.
1ebe5c4c
SS
25
26A filterchain consists of a sequence of connected filters, each one
27connected to the previous one in the sequence. A filterchain is
28represented by a list of ","-separated filter descriptions.
29
30A filtergraph consists of a sequence of filterchains. A sequence of
31filterchains is represented by a list of ";"-separated filterchain
32descriptions.
33
34A filter is represented by a string of the form:
35[@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
36
37@var{filter_name} is the name of the filter class of which the
38described filter is an instance of, and has to be the name of one of
39the filter classes registered in the program.
40The name of the filter class is optionally followed by a string
41"=@var{arguments}".
42
43@var{arguments} is a string which contains the parameters used to
d4a8a86c 44initialize the filter instance. It may have one of two forms:
b439c992
AK
45@itemize
46
47@item
48A ':'-separated list of @var{key=value} pairs.
49
50@item
51A ':'-separated list of @var{value}. In this case, the keys are assumed to be
52the option names in the order they are declared. E.g. the @code{fade} filter
53declares three options in this order -- @option{type}, @option{start_frame} and
54@option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
55@var{in} is assigned to the option @option{type}, @var{0} to
56@option{start_frame} and @var{30} to @option{nb_frames}.
57
58@end itemize
59
60If the option value itself is a list of items (e.g. the @code{format} filter
61takes a list of pixel formats), the items in the list are usually separated by
62'|'.
1ebe5c4c
SS
63
64The list of arguments can be quoted using the character "'" as initial
65and ending mark, and the character '\' for escaping the characters
66within the quoted text; otherwise the argument string is considered
67terminated when the next special character (belonging to the set
68"[]=;,") is encountered.
69
70The name and arguments of the filter are optionally preceded and
71followed by a list of link labels.
72A link label allows to name a link and associate it to a filter output
73or input pad. The preceding labels @var{in_link_1}
74... @var{in_link_N}, are associated to the filter input pads,
75the following labels @var{out_link_1} ... @var{out_link_M}, are
76associated to the output pads.
77
78When two link labels with the same name are found in the
79filtergraph, a link between the corresponding input and output pad is
80created.
81
82If an output pad is not labelled, it is linked by default to the first
83unlabelled input pad of the next filter in the filterchain.
d4a8a86c 84For example in the filterchain
1ebe5c4c
SS
85@example
86nullsrc, split[L1], [L2]overlay, nullsink
87@end example
88the split filter instance has two output pads, and the overlay filter
89instance two input pads. The first output pad of split is labelled
90"L1", the first input pad of overlay is labelled "L2", and the second
91output pad of split is linked to the second input pad of overlay,
92which are both unlabelled.
93
94In a complete filterchain all the unlabelled filter input and output
95pads must be connected. A filtergraph is considered valid if all the
96filter input and output pads of all the filterchains are connected.
97
dd249245 98Libavfilter will automatically insert @ref{scale} filters where format
12e7e1d0
AK
99conversion is required. It is possible to specify swscale flags
100for those automatically inserted scalers by prepending
101@code{sws_flags=@var{flags};}
102to the filtergraph description.
103
d4a8a86c 104Here is a BNF description of the filtergraph syntax:
1ebe5c4c
SS
105@example
106@var{NAME} ::= sequence of alphanumeric characters and '_'
107@var{LINKLABEL} ::= "[" @var{NAME} "]"
108@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
d4a8a86c 109@var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
b5ad422b 110@var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
1ebe5c4c 111@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
12e7e1d0 112@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
1ebe5c4c
SS
113@end example
114
115@c man end FILTERGRAPH DESCRIPTION
116
f59e9eaf
SS
117@chapter Audio Filters
118@c man begin AUDIO FILTERS
119
f8a45fa1 120When you configure your Libav build, you can disable any of the
f59e9eaf
SS
121existing filters using --disable-filters.
122The configure output will show the audio filters included in your
123build.
124
125Below is a description of the currently available audio filters.
126
fb604ae8
AK
127@section aformat
128
129Convert the input audio to one of the specified formats. The framework will
130negotiate the most appropriate format to minimize conversions.
131
d4a8a86c 132It accepts the following parameters:
fb604ae8
AK
133@table @option
134
135@item sample_fmts
0af7fe1f 136A '|'-separated list of requested sample formats.
fb604ae8
AK
137
138@item sample_rates
0af7fe1f 139A '|'-separated list of requested sample rates.
fb604ae8
AK
140
141@item channel_layouts
0af7fe1f 142A '|'-separated list of requested channel layouts.
fb604ae8
AK
143
144@end table
145
146If a parameter is omitted, all values are allowed.
147
d4a8a86c 148Force the output to either unsigned 8-bit or signed 16-bit stereo
fb604ae8 149@example
0af7fe1f 150aformat=sample_fmts=u8|s16:channel_layouts=stereo
fb604ae8
AK
151@end example
152
c7448c18
JR
153@section amix
154
155Mixes multiple audio inputs into a single output.
156
157For example
158@example
159avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
160@end example
161will mix 3 input audio streams to a single output with the same duration as the
162first input and a dropout transition time of 3 seconds.
163
d4a8a86c 164It accepts the following parameters:
c7448c18
JR
165@table @option
166
167@item inputs
d4a8a86c 168The number of inputs. If unspecified, it defaults to 2.
c7448c18
JR
169
170@item duration
171How to determine the end-of-stream.
172@table @option
173
174@item longest
d4a8a86c 175The duration of the longest input. (default)
c7448c18
JR
176
177@item shortest
d4a8a86c 178The duration of the shortest input.
c7448c18
JR
179
180@item first
d4a8a86c 181The duration of the first input.
c7448c18
JR
182
183@end table
184
185@item dropout_transition
d4a8a86c 186The transition time, in seconds, for volume renormalization when an input
c7448c18
JR
187stream ends. The default value is 2 seconds.
188
189@end table
190
99046339
HM
191@section anull
192
193Pass the audio source unchanged to the output.
194
b4729382
AK
195@section asetpts
196
197Change the PTS (presentation timestamp) of the input audio frames.
198
d4a8a86c 199It accepts the following parameters:
b4729382
AK
200
201@table @option
202
203@item expr
204The expression which is evaluated for each frame to construct its timestamp.
205
206@end table
207
208The expression is evaluated through the eval API and can contain the following
209constants:
210
211@table @option
212@item PTS
213the presentation timestamp in input
214
d4a8a86c
KBA
215@item E, PI, PHI
216These are approximated values for the mathematical constants e
217(Euler's number), pi (Greek pi), and phi (the golden ratio).
b4729382
AK
218
219@item N
d4a8a86c 220The number of audio samples passed through the filter so far, starting at 0.
b4729382
AK
221
222@item S
d4a8a86c 223The number of audio samples in the current frame.
b4729382
AK
224
225@item SR
d4a8a86c 226The audio sample rate.
b4729382
AK
227
228@item STARTPTS
d4a8a86c 229The PTS of the first frame.
b4729382
AK
230
231@item PREV_INPTS
d4a8a86c 232The previous input PTS.
b4729382
AK
233
234@item PREV_OUTPTS
d4a8a86c 235The previous output PTS.
b4729382
AK
236
237@item RTCTIME
d4a8a86c 238The wallclock (RTC) time in microseconds.
b4729382
AK
239
240@item RTCSTART
d4a8a86c 241The wallclock (RTC) time at the start of the movie in microseconds.
b4729382
AK
242
243@end table
244
d4a8a86c 245Some examples:
b4729382
AK
246
247@example
d4a8a86c 248# Start counting PTS from zero
b4729382
AK
249asetpts=expr=PTS-STARTPTS
250
d4a8a86c 251# Generate timestamps by counting samples
b4729382
AK
252asetpts=expr=N/SR/TB
253
d4a8a86c 254# Generate timestamps from a "live source" and rebase onto the current timebase
b4729382
AK
255asetpts='(RTCTIME - RTCSTART) / (TB * 1000000)"
256@end example
257
ad8159e0
NG
258@section asettb
259
260Set the timebase to use for the output frames timestamps.
261It is mainly useful for testing timebase configuration.
262
263This filter accepts the following parameters:
264
265@table @option
266
267@item expr
268The expression which is evaluated into the output timebase.
269
270@end table
271
272The expression can contain the constants @var{PI}, @var{E}, @var{PHI}, @var{AVTB} (the
273default timebase), @var{intb} (the input timebase), and @var{sr} (the sample rate,
274audio only).
275
276The default value for the input is @var{intb}.
277
278Some examples:
279
280@example
281# Set the timebase to 1/25:
282settb=1/25
283
284# Set the timebase to 1/10:
285settb=0.1
286
287# Set the timebase to 1001/1000:
288settb=1+0.001
289
290# Set the timebase to 2*intb:
291settb=2*intb
292
293# Set the default timebase value:
294settb=AVTB
295
296# Set the timebase to twice the sample rate:
297asettb=sr*2
298@end example
b4729382 299
20dd41af
AK
300@section ashowinfo
301
302Show a line containing various information for each input audio frame.
303The input audio is not modified.
304
305The shown line contains a sequence of key/value pairs of the form
306@var{key}:@var{value}.
307
d4a8a86c 308It accepts the following parameters:
20dd41af
AK
309
310@table @option
311@item n
d4a8a86c 312The (sequential) number of the input frame, starting from 0.
20dd41af
AK
313
314@item pts
d4a8a86c 315The presentation timestamp of the input frame, in time base units; the time base
20dd41af
AK
316depends on the filter input pad, and is usually 1/@var{sample_rate}.
317
318@item pts_time
d4a8a86c 319The presentation timestamp of the input frame in seconds.
20dd41af
AK
320
321@item fmt
d4a8a86c 322The sample format.
20dd41af
AK
323
324@item chlayout
d4a8a86c 325The channel layout.
20dd41af
AK
326
327@item rate
d4a8a86c 328The sample rate for the audio frame.
20dd41af
AK
329
330@item nb_samples
d4a8a86c 331The number of samples (per channel) in the frame.
20dd41af
AK
332
333@item checksum
d4a8a86c
KBA
334The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
335audio, the data is treated as if all the planes were concatenated.
20dd41af
AK
336
337@item plane_checksums
338A list of Adler-32 checksums for each data plane.
339@end table
340
afeb3590
JR
341@section asplit
342
343Split input audio into several identical outputs.
344
d4a8a86c 345It accepts a single parameter, which specifies the number of outputs. If
afeb3590
JR
346unspecified, it defaults to 2.
347
d4a8a86c 348For example,
afeb3590
JR
349@example
350avconv -i INPUT -filter_complex asplit=5 OUTPUT
351@end example
352will create 5 copies of the input audio.
353
9f26421b
AK
354@section asyncts
355Synchronize audio data with timestamps by squeezing/stretching it and/or
356dropping samples/adding silence when needed.
357
d4a8a86c 358It accepts the following parameters:
9f26421b
AK
359@table @option
360
361@item compensate
04438790
AU
362Enable stretching/squeezing the data to make it match the timestamps. Disabled
363by default. When disabled, time gaps are covered with silence.
9f26421b
AK
364
365@item min_delta
d4a8a86c
KBA
366The minimum difference between timestamps and audio data (in seconds) to trigger
367adding/dropping samples. The default value is 0.1. If you get an imperfect
368sync with this filter, try setting this parameter to 0.
9f26421b
AK
369
370@item max_comp
d4a8a86c
KBA
371The maximum compensation in samples per second. Only relevant with compensate=1.
372The default value is 500.
9f26421b 373
70d71b58 374@item first_pts
d4a8a86c
KBA
375Assume that the first PTS should be this value. The time base is 1 / sample
376rate. This allows for padding/trimming at the start of the stream. By default,
377no assumption is made about the first frame's expected PTS, so no padding or
70d71b58 378trimming is done. For example, this could be set to 0 to pad the beginning with
b35e5d98 379silence if an audio stream starts after the video stream or to trim any samples
d4a8a86c 380with a negative PTS due to encoder delay.
70d71b58 381
9f26421b
AK
382@end table
383
a1e05b04
AK
384@section atrim
385Trim the input so that the output contains one continuous subpart of the input.
386
d4a8a86c 387It accepts the following parameters:
a1e05b04
AK
388@table @option
389@item start
d4a8a86c
KBA
390Timestamp (in seconds) of the start of the section to keep. I.e. the audio
391sample with the timestamp @var{start} will be the first sample in the output.
a1e05b04
AK
392
393@item end
394Timestamp (in seconds) of the first audio sample that will be dropped. I.e. the
395audio sample immediately preceding the one with the timestamp @var{end} will be
396the last sample in the output.
397
398@item start_pts
399Same as @var{start}, except this option sets the start timestamp in samples
400instead of seconds.
401
402@item end_pts
403Same as @var{end}, except this option sets the end timestamp in samples instead
404of seconds.
405
406@item duration
d4a8a86c 407The maximum duration of the output in seconds.
a1e05b04
AK
408
409@item start_sample
d4a8a86c 410The number of the first sample that should be output.
a1e05b04
AK
411
412@item end_sample
d4a8a86c 413The number of the first sample that should be dropped.
a1e05b04
AK
414@end table
415
416Note that the first two sets of the start/end options and the @option{duration}
417option look at the frame timestamp, while the _sample options simply count the
418samples that pass through the filter. So start/end_pts and start/end_sample will
419give different results when the timestamps are wrong, inexact or do not start at
420zero. Also note that this filter does not modify the timestamps. If you wish
d4a8a86c 421to have the output timestamps start at zero, insert the asetpts filter after the
a1e05b04
AK
422atrim filter.
423
424If multiple start or end options are set, this filter tries to be greedy and
425keep all samples that match at least one of the specified constraints. To keep
426only the part that matches all the constraints at once, chain multiple atrim
427filters.
428
429The defaults are such that all the input is kept. So it is possible to set e.g.
430just the end values to keep everything before the specified time.
431
432Examples:
433@itemize
434@item
d4a8a86c 435Drop everything except the second minute of input:
a1e05b04
AK
436@example
437avconv -i INPUT -af atrim=60:120
438@end example
439
440@item
d4a8a86c 441Keep only the first 1000 samples:
a1e05b04
AK
442@example
443avconv -i INPUT -af atrim=end_sample=1000
444@end example
445
446@end itemize
447
1c0210c7
AG
448@section bs2b
449Bauer stereo to binaural transformation, which improves headphone listening of
450stereo audio records.
451
452It accepts the following parameters:
453@table @option
454
455@item profile
456Pre-defined crossfeed level.
457@table @option
458
459@item default
460Default level (fcut=700, feed=50).
461
462@item cmoy
463Chu Moy circuit (fcut=700, feed=60).
464
465@item jmeier
466Jan Meier circuit (fcut=650, feed=95).
467
468@end table
469
470@item fcut
471Cut frequency (in Hz).
472
473@item feed
474Feed level (in Hz).
475
476@end table
477
d6251368 478@section channelsplit
d4a8a86c 479Split each channel from an input audio stream into a separate output stream.
d6251368 480
d4a8a86c 481It accepts the following parameters:
d6251368
AK
482@table @option
483@item channel_layout
d4a8a86c 484The channel layout of the input stream. The default is "stereo".
d6251368
AK
485@end table
486
d4a8a86c 487For example, assuming a stereo input MP3 file,
d6251368
AK
488@example
489avconv -i in.mp3 -filter_complex channelsplit out.mkv
490@end example
491will create an output Matroska file with two audio streams, one containing only
492the left channel and the other the right channel.
493
d4a8a86c 494Split a 5.1 WAV file into per-channel files:
d6251368
AK
495@example
496avconv -i in.wav -filter_complex
497'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
498-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
499front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
500side_right.wav
501@end example
502
41e637e4
AC
503@section channelmap
504Remap input channels to new locations.
505
d4a8a86c 506It accepts the following parameters:
41e637e4
AC
507@table @option
508@item channel_layout
d4a8a86c 509The channel layout of the output stream.
41e637e4
AC
510
511@item map
ba8efac9 512Map channels from input to output. The argument is a '|'-separated list of
41e637e4
AC
513mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
514@var{in_channel} form. @var{in_channel} can be either the name of the input
515channel (e.g. FL for front left) or its index in the input channel layout.
516@var{out_channel} is the name of the output channel or its index in the output
517channel layout. If @var{out_channel} is not given then it is implicitly an
518index, starting with zero and increasing by one for each mapping.
519@end table
520
521If no mapping is present, the filter will implicitly map input channels to
d4a8a86c 522output channels, preserving indices.
41e637e4 523
d4a8a86c 524For example, assuming a 5.1+downmix input MOV file,
41e637e4 525@example
ba8efac9 526avconv -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
41e637e4
AC
527@end example
528will create an output WAV file tagged as stereo from the downmix channels of
529the input.
530
531To fix a 5.1 WAV improperly encoded in AAC's native channel order
532@example
8fcd121b 533avconv -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
41e637e4
AC
534@end example
535
738f8358 536@section compand
d4a8a86c 537Compress or expand the audio's dynamic range.
738f8358 538
d4a8a86c 539It accepts the following parameters:
738f8358
AK
540
541@table @option
542
543@item attacks
544@item decays
d4a8a86c 545A list of times in seconds for each channel over which the instantaneous level
738f8358
AK
546of the input signal is averaged to determine its volume. @var{attacks} refers to
547increase of volume and @var{decays} refers to decrease of volume. For most
548situations, the attack time (response to the audio getting louder) should be
d4a8a86c 549shorter than the decay time, because the human ear is more sensitive to sudden
738f8358
AK
550loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
551a typical value for decay is 0.8 seconds.
552
553@item points
d4a8a86c 554A list of points for the transfer function, specified in dB relative to the
738f8358
AK
555maximum possible signal amplitude. Each key points list must be defined using
556the following syntax: @code{x0/y0|x1/y1|x2/y2|....}
557
558The input values must be in strictly increasing order but the transfer function
559does not have to be monotonically rising. The point @code{0/0} is assumed but
560may be overridden (by @code{0/out-dBn}). Typical values for the transfer
561function are @code{-70/-70|-60/-20}.
562
563@item soft-knee
d4a8a86c 564Set the curve radius in dB for all joints. It defaults to 0.01.
738f8358
AK
565
566@item gain
d4a8a86c
KBA
567Set the additional gain in dB to be applied at all points on the transfer
568function. This allows for easy adjustment of the overall gain.
569It defaults to 0.
738f8358
AK
570
571@item volume
d4a8a86c
KBA
572Set an initial volume, in dB, to be assumed for each channel when filtering
573starts. This permits the user to supply a nominal level initially, so that, for
738f8358
AK
574example, a very large gain is not applied to initial signal levels before the
575companding has begun to operate. A typical value for audio which is initially
d4a8a86c 576quiet is -90 dB. It defaults to 0.
738f8358
AK
577
578@item delay
d4a8a86c 579Set a delay, in seconds. The input audio is analyzed immediately, but audio is
738f8358
AK
580delayed before being fed to the volume adjuster. Specifying a delay
581approximately equal to the attack/decay times allows the filter to effectively
d4a8a86c 582operate in predictive rather than reactive mode. It defaults to 0.
738f8358
AK
583
584@end table
585
586@subsection Examples
587
588@itemize
589@item
d4a8a86c
KBA
590Make music with both quiet and loud passages suitable for listening to in a
591noisy environment:
738f8358
AK
592@example
593compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
594@end example
595
596@item
d4a8a86c 597A noise gate for when the noise is at a lower level than the signal:
738f8358
AK
598@example
599compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
600@end example
601
602@item
603Here is another noise gate, this time for when the noise is at a higher level
604than the signal (making it, in some ways, similar to squelch):
605@example
606compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
607@end example
608@end itemize
609
dc07fb6f
AK
610@section join
611Join multiple input streams into one multi-channel stream.
612
d4a8a86c 613It accepts the following parameters:
dc07fb6f
AK
614@table @option
615
616@item inputs
d4a8a86c 617The number of input streams. It defaults to 2.
dc07fb6f
AK
618
619@item channel_layout
d4a8a86c 620The desired output channel layout. It defaults to stereo.
dc07fb6f
AK
621
622@item map
dd7fc37c 623Map channels from inputs to output. The argument is a '|'-separated list of
dc07fb6f
AK
624mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
625form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
7a8059eb 626can be either the name of the input channel (e.g. FL for front left) or its
dc07fb6f
AK
627index in the specified input stream. @var{out_channel} is the name of the output
628channel.
629@end table
630
d4a8a86c 631The filter will attempt to guess the mappings when they are not specified
dc07fb6f
AK
632explicitly. It does so by first trying to find an unused matching input channel
633and if that fails it picks the first unused input channel.
634
d4a8a86c 635Join 3 inputs (with properly set channel layouts):
dc07fb6f
AK
636@example
637avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
638@end example
639
d4a8a86c 640Build a 5.1 output from 6 single-channel streams:
dc07fb6f
AK
641@example
642avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
dd7fc37c 643'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'
dc07fb6f
AK
644out
645@end example
646
d371e7b9 647@section resample
d4a8a86c
KBA
648Convert the audio sample format, sample rate and channel layout. It is
649not meant to be used directly; it is inserted automatically by libavfilter
d371e7b9
AK
650whenever conversion is needed. Use the @var{aformat} filter to force a specific
651conversion.
652
b384e031
JR
653@section volume
654
655Adjust the input audio volume.
656
d4a8a86c 657It accepts the following parameters:
b384e031
JR
658@table @option
659
660@item volume
d4a8a86c 661This expresses how the audio volume will be increased or decreased.
b384e031
JR
662
663Output values are clipped to the maximum value.
664
665The output audio volume is given by the relation:
666@example
667@var{output_volume} = @var{volume} * @var{input_volume}
668@end example
669
d4a8a86c 670The default value for @var{volume} is 1.0.
b384e031
JR
671
672@item precision
d4a8a86c 673This parameter represents the mathematical precision.
b384e031 674
d4a8a86c 675It determines which input sample formats will be allowed, which affects the
b384e031
JR
676precision of the volume scaling.
677
678@table @option
679@item fixed
d4a8a86c 6808-bit fixed-point; this limits input sample format to U8, S16, and S32.
b384e031 681@item float
d4a8a86c 68232-bit floating-point; this limits input sample format to FLT. (default)
b384e031 683@item double
d4a8a86c 68464-bit floating-point; this limits input sample format to DBL.
b384e031 685@end table
06c3cd3c
AK
686
687@item replaygain
d4a8a86c 688Choose the behaviour on encountering ReplayGain side data in input frames.
06c3cd3c
AK
689
690@table @option
691@item drop
692Remove ReplayGain side data, ignoring its contents (the default).
693
694@item ignore
695Ignore ReplayGain side data, but leave it in the frame.
696
697@item track
d4a8a86c 698Prefer the track gain, if present.
06c3cd3c
AK
699
700@item album
d4a8a86c 701Prefer the album gain, if present.
06c3cd3c 702@end table
a49aa440
AG
703
704@item replaygain_preamp
705Pre-amplification gain in dB to apply to the selected replaygain gain.
706
707Default value for @var{replaygain_preamp} is 0.0.
708
aaab192d
AG
709@item replaygain_noclip
710Prevent clipping by limiting the gain applied.
711
712Default value for @var{replaygain_noclip} is 1.
713
b384e031
JR
714@end table
715
716@subsection Examples
717
718@itemize
719@item
720Halve the input audio volume:
721@example
722volume=volume=0.5
723volume=volume=1/2
724volume=volume=-6.0206dB
725@end example
726
727@item
728Increase input audio power by 6 decibels using fixed-point precision:
729@example
730volume=volume=6dB:precision=fixed
731@end example
732@end itemize
733
f59e9eaf
SS
734@c man end AUDIO FILTERS
735
1ee410f3
SS
736@chapter Audio Sources
737@c man begin AUDIO SOURCES
738
739Below is a description of the currently available audio sources.
740
741@section anullsrc
742
d4a8a86c
KBA
743The null audio source; it never returns audio frames. It is mainly useful as a
744template and for use in analysis / debugging tools.
1ee410f3 745
d4a8a86c 746It accepts, as an optional parameter, a string of the form
1ee410f3
SS
747@var{sample_rate}:@var{channel_layout}.
748
d4a8a86c 749@var{sample_rate} specifies the sample rate, and defaults to 44100.
1ee410f3 750
d4a8a86c 751@var{channel_layout} specifies the channel layout, and can be either an
1ee410f3
SS
752integer or a string representing a channel layout. The default value
753of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
754
755Check the channel_layout_map definition in
a903f8f0 756@file{libavutil/channel_layout.c} for the mapping between strings and
6ef93402 757channel layout values.
1ee410f3 758
d4a8a86c 759Some examples:
1ee410f3 760@example
d4a8a86c 761# Set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO
1ee410f3
SS
762anullsrc=48000:4
763
d4a8a86c 764# The same as above
1ee410f3
SS
765anullsrc=48000:mono
766@end example
767
4c66c407
AK
768@section abuffer
769Buffer audio frames, and make them available to the filter chain.
770
d4a8a86c
KBA
771This source is not intended to be part of user-supplied graph descriptions; it
772is for insertion by calling programs, through the interface defined in
4c66c407
AK
773@file{libavfilter/buffersrc.h}.
774
d4a8a86c 775It accepts the following parameters:
4c66c407
AK
776@table @option
777
778@item time_base
d4a8a86c 779The timebase which will be used for timestamps of submitted frames. It must be
4c66c407
AK
780either a floating-point number or in @var{numerator}/@var{denominator} form.
781
782@item sample_rate
d4a8a86c 783The audio sample rate.
4c66c407
AK
784
785@item sample_fmt
d4a8a86c 786The name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
4c66c407
AK
787
788@item channel_layout
d4a8a86c 789The channel layout of the audio data, in the form that can be accepted by
4c66c407
AK
790@code{av_get_channel_layout()}.
791@end table
792
793All the parameters need to be explicitly defined.
794
1ee410f3
SS
795@c man end AUDIO SOURCES
796
f0a55438
HM
797@chapter Audio Sinks
798@c man begin AUDIO SINKS
799
800Below is a description of the currently available audio sinks.
801
802@section anullsink
803
d4a8a86c
KBA
804Null audio sink; do absolutely nothing with the input audio. It is
805mainly useful as a template and for use in analysis / debugging
f0a55438
HM
806tools.
807
a2cd9be2
AK
808@section abuffersink
809This sink is intended for programmatic use. Frames that arrive on this sink can
d4a8a86c 810be retrieved by the calling program, using the interface defined in
a2cd9be2
AK
811@file{libavfilter/buffersink.h}.
812
d4a8a86c 813It does not accept any parameters.
a2cd9be2 814
f0a55438
HM
815@c man end AUDIO SINKS
816
3275ac6a
SS
817@chapter Video Filters
818@c man begin VIDEO FILTERS
819
f8a45fa1 820When you configure your Libav build, you can disable any of the
3275ac6a
SS
821existing filters using --disable-filters.
822The configure output will show the video filters included in your
823build.
824
825Below is a description of the currently available video filters.
826
13fabd7a
SS
827@section blackframe
828
829Detect frames that are (almost) completely black. Can be useful to
830detect chapter transitions or commercials. Output lines consist of
831the frame number of the detected frame, the percentage of blackness,
832the position in the file if known or -1 and the timestamp in seconds.
833
834In order to display the output lines, you need to set the loglevel at
835least to the AV_LOG_INFO value.
836
d4a8a86c 837It accepts the following parameters:
62dcdb02
AK
838
839@table @option
840
841@item amount
d4a8a86c 842The percentage of the pixels that have to be below the threshold; it defaults to
62dcdb02 84398.
13fabd7a 844
62dcdb02 845@item threshold
d4a8a86c 846The threshold below which a pixel value is considered black; it defaults to 32.
13fabd7a 847
62dcdb02 848@end table
13fabd7a 849
ce6b6ef6
SS
850@section boxblur
851
d4a8a86c 852Apply a boxblur algorithm to the input video.
ce6b6ef6 853
d4a8a86c 854It accepts the following parameters:
51def31d
AK
855
856@table @option
857
858@item luma_radius
859@item luma_power
860@item chroma_radius
861@item chroma_power
862@item alpha_radius
863@item alpha_power
864
865@end table
ce6b6ef6 866
d4a8a86c 867The chroma and alpha parameters are optional. If not specified, they default
ce6b6ef6
SS
868to the corresponding values set for @var{luma_radius} and
869@var{luma_power}.
870
871@var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
872the radius in pixels of the box used for blurring the corresponding
873input plane. They are expressions, and can contain the following
874constants:
875@table @option
876@item w, h
d4a8a86c 877The input width and height in pixels.
ce6b6ef6
SS
878
879@item cw, ch
d4a8a86c 880The input chroma image width and height in pixels.
ce6b6ef6
SS
881
882@item hsub, vsub
d4a8a86c
KBA
883The horizontal and vertical chroma subsample values. For example, for the
884pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
ce6b6ef6
SS
885@end table
886
887The radius must be a non-negative number, and must not be greater than
888the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
889and of @code{min(cw,ch)/2} for the chroma planes.
890
891@var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
892how many times the boxblur filter is applied to the corresponding
893plane.
894
d4a8a86c 895Some examples:
ce6b6ef6
SS
896
897@itemize
898
899@item
d4a8a86c 900Apply a boxblur filter with the luma, chroma, and alpha radii
ce6b6ef6
SS
901set to 2:
902@example
51def31d 903boxblur=luma_radius=2:luma_power=1
ce6b6ef6
SS
904@end example
905
906@item
d4a8a86c 907Set the luma radius to 2, and alpha and chroma radius to 0:
ce6b6ef6
SS
908@example
909boxblur=2:1:0:0:0:0
910@end example
911
912@item
d4a8a86c 913Set the luma and chroma radii to a fraction of the video dimension:
ce6b6ef6 914@example
51def31d 915boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
ce6b6ef6
SS
916@end example
917
918@end itemize
919
b5670209
SS
920@section copy
921
d4a8a86c 922Copy the input source unchanged to the output. This is mainly useful for
b5670209
SS
923testing purposes.
924
3275ac6a
SS
925@section crop
926
fba0156a
AK
927Crop the input video to given dimensions.
928
d4a8a86c 929It accepts the following parameters:
fba0156a
AK
930
931@table @option
932
933@item out_w
d4a8a86c 934The width of the output video.
fba0156a
AK
935
936@item out_h
d4a8a86c 937The height of the output video.
fba0156a
AK
938
939@item x
d4a8a86c
KBA
940The horizontal position, in the input video, of the left edge of the output
941video.
fba0156a
AK
942
943@item y
d4a8a86c 944The vertical position, in the input video, of the top edge of the output video.
fba0156a
AK
945
946@end table
3275ac6a 947
75b67a8a
SS
948The parameters are expressions containing the following constants:
949
950@table @option
951@item E, PI, PHI
d4a8a86c
KBA
952These are approximated values for the mathematical constants e
953(Euler's number), pi (Greek pi), and phi (the golden ratio).
75b67a8a
SS
954
955@item x, y
d4a8a86c 956The computed values for @var{x} and @var{y}. They are evaluated for
75b67a8a
SS
957each new frame.
958
959@item in_w, in_h
d4a8a86c 960The input width and height.
75b67a8a
SS
961
962@item iw, ih
d4a8a86c 963These are the same as @var{in_w} and @var{in_h}.
75b67a8a
SS
964
965@item out_w, out_h
d4a8a86c 966The output (cropped) width and height.
75b67a8a
SS
967
968@item ow, oh
d4a8a86c 969These are the same as @var{out_w} and @var{out_h}.
75b67a8a
SS
970
971@item n
d4a8a86c 972The number of the input frame, starting from 0.
75b67a8a 973
75b67a8a 974@item t
d4a8a86c 975The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
3275ac6a 976
75b67a8a 977@end table
3275ac6a 978
75b67a8a 979The @var{out_w} and @var{out_h} parameters specify the expressions for
d4a8a86c
KBA
980the width and height of the output (cropped) video. They are only
981evaluated during the configuration of the filter.
3275ac6a 982
75b67a8a
SS
983The default value of @var{out_w} is "in_w", and the default value of
984@var{out_h} is "in_h".
2bc05d35 985
75b67a8a
SS
986The expression for @var{out_w} may depend on the value of @var{out_h},
987and the expression for @var{out_h} may depend on @var{out_w}, but they
988cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
989evaluated after @var{out_w} and @var{out_h}.
2bc05d35 990
75b67a8a
SS
991The @var{x} and @var{y} parameters specify the expressions for the
992position of the top-left corner of the output (non-cropped) area. They
993are evaluated for each frame. If the evaluated value is not valid, it
994is approximated to the nearest valid value.
3275ac6a 995
75b67a8a
SS
996The default value of @var{x} is "(in_w-out_w)/2", and the default
997value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
998the center of the input image.
999
1000The expression for @var{x} may depend on @var{y}, and the expression
1001for @var{y} may depend on @var{x}.
1002
d4a8a86c 1003Some examples:
3275ac6a 1004@example
d4a8a86c 1005# Crop the central input area with size 100x100
fba0156a 1006crop=out_w=100:out_h=100
75b67a8a 1007
d4a8a86c 1008# Crop the central input area with size 2/3 of the input video
fba0156a 1009"crop=out_w=2/3*in_w:out_h=2/3*in_h"
75b67a8a 1010
d4a8a86c 1011# Crop the input video central square
fba0156a 1012crop=out_w=in_h
75b67a8a 1013
d4a8a86c 1014# Delimit the rectangle with the top-left corner placed at position
75b67a8a 1015# 100:100 and the right-bottom corner corresponding to the right-bottom
d4a8a86c 1016# corner of the input image
fba0156a 1017crop=out_w=in_w-100:out_h=in_h-100:x=100:y=100
3275ac6a 1018
d4a8a86c 1019# Crop 10 pixels from the left and right borders, and 20 pixels from
75b67a8a 1020# the top and bottom borders
fba0156a 1021"crop=out_w=in_w-2*10:out_h=in_h-2*20"
3275ac6a 1022
d4a8a86c 1023# Keep only the bottom right quarter of the input image
fba0156a 1024"crop=out_w=in_w/2:out_h=in_h/2:x=in_w/2:y=in_h/2"
75b67a8a 1025
d4a8a86c 1026# Crop height for getting Greek harmony
fba0156a 1027"crop=out_w=in_w:out_h=1/PHI*in_w"
75b67a8a 1028
d4a8a86c 1029# Trembling effect
75b67a8a
SS
1030"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)"
1031
d4a8a86c 1032# Erratic camera effect depending on timestamp
fba0156a 1033"crop=out_w=in_w/2:out_h=in_h/2:x=(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):y=(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
75b67a8a 1034
d4a8a86c 1035# Set x depending on the value of y
75b67a8a
SS
1036"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
1037@end example
3275ac6a 1038
68b79bfc
SS
1039@section cropdetect
1040
d4a8a86c 1041Auto-detect the crop size.
68b79bfc 1042
d4a8a86c
KBA
1043It calculates the necessary cropping parameters and prints the
1044recommended parameters via the logging system. The detected dimensions
68b79bfc
SS
1045correspond to the non-black area of the input video.
1046
d4a8a86c 1047It accepts the following parameters:
68b79bfc
SS
1048
1049@table @option
1050
1051@item limit
d4a8a86c
KBA
1052The threshold, an optional parameter between nothing (0) and
1053everything (255). It defaults to 24.
68b79bfc
SS
1054
1055@item round
d4a8a86c 1056The value which the width/height should be divisible by. It defaults to
68b79bfc
SS
105716. The offset is automatically adjusted to center the video. Use 2 to
1058get only even dimensions (needed for 4:2:2 video). 16 is best when
1059encoding to most video codecs.
1060
1061@item reset
d4a8a86c
KBA
1062A counter that determines how many frames cropdetect will reset
1063the previously detected largest video area after. It will then start over
1064and detect the current optimal crop area. It defaults to 0.
68b79bfc
SS
1065
1066This can be useful when channel logos distort the video area. 0
d4a8a86c 1067indicates 'never reset', and returns the largest area encountered during
68b79bfc
SS
1068playback.
1069@end table
1070
b157be1f
SS
1071@section delogo
1072
1073Suppress a TV station logo by a simple interpolation of the surrounding
1074pixels. Just set a rectangle covering the logo and watch it disappear
1075(and sometimes something even uglier appear - your mileage may vary).
1076
d4a8a86c 1077It accepts the following parameters:
b157be1f
SS
1078@table @option
1079
1080@item x, y
1081Specify the top left corner coordinates of the logo. They must be
1082specified.
1083
1084@item w, h
1085Specify the width and height of the logo to clear. They must be
1086specified.
1087
1088@item band, t
1089Specify the thickness of the fuzzy edge of the rectangle (added to
1090@var{w} and @var{h}). The default value is 4.
1091
1092@item show
1093When set to 1, a green rectangle is drawn on the screen to simplify
1094finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
1095@var{band} is set to 4. The default value is 0.
1096
1097@end table
1098
d4a8a86c 1099An example:
b157be1f
SS
1100
1101@itemize
1102
1103@item
1104Set a rectangle covering the area with top left corner coordinates 0,0
d4a8a86c 1105and size 100x77, and a band of size 10:
b157be1f 1106@example
b157be1f
SS
1107delogo=x=0:y=0:w=100:h=77:band=10
1108@end example
1109
1110@end itemize
1111
e40032e2
SS
1112@section drawbox
1113
1114Draw a colored box on the input image.
1115
d4a8a86c 1116It accepts the following parameters:
e40032e2
SS
1117
1118@table @option
1119
1120@item x, y
d4a8a86c 1121Specify the top left corner coordinates of the box. It defaults to 0.
e40032e2
SS
1122
1123@item width, height
d4a8a86c
KBA
1124Specify the width and height of the box; if 0 they are interpreted as
1125the input width and height. It defaults to 0.
e40032e2
SS
1126
1127@item color
d4a8a86c 1128Specify the color of the box to write. It can be the name of a color
e40032e2
SS
1129(case insensitive match) or a 0xRRGGBB[AA] sequence.
1130@end table
1131
d4a8a86c 1132Some examples:
e40032e2 1133@example
d4a8a86c 1134# Draw a black box around the edge of the input image
e40032e2
SS
1135drawbox
1136
d4a8a86c 1137# Draw a box with color red and an opacity of 50%
335c3129 1138drawbox=x=10:y=20:width=200:height=60:color=red@@0.5"
e40032e2
SS
1139@end example
1140
a5b64584
SS
1141@section drawtext
1142
d4a8a86c 1143Draw a text string or text from a specified file on top of a video, using the
a5b64584
SS
1144libfreetype library.
1145
d4a8a86c 1146To enable compilation of this filter, you need to configure Libav with
a5b64584 1147@code{--enable-libfreetype}.
f1b239ec
LB
1148To enable default font fallback and the @var{font} option you need to
1149configure Libav with @code{--enable-libfontconfig}.
a5b64584
SS
1150
1151The filter also recognizes strftime() sequences in the provided text
1152and expands them accordingly. Check the documentation of strftime().
1153
d4a8a86c 1154It accepts the following parameters:
a5b64584
SS
1155
1156@table @option
1157
f1b239ec
LB
1158@item font
1159The font family to be used for drawing text. By default Sans.
1160
a5b64584 1161@item fontfile
d4a8a86c 1162The font file to be used for drawing text. The path must be included.
f1b239ec 1163This parameter is mandatory if the fontconfig support is disabled.
a5b64584
SS
1164
1165@item text
1166The text string to be drawn. The text must be a sequence of UTF-8
1167encoded characters.
1168This parameter is mandatory if no file is specified with the parameter
1169@var{textfile}.
1170
1171@item textfile
1172A text file containing text to be drawn. The text must be a sequence
1173of UTF-8 encoded characters.
1174
1175This parameter is mandatory if no text string is specified with the
1176parameter @var{text}.
1177
1178If both text and textfile are specified, an error is thrown.
1179
1180@item x, y
1181The offsets where text will be drawn within the video frame.
d4a8a86c 1182It is relative to the top/left border of the output image.
2cf74eca
LB
1183They accept expressions similar to the @ref{overlay} filter:
1184@table @option
1185
1186@item x, y
d4a8a86c 1187The computed values for @var{x} and @var{y}. They are evaluated for
2cf74eca
LB
1188each new frame.
1189
1190@item main_w, main_h
d4a8a86c 1191The main input width and height.
2cf74eca
LB
1192
1193@item W, H
d4a8a86c 1194These are the same as @var{main_w} and @var{main_h}.
2cf74eca
LB
1195
1196@item text_w, text_h
d4a8a86c 1197The rendered text's width and height.
2cf74eca
LB
1198
1199@item w, h
d4a8a86c 1200These are the same as @var{text_w} and @var{text_h}.
2cf74eca
LB
1201
1202@item n
d4a8a86c 1203The number of frames processed, starting from 0.
2cf74eca
LB
1204
1205@item t
d4a8a86c 1206The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
2cf74eca
LB
1207
1208@end table
a5b64584
SS
1209
1210The default value of @var{x} and @var{y} is 0.
1211
9b2c57be
LB
1212@item draw
1213Draw the text only if the expression evaluates as non-zero.
1214The expression accepts the same variables @var{x, y} do.
1215The default value is 1.
1216
1217@item alpha
1218Draw the text applying alpha blending. The value can
1219be either a number between 0.0 and 1.0
1220The expression accepts the same variables @var{x, y} do.
1221The default value is 1.
1222
a5b64584
SS
1223@item fontsize
1224The font size to be used for drawing text.
1225The default value of @var{fontsize} is 16.
1226
1227@item fontcolor
1228The color to be used for drawing fonts.
d4a8a86c 1229It is either a string (e.g. "red"), or in 0xRRGGBB[AA] format
a5b64584
SS
1230(e.g. "0xff000033"), possibly followed by an alpha specifier.
1231The default value of @var{fontcolor} is "black".
1232
1233@item boxcolor
1234The color to be used for drawing box around text.
d4a8a86c 1235It is either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
a5b64584
SS
1236(e.g. "0xff00ff"), possibly followed by an alpha specifier.
1237The default value of @var{boxcolor} is "white".
1238
1239@item box
d4a8a86c
KBA
1240Used to draw a box around text using the background color.
1241The value must be either 1 (enable) or 0 (disable).
a5b64584
SS
1242The default value of @var{box} is 0.
1243
994de197
SS
1244@item shadowx, shadowy
1245The x and y offsets for the text shadow position with respect to the
1246position of the text. They can be either positive or negative
d4a8a86c 1247values. The default value for both is "0".
994de197
SS
1248
1249@item shadowcolor
1250The color to be used for drawing a shadow behind the drawn text. It
1251can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
1252form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1253The default value of @var{shadowcolor} is "black".
1254
a5b64584 1255@item ft_load_flags
d4a8a86c 1256The flags to be used for loading the fonts.
a5b64584
SS
1257
1258The flags map the corresponding flags supported by libfreetype, and are
1259a combination of the following values:
1260@table @var
1261@item default
1262@item no_scale
1263@item no_hinting
1264@item render
1265@item no_bitmap
1266@item vertical_layout
1267@item force_autohint
1268@item crop_bitmap
1269@item pedantic
1270@item ignore_global_advance_width
1271@item no_recurse
1272@item ignore_transform
1273@item monochrome
1274@item linear_design
1275@item no_autohint
1276@item end table
1277@end table
1278
1279Default value is "render".
1280
1281For more information consult the documentation for the FT_LOAD_*
1282libfreetype flags.
1283
1284@item tabsize
1285The size in number of spaces to use for rendering the tab.
1286Default value is 4.
e496c45d
AU
1287
1288@item fix_bounds
1289If true, check and fix text coords to avoid clipping.
a5b64584
SS
1290@end table
1291
1292For example the command:
1293@example
1294drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
1295@end example
1296
1297will draw "Test Text" with font FreeSerif, using the default values
1298for the optional parameters.
1299
1300The command:
1301@example
1302drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
1303 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
1304@end example
1305
1306will draw 'Test Text' with font FreeSerif of size 24 at position x=100
1307and y=50 (counting from the top-left corner of the screen), text is
1308yellow with a red box around it. Both the text and the box have an
1309opacity of 20%.
1310
1311Note that the double quotes are not necessary if spaces are not used
1312within the parameter list.
1313
1314For more information about libfreetype, check:
1315@url{http://www.freetype.org/}.
1316
aadfc9ee
BM
1317@section fade
1318
d4a8a86c 1319Apply a fade-in/out effect to the input video.
aadfc9ee 1320
d4a8a86c 1321It accepts the following parameters:
b9dfee9f
AK
1322
1323@table @option
aadfc9ee 1324
b9dfee9f 1325@item type
d4a8a86c 1326The effect type can be either "in" for a fade-in, or "out" for a fade-out
b9dfee9f 1327effect.
aadfc9ee 1328
b9dfee9f 1329@item start_frame
d4a8a86c 1330The number of the frame to start applying the fade effect at.
aadfc9ee 1331
b9dfee9f 1332@item nb_frames
d4a8a86c
KBA
1333The number of frames that the fade effect lasts. At the end of the
1334fade-in effect, the output video will have the same intensity as the input video.
1335At the end of the fade-out transition, the output video will be completely black.
b9dfee9f
AK
1336
1337@end table
aadfc9ee 1338
d4a8a86c 1339Some examples:
aadfc9ee 1340@example
d4a8a86c 1341# Fade in the first 30 frames of video
b9dfee9f 1342fade=type=in:nb_frames=30
aadfc9ee 1343
d4a8a86c 1344# Fade out the last 45 frames of a 200-frame video
b9dfee9f 1345fade=type=out:start_frame=155:nb_frames=45
aadfc9ee 1346
d4a8a86c 1347# Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video
b9dfee9f 1348fade=type=in:start_frame=0:nb_frames=25, fade=type=out:start_frame=975:nb_frames=25
aadfc9ee 1349
d4a8a86c 1350# Make the first 5 frames black, then fade in from frame 5-24
b9dfee9f 1351fade=type=in:start_frame=5:nb_frames=20
aadfc9ee
BM
1352@end example
1353
2f84bb42
MH
1354@section fieldorder
1355
1356Transform the field order of the input video.
1357
d4a8a86c 1358It accepts the following parameters:
2f84bb42
MH
1359
1360@table @option
a39c1540
AK
1361
1362@item order
d4a8a86c 1363The output field order. Valid values are @var{tff} for top field first or @var{bff}
a39c1540 1364for bottom field first.
2f84bb42
MH
1365@end table
1366
d4a8a86c 1367The default value is "tff".
2f84bb42 1368
d4a8a86c 1369The transformation is done by shifting the picture content up or down
2f84bb42
MH
1370by one line, and filling the remaining line with appropriate picture content.
1371This method is consistent with most broadcast field order converters.
1372
1373If the input video is not flagged as being interlaced, or it is already
d4a8a86c 1374flagged as being of the required output field order, then this filter does
2f84bb42
MH
1375not alter the incoming video.
1376
d4a8a86c 1377It is very useful when converting to or from PAL DV material,
2f84bb42
MH
1378which is bottom field first.
1379
1380For example:
1381@example
a39c1540 1382./avconv -i in.vob -vf "fieldorder=order=bff" out.dv
2f84bb42
MH
1383@end example
1384
7f1af825
SS
1385@section fifo
1386
1387Buffer input images and send them when they are requested.
1388
d4a8a86c 1389It is mainly useful when auto-inserted by the libavfilter
7f1af825
SS
1390framework.
1391
d4a8a86c 1392It does not take parameters.
7f1af825 1393
3275ac6a
SS
1394@section format
1395
1396Convert the input video to one of the specified pixel formats.
d4a8a86c 1397Libavfilter will try to pick one that is suitable as input to
3275ac6a
SS
1398the next filter.
1399
d4a8a86c 1400It accepts the following parameters:
e67a87ea
AK
1401@table @option
1402
1403@item pix_fmts
d4a8a86c 1404A '|'-separated list of pixel format names, such as
e67a87ea
AK
1405"pix_fmts=yuv420p|monow|rgb24".
1406
1407@end table
3275ac6a 1408
d4a8a86c 1409Some examples:
3275ac6a 1410@example
d4a8a86c 1411# Convert the input video to the "yuv420p" format
e67a87ea 1412format=pix_fmts=yuv420p
3275ac6a 1413
d4a8a86c 1414# Convert the input video to any of the formats in the list
e67a87ea 1415format=pix_fmts=yuv420p|yuv444p|yuv410p
f150e4dc 1416@end example
3275ac6a 1417
dd249245 1418@anchor{fps}
54c5dd89
AK
1419@section fps
1420
1421Convert the video to specified constant framerate by duplicating or dropping
1422frames as necessary.
1423
d4a8a86c 1424It accepts the following parameters:
54c5dd89
AK
1425@table @option
1426
1427@item fps
d4a8a86c 1428The desired output framerate.
54c5dd89 1429
545a0b80
JR
1430@item start_time
1431Assume the first PTS should be the given value, in seconds. This allows for
1432padding/trimming at the start of stream. By default, no assumption is made
1433about the first frame's expected PTS, so no padding or trimming is done.
1434For example, this could be set to 0 to pad the beginning with duplicates of
1435the first frame if a video stream starts after the audio stream or to trim any
1436frames with a negative PTS.
1437
54c5dd89
AK
1438@end table
1439
a7d0e7ea
VG
1440@section framepack
1441
1442Pack two different video streams into a stereoscopic video, setting proper
1443metadata on supported codecs. The two views should have the same size and
1444framerate and processing will stop when the shorter video ends. Please note
1445that you may conveniently adjust view properties with the @ref{scale} and
1446@ref{fps} filters.
1447
d4a8a86c 1448It accepts the following parameters:
a7d0e7ea
VG
1449@table @option
1450
1451@item format
d4a8a86c 1452The desired packing format. Supported values are:
a7d0e7ea
VG
1453
1454@table @option
1455
1456@item sbs
d4a8a86c 1457The views are next to each other (default).
a7d0e7ea
VG
1458
1459@item tab
d4a8a86c 1460The views are on top of each other.
a7d0e7ea
VG
1461
1462@item lines
d4a8a86c 1463The views are packed by line.
a7d0e7ea
VG
1464
1465@item columns
d4a8a86c 1466The views are packed by column.
a7d0e7ea
VG
1467
1468@item frameseq
d4a8a86c 1469The views are temporally interleaved.
a7d0e7ea
VG
1470
1471@end table
1472
1473@end table
1474
d4a8a86c 1475Some examples:
a7d0e7ea
VG
1476
1477@example
d4a8a86c 1478# Convert left and right views into a frame-sequential video
a7d0e7ea
VG
1479avconv -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
1480
d4a8a86c 1481# Convert views into a side-by-side video with the same output resolution as the input
a7d0e7ea
VG
1482avconv -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
1483@end example
1484
f8608dca 1485@anchor{frei0r}
47941088
SS
1486@section frei0r
1487
1488Apply a frei0r effect to the input video.
1489
d4a8a86c 1490To enable the compilation of this filter, you need to install the frei0r
f8a45fa1 1491header and configure Libav with --enable-frei0r.
47941088 1492
d4a8a86c 1493It accepts the following parameters:
5aa1a668
AK
1494
1495@table @option
1496
1497@item filter_name
d4a8a86c
KBA
1498The name of the frei0r effect to load. If the environment variable
1499@env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
1500directories specified by the colon-separated list in @env{FREIOR_PATH}.
1501Otherwise, the standard frei0r paths are searched, in this order:
5aa1a668
AK
1502@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
1503@file{/usr/lib/frei0r-1/}.
47941088 1504
5aa1a668
AK
1505@item filter_params
1506A '|'-separated list of parameters to pass to the frei0r effect.
47941088 1507
5aa1a668 1508@end table
47941088 1509
d4a8a86c
KBA
1510A frei0r effect parameter can be a boolean (its value is either
1511"y" or "n"), a double, a color (specified as
1512@var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
1513numbers between 0.0 and 1.0, inclusive) or by an @code{av_parse_color()} color
1514description), a position (specified as @var{X}/@var{Y}, where
1515@var{X} and @var{Y} are floating point numbers) and/or a string.
47941088 1516
d4a8a86c
KBA
1517The number and types of parameters depend on the loaded effect. If an
1518effect parameter is not specified, the default value is set.
47941088 1519
d4a8a86c 1520Some examples:
47941088 1521@example
d4a8a86c 1522# Apply the distort0r effect, setting the first two double parameters
5aa1a668 1523frei0r=filter_name=distort0r:filter_params=0.5|0.01
47941088 1524
d4a8a86c 1525# Apply the colordistance effect, taking a color as the first parameter
47941088
SS
1526frei0r=colordistance:0.2/0.3/0.4
1527frei0r=colordistance:violet
1528frei0r=colordistance:0x112233
1529
d4a8a86c 1530# Apply the perspective effect, specifying the top left and top right
47941088 1531# image positions
5aa1a668 1532frei0r=perspective:0.2/0.2|0.8/0.2
47941088
SS
1533@end example
1534
d4a8a86c 1535For more information, see
47941088
SS
1536@url{http://piksel.org/frei0r}
1537
d5f187fd
N
1538@section gradfun
1539
1540Fix the banding artifacts that are sometimes introduced into nearly flat
1541regions by truncation to 8bit colordepth.
1542Interpolate the gradients that should go where the bands are, and
1543dither them.
1544
d4a8a86c 1545It is designed for playback only. Do not use it prior to
3eccfaa0
SS
1546lossy compression, because compression tends to lose the dither and
1547bring back the bands.
1548
d4a8a86c 1549It accepts the following parameters:
7ed833d7
AK
1550
1551@table @option
d5f187fd 1552
7ed833d7 1553@item strength
d4a8a86c
KBA
1554The maximum amount by which the filter will change any one pixel. This is also
1555the threshold for detecting nearly flat regions. Acceptable values range from
1556.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
1557valid range.
d5f187fd 1558
7ed833d7
AK
1559@item radius
1560The neighborhood to fit the gradient to. A larger radius makes for smoother
1561gradients, but also prevents the filter from modifying the pixels near detailed
d4a8a86c
KBA
1562regions. Acceptable values are 8-32; the default value is 16. Out-of-range
1563values will be clipped to the valid range.
7ed833d7
AK
1564
1565@end table
d5f187fd
N
1566
1567@example
d4a8a86c 1568# Default parameters
7ed833d7 1569gradfun=strength=1.2:radius=16
d5f187fd 1570
d4a8a86c 1571# Omitting the radius
d5f187fd
N
1572gradfun=1.2
1573@end example
1574
a1e171df
SS
1575@section hflip
1576
1577Flip the input video horizontally.
1578
d4a8a86c 1579For example, to horizontally flip the input video with @command{avconv}:
a1e171df 1580@example
9270b8a3 1581avconv -i in.avi -vf "hflip" out.avi
a1e171df
SS
1582@end example
1583
a4dc7aa5
BC
1584@section hqdn3d
1585
d4a8a86c
KBA
1586This is a high precision/quality 3d denoise filter. It aims to reduce
1587image noise, producing smooth images and making still images really
a4dc7aa5
BC
1588still. It should enhance compressibility.
1589
1590It accepts the following optional parameters:
a4dc7aa5
BC
1591
1592@table @option
1593@item luma_spatial
d4a8a86c
KBA
1594A non-negative floating point number which specifies spatial luma strength.
1595It defaults to 4.0.
a4dc7aa5
BC
1596
1597@item chroma_spatial
d4a8a86c
KBA
1598A non-negative floating point number which specifies spatial chroma strength.
1599It defaults to 3.0*@var{luma_spatial}/4.0.
a4dc7aa5
BC
1600
1601@item luma_tmp
d4a8a86c
KBA
1602A floating point number which specifies luma temporal strength. It defaults to
16036.0*@var{luma_spatial}/4.0.
a4dc7aa5
BC
1604
1605@item chroma_tmp
d4a8a86c
KBA
1606A floating point number which specifies chroma temporal strength. It defaults to
1607@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
a4dc7aa5
BC
1608@end table
1609
3fce1367
VG
1610@section interlace
1611
1612Simple interlacing filter from progressive contents. This interleaves upper (or
1613lower) lines from odd frames with lower (or upper) lines from even frames,
52269f48 1614halving the frame rate and preserving image height.
3fce1367
VG
1615
1616@example
1617 Original Original New Frame
1618 Frame 'j' Frame 'j+1' (tff)
1619 ========== =========== ==================
1620 Line 0 --------------------> Frame 'j' Line 0
1621 Line 1 Line 1 ----> Frame 'j+1' Line 1
1622 Line 2 ---------------------> Frame 'j' Line 2
1623 Line 3 Line 3 ----> Frame 'j+1' Line 3
1624 ... ... ...
1625New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
1626@end example
1627
1628It accepts the following optional parameters:
1629
1630@table @option
1631@item scan
d4a8a86c
KBA
1632This determines whether the interlaced frame is taken from the even
1633(tff - default) or odd (bff) lines of the progressive frame.
52269f48
VG
1634
1635@item lowpass
1636Enable (default) or disable the vertical lowpass filter to avoid twitter
1637interlacing and reduce moire patterns.
3fce1367
VG
1638@end table
1639
8fe0c527
SS
1640@section lut, lutrgb, lutyuv
1641
1642Compute a look-up table for binding each pixel component input value
d4a8a86c 1643to an output value, and apply it to the input video.
8fe0c527
SS
1644
1645@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
1646to an RGB input video.
1647
d4a8a86c 1648These filters accept the following parameters:
8fe0c527 1649@table @option
91f5f875
LB
1650@item @var{c0} (first pixel component)
1651@item @var{c1} (second pixel component)
1652@item @var{c2} (third pixel component)
1653@item @var{c3} (fourth pixel component, corresponds to the alpha component)
8fe0c527 1654
91f5f875
LB
1655@item @var{r} (red component)
1656@item @var{g} (green component)
1657@item @var{b} (blue component)
1658@item @var{a} (alpha component)
8fe0c527 1659
91f5f875
LB
1660@item @var{y} (Y/luminance component)
1661@item @var{u} (U/Cb component)
1662@item @var{v} (V/Cr component)
8fe0c527
SS
1663@end table
1664
20b46f8f
AK
1665Each of them specifies the expression to use for computing the lookup table for
1666the corresponding pixel component values.
1667
1668The exact component associated to each of the @var{c*} options depends on the
1669format in input.
1670
1671The @var{lut} filter requires either YUV or RGB pixel formats in input,
1672@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
1673
8fe0c527
SS
1674The expressions can contain the following constants and functions:
1675
1676@table @option
1677@item E, PI, PHI
d4a8a86c
KBA
1678These are approximated values for the mathematical constants e
1679(Euler's number), pi (Greek pi), and phi (the golden ratio).
8fe0c527
SS
1680
1681@item w, h
d4a8a86c 1682The input width and height.
8fe0c527
SS
1683
1684@item val
d4a8a86c 1685The input value for the pixel component.
8fe0c527
SS
1686
1687@item clipval
d4a8a86c 1688The input value, clipped to the @var{minval}-@var{maxval} range.
8fe0c527
SS
1689
1690@item maxval
d4a8a86c 1691The maximum value for the pixel component.
8fe0c527
SS
1692
1693@item minval
d4a8a86c 1694The minimum value for the pixel component.
8fe0c527
SS
1695
1696@item negval
d4a8a86c
KBA
1697The negated value for the pixel component value, clipped to the
1698@var{minval}-@var{maxval} range; it corresponds to the expression
1699"maxval-clipval+minval".
8fe0c527
SS
1700
1701@item clip(val)
d4a8a86c
KBA
1702The computed value in @var{val}, clipped to the
1703@var{minval}-@var{maxval} range.
8fe0c527
SS
1704
1705@item gammaval(gamma)
d4a8a86c
KBA
1706The computed gamma correction value of the pixel component value,
1707clipped to the @var{minval}-@var{maxval} range. It corresponds to the
8fe0c527
SS
1708expression
1709"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
1710
1711@end table
1712
1713All expressions default to "val".
1714
d4a8a86c 1715Some examples:
8fe0c527 1716@example
d4a8a86c 1717# Negate input video
8fe0c527
SS
1718lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
1719lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
1720
d4a8a86c 1721# The above is the same as
8fe0c527
SS
1722lutrgb="r=negval:g=negval:b=negval"
1723lutyuv="y=negval:u=negval:v=negval"
1724
d4a8a86c 1725# Negate luminance
8fe0c527
SS
1726lutyuv=negval
1727
d4a8a86c 1728# Remove chroma components, turning the video into a graytone image
8fe0c527
SS
1729lutyuv="u=128:v=128"
1730
d4a8a86c 1731# Apply a luma burning effect
8fe0c527
SS
1732lutyuv="y=2*val"
1733
d4a8a86c 1734# Remove green and blue components
8fe0c527
SS
1735lutrgb="g=0:b=0"
1736
d4a8a86c 1737# Set a constant alpha channel value on input
8fe0c527
SS
1738format=rgba,lutrgb=a="maxval-minval/2"
1739
d4a8a86c 1740# Correct luminance gamma by a factor of 0.5
8fe0c527
SS
1741lutyuv=y=gammaval(0.5)
1742@end example
1743
171868e2
SS
1744@section negate
1745
1746Negate input video.
1747
d4a8a86c 1748It accepts an integer in input; if non-zero it negates the
171868e2 1749alpha component (if available). The default value in input is 0.
3275ac6a 1750
ef4d34aa
AK
1751@section noformat
1752
3275ac6a
SS
1753Force libavfilter not to use any of the specified pixel formats for the
1754input to the next filter.
1755
d4a8a86c 1756It accepts the following parameters:
e67a87ea
AK
1757@table @option
1758
1759@item pix_fmts
d4a8a86c
KBA
1760A '|'-separated list of pixel format names, such as
1761apix_fmts=yuv420p|monow|rgb24".
e67a87ea
AK
1762
1763@end table
3275ac6a 1764
d4a8a86c 1765Some examples:
3275ac6a 1766@example
d4a8a86c 1767# Force libavfilter to use a format different from "yuv420p" for the
f150e4dc 1768# input to the vflip filter
e67a87ea 1769noformat=pix_fmts=yuv420p,vflip
3275ac6a 1770
d4a8a86c 1771# Convert the input video to any of the formats not contained in the list
e67a87ea 1772noformat=yuv420p|yuv444p|yuv410p
f150e4dc 1773@end example
3275ac6a
SS
1774
1775@section null
1776
99046339 1777Pass the video source unchanged to the output.
3275ac6a 1778
cf69ad35 1779@section ocv
6ebf0bfc 1780
d4a8a86c 1781Apply a video transform using libopencv.
6ebf0bfc 1782
d4a8a86c 1783To enable this filter, install the libopencv library and headers and
f8a45fa1 1784configure Libav with --enable-libopencv.
6ebf0bfc 1785
d4a8a86c 1786It accepts the following parameters:
ee0e8d4b
AK
1787
1788@table @option
cf69ad35 1789
ee0e8d4b
AK
1790@item filter_name
1791The name of the libopencv filter to apply.
cf69ad35 1792
ee0e8d4b 1793@item filter_params
d4a8a86c 1794The parameters to pass to the libopencv filter. If not specified, the default
ee0e8d4b
AK
1795values are assumed.
1796
1797@end table
cf69ad35
SS
1798
1799Refer to the official libopencv documentation for more precise
da9cea77 1800information:
cf69ad35
SS
1801@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
1802
d4a8a86c 1803Several libopencv filters are supported; see the following subsections.
cf69ad35 1804
17fc9493 1805@anchor{dilate}
91cbb6ba
SS
1806@subsection dilate
1807
1808Dilate an image by using a specific structuring element.
d4a8a86c 1809It corresponds to the libopencv function @code{cvDilate}.
91cbb6ba 1810
ee0e8d4b 1811It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
91cbb6ba
SS
1812
1813@var{struct_el} represents a structuring element, and has the syntax:
1814@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
1815
da9cea77 1816@var{cols} and @var{rows} represent the number of columns and rows of
91cbb6ba 1817the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
d4a8a86c
KBA
1818point, and @var{shape} the shape for the structuring element. @var{shape}
1819must be "rect", "cross", "ellipse", or "custom".
91cbb6ba
SS
1820
1821If the value for @var{shape} is "custom", it must be followed by a
1822string of the form "=@var{filename}". The file with name
1823@var{filename} is assumed to represent a binary image, with each
1824printable character corresponding to a bright pixel. When a custom
1825@var{shape} is used, @var{cols} and @var{rows} are ignored, the number
1826or columns and rows of the read file are assumed instead.
1827
1828The default value for @var{struct_el} is "3x3+0x0/rect".
1829
1830@var{nb_iterations} specifies the number of times the transform is
1831applied to the image, and defaults to 1.
1832
d4a8a86c 1833Some examples:
91cbb6ba 1834@example
d4a8a86c 1835# Use the default values
91cbb6ba
SS
1836ocv=dilate
1837
d4a8a86c 1838# Dilate using a structuring element with a 5x5 cross, iterating two times
ee0e8d4b 1839ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
91cbb6ba 1840
d4a8a86c
KBA
1841# Read the shape from the file diamond.shape, iterating two times.
1842# The file diamond.shape may contain a pattern of characters like this
91cbb6ba
SS
1843# *
1844# ***
1845# *****
1846# ***
1847# *
d4a8a86c
KBA
1848# The specified columns and rows are ignored
1849# but the anchor point coordinates are not
ee0e8d4b 1850ocv=dilate:0x0+2x2/custom=diamond.shape|2
91cbb6ba
SS
1851@end example
1852
17fc9493
SS
1853@subsection erode
1854
1855Erode an image by using a specific structuring element.
d4a8a86c 1856It corresponds to the libopencv function @code{cvErode}.
17fc9493 1857
d4a8a86c 1858It accepts the parameters: @var{struct_el}:@var{nb_iterations},
4c989761 1859with the same syntax and semantics as the @ref{dilate} filter.
17fc9493 1860
cf69ad35
SS
1861@subsection smooth
1862
1863Smooth the input video.
1864
1865The filter takes the following parameters:
ee0e8d4b 1866@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
6ebf0bfc 1867
d4a8a86c 1868@var{type} is the type of smooth filter to apply, and must be one of
58d94364 1869the following values: "blur", "blur_no_scale", "median", "gaussian",
d4a8a86c 1870or "bilateral". The default value is "gaussian".
6ebf0bfc 1871
d4a8a86c
KBA
1872The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
1873depend on the smooth type. @var{param1} and
1874@var{param2} accept integer positive values or 0. @var{param3} and
1875@var{param4} accept floating point values.
6ebf0bfc 1876
d4a8a86c 1877The default value for @var{param1} is 3. The default value for the
6ebf0bfc
SS
1878other parameters is 0.
1879
58d94364 1880These parameters correspond to the parameters assigned to the
cf69ad35 1881libopencv function @code{cvSmooth}.
6ebf0bfc 1882
2cf74eca 1883@anchor{overlay}
58935b25
SS
1884@section overlay
1885
1886Overlay one video on top of another.
1887
d4a8a86c 1888It takes two inputs and has one output. The first input is the "main"
58935b25
SS
1889video on which the second input is overlayed.
1890
d4a8a86c 1891It accepts the following parameters:
9087eaf1
AK
1892
1893@table @option
1894
1895@item x
1896The horizontal position of the left edge of the overlaid video on the main video.
1897
1898@item y
1899The vertical position of the top edge of the overlaid video on the main video.
1900
1901@end table
58935b25 1902
9087eaf1 1903The parameters are expressions containing the following parameters:
58935b25
SS
1904
1905@table @option
1906@item main_w, main_h
d4a8a86c 1907The main input width and height.
58935b25
SS
1908
1909@item W, H
d4a8a86c 1910These are the same as @var{main_w} and @var{main_h}.
58935b25
SS
1911
1912@item overlay_w, overlay_h
d4a8a86c 1913The overlay input width and height.
58935b25
SS
1914
1915@item w, h
d4a8a86c 1916These are the same as @var{overlay_w} and @var{overlay_h}.
de203abd
KL
1917
1918@item eof_action
d4a8a86c
KBA
1919The action to take when EOF is encountered on the secondary input; it accepts
1920one of the following values:
de203abd
KL
1921
1922@table @option
1923@item repeat
d4a8a86c 1924Repeat the last frame (the default).
de203abd 1925@item endall
d4a8a86c 1926End both streams.
de203abd 1927@item pass
d4a8a86c 1928Pass the main input through.
de203abd
KL
1929@end table
1930
58935b25
SS
1931@end table
1932
1933Be aware that frames are taken from each input video in timestamp
1934order, hence, if their initial timestamps differ, it is a a good idea
1935to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
d4a8a86c
KBA
1936have them begin in the same zero timestamp, as the example for
1937the @var{movie} filter does.
58935b25 1938
d4a8a86c 1939Some examples:
58935b25 1940@example
d4a8a86c
KBA
1941# Draw the overlay at 10 pixels from the bottom right
1942# corner of the main video
9087eaf1 1943overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
58935b25 1944
d4a8a86c 1945# Insert a transparent PNG logo in the bottom left corner of the input
9087eaf1 1946avconv -i input -i logo -filter_complex 'overlay=x=10:y=main_h-overlay_h-10' output
58935b25 1947
d4a8a86c
KBA
1948# Insert 2 different transparent PNG logos (second logo on bottom
1949# right corner)
7ce118ba 1950avconv -i input -i logo1 -i logo2 -filter_complex
9087eaf1 1951'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output
58935b25 1952
d4a8a86c 1953# Add a transparent color layer on top of the main video;
58935b25
SS
1954# WxH specifies the size of the main input to the overlay filter
1955color=red@.3:WxH [over]; [in][over] overlay [out]
de203abd 1956
d4a8a86c 1957# Mask 10-20 seconds of a video by applying the delogo filter to a section
de203abd
KL
1958avconv -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
1959-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]'
1960masked.avi
58935b25
SS
1961@end example
1962
b0641ab7 1963You can chain together more overlays but the efficiency of such
58935b25
SS
1964approach is yet to be tested.
1965
3275ac6a
SS
1966@section pad
1967
d4a8a86c
KBA
1968Add paddings to the input image, and place the original input at the
1969provided @var{x}, @var{y} coordinates.
3275ac6a 1970
d4a8a86c 1971It accepts the following parameters:
40c885c5
AK
1972
1973@table @option
1974@item width, height
1975
1976Specify the size of the output image with the paddings added. If the
1977value for @var{width} or @var{height} is 0, the corresponding input size
1978is used for the output.
1979
1980The @var{width} expression can reference the value set by the
1981@var{height} expression, and vice versa.
1982
1983The default value of @var{width} and @var{height} is 0.
1984
1985@item x, y
1986
d4a8a86c 1987Specify the offsets to place the input image at within the padded area,
40c885c5
AK
1988with respect to the top/left border of the output image.
1989
1990The @var{x} expression can reference the value set by the @var{y}
1991expression, and vice versa.
1992
1993The default value of @var{x} and @var{y} is 0.
1994
1995@item color
1996
d4a8a86c
KBA
1997Specify the color of the padded area. It can be the name of a color
1998(case insensitive match) or an 0xRRGGBB[AA] sequence.
40c885c5
AK
1999
2000The default value of @var{color} is "black".
2001
2002@end table
3275ac6a 2003
73a4f7c2
SS
2004The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
2005expressions containing the following constants:
2006
2007@table @option
2008@item E, PI, PHI
d4a8a86c
KBA
2009These are approximated values for the mathematical constants e
2010(Euler's number), pi (Greek pi), and phi (the golden ratio).
73a4f7c2
SS
2011
2012@item in_w, in_h
d4a8a86c 2013The input video width and height.
73a4f7c2
SS
2014
2015@item iw, ih
d4a8a86c 2016These are the same as @var{in_w} and @var{in_h}.
73a4f7c2
SS
2017
2018@item out_w, out_h
d4a8a86c
KBA
2019The output width and height (the size of the padded area), as
2020specified by the @var{width} and @var{height} expressions.
73a4f7c2
SS
2021
2022@item ow, oh
d4a8a86c 2023These are the same as @var{out_w} and @var{out_h}.
73a4f7c2
SS
2024
2025@item x, y
d4a8a86c
KBA
2026The x and y offsets as specified by the @var{x} and @var{y}
2027expressions, or NAN if not yet specified.
73a4f7c2
SS
2028
2029@item a
d4a8a86c 2030The input display aspect ratio, same as @var{iw} / @var{ih}.
73a4f7c2
SS
2031
2032@item hsub, vsub
d4a8a86c 2033The horizontal and vertical chroma subsample values. For example for the
73a4f7c2
SS
2034pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2035@end table
2036
d4a8a86c 2037Some examples:
3d17f4b9
SS
2038
2039@example
d4a8a86c
KBA
2040# Add paddings with the color "violet" to the input video. The output video
2041# size is 640x480, and the top-left corner of the input video is placed at
2042# column 0, row 40
40c885c5 2043pad=width=640:height=480:x=0:y=40:color=violet
73a4f7c2 2044
d4a8a86c 2045# Pad the input to get an output with dimensions increased by 3/2,
73a4f7c2
SS
2046# and put the input video at the center of the padded area
2047pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
2048
d4a8a86c 2049# Pad the input to get a squared output with size equal to the maximum
73a4f7c2
SS
2050# value between the input width and height, and put the input video at
2051# the center of the padded area
2052pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
2053
d4a8a86c 2054# Pad the input to get a final w/h ratio of 16:9
73a4f7c2
SS
2055pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
2056
d4a8a86c 2057# Double the output size and put the input video in the bottom-right
73a4f7c2
SS
2058# corner of the output padded area
2059pad="2*iw:2*ih:ow-iw:oh-ih"
3d17f4b9
SS
2060@end example
2061
ce2e4ae3
SS
2062@section pixdesctest
2063
2064Pixel format descriptor test filter, mainly useful for internal
2065testing. The output video should be equal to the input video.
2066
2067For example:
2068@example
2069format=monow, pixdesctest
2070@end example
2071
2072can be used to test the monowhite pixel format descriptor definition.
2073
dd249245 2074@anchor{scale}
3275ac6a
SS
2075@section scale
2076
c334c113 2077Scale the input video and/or convert the image format.
3275ac6a 2078
d4a8a86c 2079It accepts the following parameters:
c334c113
AK
2080
2081@table @option
2082
2083@item w
d4a8a86c 2084The output video width.
c334c113
AK
2085
2086@item h
d4a8a86c 2087The output video height.
c334c113
AK
2088
2089@end table
2090
2091The parameters @var{w} and @var{h} are expressions containing
68e23c08 2092the following constants:
3275ac6a 2093
68e23c08
SS
2094@table @option
2095@item E, PI, PHI
d4a8a86c
KBA
2096These are approximated values for the mathematical constants e
2097(Euler's number), pi (Greek pi), and phi (the golden ratio).
68e23c08
SS
2098
2099@item in_w, in_h
d4a8a86c 2100The input width and height.
68e23c08
SS
2101
2102@item iw, ih
d4a8a86c 2103These are the same as @var{in_w} and @var{in_h}.
68e23c08
SS
2104
2105@item out_w, out_h
d4a8a86c 2106The output (cropped) width and height.
68e23c08
SS
2107
2108@item ow, oh
d4a8a86c 2109These are the same as @var{out_w} and @var{out_h}.
3275ac6a 2110
3a14b160 2111@item a
d4a8a86c 2112This is the same as @var{iw} / @var{ih}.
68e23c08 2113
46b29397
SS
2114@item sar
2115input sample aspect ratio
2116
3a14b160 2117@item dar
d4a8a86c
KBA
2118The input display aspect ratio; it is the same as
2119(@var{iw} / @var{ih}) * @var{sar}.
3a14b160 2120
68e23c08 2121@item hsub, vsub
d4a8a86c 2122The horizontal and vertical chroma subsample values. For example, for the
68e23c08
SS
2123pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2124@end table
3275ac6a
SS
2125
2126If the input image format is different from the format requested by
2127the next filter, the scale filter will convert the input to the
2128requested format.
2129
c334c113 2130If the value for @var{w} or @var{h} is 0, the respective input
3275ac6a
SS
2131size is used for the output.
2132
c334c113
AK
2133If the value for @var{w} or @var{h} is -1, the scale filter will use, for the
2134respective output size, a value that maintains the aspect ratio of the input
2135image.
3275ac6a 2136
c334c113 2137The default value of @var{w} and @var{h} is 0.
3275ac6a 2138
d4a8a86c 2139Some examples:
68e23c08 2140@example
d4a8a86c 2141# Scale the input video to a size of 200x100
c334c113 2142scale=w=200:h=100
68e23c08 2143
d4a8a86c 2144# Scale the input to 2x
c334c113 2145scale=w=2*iw:h=2*ih
d4a8a86c 2146# The above is the same as
68e23c08
SS
2147scale=2*in_w:2*in_h
2148
d4a8a86c 2149# Scale the input to half the original size
c334c113 2150scale=w=iw/2:h=ih/2
68e23c08 2151
d4a8a86c 2152# Increase the width, and set the height to the same size
68e23c08
SS
2153scale=3/2*iw:ow
2154
d4a8a86c 2155# Seek Greek harmony
68e23c08
SS
2156scale=iw:1/PHI*iw
2157scale=ih*PHI:ih
2158
d4a8a86c 2159# Increase the height, and set the width to 3/2 of the height
c334c113 2160scale=w=3/2*oh:h=3/5*ih
68e23c08 2161
d4a8a86c 2162# Increase the size, making the size a multiple of the chroma
68e23c08
SS
2163scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
2164
d4a8a86c
KBA
2165# Increase the width to a maximum of 500 pixels,
2166# keeping the same aspect ratio as the input
c334c113 2167scale=w='min(500\, iw*3/2):h=-1'
68e23c08
SS
2168@end example
2169
d763fb7d
SS
2170@section select
2171Select frames to pass in output.
2172
d4a8a86c 2173It accepts the following parameters:
95f1f56a
AK
2174
2175@table @option
2176
2177@item expr
2178An expression, which is evaluated for each input frame. If the expression is
2179evaluated to a non-zero value, the frame is selected and passed to the output,
2180otherwise it is discarded.
2181
2182@end table
d763fb7d
SS
2183
2184The expression can contain the following constants:
2185
2186@table @option
d4a8a86c
KBA
2187@item E, PI, PHI
2188These are approximated values for the mathematical constants e
2189(Euler's number), pi (Greek pi), and phi (the golden ratio).
d763fb7d
SS
2190
2191@item n
d4a8a86c 2192The (sequential) number of the filtered frame, starting from 0.
d763fb7d
SS
2193
2194@item selected_n
d4a8a86c 2195The (sequential) number of the selected frame, starting from 0.
d763fb7d
SS
2196
2197@item prev_selected_n
d4a8a86c 2198The sequential number of the last selected frame. It's NAN if undefined.
d763fb7d
SS
2199
2200@item TB
d4a8a86c 2201The timebase of the input timestamps.
d763fb7d
SS
2202
2203@item pts
d4a8a86c
KBA
2204The PTS (Presentation TimeStamp) of the filtered video frame,
2205expressed in @var{TB} units. It's NAN if undefined.
d763fb7d
SS
2206
2207@item t
d4a8a86c
KBA
2208The PTS of the filtered video frame,
2209expressed in seconds. It's NAN if undefined.
d763fb7d
SS
2210
2211@item prev_pts
d4a8a86c 2212The PTS of the previously filtered video frame. It's NAN if undefined.
d763fb7d
SS
2213
2214@item prev_selected_pts
d4a8a86c 2215The PTS of the last previously filtered video frame. It's NAN if undefined.
d763fb7d
SS
2216
2217@item prev_selected_t
d4a8a86c 2218The PTS of the last previously selected video frame. It's NAN if undefined.
d763fb7d
SS
2219
2220@item start_pts
d4a8a86c 2221The PTS of the first video frame in the video. It's NAN if undefined.
d763fb7d
SS
2222
2223@item start_t
d4a8a86c 2224The time of the first video frame in the video. It's NAN if undefined.
d763fb7d
SS
2225
2226@item pict_type
d4a8a86c 2227The type of the filtered frame. It can assume one of the following
d763fb7d
SS
2228values:
2229@table @option
2230@item I
2231@item P
2232@item B
2233@item S
2234@item SI
2235@item SP
2236@item BI
2237@end table
2238
2239@item interlace_type
d4a8a86c 2240The frame interlace type. It can assume one of the following values:
d763fb7d
SS
2241@table @option
2242@item PROGRESSIVE
d4a8a86c 2243The frame is progressive (not interlaced).
d763fb7d 2244@item TOPFIRST
d4a8a86c 2245The frame is top-field-first.
d763fb7d 2246@item BOTTOMFIRST
d4a8a86c 2247The frame is bottom-field-first.
d763fb7d
SS
2248@end table
2249
2250@item key
d4a8a86c 2251This is 1 if the filtered frame is a key-frame, 0 otherwise.
d763fb7d 2252
d763fb7d
SS
2253@end table
2254
2255The default value of the select expression is "1".
2256
d4a8a86c 2257Some examples:
d763fb7d
SS
2258
2259@example
d4a8a86c 2260# Select all the frames in input
d763fb7d
SS
2261select
2262
d4a8a86c 2263# The above is the same as
95f1f56a 2264select=expr=1
d763fb7d 2265
d4a8a86c 2266# Skip all frames
95f1f56a 2267select=expr=0
d763fb7d 2268
d4a8a86c 2269# Select only I-frames
95f1f56a 2270select='expr=eq(pict_type\,I)'
d763fb7d 2271
d4a8a86c 2272# Select one frame per 100
d763fb7d
SS
2273select='not(mod(n\,100))'
2274
d4a8a86c 2275# Select only frames contained in the 10-20 time interval
d763fb7d
SS
2276select='gte(t\,10)*lte(t\,20)'
2277
d4a8a86c 2278# Select only I frames contained in the 10-20 time interval
d763fb7d
SS
2279select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
2280
d4a8a86c 2281# Select frames with a minimum distance of 10 seconds
d763fb7d
SS
2282select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
2283@end example
2284
2fd8756b
SS
2285@anchor{setdar}
2286@section setdar
2287
2288Set the Display Aspect Ratio for the filter output video.
2289
2290This is done by changing the specified Sample (aka Pixel) Aspect
2291Ratio, according to the following equation:
2292@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2293
2294Keep in mind that this filter does not modify the pixel dimensions of
d4a8a86c 2295the video frame. Also, the display aspect ratio set by this filter may
2fd8756b
SS
2296be changed by later filters in the filterchain, e.g. in case of
2297scaling or if another "setdar" or a "setsar" filter is applied.
2298
d4a8a86c 2299It accepts the following parameters:
2831b307
AK
2300
2301@table @option
2302
2303@item dar
d4a8a86c 2304The output display aspect ratio.
2831b307
AK
2305
2306@end table
2fd8756b 2307
34a0ac41
RP
2308The parameter @var{dar} is an expression containing
2309the following constants:
2310
2311@table @option
2312@item E, PI, PHI
d4a8a86c
KBA
2313These are approximated values for the mathematical constants e
2314(Euler's number), pi (Greek pi), and phi (the golden ratio).
34a0ac41
RP
2315
2316@item w, h
d4a8a86c 2317The input width and height.
34a0ac41
RP
2318
2319@item a
d4a8a86c 2320This is the same as @var{w} / @var{h}.
34a0ac41
RP
2321
2322@item sar
d4a8a86c 2323The input sample aspect ratio.
34a0ac41
RP
2324
2325@item dar
d4a8a86c
KBA
2326The input display aspect ratio. It is the same as
2327(@var{w} / @var{h}) * @var{sar}.
34a0ac41
RP
2328
2329@item hsub, vsub
d4a8a86c 2330The horizontal and vertical chroma subsample values. For example, for the
34a0ac41
RP
2331pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2332@end table
2333
d4a8a86c 2334To change the display aspect ratio to 16:9, specify:
2fd8756b 2335@example
2831b307 2336setdar=dar=16/9
d4a8a86c 2337# The above is equivalent to
2831b307 2338setdar=dar=1.77777
2fd8756b
SS
2339@end example
2340
d4a8a86c 2341Also see the the @ref{setsar} filter documentation.
2fd8756b 2342
a532bb39
SS
2343@section setpts
2344
2345Change the PTS (presentation timestamp) of the input video frames.
2346
d4a8a86c 2347It accepts the following parameters:
33b97faa
AK
2348
2349@table @option
2350
2351@item expr
2352The expression which is evaluated for each frame to construct its timestamp.
2353
2354@end table
2355
2356The expression is evaluated through the eval API and can contain the following
2357constants:
a532bb39
SS
2358
2359@table @option
2360@item PTS
d4a8a86c 2361The presentation timestamp in input.
a532bb39 2362
d4a8a86c
KBA
2363@item E, PI, PHI
2364These are approximated values for the mathematical constants e
2365(Euler's number), pi (Greek pi), and phi (the golden ratio).
a532bb39
SS
2366
2367@item N
d4a8a86c 2368The count of the input frame, starting from 0.
a532bb39
SS
2369
2370@item STARTPTS
d4a8a86c 2371The PTS of the first video frame.
a532bb39
SS
2372
2373@item INTERLACED
d4a8a86c 2374State whether the current frame is interlaced.
a532bb39 2375
a532bb39 2376@item PREV_INPTS
d4a8a86c 2377The previous input PTS.
a532bb39
SS
2378
2379@item PREV_OUTPTS
d4a8a86c 2380The previous output PTS.
a532bb39 2381
0b55b16a 2382@item RTCTIME
d4a8a86c 2383The wallclock (RTC) time in microseconds.
0b55b16a
VP
2384
2385@item RTCSTART
d4a8a86c 2386The wallclock (RTC) time at the start of the movie in microseconds.
0b55b16a 2387
0ebfdae0 2388@item TB
d4a8a86c 2389The timebase of the input timestamps.
0ebfdae0 2390
a532bb39
SS
2391@end table
2392
d4a8a86c 2393Some examples:
a532bb39
SS
2394
2395@example
d4a8a86c 2396# Start counting the PTS from zero
33b97faa 2397setpts=expr=PTS-STARTPTS
a532bb39 2398
d4a8a86c 2399# Fast motion
33b97faa 2400setpts=expr=0.5*PTS
a532bb39 2401
d4a8a86c 2402# Slow motion
a532bb39
SS
2403setpts=2.0*PTS
2404
d4a8a86c 2405# Fixed rate 25 fps
a532bb39
SS
2406setpts=N/(25*TB)
2407
d4a8a86c 2408# Fixed rate 25 fps with some jitter
a532bb39 2409setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
0b55b16a 2410
d4a8a86c 2411# Generate timestamps from a "live source" and rebase onto the current timebase
0b55b16a 2412setpts='(RTCTIME - RTCSTART) / (TB * 1000000)"
a532bb39
SS
2413@end example
2414
2fd8756b
SS
2415@anchor{setsar}
2416@section setsar
2417
2418Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
2419
2420Note that as a consequence of the application of this filter, the
2421output display aspect ratio will change according to the following
2422equation:
2423@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2424
2425Keep in mind that the sample aspect ratio set by this filter may be
2426changed by later filters in the filterchain, e.g. if another "setsar"
2427or a "setdar" filter is applied.
2428
d4a8a86c 2429It accepts the following parameters:
2831b307
AK
2430
2431@table @option
2432
2433@item sar
d4a8a86c 2434The output sample aspect ratio.
2831b307
AK
2435
2436@end table
2fd8756b 2437
34a0ac41
RP
2438The parameter @var{sar} is an expression containing
2439the following constants:
2440
2441@table @option
2442@item E, PI, PHI
d4a8a86c
KBA
2443These are approximated values for the mathematical constants e
2444(Euler's number), pi (Greek pi), and phi (the golden ratio).
34a0ac41
RP
2445
2446@item w, h
d4a8a86c 2447The input width and height.
34a0ac41
RP
2448
2449@item a
d4a8a86c 2450These are the same as @var{w} / @var{h}.
34a0ac41
RP
2451
2452@item sar
d4a8a86c 2453The input sample aspect ratio.
34a0ac41
RP
2454
2455@item dar
d4a8a86c
KBA
2456The input display aspect ratio. It is the same as
2457(@var{w} / @var{h}) * @var{sar}.
34a0ac41
RP
2458
2459@item hsub, vsub
d4a8a86c 2460Horizontal and vertical chroma subsample values. For example, for the
34a0ac41
RP
2461pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2462@end table
2463
d4a8a86c 2464To change the sample aspect ratio to 10:11, specify:
2fd8756b 2465@example
2831b307 2466setsar=sar=10/11
2fd8756b
SS
2467@end example
2468
d89e3b36
SS
2469@section settb
2470
2471Set the timebase to use for the output frames timestamps.
2472It is mainly useful for testing timebase configuration.
2473
d4a8a86c 2474It accepts the following parameters:
ffea3b00
AK
2475
2476@table @option
2477
2478@item expr
2479The expression which is evaluated into the output timebase.
2480
2481@end table
2482
d89e3b36
SS
2483The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
2484default timebase), and "intb" (the input timebase).
2485
2486The default value for the input is "intb".
2487
d4a8a86c 2488Some examples:
d89e3b36
SS
2489
2490@example
d4a8a86c 2491# Set the timebase to 1/25
ffea3b00 2492settb=expr=1/25
d89e3b36 2493
d4a8a86c 2494# Set the timebase to 1/10
ffea3b00 2495settb=expr=0.1
d89e3b36 2496
d4a8a86c 2497# Set the timebase to 1001/1000
d89e3b36
SS
2498settb=1+0.001
2499
d4a8a86c 2500#Set the timebase to 2*intb
d89e3b36
SS
2501settb=2*intb
2502
d4a8a86c 2503#Set the default timebase value
d89e3b36
SS
2504settb=AVTB
2505@end example
2506
ee42716b
SS
2507@section showinfo
2508
2509Show a line containing various information for each input video frame.
2510The input video is not modified.
2511
2512The shown line contains a sequence of key/value pairs of the form
2513@var{key}:@var{value}.
2514
d4a8a86c 2515It accepts the following parameters:
ee42716b
SS
2516
2517@table @option
2518@item n
d4a8a86c 2519The (sequential) number of the input frame, starting from 0.
ee42716b
SS
2520
2521@item pts
d4a8a86c 2522The Presentation TimeStamp of the input frame, expressed as a number of
ee42716b
SS
2523time base units. The time base unit depends on the filter input pad.
2524
2525@item pts_time
d4a8a86c
KBA
2526The Presentation TimeStamp of the input frame, expressed as a number of
2527seconds.
ee42716b
SS
2528
2529@item pos
d4a8a86c
KBA
2530The position of the frame in the input stream, or -1 if this information is
2531unavailable and/or meaningless (for example in case of synthetic video).
ee42716b
SS
2532
2533@item fmt
d4a8a86c 2534The pixel format name.
ee42716b
SS
2535
2536@item sar
d4a8a86c
KBA
2537The sample aspect ratio of the input frame, expressed in the form
2538@var{num}/@var{den}.
ee42716b
SS
2539
2540@item s
d4a8a86c
KBA
2541The size of the input frame, expressed in the form
2542@var{width}x@var{height}.
ee42716b
SS
2543
2544@item i
d4a8a86c
KBA
2545The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
2546for bottom field first).
ee42716b
SS
2547
2548@item iskey
d4a8a86c 2549This is 1 if the frame is a key frame, 0 otherwise.
ee42716b
SS
2550
2551@item type
d4a8a86c
KBA
2552The picture type of the input frame ("I" for an I-frame, "P" for a
2553P-frame, "B" for a B-frame, or "?" for an unknown type).
2554Also refer to the documentation of the @code{AVPictureType} enum and of
ee42716b
SS
2555the @code{av_get_picture_type_char} function defined in
2556@file{libavutil/avutil.h}.
2557
2558@item checksum
d4a8a86c 2559The Adler-32 checksum of all the planes of the input frame.
ee42716b
SS
2560
2561@item plane_checksum
d4a8a86c
KBA
2562The Adler-32 checksum of each plane of the input frame, expressed in the form
2563"[@var{c0} @var{c1} @var{c2} @var{c3}]".
ee42716b
SS
2564@end table
2565
599b81ca
AK
2566@section shuffleplanes
2567
2568Reorder and/or duplicate video planes.
2569
d4a8a86c 2570It accepts the following parameters:
599b81ca
AK
2571
2572@table @option
2573
2574@item map0
2575The index of the input plane to be used as the first output plane.
2576
2577@item map1
2578The index of the input plane to be used as the second output plane.
2579
2580@item map2
2581The index of the input plane to be used as the third output plane.
2582
2583@item map3
2584The index of the input plane to be used as the fourth output plane.
2585
2586@end table
2587
2588The first plane has the index 0. The default is to keep the input unchanged.
2589
d4a8a86c 2590Swap the second and third planes of the input:
599b81ca
AK
2591@example
2592avconv -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
2593@end example
599b81ca 2594
fd18ee0f
AK
2595@section split
2596
2597Split input video into several identical outputs.
2598
d4a8a86c 2599It accepts a single parameter, which specifies the number of outputs. If
fd18ee0f
AK
2600unspecified, it defaults to 2.
2601
d4a8a86c 2602Create 5 copies of the input video:
fd18ee0f
AK
2603@example
2604avconv -i INPUT -filter_complex split=5 OUTPUT
2605@end example
fd18ee0f 2606
43945b27
SS
2607@section transpose
2608
2609Transpose rows with columns in the input video and optionally flip it.
2610
d4a8a86c 2611It accepts the following parameters:
0c2466de
AK
2612
2613@table @option
2614
2615@item dir
2616The direction of the transpose.
2617
2618@end table
2619
2620The direction can assume the following values:
43945b27
SS
2621
2622@table @samp
0c2466de 2623@item cclock_flip
43945b27
SS
2624Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2625@example
2626L.R L.l
2627. . -> . .
2628l.r R.r
2629@end example
2630
0c2466de 2631@item clock
43945b27
SS
2632Rotate by 90 degrees clockwise, that is:
2633@example
2634L.R l.L
2635. . -> . .
2636l.r r.R
2637@end example
2638
0c2466de 2639@item cclock
43945b27
SS
2640Rotate by 90 degrees counterclockwise, that is:
2641@example
2642L.R R.r
2643. . -> . .
2644l.r L.l
2645@end example
2646
0c2466de 2647@item clock_flip
43945b27
SS
2648Rotate by 90 degrees clockwise and vertically flip, that is:
2649@example
2650L.R r.R
2651. . -> . .
2652l.r l.L
2653@end example
2654@end table
2655
a1e05b04
AK
2656@section trim
2657Trim the input so that the output contains one continuous subpart of the input.
2658
d4a8a86c 2659It accepts the following parameters:
a1e05b04
AK
2660@table @option
2661@item start
d4a8a86c 2662The timestamp (in seconds) of the start of the kept section. The frame with the
a1e05b04
AK
2663timestamp @var{start} will be the first frame in the output.
2664
2665@item end
d4a8a86c 2666The timestamp (in seconds) of the first frame that will be dropped. The frame
a1e05b04
AK
2667immediately preceding the one with the timestamp @var{end} will be the last
2668frame in the output.
2669
2670@item start_pts
d4a8a86c
KBA
2671This is the same as @var{start}, except this option sets the start timestamp
2672in timebase units instead of seconds.
a1e05b04
AK
2673
2674@item end_pts
d4a8a86c
KBA
2675This is the same as @var{end}, except this option sets the end timestamp
2676in timebase units instead of seconds.
a1e05b04
AK
2677
2678@item duration
d4a8a86c 2679The maximum duration of the output in seconds.
a1e05b04
AK
2680
2681@item start_frame
d4a8a86c 2682The number of the first frame that should be passed to the output.
a1e05b04
AK
2683
2684@item end_frame
d4a8a86c 2685The number of the first frame that should be dropped.
a1e05b04
AK
2686@end table
2687
2688Note that the first two sets of the start/end options and the @option{duration}
2689option look at the frame timestamp, while the _frame variants simply count the
2690frames that pass through the filter. Also note that this filter does not modify
d4a8a86c 2691the timestamps. If you wish for the output timestamps to start at zero, insert a
a1e05b04
AK
2692setpts filter after the trim filter.
2693
2694If multiple start or end options are set, this filter tries to be greedy and
2695keep all the frames that match at least one of the specified constraints. To keep
2696only the part that matches all the constraints at once, chain multiple trim
2697filters.
2698
2699The defaults are such that all the input is kept. So it is possible to set e.g.
2700just the end values to keep everything before the specified time.
2701
2702Examples:
2703@itemize
2704@item
d4a8a86c 2705Drop everything except the second minute of input:
a1e05b04
AK
2706@example
2707avconv -i INPUT -vf trim=60:120
2708@end example
2709
2710@item
d4a8a86c 2711Keep only the first second:
a1e05b04
AK
2712@example
2713avconv -i INPUT -vf trim=duration=1
2714@end example
2715
2716@end itemize
3275ac6a
SS
2717@section unsharp
2718
843b5fd0
SS
2719Sharpen or blur the input video.
2720
2721It accepts the following parameters:
3275ac6a
SS
2722
2723@table @option
2724
2725@item luma_msize_x
d4a8a86c
KBA
2726Set the luma matrix horizontal size. It must be an integer between 3
2727and 13. The default value is 5.
3275ac6a
SS
2728
2729@item luma_msize_y
d4a8a86c
KBA
2730Set the luma matrix vertical size. It must be an integer between 3
2731and 13. The default value is 5.
3275ac6a
SS
2732
2733@item luma_amount
d4a8a86c
KBA
2734Set the luma effect strength. It must be a floating point number between -2.0
2735and 5.0. The default value is 1.0.
3275ac6a
SS
2736
2737@item chroma_msize_x
d4a8a86c
KBA
2738Set the chroma matrix horizontal size. It must be an integer between 3
2739and 13. The default value is 5.
3275ac6a
SS
2740
2741@item chroma_msize_y
d4a8a86c
KBA
2742Set the chroma matrix vertical size. It must be an integer between 3
2743and 13. The default value is 5.
3275ac6a 2744
2725f2d4 2745@item chroma_amount
d4a8a86c
KBA
2746Set the chroma effect strength. It must be a floating point number between -2.0
2747and 5.0. The default value is 0.0.
3275ac6a
SS
2748
2749@end table
2750
b83e9efc
AK
2751Negative values for the amount will blur the input video, while positive
2752values will sharpen. All parameters are optional and default to the
2753equivalent of the string '5:5:1.0:5:5:0.0'.
2754
3275ac6a
SS
2755@example
2756# Strong luma sharpen effect parameters
b83e9efc 2757unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
3275ac6a 2758
d4a8a86c 2759# A strong blur of both luma and chroma parameters
3275ac6a
SS
2760unsharp=7:7:-2:7:7:-2
2761
9270b8a3
LB
2762# Use the default values with @command{avconv}
2763./avconv -i in.avi -vf "unsharp" out.mp4
3275ac6a
SS
2764@end example
2765
2766@section vflip
2767
2768Flip the input video vertically.
2769
2770@example
9270b8a3 2771./avconv -i in.avi -vf "vflip" out.avi
3275ac6a
SS
2772@end example
2773
acbac567
MN
2774@section yadif
2775
1653027a
SS
2776Deinterlace the input video ("yadif" means "yet another deinterlacing
2777filter").
acbac567 2778
d4a8a86c 2779It accepts the following parameters:
7536c671
AK
2780
2781@table @option
acbac567 2782
7536c671 2783@item mode
d4a8a86c 2784The interlacing mode to adopt. It accepts one of the following values:
acbac567 2785
1653027a
SS
2786@table @option
2787@item 0
d4a8a86c 2788Output one frame for each frame.
1653027a 2789@item 1
d4a8a86c 2790Output one frame for each field.
1653027a 2791@item 2
d4a8a86c 2792Like 0, but it skips the spatial interlacing check.
1653027a 2793@item 3
d4a8a86c 2794Like 1, but it skips the spatial interlacing check.
1653027a 2795@end table
acbac567 2796
d4a8a86c 2797The default value is 0.
acbac567 2798
7536c671 2799@item parity
d4a8a86c
KBA
2800The picture field parity assumed for the input interlaced video. It accepts one
2801of the following values:
acbac567 2802
1653027a
SS
2803@table @option
2804@item 0
d4a8a86c 2805Assume the top field is first.
4703a7b5 2806@item 1
d4a8a86c 2807Assume the bottom field is first.
1653027a 2808@item -1
d4a8a86c 2809Enable automatic detection of field parity.
acbac567
MN
2810@end table
2811
d4a8a86c
KBA
2812The default value is -1.
2813If the interlacing is unknown or the decoder does not export this information,
a51c71bb 2814top field first will be assumed.
1653027a 2815
7536c671 2816@item auto
d4a8a86c
KBA
2817Whether the deinterlacer should trust the interlaced flag and only deinterlace
2818frames marked as interlaced.
ab09df9d
JP
2819
2820@table @option
2821@item 0
d4a8a86c 2822Deinterlace all frames.
ab09df9d 2823@item 1
d4a8a86c 2824Only deinterlace frames marked as interlaced.
ab09df9d
JP
2825@end table
2826
d4a8a86c 2827The default value is 0.
ab09df9d 2828
7536c671
AK
2829@end table
2830
3275ac6a
SS
2831@c man end VIDEO FILTERS
2832
2833@chapter Video Sources
2834@c man begin VIDEO SOURCES
2835
2836Below is a description of the currently available video sources.
2837
24413399
SS
2838@section buffer
2839
2840Buffer video frames, and make them available to the filter chain.
2841
2842This source is mainly intended for a programmatic use, in particular
ac1a31ab 2843through the interface defined in @file{libavfilter/vsrc_buffer.h}.
24413399 2844
d4a8a86c 2845It accepts the following parameters:
24413399 2846
d28cb849 2847@table @option
24413399 2848
d28cb849 2849@item width
d4a8a86c 2850The input video width.
24413399 2851
d28cb849 2852@item height
d4a8a86c 2853The input video height.
24413399 2854
d28cb849 2855@item pix_fmt
d4a8a86c 2856The name of the input video pixel format.
24413399 2857
d28cb849
AK
2858@item time_base
2859The time base used for input timestamps.
24413399 2860
d28cb849 2861@item sar
d4a8a86c 2862The sample (pixel) aspect ratio of the input video.
7a11c82f 2863
24413399
SS
2864@end table
2865
2866For example:
2867@example
d28cb849 2868buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
24413399
SS
2869@end example
2870
2871will instruct the source to accept video frames with size 320x240 and
7a11c82f
MN
2872with format "yuv410p", assuming 1/24 as the timestamps timebase and
2873square pixels (1:1 sample aspect ratio).
24413399 2874
23ccf3c7
SS
2875@section color
2876
2877Provide an uniformly colored input.
2878
2879It accepts the following parameters:
23ccf3c7
SS
2880
2881@table @option
2882
2883@item color
2884Specify the color of the source. It can be the name of a color (case
2885insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2886alpha specifier. The default value is "black".
2887
7bc1a883 2888@item size
23ccf3c7 2889Specify the size of the sourced video, it may be a string of the form
e83c2dde 2890@var{width}x@var{height}, or the name of a size abbreviation. The
23ccf3c7
SS
2891default value is "320x240".
2892
7bc1a883 2893@item framerate
23ccf3c7
SS
2894Specify the frame rate of the sourced video, as the number of frames
2895generated per second. It has to be a string in the format
d4a8a86c 2896@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23ccf3c7
SS
2897number or a valid video frame rate abbreviation. The default value is
2898"25".
2899
2900@end table
2901
d4a8a86c 2902The following graph description will generate a red source
23ccf3c7
SS
2903with an opacity of 0.2, with size "qcif" and a frame rate of 10
2904frames per second, which will be overlayed over the source connected
d4a8a86c 2905to the pad with identifier "in":
23ccf3c7
SS
2906
2907@example
2908"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2909@end example
2910
9409c381
SS
2911@section movie
2912
2913Read a video stream from a movie container.
2914
7ca14c73
AK
2915Note that this source is a hack that bypasses the standard input path. It can be
2916useful in applications that do not support arbitrary filter graphs, but its use
d4a8a86c
KBA
2917is discouraged in those that do. It should never be used with
2918@command{avconv}; the @option{-filter_complex} option fully replaces it.
7ca14c73 2919
d4a8a86c 2920It accepts the following parameters:
9409c381
SS
2921
2922@table @option
2923
a42d6e6c 2924@item filename
d4a8a86c
KBA
2925The name of the resource to read (not necessarily a file; it can also be a
2926device or a stream accessed through some protocol).
a42d6e6c 2927
9409c381
SS
2928@item format_name, f
2929Specifies the format assumed for the movie to read, and can be either
d4a8a86c 2930the name of a container or an input device. If not specified, the
9409c381
SS
2931format is guessed from @var{movie_name} or by probing.
2932
2933@item seek_point, sp
d4a8a86c
KBA
2934Specifies the seek point in seconds. The frames will be output
2935starting from this seek point. The parameter is evaluated with
2936@code{av_strtod}, so the numerical value may be suffixed by an IS
2937postfix. The default value is "0".
9409c381
SS
2938
2939@item stream_index, si
2940Specifies the index of the video stream to read. If the value is -1,
d4a8a86c 2941the most suitable video stream will be automatically selected. The default
9409c381
SS
2942value is "-1".
2943
2944@end table
2945
d4a8a86c
KBA
2946It allows overlaying a second video on top of the main input of
2947a filtergraph, as shown in this graph:
9409c381
SS
2948@example
2949input -----------> deltapts0 --> overlay --> output
2950 ^
2951 |
2952movie --> scale--> deltapts1 -------+
2953@end example
2954
d4a8a86c 2955Some examples:
9409c381 2956@example
d4a8a86c
KBA
2957# Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
2958# on top of the input labelled "in"
9409c381
SS
2959movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2960[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2961
d4a8a86c
KBA
2962# Read from a video4linux2 device, and overlay it on top of the input
2963# labelled "in"
9409c381
SS
2964movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2965[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2966
2967@end example
2968
3275ac6a
SS
2969@section nullsrc
2970
d4a8a86c 2971Null video source: never return images. It is mainly useful as a
3275ac6a
SS
2972template and to be employed in analysis / debugging tools.
2973
d4a8a86c
KBA
2974It accepts a string of the form
2975@var{width}:@var{height}:@var{timebase} as an optional parameter.
3275ac6a 2976
16134b7c
SS
2977@var{width} and @var{height} specify the size of the configured
2978source. The default values of @var{width} and @var{height} are
2979respectively 352 and 288 (corresponding to the CIF size format).
2980
2981@var{timebase} specifies an arithmetic expression representing a
d4a8a86c 2982timebase. The expression can contain the constants "PI", "E", "PHI", and
16134b7c 2983"AVTB" (the default timebase), and defaults to the value "AVTB".
3275ac6a 2984
f8608dca
SS
2985@section frei0r_src
2986
2987Provide a frei0r source.
2988
2989To enable compilation of this filter you need to install the frei0r
f8a45fa1 2990header and configure Libav with --enable-frei0r.
f8608dca 2991
d4a8a86c 2992This source accepts the following parameters:
5aa1a668
AK
2993
2994@table @option
2995
2996@item size
d4a8a86c 2997The size of the video to generate. It may be a string of the form
5aa1a668 2998@var{width}x@var{height} or a frame size abbreviation.
f8608dca 2999
5aa1a668 3000@item framerate
d4a8a86c 3001The framerate of the generated video. It may be a string of the form
5aa1a668
AK
3002@var{num}/@var{den} or a frame rate abbreviation.
3003
3004@item filter_name
3005The name to the frei0r source to load. For more information regarding frei0r and
d4a8a86c
KBA
3006how to set the parameters, read the @ref{frei0r} section in the video filters
3007documentation.
5aa1a668
AK
3008
3009@item filter_params
3010A '|'-separated list of parameters to pass to the frei0r source.
3011
3012@end table
f8608dca 3013
d4a8a86c 3014An example:
f8608dca 3015@example
d4a8a86c 3016# Generate a frei0r partik0l source with size 200x200 and framerate 10
f8608dca 3017# which is overlayed on the overlay filter main input
5aa1a668 3018frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
f8608dca
SS
3019@end example
3020
ec2ac927 3021@section rgbtestsrc, testsrc
0244879f 3022
ec2ac927
SS
3023The @code{rgbtestsrc} source generates an RGB test pattern useful for
3024detecting RGB vs BGR issues. You should see a red, green and blue
3025stripe from top to bottom.
0244879f 3026
ec2ac927
SS
3027The @code{testsrc} source generates a test video pattern, showing a
3028color pattern, a scrolling gradient and a timestamp. This is mainly
3029intended for testing purposes.
3030
d4a8a86c 3031The sources accept the following parameters:
0244879f
SS
3032
3033@table @option
3034
3035@item size, s
3036Specify the size of the sourced video, it may be a string of the form
da9cea77 3037@var{width}x@var{height}, or the name of a size abbreviation. The
0244879f
SS
3038default value is "320x240".
3039
3040@item rate, r
3041Specify the frame rate of the sourced video, as the number of frames
3042generated per second. It has to be a string in the format
d4a8a86c 3043@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
0244879f
SS
3044number or a valid video frame rate abbreviation. The default value is
3045"25".
3046
3047@item sar
3048Set the sample aspect ratio of the sourced video.
3049
3050@item duration
3051Set the video duration of the sourced video. The accepted syntax is:
3052@example
3053[-]HH[:MM[:SS[.m...]]]
3054[-]S+[.m...]
3055@end example
d4a8a86c 3056Also see the the @code{av_parse_time()} function.
0244879f
SS
3057
3058If not specified, or the expressed duration is negative, the video is
3059supposed to be generated forever.
3060@end table
3061
3062For example the following:
3063@example
3064testsrc=duration=5.3:size=qcif:rate=10
3065@end example
3066
3067will generate a video with a duration of 5.3 seconds, with size
3068176x144 and a framerate of 10 frames per second.
3069
3275ac6a
SS
3070@c man end VIDEO SOURCES
3071
3072@chapter Video Sinks
3073@c man begin VIDEO SINKS
3074
3075Below is a description of the currently available video sinks.
3076
ac712309
AK
3077@section buffersink
3078
3079Buffer video frames, and make them available to the end of the filter
3080graph.
3081
d4a8a86c 3082This sink is intended for programmatic use through the interface defined in
ac712309
AK
3083@file{libavfilter/buffersink.h}.
3084
3275ac6a
SS
3085@section nullsink
3086
d4a8a86c
KBA
3087Null video sink: do absolutely nothing with the input video. It is
3088mainly useful as a template and for use in analysis / debugging
3275ac6a
SS
3089tools.
3090
3091@c man end VIDEO SINKS