2 @c man begin AUDIO FILTERS
4 When you configure your FFmpeg build, you can disable any of the
5 existing filters using --disable-filters.
6 The configure output will show the audio filters included in your
9 Below is a description of the currently available audio filters.
13 Pass the audio source unchanged to the output.
15 @c man end AUDIO FILTERS
17 @chapter Audio Sources
18 @c man begin AUDIO SOURCES
20 Below is a description of the currently available audio sources.
24 Null audio source, never return audio frames. It is mainly useful as a
25 template and to be employed in analysis / debugging tools.
27 It accepts as optional parameter a string of the form
28 @var{sample_rate}:@var{channel_layout}.
30 @var{sample_rate} specify the sample rate, and defaults to 44100.
32 @var{channel_layout} specify the channel layout, and can be either an
33 integer or a string representing a channel layout. The default value
34 of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
36 Check the channel_layout_map definition in
37 @file{libavcodec/audioconvert.c} for the mapping between strings and
38 channel layout values.
42 # set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO.
49 @c man end AUDIO SOURCES
52 @c man begin AUDIO SINKS
54 Below is a description of the currently available audio sinks.
58 Null audio sink, do absolutely nothing with the input audio. It is
59 mainly useful as a template and to be employed in analysis / debugging
62 @c man end AUDIO SINKS
64 @chapter Video Filters
65 @c man begin VIDEO FILTERS
67 When you configure your FFmpeg build, you can disable any of the
68 existing filters using --disable-filters.
69 The configure output will show the video filters included in your
72 Below is a description of the currently available video filters.
76 Detect frames that are (almost) completely black. Can be useful to
77 detect chapter transitions or commercials. Output lines consist of
78 the frame number of the detected frame, the percentage of blackness,
79 the position in the file if known or -1 and the timestamp in seconds.
81 In order to display the output lines, you need to set the loglevel at
82 least to the AV_LOG_INFO value.
84 The filter accepts the syntax:
86 blackframe[=@var{amount}:[@var{threshold}]]
89 @var{amount} is the percentage of the pixels that have to be below the
90 threshold, and defaults to 98.
92 @var{threshold} is the threshold below which a pixel value is
93 considered black, and defaults to 32.
97 Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
99 The parameters are expressions containing the following constants:
103 the corresponding mathematical approximated values for e
104 (euler number), pi (greek PI), PHI (golden ratio)
107 the computed values for @var{x} and @var{y}. They are evaluated for
111 the input width and heigth
114 same as @var{in_w} and @var{in_h}
117 the output (cropped) width and heigth
120 same as @var{out_w} and @var{out_h}
123 the number of input frame, starting from 0
126 the position in the file of the input frame, NAN if unknown
129 timestamp expressed in seconds, NAN if the input timestamp is unknown
133 The @var{out_w} and @var{out_h} parameters specify the expressions for
134 the width and height of the output (cropped) video. They are
135 evaluated just at the configuration of the filter.
137 The default value of @var{out_w} is "in_w", and the default value of
138 @var{out_h} is "in_h".
140 The expression for @var{out_w} may depend on the value of @var{out_h},
141 and the expression for @var{out_h} may depend on @var{out_w}, but they
142 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
143 evaluated after @var{out_w} and @var{out_h}.
145 The @var{x} and @var{y} parameters specify the expressions for the
146 position of the top-left corner of the output (non-cropped) area. They
147 are evaluated for each frame. If the evaluated value is not valid, it
148 is approximated to the nearest valid value.
150 The default value of @var{x} is "(in_w-out_w)/2", and the default
151 value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
152 the center of the input image.
154 The expression for @var{x} may depend on @var{y}, and the expression
155 for @var{y} may depend on @var{x}.
157 Follow some examples:
159 # crop the central input area with size 100x100
162 # crop the central input area with size 2/3 of the input video
163 "crop=2/3*in_w:2/3*in_h"
165 # crop the input video central square
168 # delimit the rectangle with the top-left corner placed at position
169 # 100:100 and the right-bottom corner corresponding to the right-bottom
170 # corner of the input image.
171 crop=in_w-100:in_h-100:100:100
173 # crop 10 pixels from the lefth and right borders, and 20 pixels from
174 # the top and bottom borders
175 "crop=in_w-2*10:in_h-2*20"
177 # keep only the bottom right quarter of the input image
178 "crop=in_w/2:in_h/2:in_w/2:in_h/2"
180 # crop height for getting Greek harmony
181 "crop=in_w:1/PHI*in_w"
184 "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)"
186 # erratic camera effect depending on timestamp and position
187 "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)"
189 # set x depending on the value of y
190 "crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
195 Auto-detect crop size.
197 Calculate necessary cropping parameters and prints the recommended
198 parameters through the logging system. The detected dimensions
199 correspond to the non-black area of the input video.
201 It accepts the syntax:
203 cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
209 Threshold, which can be optionally specified from nothing (0) to
210 everything (255), defaults to 24.
213 Value which the width/height should be divisible by, defaults to
214 16. The offset is automatically adjusted to center the video. Use 2 to
215 get only even dimensions (needed for 4:2:2 video). 16 is best when
216 encoding to most video codecs.
219 Counter that determines after how many frames cropdetect will reset
220 the previously detected largest video area and start over to detect
221 the current optimal crop area. Defaults to 0.
223 This can be useful when channel logos distort the video area. 0
224 indicates never reset and return the largest area encountered during
230 Draw a colored box on the input image.
232 It accepts the syntax:
234 drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
240 Specify the top left corner coordinates of the box. Default to 0.
243 Specify the width and height of the box, if 0 they are interpreted as
244 the input width and height. Default to 0.
247 Specify the color of the box to write, it can be the name of a color
248 (case insensitive match) or a 0xRRGGBB[AA] sequence.
251 Follow some examples:
253 # draw a black box around the edge of the input image
256 # draw a box with color red and an opacity of 50%
257 drawbox=10:20:200:60:red@@0.5"
262 Buffer input images and send them when they are requested.
264 This filter is mainly useful when auto-inserted by the libavfilter
267 The filter does not take parameters.
271 Convert the input video to one of the specified pixel formats.
272 Libavfilter will try to pick one that is supported for the input to
275 The filter accepts a list of pixel format names, separated by ":",
276 for example "yuv420p:monow:rgb24".
278 The following command:
281 ./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
284 will convert the input video to the format "yuv420p".
289 Apply a frei0r effect to the input video.
291 To enable compilation of this filter you need to install the frei0r
292 header and configure FFmpeg with --enable-frei0r.
294 The filter supports the syntax:
296 @var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
299 @var{filter_name} is the name to the frei0r effect to load. If the
300 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
301 is searched in each one of the directories specified by the colon
302 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
303 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
304 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
306 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
307 for the frei0r effect.
309 A frei0r effect parameter can be a boolean (whose values are specified
310 with "y" and "n"), a double, a color (specified by the syntax
311 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
312 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
313 description), a position (specified by the syntax @var{X}/@var{Y},
314 @var{X} and @var{Y} being float numbers) and a string.
316 The number and kind of parameters depend on the loaded effect. If an
317 effect parameter is not specified the default value is set.
319 Some examples follow:
321 # apply the distort0r effect, set the first two double parameters
322 frei0r=distort0r:0.5:0.01
324 # apply the colordistance effect, takes a color as first parameter
325 frei0r=colordistance:0.2/0.3/0.4
326 frei0r=colordistance:violet
327 frei0r=colordistance:0x112233
329 # apply the perspective effect, specify the top left and top right
331 frei0r=perspective:0.2/0.2:0.8/0.2
334 For more information see:
335 @url{http://piksel.org/frei0r}
339 Flip the input video horizontally.
341 For example to horizontally flip the video in input with
344 ffmpeg -i in.avi -vf "hflip" out.avi
349 Force libavfilter not to use any of the specified pixel formats for the
350 input to the next filter.
352 The filter accepts a list of pixel format names, separated by ":",
353 for example "yuv420p:monow:rgb24".
355 The following command:
358 ./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
361 will make libavfilter use a format different from "yuv420p" for the
362 input to the vflip filter.
366 Pass the video source unchanged to the output.
370 Apply smooth transform using libopencv.
372 To enable this filter install libopencv library and headers and
373 configure FFmpeg with --enable-libopencv.
375 The filter accepts the following parameters:
376 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
378 @var{type} is the type of smooth filter to apply, and can be one of
379 the following values: "blur", "blur_no_scale", "median", "gaussian",
380 "bilateral". The default value is "gaussian".
382 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
383 parameters whose meanings depend on smooth type. @var{param1} and
384 @var{param2} accept integer positive values or 0, @var{param3} and
385 @var{param4} accept float values.
387 The default value for @var{param1} is 3, the default value for the
388 other parameters is 0.
390 These parameters correspond to the parameters assigned to the
391 libopencv function @code{cvSmooth}. Refer to the official libopencv
392 documentation for the exact meaning of the parameters:
393 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
397 Overlay one video on top of another.
399 It takes two inputs and one output, the first input is the "main"
400 video on which the second input is overlayed.
402 It accepts the parameters: @var{x}:@var{y}.
404 @var{x} is the x coordinate of the overlayed video on the main video,
405 @var{y} is the y coordinate. The parameters are expressions containing
406 the following parameters:
410 main input width and height
413 same as @var{main_w} and @var{main_h}
415 @item overlay_w, overlay_h
416 overlay input width and height
419 same as @var{overlay_w} and @var{overlay_h}
422 Be aware that frames are taken from each input video in timestamp
423 order, hence, if their initial timestamps differ, it is a a good idea
424 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
425 have them begin in the same zero timestamp, as it does the example for
426 the @var{movie} filter.
428 Follow some examples:
430 # draw the overlay at 10 pixels from the bottom right
431 # corner of the main video.
432 overlay=main_w-overlay_w-10:main_h-overlay_h-10
434 # insert a transparent PNG logo in the bottom left corner of the input
435 movie=0:png:logo.png [logo];
436 [in][logo] overlay=10:main_h-overlay_h-10 [out]
438 # insert 2 different transparent PNG logos (second logo on bottom
440 movie=0:png:logo1.png [logo1];
441 movie=0:png:logo2.png [logo2];
442 [in][logo1] overlay=10:H-h-10 [in+logo1];
443 [in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
445 # add a transparent color layer on top of the main video,
446 # WxH specifies the size of the main input to the overlay filter
447 color=red@.3:WxH [over]; [in][over] overlay [out]
450 You can chain togheter more overlays but the efficiency of such
451 approach is yet to be tested.
455 Add paddings to the input image, and places the original input at the
456 given coordinates @var{x}, @var{y}.
458 It accepts the following parameters:
459 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
461 Follows the description of the accepted parameters.
466 Specify the size of the output image with the paddings added. If the
467 value for @var{width} or @var{height} is 0, the corresponding input size
468 is used for the output.
470 The default value of @var{width} and @var{height} is 0.
474 Specify the offsets where to place the input image in the padded area
475 with respect to the top/left border of the output image.
477 The default value of @var{x} and @var{y} is 0.
481 Specify the color of the padded area, it can be the name of a color
482 (case insensitive match) or a 0xRRGGBB[AA] sequence.
484 The default value of @var{color} is "black".
491 # Add paddings with color "violet" to the input video. Output video
492 # size is 640x480, the top-left corner of the input video is placed at
494 pad=640:480:0:40:violet
499 Pixel format descriptor test filter, mainly useful for internal
500 testing. The output video should be equal to the input video.
504 format=monow, pixdesctest
507 can be used to test the monowhite pixel format descriptor definition.
511 Scale the input video to @var{width}:@var{height} and/or convert the image format.
513 For example the command:
516 ./ffmpeg -i in.avi -vf "scale=200:100" out.avi
519 will scale the input video to a size of 200x100.
521 If the input image format is different from the format requested by
522 the next filter, the scale filter will convert the input to the
525 If the value for @var{width} or @var{height} is 0, the respective input
526 size is used for the output.
528 If the value for @var{width} or @var{height} is -1, the scale filter will
529 use, for the respective output size, a value that maintains the aspect
530 ratio of the input image.
532 The default value of @var{width} and @var{height} is 0.
536 Change the PTS (presentation timestamp) of the input video frames.
538 Accept in input an expression evaluated through the eval API, which
539 can contain the following constants:
543 the presentation timestamp in input
555 the count of the input frame, starting from 0.
558 the PTS of the first video frame
561 tell if the current frame is interlaced
564 original position in the file of the frame, or undefined if undefined
565 for the current frame
575 Some examples follow:
578 # start counting PTS from zero
590 # fixed rate 25 fps with some jitter
591 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
596 Set the timebase to use for the output frames timestamps.
597 It is mainly useful for testing timebase configuration.
599 It accepts in input an arithmetic expression representing a rational.
600 The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
601 default timebase), and "intb" (the input timebase).
603 The default value for the input is "intb".
605 Follow some examples.
608 # set the timebase to 1/25
611 # set the timebase to 1/10
614 #set the timebase to 1001/1000
617 #set the timebase to 2*intb
620 #set the default timebase value
626 Pass the images of input video on to next video filter as multiple
630 ./ffmpeg -i in.avi -vf "slicify=32" out.avi
633 The filter accepts the slice height as parameter. If the parameter is
634 not specified it will use the default value of 16.
636 Adding this in the beginning of filter chains should make filtering
637 faster due to better use of the memory cache.
641 Transpose rows with columns in the input video and optionally flip it.
643 It accepts a parameter representing an integer, which can assume the
648 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
656 Rotate by 90 degrees clockwise, that is:
664 Rotate by 90 degrees counterclockwise, that is:
672 Rotate by 90 degrees clockwise and vertically flip, that is:
682 Sharpen or blur the input video.
684 It accepts the following parameters:
685 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
687 Negative values for the amount will blur the input video, while positive
688 values will sharpen. All parameters are optional and default to the
689 equivalent of the string '5:5:1.0:0:0:0.0'.
694 Set the luma matrix horizontal size. It can be an integer between 3
695 and 13, default value is 5.
698 Set the luma matrix vertical size. It can be an integer between 3
699 and 13, default value is 5.
702 Set the luma effect strength. It can be a float number between -2.0
703 and 5.0, default value is 1.0.
706 Set the chroma matrix horizontal size. It can be an integer between 3
707 and 13, default value is 0.
710 Set the chroma matrix vertical size. It can be an integer between 3
711 and 13, default value is 0.
714 Set the chroma effect strength. It can be a float number between -2.0
715 and 5.0, default value is 0.0.
720 # Strong luma sharpen effect parameters
723 # Strong blur of both luma and chroma parameters
724 unsharp=7:7:-2:7:7:-2
726 # Use the default values with @command{ffmpeg}
727 ./ffmpeg -i in.avi -vf "unsharp" out.mp4
732 Flip the input video vertically.
735 ./ffmpeg -i in.avi -vf "vflip" out.avi
740 yadif is "yet another deinterlacing filter".
742 It accepts the syntax:
744 yadif=[@var{mode}[:@var{parity}]]
750 Specify the interlacing mode to adopt, accepts one of the following values.
752 0: Output 1 frame for each frame.
754 1: Output 1 frame for each field.
756 2: Like 0 but skips spatial interlacing check.
758 3: Like 1 but skips spatial interlacing check.
763 0 if is bottom field first, 1 if the interlaced video is top field
764 first, -1 to enable automatic detection.
768 @c man end VIDEO FILTERS
770 @chapter Video Sources
771 @c man begin VIDEO SOURCES
773 Below is a description of the currently available video sources.
777 Buffer video frames, and make them available to the filter chain.
779 This source is mainly intended for a programmatic use, in particular
780 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
782 It accepts the following parameters:
783 @var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}
785 All the parameters need to be explicitely defined.
787 Follows the list of the accepted parameters.
792 Specify the width and height of the buffered video frames.
795 A string representing the pixel format of the buffered video frames.
796 It may be a number corresponding to a pixel format, or a pixel format
799 @item timebase_num, timebase_den
800 Specify numerator and denomitor of the timebase assumed by the
801 timestamps of the buffered frames.
806 buffer=320:240:yuv410p:1:24
809 will instruct the source to accept video frames with size 320x240 and
810 with format "yuv410p" and assuming 1/24 as the timestamps timebase.
811 Since the pixel format with name "yuv410p" corresponds to the number 6
812 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
813 this example corresponds to:
815 buffer=320:240:6:1:24
820 Provide an uniformly colored input.
822 It accepts the following parameters:
823 @var{color}:@var{frame_size}:@var{frame_rate}
825 Follows the description of the accepted parameters.
830 Specify the color of the source. It can be the name of a color (case
831 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
832 alpha specifier. The default value is "black".
835 Specify the size of the sourced video, it may be a string of the form
836 @var{width}x@var{heigth}, or the name of a size abbreviation. The
837 default value is "320x240".
840 Specify the frame rate of the sourced video, as the number of frames
841 generated per second. It has to be a string in the format
842 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
843 number or a valid video frame rate abbreviation. The default value is
848 For example the following graph description will generate a red source
849 with an opacity of 0.2, with size "qcif" and a frame rate of 10
850 frames per second, which will be overlayed over the source connected
851 to the pad with identifier "in".
854 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
859 Null video source, never return images. It is mainly useful as a
860 template and to be employed in analysis / debugging tools.
862 It accepts as optional parameter a string of the form
863 @var{width}:@var{height}:@var{timebase}.
865 @var{width} and @var{height} specify the size of the configured
866 source. The default values of @var{width} and @var{height} are
867 respectively 352 and 288 (corresponding to the CIF size format).
869 @var{timebase} specifies an arithmetic expression representing a
870 timebase. The expression can contain the constants "PI", "E", "PHI",
871 "AVTB" (the default timebase), and defaults to the value "AVTB".
875 Provide a frei0r source.
877 To enable compilation of this filter you need to install the frei0r
878 header and configure FFmpeg with --enable-frei0r.
880 The source supports the syntax:
882 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
885 @var{size} is the size of the video to generate, may be a string of the
886 form @var{width}x@var{height} or a frame size abbreviation.
887 @var{rate} is the rate of the video to generate, may be a string of
888 the form @var{num}/@var{den} or a frame rate abbreviation.
889 @var{src_name} is the name to the frei0r source to load. For more
890 information regarding frei0r and how to set the parameters read the
891 section "frei0r" (@pxref{frei0r}) in the description of the video
894 Some examples follow:
896 # generate a frei0r partik0l source with size 200x200 and framerate 10
897 # which is overlayed on the overlay filter main input
898 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
901 @c man end VIDEO SOURCES
904 @c man begin VIDEO SINKS
906 Below is a description of the currently available video sinks.
910 Null video sink, do absolutely nothing with the input video. It is
911 mainly useful as a template and to be employed in analysis / debugging
914 @c man end VIDEO SINKS