lavfi: new interlace filter
[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
8side connecting it to the one filter accepting its output.
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
14A filter with no input pads is called a "source", a filter with no
15output pads is called a "sink".
16
3b266da3 17@anchor{Filtergraph syntax}
1ebe5c4c
SS
18@section Filtergraph syntax
19
7ce118ba
AK
20A filtergraph can be represented using a textual representation, which is
21recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
22options in @command{avconv} and @option{-vf} in @command{avplay}, and by the
23@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function 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
b439c992
AK
44initialize the filter instance. It may have one of the two allowed forms:
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.
84For example in the filterchain:
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
12e7e1d0
AK
98Libavfilter will automatically insert scale filters where format
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
1ebe5c4c
SS
104Follows a BNF description for the filtergraph syntax:
105@example
106@var{NAME} ::= sequence of alphanumeric characters and '_'
107@var{LINKLABEL} ::= "[" @var{NAME} "]"
108@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
109@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually 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
132The filter accepts the following named parameters:
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
148For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
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
164The filter accepts the following named parameters:
165@table @option
166
167@item inputs
168Number of inputs. If unspecified, it defaults to 2.
169
170@item duration
171How to determine the end-of-stream.
172@table @option
173
174@item longest
175Duration of longest input. (default)
176
177@item shortest
178Duration of shortest input.
179
180@item first
181Duration of first input.
182
183@end table
184
185@item dropout_transition
186Transition time, in seconds, for volume renormalization when an input
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
20dd41af
AK
195@section ashowinfo
196
197Show a line containing various information for each input audio frame.
198The input audio is not modified.
199
200The shown line contains a sequence of key/value pairs of the form
201@var{key}:@var{value}.
202
203A description of each shown parameter follows:
204
205@table @option
206@item n
207sequential number of the input frame, starting from 0
208
209@item pts
210Presentation timestamp of the input frame, in time base units; the time base
211depends on the filter input pad, and is usually 1/@var{sample_rate}.
212
213@item pts_time
214presentation timestamp of the input frame in seconds
215
216@item fmt
217sample format
218
219@item chlayout
220channel layout
221
222@item rate
223sample rate for the audio frame
224
225@item nb_samples
226number of samples (per channel) in the frame
227
228@item checksum
229Adler-32 checksum (printed in hexadecimal) of the audio data. For planar audio
230the data is treated as if all the planes were concatenated.
231
232@item plane_checksums
233A list of Adler-32 checksums for each data plane.
234@end table
235
afeb3590
JR
236@section asplit
237
238Split input audio into several identical outputs.
239
240The filter accepts a single parameter which specifies the number of outputs. If
241unspecified, it defaults to 2.
242
243For example
244@example
245avconv -i INPUT -filter_complex asplit=5 OUTPUT
246@end example
247will create 5 copies of the input audio.
248
9f26421b
AK
249@section asyncts
250Synchronize audio data with timestamps by squeezing/stretching it and/or
251dropping samples/adding silence when needed.
252
253The filter accepts the following named parameters:
254@table @option
255
256@item compensate
04438790
AU
257Enable stretching/squeezing the data to make it match the timestamps. Disabled
258by default. When disabled, time gaps are covered with silence.
9f26421b
AK
259
260@item min_delta
261Minimum difference between timestamps and audio data (in seconds) to trigger
04438790
AU
262adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
263this filter, try setting this parameter to 0.
9f26421b
AK
264
265@item max_comp
04438790
AU
266Maximum compensation in samples per second. Relevant only with compensate=1.
267Default value 500.
9f26421b 268
70d71b58 269@item first_pts
b35e5d98 270Assume the first pts should be this value. The time base is 1 / sample rate.
70d71b58
JR
271This allows for padding/trimming at the start of stream. By default, no
272assumption is made about the first frame's expected pts, so no padding or
273trimming is done. For example, this could be set to 0 to pad the beginning with
b35e5d98
JR
274silence if an audio stream starts after the video stream or to trim any samples
275with a negative pts due to encoder delay.
70d71b58 276
9f26421b
AK
277@end table
278
d6251368
AK
279@section channelsplit
280Split each channel in input audio stream into a separate output stream.
281
282This filter accepts the following named parameters:
283@table @option
284@item channel_layout
285Channel layout of the input stream. Default is "stereo".
286@end table
287
288For example, assuming a stereo input MP3 file
289@example
290avconv -i in.mp3 -filter_complex channelsplit out.mkv
291@end example
292will create an output Matroska file with two audio streams, one containing only
293the left channel and the other the right channel.
294
295To split a 5.1 WAV file into per-channel files
296@example
297avconv -i in.wav -filter_complex
298'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
299-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
300front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
301side_right.wav
302@end example
303
41e637e4
AC
304@section channelmap
305Remap input channels to new locations.
306
307This filter accepts the following named parameters:
308@table @option
309@item channel_layout
310Channel layout of the output stream.
311
312@item map
ba8efac9 313Map channels from input to output. The argument is a '|'-separated list of
41e637e4
AC
314mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
315@var{in_channel} form. @var{in_channel} can be either the name of the input
316channel (e.g. FL for front left) or its index in the input channel layout.
317@var{out_channel} is the name of the output channel or its index in the output
318channel layout. If @var{out_channel} is not given then it is implicitly an
319index, starting with zero and increasing by one for each mapping.
320@end table
321
322If no mapping is present, the filter will implicitly map input channels to
323output channels preserving index.
324
325For example, assuming a 5.1+downmix input MOV file
326@example
ba8efac9 327avconv -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
41e637e4
AC
328@end example
329will create an output WAV file tagged as stereo from the downmix channels of
330the input.
331
332To fix a 5.1 WAV improperly encoded in AAC's native channel order
333@example
ba8efac9 334avconv -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
41e637e4
AC
335@end example
336
dc07fb6f
AK
337@section join
338Join multiple input streams into one multi-channel stream.
339
340The filter accepts the following named parameters:
341@table @option
342
343@item inputs
344Number of input streams. Defaults to 2.
345
346@item channel_layout
347Desired output channel layout. Defaults to stereo.
348
349@item map
dd7fc37c 350Map channels from inputs to output. The argument is a '|'-separated list of
dc07fb6f
AK
351mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
352form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
7a8059eb 353can be either the name of the input channel (e.g. FL for front left) or its
dc07fb6f
AK
354index in the specified input stream. @var{out_channel} is the name of the output
355channel.
356@end table
357
358The filter will attempt to guess the mappings when those are not specified
359explicitly. It does so by first trying to find an unused matching input channel
360and if that fails it picks the first unused input channel.
361
362E.g. to join 3 inputs (with properly set channel layouts)
363@example
364avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
365@end example
366
367To build a 5.1 output from 6 single-channel streams:
368@example
369avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
dd7fc37c 370'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
371out
372@end example
373
d371e7b9
AK
374@section resample
375Convert the audio sample format, sample rate and channel layout. This filter is
376not meant to be used directly, it is inserted automatically by libavfilter
377whenever conversion is needed. Use the @var{aformat} filter to force a specific
378conversion.
379
b384e031
JR
380@section volume
381
382Adjust the input audio volume.
383
384The filter accepts the following named parameters:
385@table @option
386
387@item volume
388Expresses how the audio volume will be increased or decreased.
389
390Output values are clipped to the maximum value.
391
392The output audio volume is given by the relation:
393@example
394@var{output_volume} = @var{volume} * @var{input_volume}
395@end example
396
397Default value for @var{volume} is 1.0.
398
399@item precision
400Mathematical precision.
401
402This determines which input sample formats will be allowed, which affects the
403precision of the volume scaling.
404
405@table @option
406@item fixed
4078-bit fixed-point; limits input sample format to U8, S16, and S32.
408@item float
40932-bit floating-point; limits input sample format to FLT. (default)
410@item double
41164-bit floating-point; limits input sample format to DBL.
412@end table
413@end table
414
415@subsection Examples
416
417@itemize
418@item
419Halve the input audio volume:
420@example
421volume=volume=0.5
422volume=volume=1/2
423volume=volume=-6.0206dB
424@end example
425
426@item
427Increase input audio power by 6 decibels using fixed-point precision:
428@example
429volume=volume=6dB:precision=fixed
430@end example
431@end itemize
432
f59e9eaf
SS
433@c man end AUDIO FILTERS
434
1ee410f3
SS
435@chapter Audio Sources
436@c man begin AUDIO SOURCES
437
438Below is a description of the currently available audio sources.
439
440@section anullsrc
441
442Null audio source, never return audio frames. It is mainly useful as a
443template and to be employed in analysis / debugging tools.
444
445It accepts as optional parameter a string of the form
446@var{sample_rate}:@var{channel_layout}.
447
448@var{sample_rate} specify the sample rate, and defaults to 44100.
449
450@var{channel_layout} specify the channel layout, and can be either an
451integer or a string representing a channel layout. The default value
452of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
453
454Check the channel_layout_map definition in
a903f8f0 455@file{libavutil/channel_layout.c} for the mapping between strings and
6ef93402 456channel layout values.
1ee410f3
SS
457
458Follow some examples:
459@example
460# set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO.
461anullsrc=48000:4
462
463# same as
464anullsrc=48000:mono
465@end example
466
4c66c407
AK
467@section abuffer
468Buffer audio frames, and make them available to the filter chain.
469
470This source is not intended to be part of user-supplied graph descriptions but
471for insertion by calling programs through the interface defined in
472@file{libavfilter/buffersrc.h}.
473
474It accepts the following named parameters:
475@table @option
476
477@item time_base
478Timebase which will be used for timestamps of submitted frames. It must be
479either a floating-point number or in @var{numerator}/@var{denominator} form.
480
481@item sample_rate
482Audio sample rate.
483
484@item sample_fmt
485Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
486
487@item channel_layout
488Channel layout of the audio data, in the form that can be accepted by
489@code{av_get_channel_layout()}.
490@end table
491
492All the parameters need to be explicitly defined.
493
1ee410f3
SS
494@c man end AUDIO SOURCES
495
f0a55438
HM
496@chapter Audio Sinks
497@c man begin AUDIO SINKS
498
499Below is a description of the currently available audio sinks.
500
501@section anullsink
502
503Null audio sink, do absolutely nothing with the input audio. It is
504mainly useful as a template and to be employed in analysis / debugging
505tools.
506
a2cd9be2
AK
507@section abuffersink
508This sink is intended for programmatic use. Frames that arrive on this sink can
509be retrieved by the calling program using the interface defined in
510@file{libavfilter/buffersink.h}.
511
512This filter accepts no parameters.
513
f0a55438
HM
514@c man end AUDIO SINKS
515
3275ac6a
SS
516@chapter Video Filters
517@c man begin VIDEO FILTERS
518
f8a45fa1 519When you configure your Libav build, you can disable any of the
3275ac6a
SS
520existing filters using --disable-filters.
521The configure output will show the video filters included in your
522build.
523
524Below is a description of the currently available video filters.
525
13fabd7a
SS
526@section blackframe
527
528Detect frames that are (almost) completely black. Can be useful to
529detect chapter transitions or commercials. Output lines consist of
530the frame number of the detected frame, the percentage of blackness,
531the position in the file if known or -1 and the timestamp in seconds.
532
533In order to display the output lines, you need to set the loglevel at
534least to the AV_LOG_INFO value.
535
62dcdb02
AK
536The filter accepts the following options:
537
538@table @option
539
540@item amount
541The percentage of the pixels that have to be below the threshold, defaults to
54298.
13fabd7a 543
62dcdb02
AK
544@item threshold
545Threshold below which a pixel value is considered black, defaults to 32.
13fabd7a 546
62dcdb02 547@end table
13fabd7a 548
ce6b6ef6
SS
549@section boxblur
550
551Apply boxblur algorithm to the input video.
552
51def31d
AK
553This filter accepts the following options:
554
555@table @option
556
557@item luma_radius
558@item luma_power
559@item chroma_radius
560@item chroma_power
561@item alpha_radius
562@item alpha_power
563
564@end table
ce6b6ef6
SS
565
566Chroma and alpha parameters are optional, if not specified they default
567to the corresponding values set for @var{luma_radius} and
568@var{luma_power}.
569
570@var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
571the radius in pixels of the box used for blurring the corresponding
572input plane. They are expressions, and can contain the following
573constants:
574@table @option
575@item w, h
da9cea77 576the input width and height in pixels
ce6b6ef6
SS
577
578@item cw, ch
579the input chroma image width and height in pixels
580
581@item hsub, vsub
582horizontal and vertical chroma subsample values. For example for the
583pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
584@end table
585
586The radius must be a non-negative number, and must not be greater than
587the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
588and of @code{min(cw,ch)/2} for the chroma planes.
589
590@var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
591how many times the boxblur filter is applied to the corresponding
592plane.
593
594Some examples follow:
595
596@itemize
597
598@item
599Apply a boxblur filter with luma, chroma, and alpha radius
600set to 2:
601@example
51def31d 602boxblur=luma_radius=2:luma_power=1
ce6b6ef6
SS
603@end example
604
605@item
606Set luma radius to 2, alpha and chroma radius to 0
607@example
608boxblur=2:1:0:0:0:0
609@end example
610
611@item
612Set luma and chroma radius to a fraction of the video dimension
613@example
51def31d 614boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
ce6b6ef6
SS
615@end example
616
617@end itemize
618
b5670209
SS
619@section copy
620
621Copy the input source unchanged to the output. Mainly useful for
622testing purposes.
623
3275ac6a
SS
624@section crop
625
fba0156a
AK
626Crop the input video to given dimensions.
627
628This filter accepts the following options:
629
630@table @option
631
632@item out_w
633Width of the output video.
634
635@item out_h
636Height of the output video.
637
638@item x
639Horizontal position, in the input video, of the left edge of the output video.
640
641@item y
642Vertical position, in the input video, of the top edge of the output video.
643
644@end table
3275ac6a 645
75b67a8a
SS
646The parameters are expressions containing the following constants:
647
648@table @option
649@item E, PI, PHI
650the corresponding mathematical approximated values for e
651(euler number), pi (greek PI), PHI (golden ratio)
652
653@item x, y
654the computed values for @var{x} and @var{y}. They are evaluated for
655each new frame.
656
657@item in_w, in_h
e83c2dde 658the input width and height
75b67a8a
SS
659
660@item iw, ih
661same as @var{in_w} and @var{in_h}
662
663@item out_w, out_h
e83c2dde 664the output (cropped) width and height
75b67a8a
SS
665
666@item ow, oh
667same as @var{out_w} and @var{out_h}
668
669@item n
670the number of input frame, starting from 0
671
75b67a8a
SS
672@item t
673timestamp expressed in seconds, NAN if the input timestamp is unknown
3275ac6a 674
75b67a8a 675@end table
3275ac6a 676
75b67a8a
SS
677The @var{out_w} and @var{out_h} parameters specify the expressions for
678the width and height of the output (cropped) video. They are
679evaluated just at the configuration of the filter.
3275ac6a 680
75b67a8a
SS
681The default value of @var{out_w} is "in_w", and the default value of
682@var{out_h} is "in_h".
2bc05d35 683
75b67a8a
SS
684The expression for @var{out_w} may depend on the value of @var{out_h},
685and the expression for @var{out_h} may depend on @var{out_w}, but they
686cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
687evaluated after @var{out_w} and @var{out_h}.
2bc05d35 688
75b67a8a
SS
689The @var{x} and @var{y} parameters specify the expressions for the
690position of the top-left corner of the output (non-cropped) area. They
691are evaluated for each frame. If the evaluated value is not valid, it
692is approximated to the nearest valid value.
3275ac6a 693
75b67a8a
SS
694The default value of @var{x} is "(in_w-out_w)/2", and the default
695value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
696the center of the input image.
697
698The expression for @var{x} may depend on @var{y}, and the expression
699for @var{y} may depend on @var{x}.
700
701Follow some examples:
3275ac6a 702@example
75b67a8a 703# crop the central input area with size 100x100
fba0156a 704crop=out_w=100:out_h=100
75b67a8a
SS
705
706# crop the central input area with size 2/3 of the input video
fba0156a 707"crop=out_w=2/3*in_w:out_h=2/3*in_h"
75b67a8a
SS
708
709# crop the input video central square
fba0156a 710crop=out_w=in_h
75b67a8a
SS
711
712# delimit the rectangle with the top-left corner placed at position
713# 100:100 and the right-bottom corner corresponding to the right-bottom
714# corner of the input image.
fba0156a 715crop=out_w=in_w-100:out_h=in_h-100:x=100:y=100
3275ac6a 716
e6dba1d8 717# crop 10 pixels from the left and right borders, and 20 pixels from
75b67a8a 718# the top and bottom borders
fba0156a 719"crop=out_w=in_w-2*10:out_h=in_h-2*20"
3275ac6a 720
75b67a8a 721# keep only the bottom right quarter of the input image
fba0156a 722"crop=out_w=in_w/2:out_h=in_h/2:x=in_w/2:y=in_h/2"
75b67a8a
SS
723
724# crop height for getting Greek harmony
fba0156a 725"crop=out_w=in_w:out_h=1/PHI*in_w"
75b67a8a
SS
726
727# trembling effect
728"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)"
729
e6dba1d8 730# erratic camera effect depending on timestamp
fba0156a 731"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
SS
732
733# set x depending on the value of y
734"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
735@end example
3275ac6a 736
68b79bfc
SS
737@section cropdetect
738
739Auto-detect crop size.
740
741Calculate necessary cropping parameters and prints the recommended
742parameters through the logging system. The detected dimensions
743correspond to the non-black area of the input video.
744
460e7b4f 745This filter accepts the following options:
68b79bfc
SS
746
747@table @option
748
749@item limit
750Threshold, which can be optionally specified from nothing (0) to
751everything (255), defaults to 24.
752
753@item round
754Value which the width/height should be divisible by, defaults to
75516. The offset is automatically adjusted to center the video. Use 2 to
756get only even dimensions (needed for 4:2:2 video). 16 is best when
757encoding to most video codecs.
758
759@item reset
760Counter that determines after how many frames cropdetect will reset
761the previously detected largest video area and start over to detect
762the current optimal crop area. Defaults to 0.
763
764This can be useful when channel logos distort the video area. 0
765indicates never reset and return the largest area encountered during
766playback.
767@end table
768
b157be1f
SS
769@section delogo
770
771Suppress a TV station logo by a simple interpolation of the surrounding
772pixels. Just set a rectangle covering the logo and watch it disappear
773(and sometimes something even uglier appear - your mileage may vary).
774
63e58c55 775This filter accepts the following options:
b157be1f
SS
776@table @option
777
778@item x, y
779Specify the top left corner coordinates of the logo. They must be
780specified.
781
782@item w, h
783Specify the width and height of the logo to clear. They must be
784specified.
785
786@item band, t
787Specify the thickness of the fuzzy edge of the rectangle (added to
788@var{w} and @var{h}). The default value is 4.
789
790@item show
791When set to 1, a green rectangle is drawn on the screen to simplify
792finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
793@var{band} is set to 4. The default value is 0.
794
795@end table
796
797Some examples follow.
798
799@itemize
800
801@item
802Set a rectangle covering the area with top left corner coordinates 0,0
803and size 100x77, setting a band of size 10:
804@example
b157be1f
SS
805delogo=x=0:y=0:w=100:h=77:band=10
806@end example
807
808@end itemize
809
e40032e2
SS
810@section drawbox
811
812Draw a colored box on the input image.
813
335c3129 814This filter accepts the following options:
e40032e2
SS
815
816@table @option
817
818@item x, y
819Specify the top left corner coordinates of the box. Default to 0.
820
821@item width, height
822Specify the width and height of the box, if 0 they are interpreted as
823the input width and height. Default to 0.
824
825@item color
826Specify the color of the box to write, it can be the name of a color
827(case insensitive match) or a 0xRRGGBB[AA] sequence.
828@end table
829
830Follow some examples:
831@example
832# draw a black box around the edge of the input image
833drawbox
834
835# draw a box with color red and an opacity of 50%
335c3129 836drawbox=x=10:y=20:width=200:height=60:color=red@@0.5"
e40032e2
SS
837@end example
838
a5b64584
SS
839@section drawtext
840
841Draw text string or text from specified file on top of video using the
842libfreetype library.
843
0c50edb7 844To enable compilation of this filter you need to configure Libav with
a5b64584
SS
845@code{--enable-libfreetype}.
846
847The filter also recognizes strftime() sequences in the provided text
848and expands them accordingly. Check the documentation of strftime().
849
a5b64584
SS
850The description of the accepted parameters follows.
851
852@table @option
853
854@item fontfile
855The font file to be used for drawing text. Path must be included.
856This parameter is mandatory.
857
858@item text
859The text string to be drawn. The text must be a sequence of UTF-8
860encoded characters.
861This parameter is mandatory if no file is specified with the parameter
862@var{textfile}.
863
864@item textfile
865A text file containing text to be drawn. The text must be a sequence
866of UTF-8 encoded characters.
867
868This parameter is mandatory if no text string is specified with the
869parameter @var{text}.
870
871If both text and textfile are specified, an error is thrown.
872
873@item x, y
874The offsets where text will be drawn within the video frame.
875Relative to the top/left border of the output image.
2cf74eca
LB
876They accept expressions similar to the @ref{overlay} filter:
877@table @option
878
879@item x, y
880the computed values for @var{x} and @var{y}. They are evaluated for
881each new frame.
882
883@item main_w, main_h
884main input width and height
885
886@item W, H
887same as @var{main_w} and @var{main_h}
888
889@item text_w, text_h
890rendered text width and height
891
892@item w, h
893same as @var{text_w} and @var{text_h}
894
895@item n
896the number of frames processed, starting from 0
897
898@item t
899timestamp expressed in seconds, NAN if the input timestamp is unknown
900
901@end table
a5b64584
SS
902
903The default value of @var{x} and @var{y} is 0.
904
905@item fontsize
906The font size to be used for drawing text.
907The default value of @var{fontsize} is 16.
908
909@item fontcolor
910The color to be used for drawing fonts.
911Either a string (e.g. "red") or in 0xRRGGBB[AA] format
912(e.g. "0xff000033"), possibly followed by an alpha specifier.
913The default value of @var{fontcolor} is "black".
914
915@item boxcolor
916The color to be used for drawing box around text.
917Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
918(e.g. "0xff00ff"), possibly followed by an alpha specifier.
919The default value of @var{boxcolor} is "white".
920
921@item box
922Used to draw a box around text using background color.
923Value should be either 1 (enable) or 0 (disable).
924The default value of @var{box} is 0.
925
994de197
SS
926@item shadowx, shadowy
927The x and y offsets for the text shadow position with respect to the
928position of the text. They can be either positive or negative
929values. Default value for both is "0".
930
931@item shadowcolor
932The color to be used for drawing a shadow behind the drawn text. It
933can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
934form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
935The default value of @var{shadowcolor} is "black".
936
a5b64584
SS
937@item ft_load_flags
938Flags to be used for loading the fonts.
939
940The flags map the corresponding flags supported by libfreetype, and are
941a combination of the following values:
942@table @var
943@item default
944@item no_scale
945@item no_hinting
946@item render
947@item no_bitmap
948@item vertical_layout
949@item force_autohint
950@item crop_bitmap
951@item pedantic
952@item ignore_global_advance_width
953@item no_recurse
954@item ignore_transform
955@item monochrome
956@item linear_design
957@item no_autohint
958@item end table
959@end table
960
961Default value is "render".
962
963For more information consult the documentation for the FT_LOAD_*
964libfreetype flags.
965
966@item tabsize
967The size in number of spaces to use for rendering the tab.
968Default value is 4.
e496c45d
AU
969
970@item fix_bounds
971If true, check and fix text coords to avoid clipping.
a5b64584
SS
972@end table
973
974For example the command:
975@example
976drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
977@end example
978
979will draw "Test Text" with font FreeSerif, using the default values
980for the optional parameters.
981
982The command:
983@example
984drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
985 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
986@end example
987
988will draw 'Test Text' with font FreeSerif of size 24 at position x=100
989and y=50 (counting from the top-left corner of the screen), text is
990yellow with a red box around it. Both the text and the box have an
991opacity of 20%.
992
993Note that the double quotes are not necessary if spaces are not used
994within the parameter list.
995
996For more information about libfreetype, check:
997@url{http://www.freetype.org/}.
998
aadfc9ee
BM
999@section fade
1000
1001Apply fade-in/out effect to input video.
1002
b9dfee9f
AK
1003This filter accepts the following options:
1004
1005@table @option
aadfc9ee 1006
b9dfee9f
AK
1007@item type
1008The effect type -- can be either "in" for fade-in, or "out" for a fade-out
1009effect.
aadfc9ee 1010
b9dfee9f
AK
1011@item start_frame
1012The number of the start frame for starting to apply the fade effect.
aadfc9ee 1013
b9dfee9f
AK
1014@item nb_frames
1015The number of frames for which the fade effect has to last. At the end of the
1016fade-in effect the output video will have the same intensity as the input video,
1017at the end of the fade-out transition the output video will be completely black.
1018
1019@end table
aadfc9ee
BM
1020
1021A few usage examples follow, usable too as test scenarios.
1022@example
1023# fade in first 30 frames of video
b9dfee9f 1024fade=type=in:nb_frames=30
aadfc9ee
BM
1025
1026# fade out last 45 frames of a 200-frame video
b9dfee9f 1027fade=type=out:start_frame=155:nb_frames=45
aadfc9ee
BM
1028
1029# fade in first 25 frames and fade out last 25 frames of a 1000-frame video
b9dfee9f 1030fade=type=in:start_frame=0:nb_frames=25, fade=type=out:start_frame=975:nb_frames=25
aadfc9ee
BM
1031
1032# make first 5 frames black, then fade in from frame 5-24
b9dfee9f 1033fade=type=in:start_frame=5:nb_frames=20
aadfc9ee
BM
1034@end example
1035
2f84bb42
MH
1036@section fieldorder
1037
1038Transform the field order of the input video.
1039
a39c1540 1040This filter accepts the following options:
2f84bb42
MH
1041
1042@table @option
a39c1540
AK
1043
1044@item order
1045Output field order. Valid values are @var{tff} for top field first or @var{bff}
1046for bottom field first.
2f84bb42
MH
1047@end table
1048
1049Default value is "tff".
1050
1051Transformation is achieved by shifting the picture content up or down
1052by one line, and filling the remaining line with appropriate picture content.
1053This method is consistent with most broadcast field order converters.
1054
1055If the input video is not flagged as being interlaced, or it is already
1056flagged as being of the required output field order then this filter does
1057not alter the incoming video.
1058
1059This filter is very useful when converting to or from PAL DV material,
1060which is bottom field first.
1061
1062For example:
1063@example
a39c1540 1064./avconv -i in.vob -vf "fieldorder=order=bff" out.dv
2f84bb42
MH
1065@end example
1066
7f1af825
SS
1067@section fifo
1068
1069Buffer input images and send them when they are requested.
1070
1071This filter is mainly useful when auto-inserted by the libavfilter
1072framework.
1073
1074The filter does not take parameters.
1075
3275ac6a
SS
1076@section format
1077
1078Convert the input video to one of the specified pixel formats.
1079Libavfilter will try to pick one that is supported for the input to
1080the next filter.
1081
e67a87ea
AK
1082This filter accepts the following parameters:
1083@table @option
1084
1085@item pix_fmts
1086A '|'-separated list of pixel format names, for example
1087"pix_fmts=yuv420p|monow|rgb24".
1088
1089@end table
3275ac6a 1090
f150e4dc 1091Some examples follow:
3275ac6a 1092@example
f150e4dc 1093# convert the input video to the format "yuv420p"
e67a87ea 1094format=pix_fmts=yuv420p
3275ac6a 1095
f150e4dc 1096# convert the input video to any of the formats in the list
e67a87ea 1097format=pix_fmts=yuv420p|yuv444p|yuv410p
f150e4dc 1098@end example
3275ac6a 1099
54c5dd89
AK
1100@section fps
1101
1102Convert the video to specified constant framerate by duplicating or dropping
1103frames as necessary.
1104
1105This filter accepts the following named parameters:
1106@table @option
1107
1108@item fps
1109Desired output framerate.
1110
1111@end table
1112
f8608dca 1113@anchor{frei0r}
47941088
SS
1114@section frei0r
1115
1116Apply a frei0r effect to the input video.
1117
1118To enable compilation of this filter you need to install the frei0r
f8a45fa1 1119header and configure Libav with --enable-frei0r.
47941088 1120
5aa1a668
AK
1121This filter accepts the following options:
1122
1123@table @option
1124
1125@item filter_name
1126The name to the frei0r effect to load. If the environment variable
1127@env{FREI0R_PATH} is defined, the frei0r effect is searched in each one of the
1128directories specified by the colon separated list in @env{FREIOR_PATH},
1129otherwise in the standard frei0r paths, which are in this order:
1130@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
1131@file{/usr/lib/frei0r-1/}.
47941088 1132
5aa1a668
AK
1133@item filter_params
1134A '|'-separated list of parameters to pass to the frei0r effect.
47941088 1135
5aa1a668 1136@end table
47941088
SS
1137
1138A frei0r effect parameter can be a boolean (whose values are specified
1139with "y" and "n"), a double, a color (specified by the syntax
1140@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
1141numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
1142description), a position (specified by the syntax @var{X}/@var{Y},
1143@var{X} and @var{Y} being float numbers) and a string.
1144
1145The number and kind of parameters depend on the loaded effect. If an
1146effect parameter is not specified the default value is set.
1147
1148Some examples follow:
1149@example
1150# apply the distort0r effect, set the first two double parameters
5aa1a668 1151frei0r=filter_name=distort0r:filter_params=0.5|0.01
47941088
SS
1152
1153# apply the colordistance effect, takes a color as first parameter
1154frei0r=colordistance:0.2/0.3/0.4
1155frei0r=colordistance:violet
1156frei0r=colordistance:0x112233
1157
1158# apply the perspective effect, specify the top left and top right
1159# image positions
5aa1a668 1160frei0r=perspective:0.2/0.2|0.8/0.2
47941088
SS
1161@end example
1162
1163For more information see:
1164@url{http://piksel.org/frei0r}
1165
d5f187fd
N
1166@section gradfun
1167
1168Fix the banding artifacts that are sometimes introduced into nearly flat
1169regions by truncation to 8bit colordepth.
1170Interpolate the gradients that should go where the bands are, and
1171dither them.
1172
3eccfaa0
SS
1173This filter is designed for playback only. Do not use it prior to
1174lossy compression, because compression tends to lose the dither and
1175bring back the bands.
1176
7ed833d7
AK
1177This filter accepts the following options:
1178
1179@table @option
d5f187fd 1180
7ed833d7
AK
1181@item strength
1182The maximum amount by which the filter will change any one pixel. Also the
1183threshold for detecting nearly flat regions. Acceptable values range from .51 to
118464, default value is 1.2, out-of-range values will be clipped to the valid
1185range.
d5f187fd 1186
7ed833d7
AK
1187@item radius
1188The neighborhood to fit the gradient to. A larger radius makes for smoother
1189gradients, but also prevents the filter from modifying the pixels near detailed
1190regions. Acceptable values are 8-32, default value is 16, out-of-range values
1191will be clipped to the valid range.
1192
1193@end table
d5f187fd
N
1194
1195@example
1196# default parameters
7ed833d7 1197gradfun=strength=1.2:radius=16
d5f187fd
N
1198
1199# omitting radius
1200gradfun=1.2
1201@end example
1202
a1e171df
SS
1203@section hflip
1204
1205Flip the input video horizontally.
1206
9270b8a3 1207For example to horizontally flip the input video with @command{avconv}:
a1e171df 1208@example
9270b8a3 1209avconv -i in.avi -vf "hflip" out.avi
a1e171df
SS
1210@end example
1211
a4dc7aa5
BC
1212@section hqdn3d
1213
1214High precision/quality 3d denoise filter. This filter aims to reduce
1215image noise producing smooth images and making still images really
1216still. It should enhance compressibility.
1217
1218It accepts the following optional parameters:
a4dc7aa5
BC
1219
1220@table @option
1221@item luma_spatial
1222a non-negative float number which specifies spatial luma strength,
1223defaults to 4.0
1224
1225@item chroma_spatial
1226a non-negative float number which specifies spatial chroma strength,
1227defaults to 3.0*@var{luma_spatial}/4.0
1228
1229@item luma_tmp
1230a float number which specifies luma temporal strength, defaults to
12316.0*@var{luma_spatial}/4.0
1232
1233@item chroma_tmp
1234a float number which specifies chroma temporal strength, defaults to
1235@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
1236@end table
1237
3fce1367
VG
1238@section interlace
1239
1240Simple interlacing filter from progressive contents. This interleaves upper (or
1241lower) lines from odd frames with lower (or upper) lines from even frames,
1242halving the frame rate and preserving image height.
1243
1244@example
1245 Original Original New Frame
1246 Frame 'j' Frame 'j+1' (tff)
1247 ========== =========== ==================
1248 Line 0 --------------------> Frame 'j' Line 0
1249 Line 1 Line 1 ----> Frame 'j+1' Line 1
1250 Line 2 ---------------------> Frame 'j' Line 2
1251 Line 3 Line 3 ----> Frame 'j+1' Line 3
1252 ... ... ...
1253New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
1254@end example
1255
1256It accepts the following optional parameters:
1257
1258@table @option
1259@item scan
1260determines whether the interlaced frame is taken from the even (tff - default)
1261or odd (bff) lines of the progressive frame.
1262
1263@item lowpass
1264Enable (default) or disable the vertical lowpass filter to avoid twitter
1265interlacing and reduce moire patterns.
1266@end table
1267
8fe0c527
SS
1268@section lut, lutrgb, lutyuv
1269
1270Compute a look-up table for binding each pixel component input value
1271to an output value, and apply it to input video.
1272
1273@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
1274to an RGB input video.
1275
20b46f8f 1276These filters accept the following options:
8fe0c527 1277@table @option
91f5f875
LB
1278@item @var{c0} (first pixel component)
1279@item @var{c1} (second pixel component)
1280@item @var{c2} (third pixel component)
1281@item @var{c3} (fourth pixel component, corresponds to the alpha component)
8fe0c527 1282
91f5f875
LB
1283@item @var{r} (red component)
1284@item @var{g} (green component)
1285@item @var{b} (blue component)
1286@item @var{a} (alpha component)
8fe0c527 1287
91f5f875
LB
1288@item @var{y} (Y/luminance component)
1289@item @var{u} (U/Cb component)
1290@item @var{v} (V/Cr component)
8fe0c527
SS
1291@end table
1292
20b46f8f
AK
1293Each of them specifies the expression to use for computing the lookup table for
1294the corresponding pixel component values.
1295
1296The exact component associated to each of the @var{c*} options depends on the
1297format in input.
1298
1299The @var{lut} filter requires either YUV or RGB pixel formats in input,
1300@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
1301
8fe0c527
SS
1302The expressions can contain the following constants and functions:
1303
1304@table @option
1305@item E, PI, PHI
1306the corresponding mathematical approximated values for e
1307(euler number), pi (greek PI), PHI (golden ratio)
1308
1309@item w, h
da9cea77 1310the input width and height
8fe0c527
SS
1311
1312@item val
1313input value for the pixel component
1314
1315@item clipval
1316the input value clipped in the @var{minval}-@var{maxval} range
1317
1318@item maxval
1319maximum value for the pixel component
1320
1321@item minval
1322minimum value for the pixel component
1323
1324@item negval
1325the negated value for the pixel component value clipped in the
1326@var{minval}-@var{maxval} range , it corresponds to the expression
1327"maxval-clipval+minval"
1328
1329@item clip(val)
1330the computed value in @var{val} clipped in the
1331@var{minval}-@var{maxval} range
1332
1333@item gammaval(gamma)
1334the computed gamma correction value of the pixel component value
1335clipped in the @var{minval}-@var{maxval} range, corresponds to the
1336expression
1337"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
1338
1339@end table
1340
1341All expressions default to "val".
1342
1343Some examples follow:
1344@example
1345# negate input video
1346lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
1347lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
1348
1349# the above is the same as
1350lutrgb="r=negval:g=negval:b=negval"
1351lutyuv="y=negval:u=negval:v=negval"
1352
1353# negate luminance
1354lutyuv=negval
1355
1356# remove chroma components, turns the video into a graytone image
1357lutyuv="u=128:v=128"
1358
1359# apply a luma burning effect
1360lutyuv="y=2*val"
1361
1362# remove green and blue components
1363lutrgb="g=0:b=0"
1364
1365# set a constant alpha channel value on input
1366format=rgba,lutrgb=a="maxval-minval/2"
1367
1368# correct luminance gamma by a 0.5 factor
1369lutyuv=y=gammaval(0.5)
1370@end example
1371
171868e2
SS
1372@section negate
1373
1374Negate input video.
1375
1376This filter accepts an integer in input, if non-zero it negates the
1377alpha component (if available). The default value in input is 0.
3275ac6a 1378
ef4d34aa
AK
1379@section noformat
1380
3275ac6a
SS
1381Force libavfilter not to use any of the specified pixel formats for the
1382input to the next filter.
1383
e67a87ea
AK
1384This filter accepts the following parameters:
1385@table @option
1386
1387@item pix_fmts
1388A '|'-separated list of pixel format names, for example
1389"pix_fmts=yuv420p|monow|rgb24".
1390
1391@end table
3275ac6a 1392
f150e4dc 1393Some examples follow:
3275ac6a 1394@example
f150e4dc
SS
1395# force libavfilter to use a format different from "yuv420p" for the
1396# input to the vflip filter
e67a87ea 1397noformat=pix_fmts=yuv420p,vflip
3275ac6a 1398
f150e4dc 1399# convert the input video to any of the formats not contained in the list
e67a87ea 1400noformat=yuv420p|yuv444p|yuv410p
f150e4dc 1401@end example
3275ac6a
SS
1402
1403@section null
1404
99046339 1405Pass the video source unchanged to the output.
3275ac6a 1406
cf69ad35 1407@section ocv
6ebf0bfc 1408
cf69ad35 1409Apply video transform using libopencv.
6ebf0bfc
SS
1410
1411To enable this filter install libopencv library and headers and
f8a45fa1 1412configure Libav with --enable-libopencv.
6ebf0bfc 1413
ee0e8d4b
AK
1414This filter accepts the following parameters:
1415
1416@table @option
cf69ad35 1417
ee0e8d4b
AK
1418@item filter_name
1419The name of the libopencv filter to apply.
cf69ad35 1420
ee0e8d4b
AK
1421@item filter_params
1422The parameters to pass to the libopencv filter. If not specified the default
1423values are assumed.
1424
1425@end table
cf69ad35
SS
1426
1427Refer to the official libopencv documentation for more precise
da9cea77 1428information:
cf69ad35
SS
1429@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
1430
1431Follows the list of supported libopencv filters.
1432
17fc9493 1433@anchor{dilate}
91cbb6ba
SS
1434@subsection dilate
1435
1436Dilate an image by using a specific structuring element.
1437This filter corresponds to the libopencv function @code{cvDilate}.
1438
ee0e8d4b 1439It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
91cbb6ba
SS
1440
1441@var{struct_el} represents a structuring element, and has the syntax:
1442@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
1443
da9cea77 1444@var{cols} and @var{rows} represent the number of columns and rows of
91cbb6ba
SS
1445the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
1446point, and @var{shape} the shape for the structuring element, and
1447can be one of the values "rect", "cross", "ellipse", "custom".
1448
1449If the value for @var{shape} is "custom", it must be followed by a
1450string of the form "=@var{filename}". The file with name
1451@var{filename} is assumed to represent a binary image, with each
1452printable character corresponding to a bright pixel. When a custom
1453@var{shape} is used, @var{cols} and @var{rows} are ignored, the number
1454or columns and rows of the read file are assumed instead.
1455
1456The default value for @var{struct_el} is "3x3+0x0/rect".
1457
1458@var{nb_iterations} specifies the number of times the transform is
1459applied to the image, and defaults to 1.
1460
1461Follow some example:
1462@example
1463# use the default values
1464ocv=dilate
1465
1466# dilate using a structuring element with a 5x5 cross, iterate two times
ee0e8d4b 1467ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
91cbb6ba
SS
1468
1469# read the shape from the file diamond.shape, iterate two times
1470# the file diamond.shape may contain a pattern of characters like this:
1471# *
1472# ***
1473# *****
1474# ***
1475# *
1476# the specified cols and rows are ignored (but not the anchor point coordinates)
ee0e8d4b 1477ocv=dilate:0x0+2x2/custom=diamond.shape|2
91cbb6ba
SS
1478@end example
1479
17fc9493
SS
1480@subsection erode
1481
1482Erode an image by using a specific structuring element.
1483This filter corresponds to the libopencv function @code{cvErode}.
1484
1485The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
4c989761 1486with the same syntax and semantics as the @ref{dilate} filter.
17fc9493 1487
cf69ad35
SS
1488@subsection smooth
1489
1490Smooth the input video.
1491
1492The filter takes the following parameters:
ee0e8d4b 1493@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
6ebf0bfc
SS
1494
1495@var{type} is the type of smooth filter to apply, and can be one of
58d94364 1496the following values: "blur", "blur_no_scale", "median", "gaussian",
6ebf0bfc
SS
1497"bilateral". The default value is "gaussian".
1498
1499@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
1500parameters whose meanings depend on smooth type. @var{param1} and
1501@var{param2} accept integer positive values or 0, @var{param3} and
1502@var{param4} accept float values.
1503
1504The default value for @var{param1} is 3, the default value for the
1505other parameters is 0.
1506
58d94364 1507These parameters correspond to the parameters assigned to the
cf69ad35 1508libopencv function @code{cvSmooth}.
6ebf0bfc 1509
2cf74eca 1510@anchor{overlay}
58935b25
SS
1511@section overlay
1512
1513Overlay one video on top of another.
1514
1515It takes two inputs and one output, the first input is the "main"
1516video on which the second input is overlayed.
1517
9087eaf1
AK
1518This filter accepts the following parameters:
1519
1520@table @option
1521
1522@item x
1523The horizontal position of the left edge of the overlaid video on the main video.
1524
1525@item y
1526The vertical position of the top edge of the overlaid video on the main video.
1527
1528@end table
58935b25 1529
9087eaf1 1530The parameters are expressions containing the following parameters:
58935b25
SS
1531
1532@table @option
1533@item main_w, main_h
1534main input width and height
1535
1536@item W, H
1537same as @var{main_w} and @var{main_h}
1538
1539@item overlay_w, overlay_h
1540overlay input width and height
1541
1542@item w, h
1543same as @var{overlay_w} and @var{overlay_h}
1544@end table
1545
1546Be aware that frames are taken from each input video in timestamp
1547order, hence, if their initial timestamps differ, it is a a good idea
1548to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
1549have them begin in the same zero timestamp, as it does the example for
1550the @var{movie} filter.
1551
1552Follow some examples:
1553@example
1554# draw the overlay at 10 pixels from the bottom right
1555# corner of the main video.
9087eaf1 1556overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
58935b25
SS
1557
1558# insert a transparent PNG logo in the bottom left corner of the input
9087eaf1 1559avconv -i input -i logo -filter_complex 'overlay=x=10:y=main_h-overlay_h-10' output
58935b25
SS
1560
1561# insert 2 different transparent PNG logos (second logo on bottom
1562# right corner):
7ce118ba 1563avconv -i input -i logo1 -i logo2 -filter_complex
9087eaf1 1564'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output
58935b25
SS
1565
1566# add a transparent color layer on top of the main video,
1567# WxH specifies the size of the main input to the overlay filter
1568color=red@.3:WxH [over]; [in][over] overlay [out]
1569@end example
1570
b0641ab7 1571You can chain together more overlays but the efficiency of such
58935b25
SS
1572approach is yet to be tested.
1573
3275ac6a
SS
1574@section pad
1575
1576Add paddings to the input image, and places the original input at the
1577given coordinates @var{x}, @var{y}.
1578
40c885c5
AK
1579This filter accepts the following parameters:
1580
1581@table @option
1582@item width, height
1583
1584Specify the size of the output image with the paddings added. If the
1585value for @var{width} or @var{height} is 0, the corresponding input size
1586is used for the output.
1587
1588The @var{width} expression can reference the value set by the
1589@var{height} expression, and vice versa.
1590
1591The default value of @var{width} and @var{height} is 0.
1592
1593@item x, y
1594
1595Specify the offsets where to place the input image in the padded area
1596with respect to the top/left border of the output image.
1597
1598The @var{x} expression can reference the value set by the @var{y}
1599expression, and vice versa.
1600
1601The default value of @var{x} and @var{y} is 0.
1602
1603@item color
1604
1605Specify the color of the padded area, it can be the name of a color
1606(case insensitive match) or a 0xRRGGBB[AA] sequence.
1607
1608The default value of @var{color} is "black".
1609
1610@end table
3275ac6a 1611
73a4f7c2
SS
1612The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
1613expressions containing the following constants:
1614
1615@table @option
1616@item E, PI, PHI
1617the corresponding mathematical approximated values for e
1618(euler number), pi (greek PI), phi (golden ratio)
1619
1620@item in_w, in_h
e83c2dde 1621the input video width and height
73a4f7c2
SS
1622
1623@item iw, ih
1624same as @var{in_w} and @var{in_h}
1625
1626@item out_w, out_h
e83c2dde 1627the output width and height, that is the size of the padded area as
73a4f7c2
SS
1628specified by the @var{width} and @var{height} expressions
1629
1630@item ow, oh
1631same as @var{out_w} and @var{out_h}
1632
1633@item x, y
1634x and y offsets as specified by the @var{x} and @var{y}
1635expressions, or NAN if not yet specified
1636
1637@item a
1638input display aspect ratio, same as @var{iw} / @var{ih}
1639
1640@item hsub, vsub
1641horizontal and vertical chroma subsample values. For example for the
1642pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1643@end table
1644
73a4f7c2 1645Some examples follow:
3d17f4b9
SS
1646
1647@example
1648# Add paddings with color "violet" to the input video. Output video
1649# size is 640x480, the top-left corner of the input video is placed at
aeefbf61 1650# column 0, row 40.
40c885c5 1651pad=width=640:height=480:x=0:y=40:color=violet
73a4f7c2
SS
1652
1653# pad the input to get an output with dimensions increased bt 3/2,
1654# and put the input video at the center of the padded area
1655pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
1656
1657# pad the input to get a squared output with size equal to the maximum
1658# value between the input width and height, and put the input video at
1659# the center of the padded area
1660pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
1661
1662# pad the input to get a final w/h ratio of 16:9
1663pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
1664
1665# double output size and put the input video in the bottom-right
1666# corner of the output padded area
1667pad="2*iw:2*ih:ow-iw:oh-ih"
3d17f4b9
SS
1668@end example
1669
ce2e4ae3
SS
1670@section pixdesctest
1671
1672Pixel format descriptor test filter, mainly useful for internal
1673testing. The output video should be equal to the input video.
1674
1675For example:
1676@example
1677format=monow, pixdesctest
1678@end example
1679
1680can be used to test the monowhite pixel format descriptor definition.
1681
3275ac6a
SS
1682@section scale
1683
c334c113 1684Scale the input video and/or convert the image format.
3275ac6a 1685
c334c113
AK
1686This filter accepts the following options:
1687
1688@table @option
1689
1690@item w
1691Output video width.
1692
1693@item h
1694Output video height.
1695
1696@end table
1697
1698The parameters @var{w} and @var{h} are expressions containing
68e23c08 1699the following constants:
3275ac6a 1700
68e23c08
SS
1701@table @option
1702@item E, PI, PHI
1703the corresponding mathematical approximated values for e
1704(euler number), pi (greek PI), phi (golden ratio)
1705
1706@item in_w, in_h
e83c2dde 1707the input width and height
68e23c08
SS
1708
1709@item iw, ih
1710same as @var{in_w} and @var{in_h}
1711
1712@item out_w, out_h
e83c2dde 1713the output (cropped) width and height
68e23c08
SS
1714
1715@item ow, oh
1716same as @var{out_w} and @var{out_h}
3275ac6a 1717
46b29397 1718@item dar, a
68e23c08
SS
1719input display aspect ratio, same as @var{iw} / @var{ih}
1720
46b29397
SS
1721@item sar
1722input sample aspect ratio
1723
68e23c08
SS
1724@item hsub, vsub
1725horizontal and vertical chroma subsample values. For example for the
1726pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1727@end table
3275ac6a
SS
1728
1729If the input image format is different from the format requested by
1730the next filter, the scale filter will convert the input to the
1731requested format.
1732
c334c113 1733If the value for @var{w} or @var{h} is 0, the respective input
3275ac6a
SS
1734size is used for the output.
1735
c334c113
AK
1736If the value for @var{w} or @var{h} is -1, the scale filter will use, for the
1737respective output size, a value that maintains the aspect ratio of the input
1738image.
3275ac6a 1739
c334c113 1740The default value of @var{w} and @var{h} is 0.
3275ac6a 1741
68e23c08
SS
1742Some examples follow:
1743@example
1744# scale the input video to a size of 200x100.
c334c113 1745scale=w=200:h=100
68e23c08
SS
1746
1747# scale the input to 2x
c334c113 1748scale=w=2*iw:h=2*ih
68e23c08
SS
1749# the above is the same as
1750scale=2*in_w:2*in_h
1751
1752# scale the input to half size
c334c113 1753scale=w=iw/2:h=ih/2
68e23c08
SS
1754
1755# increase the width, and set the height to the same size
1756scale=3/2*iw:ow
1757
1758# seek for Greek harmony
1759scale=iw:1/PHI*iw
1760scale=ih*PHI:ih
1761
1762# increase the height, and set the width to 3/2 of the height
c334c113 1763scale=w=3/2*oh:h=3/5*ih
68e23c08
SS
1764
1765# increase the size, but make the size a multiple of the chroma
1766scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
1767
1768# increase the width to a maximum of 500 pixels, keep the same input aspect ratio
c334c113 1769scale=w='min(500\, iw*3/2):h=-1'
68e23c08
SS
1770@end example
1771
d763fb7d
SS
1772@section select
1773Select frames to pass in output.
1774
95f1f56a
AK
1775This filter accepts the following options:
1776
1777@table @option
1778
1779@item expr
1780An expression, which is evaluated for each input frame. If the expression is
1781evaluated to a non-zero value, the frame is selected and passed to the output,
1782otherwise it is discarded.
1783
1784@end table
d763fb7d
SS
1785
1786The expression can contain the following constants:
1787
1788@table @option
1789@item PI
1790Greek PI
1791
1792@item PHI
1793golden ratio
1794
1795@item E
1796Euler number
1797
1798@item n
1799the sequential number of the filtered frame, starting from 0
1800
1801@item selected_n
1802the sequential number of the selected frame, starting from 0
1803
1804@item prev_selected_n
1805the sequential number of the last selected frame, NAN if undefined
1806
1807@item TB
1808timebase of the input timestamps
1809
1810@item pts
1811the PTS (Presentation TimeStamp) of the filtered video frame,
1812expressed in @var{TB} units, NAN if undefined
1813
1814@item t
1815the PTS (Presentation TimeStamp) of the filtered video frame,
1816expressed in seconds, NAN if undefined
1817
1818@item prev_pts
1819the PTS of the previously filtered video frame, NAN if undefined
1820
1821@item prev_selected_pts
1822the PTS of the last previously filtered video frame, NAN if undefined
1823
1824@item prev_selected_t
1825the PTS of the last previously selected video frame, NAN if undefined
1826
1827@item start_pts
1828the PTS of the first video frame in the video, NAN if undefined
1829
1830@item start_t
1831the time of the first video frame in the video, NAN if undefined
1832
1833@item pict_type
1834the type of the filtered frame, can assume one of the following
1835values:
1836@table @option
1837@item I
1838@item P
1839@item B
1840@item S
1841@item SI
1842@item SP
1843@item BI
1844@end table
1845
1846@item interlace_type
1847the frame interlace type, can assume one of the following values:
1848@table @option
1849@item PROGRESSIVE
1850the frame is progressive (not interlaced)
1851@item TOPFIRST
1852the frame is top-field-first
1853@item BOTTOMFIRST
1854the frame is bottom-field-first
1855@end table
1856
1857@item key
18581 if the filtered frame is a key-frame, 0 otherwise
1859
d763fb7d
SS
1860@end table
1861
1862The default value of the select expression is "1".
1863
1864Some examples follow:
1865
1866@example
1867# select all frames in input
1868select
1869
1870# the above is the same as:
95f1f56a 1871select=expr=1
d763fb7d
SS
1872
1873# skip all frames:
95f1f56a 1874select=expr=0
d763fb7d
SS
1875
1876# select only I-frames
95f1f56a 1877select='expr=eq(pict_type\,I)'
d763fb7d
SS
1878
1879# select one frame every 100
1880select='not(mod(n\,100))'
1881
1882# select only frames contained in the 10-20 time interval
1883select='gte(t\,10)*lte(t\,20)'
1884
1885# select only I frames contained in the 10-20 time interval
1886select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
1887
1888# select frames with a minimum distance of 10 seconds
1889select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
1890@end example
1891
2fd8756b
SS
1892@anchor{setdar}
1893@section setdar
1894
1895Set the Display Aspect Ratio for the filter output video.
1896
1897This is done by changing the specified Sample (aka Pixel) Aspect
1898Ratio, according to the following equation:
1899@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
1900
1901Keep in mind that this filter does not modify the pixel dimensions of
1902the video frame. Also the display aspect ratio set by this filter may
1903be changed by later filters in the filterchain, e.g. in case of
1904scaling or if another "setdar" or a "setsar" filter is applied.
1905
2831b307
AK
1906This filter accepts the following options:
1907
1908@table @option
1909
1910@item dar
1911Output display aspect ratio, as a rational or a decimal number.
1912
1913@end table
2fd8756b
SS
1914
1915For example to change the display aspect ratio to 16:9, specify:
1916@example
2831b307 1917setdar=dar=16/9
2fd8756b 1918# the above is equivalent to
2831b307 1919setdar=dar=1.77777
2fd8756b
SS
1920@end example
1921
4c989761 1922See also the @ref{setsar} filter documentation.
2fd8756b 1923
a532bb39
SS
1924@section setpts
1925
1926Change the PTS (presentation timestamp) of the input video frames.
1927
33b97faa
AK
1928This filter accepts the following options:
1929
1930@table @option
1931
1932@item expr
1933The expression which is evaluated for each frame to construct its timestamp.
1934
1935@end table
1936
1937The expression is evaluated through the eval API and can contain the following
1938constants:
a532bb39
SS
1939
1940@table @option
1941@item PTS
1942the presentation timestamp in input
1943
1944@item PI
1945Greek PI
1946
1947@item PHI
1948golden ratio
1949
1950@item E
1951Euler number
1952
1953@item N
1954the count of the input frame, starting from 0.
1955
1956@item STARTPTS
1957the PTS of the first video frame
1958
1959@item INTERLACED
1960tell if the current frame is interlaced
1961
a532bb39
SS
1962@item PREV_INPTS
1963previous input PTS
1964
1965@item PREV_OUTPTS
1966previous output PTS
1967
0b55b16a
VP
1968@item RTCTIME
1969wallclock (RTC) time in microseconds
1970
1971@item RTCSTART
1972wallclock (RTC) time at the start of the movie in microseconds
1973
a532bb39
SS
1974@end table
1975
1976Some examples follow:
1977
1978@example
1979# start counting PTS from zero
33b97faa 1980setpts=expr=PTS-STARTPTS
a532bb39
SS
1981
1982# fast motion
33b97faa 1983setpts=expr=0.5*PTS
a532bb39
SS
1984
1985# slow motion
1986setpts=2.0*PTS
1987
1988# fixed rate 25 fps
1989setpts=N/(25*TB)
1990
1991# fixed rate 25 fps with some jitter
1992setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
0b55b16a
VP
1993
1994# generate timestamps from a "live source" and rebase onto the current timebase
1995setpts='(RTCTIME - RTCSTART) / (TB * 1000000)"
a532bb39
SS
1996@end example
1997
2fd8756b
SS
1998@anchor{setsar}
1999@section setsar
2000
2001Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
2002
2003Note that as a consequence of the application of this filter, the
2004output display aspect ratio will change according to the following
2005equation:
2006@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2007
2008Keep in mind that the sample aspect ratio set by this filter may be
2009changed by later filters in the filterchain, e.g. if another "setsar"
2010or a "setdar" filter is applied.
2011
2831b307
AK
2012This filter accepts the following options:
2013
2014@table @option
2015
2016@item sar
2017Output sample aspect ratio, as a rational or decimal number.
2018
2019@end table
2fd8756b
SS
2020
2021For example to change the sample aspect ratio to 10:11, specify:
2022@example
2831b307 2023setsar=sar=10/11
2fd8756b
SS
2024@end example
2025
d89e3b36
SS
2026@section settb
2027
2028Set the timebase to use for the output frames timestamps.
2029It is mainly useful for testing timebase configuration.
2030
ffea3b00
AK
2031This filter accepts the following options:
2032
2033@table @option
2034
2035@item expr
2036The expression which is evaluated into the output timebase.
2037
2038@end table
2039
d89e3b36
SS
2040The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
2041default timebase), and "intb" (the input timebase).
2042
2043The default value for the input is "intb".
2044
2045Follow some examples.
2046
2047@example
2048# set the timebase to 1/25
ffea3b00 2049settb=expr=1/25
d89e3b36
SS
2050
2051# set the timebase to 1/10
ffea3b00 2052settb=expr=0.1
d89e3b36
SS
2053
2054#set the timebase to 1001/1000
2055settb=1+0.001
2056
2057#set the timebase to 2*intb
2058settb=2*intb
2059
2060#set the default timebase value
2061settb=AVTB
2062@end example
2063
ee42716b
SS
2064@section showinfo
2065
2066Show a line containing various information for each input video frame.
2067The input video is not modified.
2068
2069The shown line contains a sequence of key/value pairs of the form
2070@var{key}:@var{value}.
2071
2072A description of each shown parameter follows:
2073
2074@table @option
2075@item n
2076sequential number of the input frame, starting from 0
2077
2078@item pts
2079Presentation TimeStamp of the input frame, expressed as a number of
2080time base units. The time base unit depends on the filter input pad.
2081
2082@item pts_time
2083Presentation TimeStamp of the input frame, expressed as a number of
2084seconds
2085
2086@item pos
2087position of the frame in the input stream, -1 if this information in
da9cea77 2088unavailable and/or meaningless (for example in case of synthetic video)
ee42716b
SS
2089
2090@item fmt
2091pixel format name
2092
2093@item sar
2094sample aspect ratio of the input frame, expressed in the form
2095@var{num}/@var{den}
2096
2097@item s
2098size of the input frame, expressed in the form
2099@var{width}x@var{height}
2100
2101@item i
2102interlaced mode ("P" for "progressive", "T" for top field first, "B"
2103for bottom field first)
2104
2105@item iskey
21061 if the frame is a key frame, 0 otherwise
2107
2108@item type
2109picture type of the input frame ("I" for an I-frame, "P" for a
2110P-frame, "B" for a B-frame, "?" for unknown type).
2111Check also the documentation of the @code{AVPictureType} enum and of
2112the @code{av_get_picture_type_char} function defined in
2113@file{libavutil/avutil.h}.
2114
2115@item checksum
2116Adler-32 checksum of all the planes of the input frame
2117
2118@item plane_checksum
2119Adler-32 checksum of each plane of the input frame, expressed in the form
2120"[@var{c0} @var{c1} @var{c2} @var{c3}]"
2121@end table
2122
fd18ee0f
AK
2123@section split
2124
2125Split input video into several identical outputs.
2126
2127The filter accepts a single parameter which specifies the number of outputs. If
2128unspecified, it defaults to 2.
2129
2130For example
2131@example
2132avconv -i INPUT -filter_complex split=5 OUTPUT
2133@end example
2134will create 5 copies of the input video.
2135
43945b27
SS
2136@section transpose
2137
2138Transpose rows with columns in the input video and optionally flip it.
2139
0c2466de
AK
2140This filter accepts the following options:
2141
2142@table @option
2143
2144@item dir
2145The direction of the transpose.
2146
2147@end table
2148
2149The direction can assume the following values:
43945b27
SS
2150
2151@table @samp
0c2466de 2152@item cclock_flip
43945b27
SS
2153Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2154@example
2155L.R L.l
2156. . -> . .
2157l.r R.r
2158@end example
2159
0c2466de 2160@item clock
43945b27
SS
2161Rotate by 90 degrees clockwise, that is:
2162@example
2163L.R l.L
2164. . -> . .
2165l.r r.R
2166@end example
2167
0c2466de 2168@item cclock
43945b27
SS
2169Rotate by 90 degrees counterclockwise, that is:
2170@example
2171L.R R.r
2172. . -> . .
2173l.r L.l
2174@end example
2175
0c2466de 2176@item clock_flip
43945b27
SS
2177Rotate by 90 degrees clockwise and vertically flip, that is:
2178@example
2179L.R r.R
2180. . -> . .
2181l.r l.L
2182@end example
2183@end table
2184
3275ac6a
SS
2185@section unsharp
2186
843b5fd0
SS
2187Sharpen or blur the input video.
2188
2189It accepts the following parameters:
3275ac6a
SS
2190
2191@table @option
2192
2193@item luma_msize_x
2194Set the luma matrix horizontal size. It can be an integer between 3
2195and 13, default value is 5.
2196
2197@item luma_msize_y
2198Set the luma matrix vertical size. It can be an integer between 3
2199and 13, default value is 5.
2200
2201@item luma_amount
2202Set the luma effect strength. It can be a float number between -2.0
2203and 5.0, default value is 1.0.
2204
2205@item chroma_msize_x
2206Set the chroma matrix horizontal size. It can be an integer between 3
1ee20141 2207and 13, default value is 5.
3275ac6a
SS
2208
2209@item chroma_msize_y
2210Set the chroma matrix vertical size. It can be an integer between 3
1ee20141 2211and 13, default value is 5.
3275ac6a
SS
2212
2213@item luma_amount
2214Set the chroma effect strength. It can be a float number between -2.0
2215and 5.0, default value is 0.0.
2216
2217@end table
2218
b83e9efc
AK
2219Negative values for the amount will blur the input video, while positive
2220values will sharpen. All parameters are optional and default to the
2221equivalent of the string '5:5:1.0:5:5:0.0'.
2222
3275ac6a
SS
2223@example
2224# Strong luma sharpen effect parameters
b83e9efc 2225unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
3275ac6a
SS
2226
2227# Strong blur of both luma and chroma parameters
2228unsharp=7:7:-2:7:7:-2
2229
9270b8a3
LB
2230# Use the default values with @command{avconv}
2231./avconv -i in.avi -vf "unsharp" out.mp4
3275ac6a
SS
2232@end example
2233
2234@section vflip
2235
2236Flip the input video vertically.
2237
2238@example
9270b8a3 2239./avconv -i in.avi -vf "vflip" out.avi
3275ac6a
SS
2240@end example
2241
acbac567
MN
2242@section yadif
2243
1653027a
SS
2244Deinterlace the input video ("yadif" means "yet another deinterlacing
2245filter").
acbac567 2246
7536c671
AK
2247This filter accepts the following options:
2248
2249@table @option
acbac567 2250
7536c671
AK
2251@item mode
2252The interlacing mode to adopt, accepts one of the following values:
acbac567 2253
1653027a
SS
2254@table @option
2255@item 0
2256output 1 frame for each frame
2257@item 1
2258output 1 frame for each field
2259@item 2
2260like 0 but skips spatial interlacing check
2261@item 3
2262like 1 but skips spatial interlacing check
2263@end table
acbac567
MN
2264
2265Default value is 0.
2266
7536c671
AK
2267@item parity
2268The picture field parity assumed for the input interlaced video, accepts one of
2269the following values:
acbac567 2270
1653027a
SS
2271@table @option
2272@item 0
1653027a 2273assume top field first
4703a7b5
SS
2274@item 1
2275assume bottom field first
1653027a
SS
2276@item -1
2277enable automatic detection
acbac567
MN
2278@end table
2279
1653027a 2280Default value is -1.
a51c71bb
BC
2281If interlacing is unknown or decoder does not export this information,
2282top field first will be assumed.
1653027a 2283
7536c671
AK
2284@item auto
2285Whether deinterlacer should trust the interlaced flag and only deinterlace
2286frames marked as interlaced
ab09df9d
JP
2287
2288@table @option
2289@item 0
2290deinterlace all frames
2291@item 1
2292only deinterlace frames marked as interlaced
2293@end table
2294
2295Default value is 0.
2296
7536c671
AK
2297@end table
2298
3275ac6a
SS
2299@c man end VIDEO FILTERS
2300
2301@chapter Video Sources
2302@c man begin VIDEO SOURCES
2303
2304Below is a description of the currently available video sources.
2305
24413399
SS
2306@section buffer
2307
2308Buffer video frames, and make them available to the filter chain.
2309
2310This source is mainly intended for a programmatic use, in particular
ac1a31ab 2311through the interface defined in @file{libavfilter/vsrc_buffer.h}.
24413399 2312
d28cb849 2313This filter accepts the following parameters:
24413399 2314
d28cb849 2315@table @option
24413399 2316
d28cb849
AK
2317@item width
2318Input video width.
24413399 2319
d28cb849
AK
2320@item height
2321Input video height.
24413399 2322
d28cb849
AK
2323@item pix_fmt
2324Name of the input video pixel format.
24413399 2325
d28cb849
AK
2326@item time_base
2327The time base used for input timestamps.
24413399 2328
d28cb849
AK
2329@item sar
2330Sample (pixel) aspect ratio of the input video.
7a11c82f 2331
24413399
SS
2332@end table
2333
2334For example:
2335@example
d28cb849 2336buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
24413399
SS
2337@end example
2338
2339will instruct the source to accept video frames with size 320x240 and
7a11c82f
MN
2340with format "yuv410p", assuming 1/24 as the timestamps timebase and
2341square pixels (1:1 sample aspect ratio).
24413399 2342
23ccf3c7
SS
2343@section color
2344
2345Provide an uniformly colored input.
2346
2347It accepts the following parameters:
23ccf3c7
SS
2348
2349@table @option
2350
2351@item color
2352Specify the color of the source. It can be the name of a color (case
2353insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2354alpha specifier. The default value is "black".
2355
7bc1a883 2356@item size
23ccf3c7 2357Specify the size of the sourced video, it may be a string of the form
e83c2dde 2358@var{width}x@var{height}, or the name of a size abbreviation. The
23ccf3c7
SS
2359default value is "320x240".
2360
7bc1a883 2361@item framerate
23ccf3c7
SS
2362Specify the frame rate of the sourced video, as the number of frames
2363generated per second. It has to be a string in the format
2364@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2365number or a valid video frame rate abbreviation. The default value is
2366"25".
2367
2368@end table
2369
2370For example the following graph description will generate a red source
2371with an opacity of 0.2, with size "qcif" and a frame rate of 10
2372frames per second, which will be overlayed over the source connected
2373to the pad with identifier "in".
2374
2375@example
2376"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2377@end example
2378
9409c381
SS
2379@section movie
2380
2381Read a video stream from a movie container.
2382
7ca14c73
AK
2383Note that this source is a hack that bypasses the standard input path. It can be
2384useful in applications that do not support arbitrary filter graphs, but its use
2385is discouraged in those that do. Specifically in @command{avconv} this filter
2386should never be used, the @option{-filter_complex} option fully replaces it.
2387
a42d6e6c 2388This filter accepts the following options:
9409c381
SS
2389
2390@table @option
2391
a42d6e6c
AK
2392@item filename
2393The name of the resource to read (not necessarily a file but also a device or a
2394stream accessed through some protocol).
2395
9409c381
SS
2396@item format_name, f
2397Specifies the format assumed for the movie to read, and can be either
2398the name of a container or an input device. If not specified the
2399format is guessed from @var{movie_name} or by probing.
2400
2401@item seek_point, sp
2402Specifies the seek point in seconds, the frames will be output
2403starting from this seek point, the parameter is evaluated with
2404@code{av_strtod} so the numerical value may be suffixed by an IS
2405postfix. Default value is "0".
2406
2407@item stream_index, si
2408Specifies the index of the video stream to read. If the value is -1,
2409the best suited video stream will be automatically selected. Default
2410value is "-1".
2411
2412@end table
2413
2414This filter allows to overlay a second video on top of main input of
2415a filtergraph as shown in this graph:
2416@example
2417input -----------> deltapts0 --> overlay --> output
2418 ^
2419 |
2420movie --> scale--> deltapts1 -------+
2421@end example
2422
2423Some examples follow:
2424@example
2425# skip 3.2 seconds from the start of the avi file in.avi, and overlay it
2426# on top of the input labelled as "in".
2427movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2428[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2429
2430# read from a video4linux2 device, and overlay it on top of the input
2431# labelled as "in"
2432movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2433[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2434
2435@end example
2436
3275ac6a
SS
2437@section nullsrc
2438
2439Null video source, never return images. It is mainly useful as a
2440template and to be employed in analysis / debugging tools.
2441
2442It accepts as optional parameter a string of the form
16134b7c 2443@var{width}:@var{height}:@var{timebase}.
3275ac6a 2444
16134b7c
SS
2445@var{width} and @var{height} specify the size of the configured
2446source. The default values of @var{width} and @var{height} are
2447respectively 352 and 288 (corresponding to the CIF size format).
2448
2449@var{timebase} specifies an arithmetic expression representing a
2450timebase. The expression can contain the constants "PI", "E", "PHI",
2451"AVTB" (the default timebase), and defaults to the value "AVTB".
3275ac6a 2452
f8608dca
SS
2453@section frei0r_src
2454
2455Provide a frei0r source.
2456
2457To enable compilation of this filter you need to install the frei0r
f8a45fa1 2458header and configure Libav with --enable-frei0r.
f8608dca 2459
5aa1a668
AK
2460This source accepts the following options:
2461
2462@table @option
2463
2464@item size
2465The size of the video to generate, may be a string of the form
2466@var{width}x@var{height} or a frame size abbreviation.
f8608dca 2467
5aa1a668
AK
2468@item framerate
2469Framerate of the generated video, may be a string of the form
2470@var{num}/@var{den} or a frame rate abbreviation.
2471
2472@item filter_name
2473The name to the frei0r source to load. For more information regarding frei0r and
2474how to set the parameters read the section @ref{frei0r} in the description of
2475the video filters.
2476
2477@item filter_params
2478A '|'-separated list of parameters to pass to the frei0r source.
2479
2480@end table
f8608dca
SS
2481
2482Some examples follow:
2483@example
2484# generate a frei0r partik0l source with size 200x200 and framerate 10
2485# which is overlayed on the overlay filter main input
5aa1a668 2486frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
f8608dca
SS
2487@end example
2488
ec2ac927 2489@section rgbtestsrc, testsrc
0244879f 2490
ec2ac927
SS
2491The @code{rgbtestsrc} source generates an RGB test pattern useful for
2492detecting RGB vs BGR issues. You should see a red, green and blue
2493stripe from top to bottom.
0244879f 2494
ec2ac927
SS
2495The @code{testsrc} source generates a test video pattern, showing a
2496color pattern, a scrolling gradient and a timestamp. This is mainly
2497intended for testing purposes.
2498
7b3eb745 2499The sources accept the following options:
0244879f
SS
2500
2501@table @option
2502
2503@item size, s
2504Specify the size of the sourced video, it may be a string of the form
da9cea77 2505@var{width}x@var{height}, or the name of a size abbreviation. The
0244879f
SS
2506default value is "320x240".
2507
2508@item rate, r
2509Specify the frame rate of the sourced video, as the number of frames
2510generated per second. It has to be a string in the format
2511@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2512number or a valid video frame rate abbreviation. The default value is
2513"25".
2514
2515@item sar
2516Set the sample aspect ratio of the sourced video.
2517
2518@item duration
2519Set the video duration of the sourced video. The accepted syntax is:
2520@example
2521[-]HH[:MM[:SS[.m...]]]
2522[-]S+[.m...]
2523@end example
2524See also the function @code{av_parse_time()}.
2525
2526If not specified, or the expressed duration is negative, the video is
2527supposed to be generated forever.
2528@end table
2529
2530For example the following:
2531@example
2532testsrc=duration=5.3:size=qcif:rate=10
2533@end example
2534
2535will generate a video with a duration of 5.3 seconds, with size
2536176x144 and a framerate of 10 frames per second.
2537
3275ac6a
SS
2538@c man end VIDEO SOURCES
2539
2540@chapter Video Sinks
2541@c man begin VIDEO SINKS
2542
2543Below is a description of the currently available video sinks.
2544
ac712309
AK
2545@section buffersink
2546
2547Buffer video frames, and make them available to the end of the filter
2548graph.
2549
2550This sink is intended for a programmatic use through the interface defined in
2551@file{libavfilter/buffersink.h}.
2552
3275ac6a
SS
2553@section nullsink
2554
2555Null video sink, do absolutely nothing with the input video. It is
2556mainly useful as a template and to be employed in analysis / debugging
2557tools.
2558
2559@c man end VIDEO SINKS