lavfi: port boxblur filter from libmpcodecs
[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
17@section Filtergraph syntax
18
19A filtergraph can be represented using a textual representation, which
20is recognized by the @code{-vf} and @code{-af} options of the ff*
21tools, and by the @code{av_parse_graph()} function defined in
22@file{libavfilter/avfiltergraph}.
23
24A filterchain consists of a sequence of connected filters, each one
25connected to the previous one in the sequence. A filterchain is
26represented by a list of ","-separated filter descriptions.
27
28A filtergraph consists of a sequence of filterchains. A sequence of
29filterchains is represented by a list of ";"-separated filterchain
30descriptions.
31
32A filter is represented by a string of the form:
33[@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
34
35@var{filter_name} is the name of the filter class of which the
36described filter is an instance of, and has to be the name of one of
37the filter classes registered in the program.
38The name of the filter class is optionally followed by a string
39"=@var{arguments}".
40
41@var{arguments} is a string which contains the parameters used to
42initialize the filter instance, and are described in the filter
43descriptions below.
44
45The list of arguments can be quoted using the character "'" as initial
46and ending mark, and the character '\' for escaping the characters
47within the quoted text; otherwise the argument string is considered
48terminated when the next special character (belonging to the set
49"[]=;,") is encountered.
50
51The name and arguments of the filter are optionally preceded and
52followed by a list of link labels.
53A link label allows to name a link and associate it to a filter output
54or input pad. The preceding labels @var{in_link_1}
55... @var{in_link_N}, are associated to the filter input pads,
56the following labels @var{out_link_1} ... @var{out_link_M}, are
57associated to the output pads.
58
59When two link labels with the same name are found in the
60filtergraph, a link between the corresponding input and output pad is
61created.
62
63If an output pad is not labelled, it is linked by default to the first
64unlabelled input pad of the next filter in the filterchain.
65For example in the filterchain:
66@example
67nullsrc, split[L1], [L2]overlay, nullsink
68@end example
69the split filter instance has two output pads, and the overlay filter
70instance two input pads. The first output pad of split is labelled
71"L1", the first input pad of overlay is labelled "L2", and the second
72output pad of split is linked to the second input pad of overlay,
73which are both unlabelled.
74
75In a complete filterchain all the unlabelled filter input and output
76pads must be connected. A filtergraph is considered valid if all the
77filter input and output pads of all the filterchains are connected.
78
79Follows a BNF description for the filtergraph syntax:
80@example
81@var{NAME} ::= sequence of alphanumeric characters and '_'
82@var{LINKLABEL} ::= "[" @var{NAME} "]"
83@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
84@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
85@var{FILTER} ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
86@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
87@var{FILTERGRAPH} ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
88@end example
89
90@c man end FILTERGRAPH DESCRIPTION
91
f59e9eaf
SS
92@chapter Audio Filters
93@c man begin AUDIO FILTERS
94
f8a45fa1 95When you configure your Libav build, you can disable any of the
f59e9eaf
SS
96existing filters using --disable-filters.
97The configure output will show the audio filters included in your
98build.
99
100Below is a description of the currently available audio filters.
101
99046339
HM
102@section anull
103
104Pass the audio source unchanged to the output.
105
f59e9eaf
SS
106@c man end AUDIO FILTERS
107
1ee410f3
SS
108@chapter Audio Sources
109@c man begin AUDIO SOURCES
110
111Below is a description of the currently available audio sources.
112
113@section anullsrc
114
115Null audio source, never return audio frames. It is mainly useful as a
116template and to be employed in analysis / debugging tools.
117
118It accepts as optional parameter a string of the form
119@var{sample_rate}:@var{channel_layout}.
120
121@var{sample_rate} specify the sample rate, and defaults to 44100.
122
123@var{channel_layout} specify the channel layout, and can be either an
124integer or a string representing a channel layout. The default value
125of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
126
127Check the channel_layout_map definition in
6ef93402
SS
128@file{libavcodec/audioconvert.c} for the mapping between strings and
129channel layout values.
1ee410f3
SS
130
131Follow some examples:
132@example
133# set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO.
134anullsrc=48000:4
135
136# same as
137anullsrc=48000:mono
138@end example
139
140@c man end AUDIO SOURCES
141
f0a55438
HM
142@chapter Audio Sinks
143@c man begin AUDIO SINKS
144
145Below is a description of the currently available audio sinks.
146
147@section anullsink
148
149Null audio sink, do absolutely nothing with the input audio. It is
150mainly useful as a template and to be employed in analysis / debugging
151tools.
152
153@c man end AUDIO SINKS
154
3275ac6a
SS
155@chapter Video Filters
156@c man begin VIDEO FILTERS
157
f8a45fa1 158When you configure your Libav build, you can disable any of the
3275ac6a
SS
159existing filters using --disable-filters.
160The configure output will show the video filters included in your
161build.
162
163Below is a description of the currently available video filters.
164
13fabd7a
SS
165@section blackframe
166
167Detect frames that are (almost) completely black. Can be useful to
168detect chapter transitions or commercials. Output lines consist of
169the frame number of the detected frame, the percentage of blackness,
170the position in the file if known or -1 and the timestamp in seconds.
171
172In order to display the output lines, you need to set the loglevel at
173least to the AV_LOG_INFO value.
174
175The filter accepts the syntax:
176@example
177blackframe[=@var{amount}:[@var{threshold}]]
178@end example
179
180@var{amount} is the percentage of the pixels that have to be below the
181threshold, and defaults to 98.
182
183@var{threshold} is the threshold below which a pixel value is
184considered black, and defaults to 32.
185
ce6b6ef6
SS
186@section boxblur
187
188Apply boxblur algorithm to the input video.
189
190This filter accepts the parameters:
191@var{luma_power}:@var{luma_radius}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
192
193Chroma and alpha parameters are optional, if not specified they default
194to the corresponding values set for @var{luma_radius} and
195@var{luma_power}.
196
197@var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
198the radius in pixels of the box used for blurring the corresponding
199input plane. They are expressions, and can contain the following
200constants:
201@table @option
202@item w, h
203the input width and heigth in pixels
204
205@item cw, ch
206the input chroma image width and height in pixels
207
208@item hsub, vsub
209horizontal and vertical chroma subsample values. For example for the
210pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
211@end table
212
213The radius must be a non-negative number, and must not be greater than
214the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
215and of @code{min(cw,ch)/2} for the chroma planes.
216
217@var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
218how many times the boxblur filter is applied to the corresponding
219plane.
220
221Some examples follow:
222
223@itemize
224
225@item
226Apply a boxblur filter with luma, chroma, and alpha radius
227set to 2:
228@example
229boxblur=2:1
230@end example
231
232@item
233Set luma radius to 2, alpha and chroma radius to 0
234@example
235boxblur=2:1:0:0:0:0
236@end example
237
238@item
239Set luma and chroma radius to a fraction of the video dimension
240@example
241boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
242@end example
243
244@end itemize
245
b5670209
SS
246@section copy
247
248Copy the input source unchanged to the output. Mainly useful for
249testing purposes.
250
3275ac6a
SS
251@section crop
252
75b67a8a 253Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
3275ac6a 254
75b67a8a
SS
255The parameters are expressions containing the following constants:
256
257@table @option
258@item E, PI, PHI
259the corresponding mathematical approximated values for e
260(euler number), pi (greek PI), PHI (golden ratio)
261
262@item x, y
263the computed values for @var{x} and @var{y}. They are evaluated for
264each new frame.
265
266@item in_w, in_h
e83c2dde 267the input width and height
75b67a8a
SS
268
269@item iw, ih
270same as @var{in_w} and @var{in_h}
271
272@item out_w, out_h
e83c2dde 273the output (cropped) width and height
75b67a8a
SS
274
275@item ow, oh
276same as @var{out_w} and @var{out_h}
277
278@item n
279the number of input frame, starting from 0
280
281@item pos
282the position in the file of the input frame, NAN if unknown
283
284@item t
285timestamp expressed in seconds, NAN if the input timestamp is unknown
3275ac6a 286
75b67a8a 287@end table
3275ac6a 288
75b67a8a
SS
289The @var{out_w} and @var{out_h} parameters specify the expressions for
290the width and height of the output (cropped) video. They are
291evaluated just at the configuration of the filter.
3275ac6a 292
75b67a8a
SS
293The default value of @var{out_w} is "in_w", and the default value of
294@var{out_h} is "in_h".
2bc05d35 295
75b67a8a
SS
296The expression for @var{out_w} may depend on the value of @var{out_h},
297and the expression for @var{out_h} may depend on @var{out_w}, but they
298cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
299evaluated after @var{out_w} and @var{out_h}.
2bc05d35 300
75b67a8a
SS
301The @var{x} and @var{y} parameters specify the expressions for the
302position of the top-left corner of the output (non-cropped) area. They
303are evaluated for each frame. If the evaluated value is not valid, it
304is approximated to the nearest valid value.
3275ac6a 305
75b67a8a
SS
306The default value of @var{x} is "(in_w-out_w)/2", and the default
307value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
308the center of the input image.
309
310The expression for @var{x} may depend on @var{y}, and the expression
311for @var{y} may depend on @var{x}.
312
313Follow some examples:
3275ac6a 314@example
75b67a8a
SS
315# crop the central input area with size 100x100
316crop=100:100
317
318# crop the central input area with size 2/3 of the input video
319"crop=2/3*in_w:2/3*in_h"
320
321# crop the input video central square
322crop=in_h
323
324# delimit the rectangle with the top-left corner placed at position
325# 100:100 and the right-bottom corner corresponding to the right-bottom
326# corner of the input image.
327crop=in_w-100:in_h-100:100:100
3275ac6a 328
e6dba1d8 329# crop 10 pixels from the left and right borders, and 20 pixels from
75b67a8a
SS
330# the top and bottom borders
331"crop=in_w-2*10:in_h-2*20"
3275ac6a 332
75b67a8a
SS
333# keep only the bottom right quarter of the input image
334"crop=in_w/2:in_h/2:in_w/2:in_h/2"
335
336# crop height for getting Greek harmony
337"crop=in_w:1/PHI*in_w"
338
339# trembling effect
340"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)"
341
e6dba1d8 342# erratic camera effect depending on timestamp
75b67a8a
SS
343"crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
344
345# set x depending on the value of y
346"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
347@end example
3275ac6a 348
68b79bfc
SS
349@section cropdetect
350
351Auto-detect crop size.
352
353Calculate necessary cropping parameters and prints the recommended
354parameters through the logging system. The detected dimensions
355correspond to the non-black area of the input video.
356
357It accepts the syntax:
358@example
3699c1f1 359cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
68b79bfc
SS
360@end example
361
362@table @option
363
364@item limit
365Threshold, which can be optionally specified from nothing (0) to
366everything (255), defaults to 24.
367
368@item round
369Value which the width/height should be divisible by, defaults to
37016. The offset is automatically adjusted to center the video. Use 2 to
371get only even dimensions (needed for 4:2:2 video). 16 is best when
372encoding to most video codecs.
373
374@item reset
375Counter that determines after how many frames cropdetect will reset
376the previously detected largest video area and start over to detect
377the current optimal crop area. Defaults to 0.
378
379This can be useful when channel logos distort the video area. 0
380indicates never reset and return the largest area encountered during
381playback.
382@end table
383
e40032e2
SS
384@section drawbox
385
386Draw a colored box on the input image.
387
388It accepts the syntax:
389@example
390drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
391@end example
392
393@table @option
394
395@item x, y
396Specify the top left corner coordinates of the box. Default to 0.
397
398@item width, height
399Specify the width and height of the box, if 0 they are interpreted as
400the input width and height. Default to 0.
401
402@item color
403Specify the color of the box to write, it can be the name of a color
404(case insensitive match) or a 0xRRGGBB[AA] sequence.
405@end table
406
407Follow some examples:
408@example
409# draw a black box around the edge of the input image
410drawbox
411
412# draw a box with color red and an opacity of 50%
413drawbox=10:20:200:60:red@@0.5"
414@end example
415
a5b64584
SS
416@section drawtext
417
418Draw text string or text from specified file on top of video using the
419libfreetype library.
420
421To enable compilation of this filter you need to configure FFmpeg with
422@code{--enable-libfreetype}.
423
424The filter also recognizes strftime() sequences in the provided text
425and expands them accordingly. Check the documentation of strftime().
426
427The filter accepts parameters as a list of @var{key}=@var{value} pairs,
428separated by ":".
429
430The description of the accepted parameters follows.
431
432@table @option
433
434@item fontfile
435The font file to be used for drawing text. Path must be included.
436This parameter is mandatory.
437
438@item text
439The text string to be drawn. The text must be a sequence of UTF-8
440encoded characters.
441This parameter is mandatory if no file is specified with the parameter
442@var{textfile}.
443
444@item textfile
445A text file containing text to be drawn. The text must be a sequence
446of UTF-8 encoded characters.
447
448This parameter is mandatory if no text string is specified with the
449parameter @var{text}.
450
451If both text and textfile are specified, an error is thrown.
452
453@item x, y
454The offsets where text will be drawn within the video frame.
455Relative to the top/left border of the output image.
456
457The default value of @var{x} and @var{y} is 0.
458
459@item fontsize
460The font size to be used for drawing text.
461The default value of @var{fontsize} is 16.
462
463@item fontcolor
464The color to be used for drawing fonts.
465Either a string (e.g. "red") or in 0xRRGGBB[AA] format
466(e.g. "0xff000033"), possibly followed by an alpha specifier.
467The default value of @var{fontcolor} is "black".
468
469@item boxcolor
470The color to be used for drawing box around text.
471Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
472(e.g. "0xff00ff"), possibly followed by an alpha specifier.
473The default value of @var{boxcolor} is "white".
474
475@item box
476Used to draw a box around text using background color.
477Value should be either 1 (enable) or 0 (disable).
478The default value of @var{box} is 0.
479
994de197
SS
480@item shadowx, shadowy
481The x and y offsets for the text shadow position with respect to the
482position of the text. They can be either positive or negative
483values. Default value for both is "0".
484
485@item shadowcolor
486The color to be used for drawing a shadow behind the drawn text. It
487can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
488form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
489The default value of @var{shadowcolor} is "black".
490
a5b64584
SS
491@item ft_load_flags
492Flags to be used for loading the fonts.
493
494The flags map the corresponding flags supported by libfreetype, and are
495a combination of the following values:
496@table @var
497@item default
498@item no_scale
499@item no_hinting
500@item render
501@item no_bitmap
502@item vertical_layout
503@item force_autohint
504@item crop_bitmap
505@item pedantic
506@item ignore_global_advance_width
507@item no_recurse
508@item ignore_transform
509@item monochrome
510@item linear_design
511@item no_autohint
512@item end table
513@end table
514
515Default value is "render".
516
517For more information consult the documentation for the FT_LOAD_*
518libfreetype flags.
519
520@item tabsize
521The size in number of spaces to use for rendering the tab.
522Default value is 4.
523@end table
524
525For example the command:
526@example
527drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
528@end example
529
530will draw "Test Text" with font FreeSerif, using the default values
531for the optional parameters.
532
533The command:
534@example
535drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
536 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
537@end example
538
539will draw 'Test Text' with font FreeSerif of size 24 at position x=100
540and y=50 (counting from the top-left corner of the screen), text is
541yellow with a red box around it. Both the text and the box have an
542opacity of 20%.
543
544Note that the double quotes are not necessary if spaces are not used
545within the parameter list.
546
547For more information about libfreetype, check:
548@url{http://www.freetype.org/}.
549
aadfc9ee
BM
550@section fade
551
552Apply fade-in/out effect to input video.
553
554It accepts the parameters:
555@var{type}:@var{start_frame}:@var{nb_frames}
556
557@var{type} specifies if the effect type, can be either "in" for
558fade-in, or "out" for a fade-out effect.
559
560@var{start_frame} specifies the number of the start frame for starting
561to apply the fade effect.
562
563@var{nb_frames} specifies the number of frames for which the fade
564effect has to last. At the end of the fade-in effect the output video
565will have the same intensity as the input video, at the end of the
566fade-out transition the output video will be completely black.
567
568A few usage examples follow, usable too as test scenarios.
569@example
570# fade in first 30 frames of video
571fade=in:0:30
572
573# fade out last 45 frames of a 200-frame video
574fade=out:155:45
575
576# fade in first 25 frames and fade out last 25 frames of a 1000-frame video
577fade=in:0:25, fade=out:975:25
578
579# make first 5 frames black, then fade in from frame 5-24
580fade=in:5:20
581@end example
582
2f84bb42
MH
583@section fieldorder
584
585Transform the field order of the input video.
586
587It accepts one parameter which specifies the required field order that
588the input interlaced video will be transformed to. The parameter can
589assume one of the following values:
590
591@table @option
592@item 0 or bff
593output bottom field first
594@item 1 or tff
595output top field first
596@end table
597
598Default value is "tff".
599
600Transformation is achieved by shifting the picture content up or down
601by one line, and filling the remaining line with appropriate picture content.
602This method is consistent with most broadcast field order converters.
603
604If the input video is not flagged as being interlaced, or it is already
605flagged as being of the required output field order then this filter does
606not alter the incoming video.
607
608This filter is very useful when converting to or from PAL DV material,
609which is bottom field first.
610
611For example:
612@example
613./ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
614@end example
615
7f1af825
SS
616@section fifo
617
618Buffer input images and send them when they are requested.
619
620This filter is mainly useful when auto-inserted by the libavfilter
621framework.
622
623The filter does not take parameters.
624
3275ac6a
SS
625@section format
626
627Convert the input video to one of the specified pixel formats.
628Libavfilter will try to pick one that is supported for the input to
629the next filter.
630
b1094275
SS
631The filter accepts a list of pixel format names, separated by ":",
632for example "yuv420p:monow:rgb24".
3275ac6a 633
f150e4dc 634Some examples follow:
3275ac6a 635@example
f150e4dc
SS
636# convert the input video to the format "yuv420p"
637format=yuv420p
3275ac6a 638
f150e4dc
SS
639# convert the input video to any of the formats in the list
640format=yuv420p:yuv444p:yuv410p
641@end example
3275ac6a 642
f8608dca 643@anchor{frei0r}
47941088
SS
644@section frei0r
645
646Apply a frei0r effect to the input video.
647
648To enable compilation of this filter you need to install the frei0r
f8a45fa1 649header and configure Libav with --enable-frei0r.
47941088
SS
650
651The filter supports the syntax:
652@example
f51aeedd 653@var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
47941088
SS
654@end example
655
656@var{filter_name} is the name to the frei0r effect to load. If the
657environment variable @env{FREI0R_PATH} is defined, the frei0r effect
658is searched in each one of the directories specified by the colon
659separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
660paths, which are in this order: @file{HOME/.frei0r-1/lib/},
661@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
662
663@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
664for the frei0r effect.
665
666A frei0r effect parameter can be a boolean (whose values are specified
667with "y" and "n"), a double, a color (specified by the syntax
668@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
669numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
670description), a position (specified by the syntax @var{X}/@var{Y},
671@var{X} and @var{Y} being float numbers) and a string.
672
673The number and kind of parameters depend on the loaded effect. If an
674effect parameter is not specified the default value is set.
675
676Some examples follow:
677@example
678# apply the distort0r effect, set the first two double parameters
679frei0r=distort0r:0.5:0.01
680
681# apply the colordistance effect, takes a color as first parameter
682frei0r=colordistance:0.2/0.3/0.4
683frei0r=colordistance:violet
684frei0r=colordistance:0x112233
685
686# apply the perspective effect, specify the top left and top right
687# image positions
688frei0r=perspective:0.2/0.2:0.8/0.2
689@end example
690
691For more information see:
692@url{http://piksel.org/frei0r}
693
d5f187fd
N
694@section gradfun
695
696Fix the banding artifacts that are sometimes introduced into nearly flat
697regions by truncation to 8bit colordepth.
698Interpolate the gradients that should go where the bands are, and
699dither them.
700
3eccfaa0
SS
701This filter is designed for playback only. Do not use it prior to
702lossy compression, because compression tends to lose the dither and
703bring back the bands.
704
d5f187fd
N
705The filter takes two optional parameters, separated by ':':
706@var{strength}:@var{radius}
707
708@var{strength} is the maximum amount by which the filter will change
709any one pixel. Also the threshold for detecting nearly flat
710regions. Acceptable values range from .51 to 255, default value is
7111.2, out-of-range values will be clipped to the valid range.
712
713@var{radius} is the neighborhood to fit the gradient to. A larger
714radius makes for smoother gradients, but also prevents the filter from
715modifying the pixels near detailed regions. Acceptable values are
7168-32, default value is 16, out-of-range values will be clipped to the
717valid range.
718
719@example
720# default parameters
721gradfun=1.2:16
722
723# omitting radius
724gradfun=1.2
725@end example
726
a1e171df
SS
727@section hflip
728
729Flip the input video horizontally.
730
731For example to horizontally flip the video in input with
732@file{ffmpeg}:
733@example
734ffmpeg -i in.avi -vf "hflip" out.avi
735@end example
736
a4dc7aa5
BC
737@section hqdn3d
738
739High precision/quality 3d denoise filter. This filter aims to reduce
740image noise producing smooth images and making still images really
741still. It should enhance compressibility.
742
743It accepts the following optional parameters:
744@var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
745
746@table @option
747@item luma_spatial
748a non-negative float number which specifies spatial luma strength,
749defaults to 4.0
750
751@item chroma_spatial
752a non-negative float number which specifies spatial chroma strength,
753defaults to 3.0*@var{luma_spatial}/4.0
754
755@item luma_tmp
756a float number which specifies luma temporal strength, defaults to
7576.0*@var{luma_spatial}/4.0
758
759@item chroma_tmp
760a float number which specifies chroma temporal strength, defaults to
761@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
762@end table
763
8fe0c527
SS
764@section lut, lutrgb, lutyuv
765
766Compute a look-up table for binding each pixel component input value
767to an output value, and apply it to input video.
768
769@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
770to an RGB input video.
771
772These filters accept in input a ":"-separated list of options, which
773specify the expressions used for computing the lookup table for the
774corresponding pixel component values.
775
776The @var{lut} filter requires either YUV or RGB pixel formats in
777input, and accepts the options:
778@table @option
779@var{c0} (first pixel component)
780@var{c1} (second pixel component)
781@var{c2} (third pixel component)
782@var{c3} (fourth pixel component, corresponds to the alpha component)
783@end table
784
785The exact component associated to each option depends on the format in
786input.
787
788The @var{lutrgb} filter requires RGB pixel formats in input, and
789accepts the options:
790@table @option
791@var{r} (red component)
792@var{g} (green component)
793@var{b} (blue component)
794@var{a} (alpha component)
795@end table
796
797The @var{lutyuv} filter requires YUV pixel formats in input, and
798accepts the options:
799@table @option
800@var{y} (Y/luminance component)
801@var{u} (U/Cb component)
802@var{v} (V/Cr component)
803@var{a} (alpha component)
804@end table
805
806The expressions can contain the following constants and functions:
807
808@table @option
809@item E, PI, PHI
810the corresponding mathematical approximated values for e
811(euler number), pi (greek PI), PHI (golden ratio)
812
813@item w, h
814the input width and heigth
815
816@item val
817input value for the pixel component
818
819@item clipval
820the input value clipped in the @var{minval}-@var{maxval} range
821
822@item maxval
823maximum value for the pixel component
824
825@item minval
826minimum value for the pixel component
827
828@item negval
829the negated value for the pixel component value clipped in the
830@var{minval}-@var{maxval} range , it corresponds to the expression
831"maxval-clipval+minval"
832
833@item clip(val)
834the computed value in @var{val} clipped in the
835@var{minval}-@var{maxval} range
836
837@item gammaval(gamma)
838the computed gamma correction value of the pixel component value
839clipped in the @var{minval}-@var{maxval} range, corresponds to the
840expression
841"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
842
843@end table
844
845All expressions default to "val".
846
847Some examples follow:
848@example
849# negate input video
850lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
851lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
852
853# the above is the same as
854lutrgb="r=negval:g=negval:b=negval"
855lutyuv="y=negval:u=negval:v=negval"
856
857# negate luminance
858lutyuv=negval
859
860# remove chroma components, turns the video into a graytone image
861lutyuv="u=128:v=128"
862
863# apply a luma burning effect
864lutyuv="y=2*val"
865
866# remove green and blue components
867lutrgb="g=0:b=0"
868
869# set a constant alpha channel value on input
870format=rgba,lutrgb=a="maxval-minval/2"
871
872# correct luminance gamma by a 0.5 factor
873lutyuv=y=gammaval(0.5)
874@end example
875
171868e2
SS
876@section negate
877
878Negate input video.
879
880This filter accepts an integer in input, if non-zero it negates the
881alpha component (if available). The default value in input is 0.
3275ac6a
SS
882
883Force libavfilter not to use any of the specified pixel formats for the
884input to the next filter.
885
b1094275
SS
886The filter accepts a list of pixel format names, separated by ":",
887for example "yuv420p:monow:rgb24".
3275ac6a 888
f150e4dc 889Some examples follow:
3275ac6a 890@example
f150e4dc
SS
891# force libavfilter to use a format different from "yuv420p" for the
892# input to the vflip filter
893noformat=yuv420p,vflip
3275ac6a 894
f150e4dc
SS
895# convert the input video to any of the formats not contained in the list
896noformat=yuv420p:yuv444p:yuv410p
897@end example
3275ac6a
SS
898
899@section null
900
99046339 901Pass the video source unchanged to the output.
3275ac6a 902
cf69ad35 903@section ocv
6ebf0bfc 904
cf69ad35 905Apply video transform using libopencv.
6ebf0bfc
SS
906
907To enable this filter install libopencv library and headers and
f8a45fa1 908configure Libav with --enable-libopencv.
6ebf0bfc 909
cf69ad35
SS
910The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
911
912@var{filter_name} is the name of the libopencv filter to apply.
913
914@var{filter_params} specifies the parameters to pass to the libopencv
915filter. If not specified the default values are assumed.
916
917Refer to the official libopencv documentation for more precise
918informations:
919@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
920
921Follows the list of supported libopencv filters.
922
17fc9493 923@anchor{dilate}
91cbb6ba
SS
924@subsection dilate
925
926Dilate an image by using a specific structuring element.
927This filter corresponds to the libopencv function @code{cvDilate}.
928
929It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
930
931@var{struct_el} represents a structuring element, and has the syntax:
932@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
933
934@var{cols} and @var{rows} represent the number of colums and rows of
935the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
936point, and @var{shape} the shape for the structuring element, and
937can be one of the values "rect", "cross", "ellipse", "custom".
938
939If the value for @var{shape} is "custom", it must be followed by a
940string of the form "=@var{filename}". The file with name
941@var{filename} is assumed to represent a binary image, with each
942printable character corresponding to a bright pixel. When a custom
943@var{shape} is used, @var{cols} and @var{rows} are ignored, the number
944or columns and rows of the read file are assumed instead.
945
946The default value for @var{struct_el} is "3x3+0x0/rect".
947
948@var{nb_iterations} specifies the number of times the transform is
949applied to the image, and defaults to 1.
950
951Follow some example:
952@example
953# use the default values
954ocv=dilate
955
956# dilate using a structuring element with a 5x5 cross, iterate two times
957ocv=dilate=5x5+2x2/cross:2
958
959# read the shape from the file diamond.shape, iterate two times
960# the file diamond.shape may contain a pattern of characters like this:
961# *
962# ***
963# *****
964# ***
965# *
966# the specified cols and rows are ignored (but not the anchor point coordinates)
967ocv=0x0+2x2/custom=diamond.shape:2
968@end example
969
17fc9493
SS
970@subsection erode
971
972Erode an image by using a specific structuring element.
973This filter corresponds to the libopencv function @code{cvErode}.
974
975The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
4c989761 976with the same syntax and semantics as the @ref{dilate} filter.
17fc9493 977
cf69ad35
SS
978@subsection smooth
979
980Smooth the input video.
981
982The filter takes the following parameters:
6ebf0bfc
SS
983@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
984
985@var{type} is the type of smooth filter to apply, and can be one of
58d94364 986the following values: "blur", "blur_no_scale", "median", "gaussian",
6ebf0bfc
SS
987"bilateral". The default value is "gaussian".
988
989@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
990parameters whose meanings depend on smooth type. @var{param1} and
991@var{param2} accept integer positive values or 0, @var{param3} and
992@var{param4} accept float values.
993
994The default value for @var{param1} is 3, the default value for the
995other parameters is 0.
996
58d94364 997These parameters correspond to the parameters assigned to the
cf69ad35 998libopencv function @code{cvSmooth}.
6ebf0bfc 999
58935b25
SS
1000@section overlay
1001
1002Overlay one video on top of another.
1003
1004It takes two inputs and one output, the first input is the "main"
1005video on which the second input is overlayed.
1006
1007It accepts the parameters: @var{x}:@var{y}.
1008
1009@var{x} is the x coordinate of the overlayed video on the main video,
1010@var{y} is the y coordinate. The parameters are expressions containing
1011the following parameters:
1012
1013@table @option
1014@item main_w, main_h
1015main input width and height
1016
1017@item W, H
1018same as @var{main_w} and @var{main_h}
1019
1020@item overlay_w, overlay_h
1021overlay input width and height
1022
1023@item w, h
1024same as @var{overlay_w} and @var{overlay_h}
1025@end table
1026
1027Be aware that frames are taken from each input video in timestamp
1028order, hence, if their initial timestamps differ, it is a a good idea
1029to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
1030have them begin in the same zero timestamp, as it does the example for
1031the @var{movie} filter.
1032
1033Follow some examples:
1034@example
1035# draw the overlay at 10 pixels from the bottom right
1036# corner of the main video.
1037overlay=main_w-overlay_w-10:main_h-overlay_h-10
1038
1039# insert a transparent PNG logo in the bottom left corner of the input
aa8ac53b 1040movie=logo.png [logo];
58935b25
SS
1041[in][logo] overlay=10:main_h-overlay_h-10 [out]
1042
1043# insert 2 different transparent PNG logos (second logo on bottom
1044# right corner):
aa8ac53b
SS
1045movie=logo1.png [logo1];
1046movie=logo2.png [logo2];
58935b25
SS
1047[in][logo1] overlay=10:H-h-10 [in+logo1];
1048[in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
1049
1050# add a transparent color layer on top of the main video,
1051# WxH specifies the size of the main input to the overlay filter
1052color=red@.3:WxH [over]; [in][over] overlay [out]
1053@end example
1054
1055You can chain togheter more overlays but the efficiency of such
1056approach is yet to be tested.
1057
3275ac6a
SS
1058@section pad
1059
1060Add paddings to the input image, and places the original input at the
1061given coordinates @var{x}, @var{y}.
1062
1063It accepts the following parameters:
1064@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
1065
73a4f7c2
SS
1066The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
1067expressions containing the following constants:
1068
1069@table @option
1070@item E, PI, PHI
1071the corresponding mathematical approximated values for e
1072(euler number), pi (greek PI), phi (golden ratio)
1073
1074@item in_w, in_h
e83c2dde 1075the input video width and height
73a4f7c2
SS
1076
1077@item iw, ih
1078same as @var{in_w} and @var{in_h}
1079
1080@item out_w, out_h
e83c2dde 1081the output width and height, that is the size of the padded area as
73a4f7c2
SS
1082specified by the @var{width} and @var{height} expressions
1083
1084@item ow, oh
1085same as @var{out_w} and @var{out_h}
1086
1087@item x, y
1088x and y offsets as specified by the @var{x} and @var{y}
1089expressions, or NAN if not yet specified
1090
1091@item a
1092input display aspect ratio, same as @var{iw} / @var{ih}
1093
1094@item hsub, vsub
1095horizontal and vertical chroma subsample values. For example for the
1096pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1097@end table
1098
3275ac6a
SS
1099Follows the description of the accepted parameters.
1100
1101@table @option
1102@item width, height
1103
1104Specify the size of the output image with the paddings added. If the
1105value for @var{width} or @var{height} is 0, the corresponding input size
1106is used for the output.
1107
73a4f7c2
SS
1108The @var{width} expression can reference the value set by the
1109@var{height} expression, and viceversa.
1110
3275ac6a
SS
1111The default value of @var{width} and @var{height} is 0.
1112
1113@item x, y
1114
1115Specify the offsets where to place the input image in the padded area
1116with respect to the top/left border of the output image.
1117
73a4f7c2
SS
1118The @var{x} expression can reference the value set by the @var{y}
1119expression, and viceversa.
1120
3275ac6a
SS
1121The default value of @var{x} and @var{y} is 0.
1122
1123@item color
1124
1125Specify the color of the padded area, it can be the name of a color
1126(case insensitive match) or a 0xRRGGBB[AA] sequence.
1127
b1094275 1128The default value of @var{color} is "black".
3275ac6a
SS
1129
1130@end table
1131
73a4f7c2 1132Some examples follow:
3d17f4b9
SS
1133
1134@example
1135# Add paddings with color "violet" to the input video. Output video
1136# size is 640x480, the top-left corner of the input video is placed at
aeefbf61 1137# column 0, row 40.
3d17f4b9 1138pad=640:480:0:40:violet
73a4f7c2
SS
1139
1140# pad the input to get an output with dimensions increased bt 3/2,
1141# and put the input video at the center of the padded area
1142pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
1143
1144# pad the input to get a squared output with size equal to the maximum
1145# value between the input width and height, and put the input video at
1146# the center of the padded area
1147pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
1148
1149# pad the input to get a final w/h ratio of 16:9
1150pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
1151
1152# double output size and put the input video in the bottom-right
1153# corner of the output padded area
1154pad="2*iw:2*ih:ow-iw:oh-ih"
3d17f4b9
SS
1155@end example
1156
ce2e4ae3
SS
1157@section pixdesctest
1158
1159Pixel format descriptor test filter, mainly useful for internal
1160testing. The output video should be equal to the input video.
1161
1162For example:
1163@example
1164format=monow, pixdesctest
1165@end example
1166
1167can be used to test the monowhite pixel format descriptor definition.
1168
3275ac6a
SS
1169@section scale
1170
1171Scale the input video to @var{width}:@var{height} and/or convert the image format.
1172
68e23c08
SS
1173The parameters @var{width} and @var{height} are expressions containing
1174the following constants:
3275ac6a 1175
68e23c08
SS
1176@table @option
1177@item E, PI, PHI
1178the corresponding mathematical approximated values for e
1179(euler number), pi (greek PI), phi (golden ratio)
1180
1181@item in_w, in_h
e83c2dde 1182the input width and height
68e23c08
SS
1183
1184@item iw, ih
1185same as @var{in_w} and @var{in_h}
1186
1187@item out_w, out_h
e83c2dde 1188the output (cropped) width and height
68e23c08
SS
1189
1190@item ow, oh
1191same as @var{out_w} and @var{out_h}
3275ac6a 1192
46b29397 1193@item dar, a
68e23c08
SS
1194input display aspect ratio, same as @var{iw} / @var{ih}
1195
46b29397
SS
1196@item sar
1197input sample aspect ratio
1198
68e23c08
SS
1199@item hsub, vsub
1200horizontal and vertical chroma subsample values. For example for the
1201pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1202@end table
3275ac6a
SS
1203
1204If the input image format is different from the format requested by
1205the next filter, the scale filter will convert the input to the
1206requested format.
1207
1208If the value for @var{width} or @var{height} is 0, the respective input
1209size is used for the output.
1210
1211If the value for @var{width} or @var{height} is -1, the scale filter will
1212use, for the respective output size, a value that maintains the aspect
1213ratio of the input image.
1214
1215The default value of @var{width} and @var{height} is 0.
1216
68e23c08
SS
1217Some examples follow:
1218@example
1219# scale the input video to a size of 200x100.
1220scale=200:100
1221
1222# scale the input to 2x
1223scale=2*iw:2*ih
1224# the above is the same as
1225scale=2*in_w:2*in_h
1226
1227# scale the input to half size
1228scale=iw/2:ih/2
1229
1230# increase the width, and set the height to the same size
1231scale=3/2*iw:ow
1232
1233# seek for Greek harmony
1234scale=iw:1/PHI*iw
1235scale=ih*PHI:ih
1236
1237# increase the height, and set the width to 3/2 of the height
1238scale=3/2*oh:3/5*ih
1239
1240# increase the size, but make the size a multiple of the chroma
1241scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
1242
1243# increase the width to a maximum of 500 pixels, keep the same input aspect ratio
1244scale='min(500\, iw*3/2):-1'
1245@end example
1246
d763fb7d
SS
1247@section select
1248Select frames to pass in output.
1249
1250It accepts in input an expression, which is evaluated for each input
1251frame. If the expression is evaluated to a non-zero value, the frame
1252is selected and passed to the output, otherwise it is discarded.
1253
1254The expression can contain the following constants:
1255
1256@table @option
1257@item PI
1258Greek PI
1259
1260@item PHI
1261golden ratio
1262
1263@item E
1264Euler number
1265
1266@item n
1267the sequential number of the filtered frame, starting from 0
1268
1269@item selected_n
1270the sequential number of the selected frame, starting from 0
1271
1272@item prev_selected_n
1273the sequential number of the last selected frame, NAN if undefined
1274
1275@item TB
1276timebase of the input timestamps
1277
1278@item pts
1279the PTS (Presentation TimeStamp) of the filtered video frame,
1280expressed in @var{TB} units, NAN if undefined
1281
1282@item t
1283the PTS (Presentation TimeStamp) of the filtered video frame,
1284expressed in seconds, NAN if undefined
1285
1286@item prev_pts
1287the PTS of the previously filtered video frame, NAN if undefined
1288
1289@item prev_selected_pts
1290the PTS of the last previously filtered video frame, NAN if undefined
1291
1292@item prev_selected_t
1293the PTS of the last previously selected video frame, NAN if undefined
1294
1295@item start_pts
1296the PTS of the first video frame in the video, NAN if undefined
1297
1298@item start_t
1299the time of the first video frame in the video, NAN if undefined
1300
1301@item pict_type
1302the type of the filtered frame, can assume one of the following
1303values:
1304@table @option
1305@item I
1306@item P
1307@item B
1308@item S
1309@item SI
1310@item SP
1311@item BI
1312@end table
1313
1314@item interlace_type
1315the frame interlace type, can assume one of the following values:
1316@table @option
1317@item PROGRESSIVE
1318the frame is progressive (not interlaced)
1319@item TOPFIRST
1320the frame is top-field-first
1321@item BOTTOMFIRST
1322the frame is bottom-field-first
1323@end table
1324
1325@item key
13261 if the filtered frame is a key-frame, 0 otherwise
1327
1328@item pos
1329the position in the file of the filtered frame, -1 if the information
1330is not available (e.g. for synthetic video)
1331@end table
1332
1333The default value of the select expression is "1".
1334
1335Some examples follow:
1336
1337@example
1338# select all frames in input
1339select
1340
1341# the above is the same as:
1342select=1
1343
1344# skip all frames:
1345select=0
1346
1347# select only I-frames
1348select='eq(pict_type\,I)'
1349
1350# select one frame every 100
1351select='not(mod(n\,100))'
1352
1353# select only frames contained in the 10-20 time interval
1354select='gte(t\,10)*lte(t\,20)'
1355
1356# select only I frames contained in the 10-20 time interval
1357select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
1358
1359# select frames with a minimum distance of 10 seconds
1360select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
1361@end example
1362
2fd8756b
SS
1363@anchor{setdar}
1364@section setdar
1365
1366Set the Display Aspect Ratio for the filter output video.
1367
1368This is done by changing the specified Sample (aka Pixel) Aspect
1369Ratio, according to the following equation:
1370@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
1371
1372Keep in mind that this filter does not modify the pixel dimensions of
1373the video frame. Also the display aspect ratio set by this filter may
1374be changed by later filters in the filterchain, e.g. in case of
1375scaling or if another "setdar" or a "setsar" filter is applied.
1376
1377The filter accepts a parameter string which represents the wanted
1378display aspect ratio.
1379The parameter can be a floating point number string, or an expression
1380of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
1381numerator and denominator of the aspect ratio.
1382If the parameter is not specified, it is assumed the value "0:1".
1383
1384For example to change the display aspect ratio to 16:9, specify:
1385@example
1386setdar=16:9
1387# the above is equivalent to
1388setdar=1.77777
1389@end example
1390
4c989761 1391See also the @ref{setsar} filter documentation.
2fd8756b 1392
a532bb39
SS
1393@section setpts
1394
1395Change the PTS (presentation timestamp) of the input video frames.
1396
1397Accept in input an expression evaluated through the eval API, which
1398can contain the following constants:
1399
1400@table @option
1401@item PTS
1402the presentation timestamp in input
1403
1404@item PI
1405Greek PI
1406
1407@item PHI
1408golden ratio
1409
1410@item E
1411Euler number
1412
1413@item N
1414the count of the input frame, starting from 0.
1415
1416@item STARTPTS
1417the PTS of the first video frame
1418
1419@item INTERLACED
1420tell if the current frame is interlaced
1421
1422@item POS
1423original position in the file of the frame, or undefined if undefined
1424for the current frame
1425
1426@item PREV_INPTS
1427previous input PTS
1428
1429@item PREV_OUTPTS
1430previous output PTS
1431
1432@end table
1433
1434Some examples follow:
1435
1436@example
1437# start counting PTS from zero
1438setpts=PTS-STARTPTS
1439
1440# fast motion
1441setpts=0.5*PTS
1442
1443# slow motion
1444setpts=2.0*PTS
1445
1446# fixed rate 25 fps
1447setpts=N/(25*TB)
1448
1449# fixed rate 25 fps with some jitter
1450setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
1451@end example
1452
2fd8756b
SS
1453@anchor{setsar}
1454@section setsar
1455
1456Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
1457
1458Note that as a consequence of the application of this filter, the
1459output display aspect ratio will change according to the following
1460equation:
1461@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
1462
1463Keep in mind that the sample aspect ratio set by this filter may be
1464changed by later filters in the filterchain, e.g. if another "setsar"
1465or a "setdar" filter is applied.
1466
1467The filter accepts a parameter string which represents the wanted
1468sample aspect ratio.
1469The parameter can be a floating point number string, or an expression
1470of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
1471numerator and denominator of the aspect ratio.
1472If the parameter is not specified, it is assumed the value "0:1".
1473
1474For example to change the sample aspect ratio to 10:11, specify:
1475@example
1476setsar=10:11
1477@end example
1478
d89e3b36
SS
1479@section settb
1480
1481Set the timebase to use for the output frames timestamps.
1482It is mainly useful for testing timebase configuration.
1483
1484It accepts in input an arithmetic expression representing a rational.
1485The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
1486default timebase), and "intb" (the input timebase).
1487
1488The default value for the input is "intb".
1489
1490Follow some examples.
1491
1492@example
1493# set the timebase to 1/25
1494settb=1/25
1495
1496# set the timebase to 1/10
1497settb=0.1
1498
1499#set the timebase to 1001/1000
1500settb=1+0.001
1501
1502#set the timebase to 2*intb
1503settb=2*intb
1504
1505#set the default timebase value
1506settb=AVTB
1507@end example
1508
ee42716b
SS
1509@section showinfo
1510
1511Show a line containing various information for each input video frame.
1512The input video is not modified.
1513
1514The shown line contains a sequence of key/value pairs of the form
1515@var{key}:@var{value}.
1516
1517A description of each shown parameter follows:
1518
1519@table @option
1520@item n
1521sequential number of the input frame, starting from 0
1522
1523@item pts
1524Presentation TimeStamp of the input frame, expressed as a number of
1525time base units. The time base unit depends on the filter input pad.
1526
1527@item pts_time
1528Presentation TimeStamp of the input frame, expressed as a number of
1529seconds
1530
1531@item pos
1532position of the frame in the input stream, -1 if this information in
1533unavailable and/or meanigless (for example in case of synthetic video)
1534
1535@item fmt
1536pixel format name
1537
1538@item sar
1539sample aspect ratio of the input frame, expressed in the form
1540@var{num}/@var{den}
1541
1542@item s
1543size of the input frame, expressed in the form
1544@var{width}x@var{height}
1545
1546@item i
1547interlaced mode ("P" for "progressive", "T" for top field first, "B"
1548for bottom field first)
1549
1550@item iskey
15511 if the frame is a key frame, 0 otherwise
1552
1553@item type
1554picture type of the input frame ("I" for an I-frame, "P" for a
1555P-frame, "B" for a B-frame, "?" for unknown type).
1556Check also the documentation of the @code{AVPictureType} enum and of
1557the @code{av_get_picture_type_char} function defined in
1558@file{libavutil/avutil.h}.
1559
1560@item checksum
1561Adler-32 checksum of all the planes of the input frame
1562
1563@item plane_checksum
1564Adler-32 checksum of each plane of the input frame, expressed in the form
1565"[@var{c0} @var{c1} @var{c2} @var{c3}]"
1566@end table
1567
3275ac6a
SS
1568@section slicify
1569
1570Pass the images of input video on to next video filter as multiple
1571slices.
1572
1573@example
1574./ffmpeg -i in.avi -vf "slicify=32" out.avi
1575@end example
1576
1577The filter accepts the slice height as parameter. If the parameter is
1578not specified it will use the default value of 16.
1579
1580Adding this in the beginning of filter chains should make filtering
1581faster due to better use of the memory cache.
1582
43945b27
SS
1583@section transpose
1584
1585Transpose rows with columns in the input video and optionally flip it.
1586
1587It accepts a parameter representing an integer, which can assume the
1588values:
1589
1590@table @samp
1591@item 0
1592Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
1593@example
1594L.R L.l
1595. . -> . .
1596l.r R.r
1597@end example
1598
1599@item 1
1600Rotate by 90 degrees clockwise, that is:
1601@example
1602L.R l.L
1603. . -> . .
1604l.r r.R
1605@end example
1606
1607@item 2
1608Rotate by 90 degrees counterclockwise, that is:
1609@example
1610L.R R.r
1611. . -> . .
1612l.r L.l
1613@end example
1614
1615@item 3
1616Rotate by 90 degrees clockwise and vertically flip, that is:
1617@example
1618L.R r.R
1619. . -> . .
1620l.r l.L
1621@end example
1622@end table
1623
3275ac6a
SS
1624@section unsharp
1625
843b5fd0
SS
1626Sharpen or blur the input video.
1627
1628It accepts the following parameters:
1629@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
3275ac6a
SS
1630
1631Negative values for the amount will blur the input video, while positive
1632values will sharpen. All parameters are optional and default to the
1ee20141 1633equivalent of the string '5:5:1.0:5:5:0.0'.
3275ac6a
SS
1634
1635@table @option
1636
1637@item luma_msize_x
1638Set the luma matrix horizontal size. It can be an integer between 3
1639and 13, default value is 5.
1640
1641@item luma_msize_y
1642Set the luma matrix vertical size. It can be an integer between 3
1643and 13, default value is 5.
1644
1645@item luma_amount
1646Set the luma effect strength. It can be a float number between -2.0
1647and 5.0, default value is 1.0.
1648
1649@item chroma_msize_x
1650Set the chroma matrix horizontal size. It can be an integer between 3
1ee20141 1651and 13, default value is 5.
3275ac6a
SS
1652
1653@item chroma_msize_y
1654Set the chroma matrix vertical size. It can be an integer between 3
1ee20141 1655and 13, default value is 5.
3275ac6a
SS
1656
1657@item luma_amount
1658Set the chroma effect strength. It can be a float number between -2.0
1659and 5.0, default value is 0.0.
1660
1661@end table
1662
1663@example
1664# Strong luma sharpen effect parameters
1665unsharp=7:7:2.5
1666
1667# Strong blur of both luma and chroma parameters
1668unsharp=7:7:-2:7:7:-2
1669
1670# Use the default values with @command{ffmpeg}
1671./ffmpeg -i in.avi -vf "unsharp" out.mp4
1672@end example
1673
1674@section vflip
1675
1676Flip the input video vertically.
1677
1678@example
1679./ffmpeg -i in.avi -vf "vflip" out.avi
1680@end example
1681
acbac567
MN
1682@section yadif
1683
1653027a
SS
1684Deinterlace the input video ("yadif" means "yet another deinterlacing
1685filter").
acbac567 1686
ab09df9d 1687It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
acbac567 1688
1653027a
SS
1689@var{mode} specifies the interlacing mode to adopt, accepts one of the
1690following values:
acbac567 1691
1653027a
SS
1692@table @option
1693@item 0
1694output 1 frame for each frame
1695@item 1
1696output 1 frame for each field
1697@item 2
1698like 0 but skips spatial interlacing check
1699@item 3
1700like 1 but skips spatial interlacing check
1701@end table
acbac567
MN
1702
1703Default value is 0.
1704
1653027a
SS
1705@var{parity} specifies the picture field parity assumed for the input
1706interlaced video, accepts one of the following values:
acbac567 1707
1653027a
SS
1708@table @option
1709@item 0
1653027a 1710assume top field first
4703a7b5
SS
1711@item 1
1712assume bottom field first
1653027a
SS
1713@item -1
1714enable automatic detection
acbac567
MN
1715@end table
1716
1653027a 1717Default value is -1.
a51c71bb
BC
1718If interlacing is unknown or decoder does not export this information,
1719top field first will be assumed.
1653027a 1720
ab09df9d
JP
1721@var{auto] specifies if deinterlacer should trust the interlaced flag
1722and only deinterlace frames marked as interlaced
1723
1724@table @option
1725@item 0
1726deinterlace all frames
1727@item 1
1728only deinterlace frames marked as interlaced
1729@end table
1730
1731Default value is 0.
1732
3275ac6a
SS
1733@c man end VIDEO FILTERS
1734
1735@chapter Video Sources
1736@c man begin VIDEO SOURCES
1737
1738Below is a description of the currently available video sources.
1739
24413399
SS
1740@section buffer
1741
1742Buffer video frames, and make them available to the filter chain.
1743
1744This source is mainly intended for a programmatic use, in particular
ac1a31ab 1745through the interface defined in @file{libavfilter/vsrc_buffer.h}.
24413399
SS
1746
1747It accepts the following parameters:
7a11c82f 1748@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}
24413399
SS
1749
1750All the parameters need to be explicitely defined.
1751
1752Follows the list of the accepted parameters.
1753
1754@table @option
1755
1756@item width, height
1757Specify the width and height of the buffered video frames.
1758
1759@item pix_fmt_string
24413399
SS
1760A string representing the pixel format of the buffered video frames.
1761It may be a number corresponding to a pixel format, or a pixel format
1762name.
1763
94498ec9
SS
1764@item timebase_num, timebase_den
1765Specify numerator and denomitor of the timebase assumed by the
1766timestamps of the buffered frames.
7a11c82f
MN
1767
1768@item sample_aspect_ratio.num, sample_aspect_ratio.den
1769Specify numerator and denominator of the sample aspect ratio assumed
1770by the video frames.
24413399
SS
1771@end table
1772
1773For example:
1774@example
7a11c82f 1775buffer=320:240:yuv410p:1:24:1:1
24413399
SS
1776@end example
1777
1778will instruct the source to accept video frames with size 320x240 and
7a11c82f
MN
1779with format "yuv410p", assuming 1/24 as the timestamps timebase and
1780square pixels (1:1 sample aspect ratio).
94498ec9
SS
1781Since the pixel format with name "yuv410p" corresponds to the number 6
1782(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
1783this example corresponds to:
24413399 1784@example
94498ec9 1785buffer=320:240:6:1:24
24413399
SS
1786@end example
1787
23ccf3c7
SS
1788@section color
1789
1790Provide an uniformly colored input.
1791
1792It accepts the following parameters:
b5f47309 1793@var{color}:@var{frame_size}:@var{frame_rate}
23ccf3c7
SS
1794
1795Follows the description of the accepted parameters.
1796
1797@table @option
1798
1799@item color
1800Specify the color of the source. It can be the name of a color (case
1801insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
1802alpha specifier. The default value is "black".
1803
1804@item frame_size
1805Specify the size of the sourced video, it may be a string of the form
e83c2dde 1806@var{width}x@var{height}, or the name of a size abbreviation. The
23ccf3c7
SS
1807default value is "320x240".
1808
1809@item frame_rate
1810Specify the frame rate of the sourced video, as the number of frames
1811generated per second. It has to be a string in the format
1812@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
1813number or a valid video frame rate abbreviation. The default value is
1814"25".
1815
1816@end table
1817
1818For example the following graph description will generate a red source
1819with an opacity of 0.2, with size "qcif" and a frame rate of 10
1820frames per second, which will be overlayed over the source connected
1821to the pad with identifier "in".
1822
1823@example
1824"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
1825@end example
1826
9409c381
SS
1827@section movie
1828
1829Read a video stream from a movie container.
1830
1831It accepts the syntax: @var{movie_name}[:@var{options}] where
1832@var{movie_name} is the name of the resource to read (not necessarily
1833a file but also a device or a stream accessed through some protocol),
1834and @var{options} is an optional sequence of @var{key}=@var{value}
1835pairs, separated by ":".
1836
1837The description of the accepted options follows.
1838
1839@table @option
1840
1841@item format_name, f
1842Specifies the format assumed for the movie to read, and can be either
1843the name of a container or an input device. If not specified the
1844format is guessed from @var{movie_name} or by probing.
1845
1846@item seek_point, sp
1847Specifies the seek point in seconds, the frames will be output
1848starting from this seek point, the parameter is evaluated with
1849@code{av_strtod} so the numerical value may be suffixed by an IS
1850postfix. Default value is "0".
1851
1852@item stream_index, si
1853Specifies the index of the video stream to read. If the value is -1,
1854the best suited video stream will be automatically selected. Default
1855value is "-1".
1856
1857@end table
1858
1859This filter allows to overlay a second video on top of main input of
1860a filtergraph as shown in this graph:
1861@example
1862input -----------> deltapts0 --> overlay --> output
1863 ^
1864 |
1865movie --> scale--> deltapts1 -------+
1866@end example
1867
1868Some examples follow:
1869@example
1870# skip 3.2 seconds from the start of the avi file in.avi, and overlay it
1871# on top of the input labelled as "in".
1872movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
1873[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
1874
1875# read from a video4linux2 device, and overlay it on top of the input
1876# labelled as "in"
1877movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
1878[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
1879
1880@end example
1881
3275ac6a
SS
1882@section nullsrc
1883
1884Null video source, never return images. It is mainly useful as a
1885template and to be employed in analysis / debugging tools.
1886
1887It accepts as optional parameter a string of the form
16134b7c 1888@var{width}:@var{height}:@var{timebase}.
3275ac6a 1889
16134b7c
SS
1890@var{width} and @var{height} specify the size of the configured
1891source. The default values of @var{width} and @var{height} are
1892respectively 352 and 288 (corresponding to the CIF size format).
1893
1894@var{timebase} specifies an arithmetic expression representing a
1895timebase. The expression can contain the constants "PI", "E", "PHI",
1896"AVTB" (the default timebase), and defaults to the value "AVTB".
3275ac6a 1897
f8608dca
SS
1898@section frei0r_src
1899
1900Provide a frei0r source.
1901
1902To enable compilation of this filter you need to install the frei0r
f8a45fa1 1903header and configure Libav with --enable-frei0r.
f8608dca
SS
1904
1905The source supports the syntax:
1906@example
1907@var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
1908@end example
1909
1910@var{size} is the size of the video to generate, may be a string of the
1911form @var{width}x@var{height} or a frame size abbreviation.
1912@var{rate} is the rate of the video to generate, may be a string of
1913the form @var{num}/@var{den} or a frame rate abbreviation.
1914@var{src_name} is the name to the frei0r source to load. For more
1915information regarding frei0r and how to set the parameters read the
4c989761 1916section @ref{frei0r} in the description of the video filters.
f8608dca
SS
1917
1918Some examples follow:
1919@example
1920# generate a frei0r partik0l source with size 200x200 and framerate 10
1921# which is overlayed on the overlay filter main input
1922frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
1923@end example
1924
3275ac6a
SS
1925@c man end VIDEO SOURCES
1926
1927@chapter Video Sinks
1928@c man begin VIDEO SINKS
1929
1930Below is a description of the currently available video sinks.
1931
1932@section nullsink
1933
1934Null video sink, do absolutely nothing with the input video. It is
1935mainly useful as a template and to be employed in analysis / debugging
1936tools.
1937
1938@c man end VIDEO SINKS
1939