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