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